@rvoh/dream 2.27.0 → 2.28.0

package/dist/esm/src/dream/QueryDriver/Postgres.js

@@ -10,7 +10,9 @@ import pg from 'pg';
 import { sql } from 'kysely';
 import DreamCLI from '../../cli/index.js';
 import { isPrimitiveDataType } from '../../db/dataTypes.js';
+import { LOCK_NOT_AVAILABLE, pgErrorType } from '../../db/errors.js';
 import DreamApp from '../../dream-app/index.js';
+import SortableScopeLockWaitTimedOut from '../../errors/SortableScopeLockWaitTimedOut.js';
 import camelize from '../../helpers/camelize.js';
 import { findCitextArrayOid, findCorrespondingArrayOid, findEnumArrayOids, parsePostgresBigint, parsePostgresDate, parsePostgresDatetime, parsePostgresDatetimeTz, parsePostgresDecimal, parsePostgresTime, parsePostgresTimeTz, } from '../../helpers/customPgParsers.js';
 import { testDatabasePoolSize } from '../../db/testDatabasePool.js';
@@ -219,6 +221,78 @@ export default class PostgresQueryDriver extends KyselyQueryDriver {
     applyRowLock(kyselyQuery, tableAlias) {
         return kyselyQuery.forUpdate(tableAlias);
     }
+    static supportsAdvisoryTransactionLocks = true;
+    /**
+     * @internal
+     *
+     * Postgres implementation of the transaction-scoped advisory lock seam.
+     *
+     * Uses the single-`bigint` form `pg_advisory_xact_lock(bigint)`, whose lock
+     * space is distinct from the two-`int4` form the test-database pool claims
+     * with (see {@link openTestDatabaseLockSession}), so an application lock can
+     * never collide with a pool claim.
+     *
+     * Every key is taken in one statement, over `unnest` of the key array: a
+     * function scan yields its rows in array order, so the caller's sorted
+     * acquisition order — the thing that keeps two operations over the same
+     * scopes from deadlocking — is preserved, while a batch that needs one key
+     * per candidate record costs one round trip rather than N.
+     *
+     * The locks are held until the enclosing transaction ends, and are waiting
+     * (no `NOWAIT`): a second transaction asking for the same key blocks at that
+     * key's row until the holder commits or rolls back. Because they are
+     * transaction-scoped there is nothing to release, and re-acquiring a key
+     * within one transaction is a no-op rather than an error.
+     *
+     * The wait is bounded by `lock_timeout`, taken from
+     * {@link DreamApp.sortableScopeLockTimeout} and applied to the acquisition
+     * statement alone: the prior value is read in the same statement that sets
+     * the bound and restored in the next one, so the transaction's row-lock waits
+     * keep whatever the application configured. Postgres cancels the statement
+     * with `55P03` when the bound elapses, and that is translated here into
+     * {@link SortableScopeLockWaitTimedOut} so no Postgres error code escapes the
+     * driver.
+     *
+     * A timeout of `0` means "no bound", which is what `lock_timeout` itself
+     * means by it, and is sent as the bound rather than skipped: an application
+     * whose connection carries a `lock_timeout` of its own would otherwise have
+     * its acquisition cancelled by that bound, which is neither the unbounded
+     * wait `0` asks for nor a cancellation this driver could translate.
+     */
+    static async acquireAdvisoryTransactionLocks(txn, keys) {
+        if (!keys.length)
+            return;
+        // the keys are passed as text and cast, since a JS bigint is not a value
+        // the pg driver can bind directly
+        const lockKeys = keys.map(key => key.toString());
+        const timeoutMs = DreamApp.getOrFail().sortableScopeLockTimeout;
+        let priorLockTimeout;
+        try {
+            // one statement, three things in a forced order: `bounded` selects from
+            // `prior_setting`, so the prior value is read before the bound replaces
+            // it, and both are `from` items, so both are scanned before the target
+            // list takes a single lock. Merging them costs nothing where separate
+            // statements would cost round trips inside the lock window.
+            //
+            // The returned column is aliased to a single word deliberately: result
+            // keys come back camelized, and a one-word alias is the same either way
+            const result = await sql `
+        with prior_setting as (select current_setting('lock_timeout') as value),
+             bounded as (select set_config('lock_timeout', ${timeoutMs.toString()}, true) as value from prior_setting)
+        select prior_setting.value as prior, pg_advisory_xact_lock(sortable_lock_keys.lock_key)
+        from prior_setting, bounded, unnest(${lockKeys}::bigint[]) as sortable_lock_keys(lock_key)
+      `.execute(txn.kyselyTransaction);
+            priorLockTimeout = result.rows[0].prior;
+        }
+        catch (error) {
+            if (pgErrorType(error) === LOCK_NOT_AVAILABLE)
+                throw new SortableScopeLockWaitTimedOut(timeoutMs);
+            throw error;
+        }
+        // `current_setting` returns the value with its unit ('0', '5s', '250ms'),
+        // which is a form `set_config` accepts back unchanged
+        await sql `select set_config('lock_timeout', ${priorLockTimeout}, true)`.execute(txn.kyselyTransaction);
+    }
     static supportsParallelTestDatabases = true;
     /**
      * @internal

package/dist/esm/src/dream/internal/destroyDream.js

@@ -1,3 +1,5 @@
+import performSortableDestroyWork from '../../decorators/field/sortable/helpers/performSortableDestroyWork.js';
+import prepareSortableFieldsForDestroy, { clearSortableFieldsForDestroy, } from '../../decorators/field/sortable/helpers/prepareSortableFieldsForDestroy.js';
 import DreamApp from '../../dream-app/index.js';
 import destroyAssociatedRecords from './destroyAssociatedRecords.js';
 import runHooksFor from './runHooksFor.js';
@@ -29,6 +31,17 @@ export default async function destroyDream(dream, txn = null, options) {
  */
 async function destroyDreamWithTransaction(dream, txn, options) {
     const { cascade, reallyDestroy, skipHooks } = options;
+    if (!skipHooks)
+        await runHooksFor('beforeDestroy', dream, true, null, txn);
+    // `preventDeletion` is fail-closed: a veto returns before the
+    // dependent-destroy cascade, so neither this record nor any of its
+    // `dependent: 'destroy'` associations are touched. The check sits outside the
+    // hook guard because the flag can also be set by the caller ahead of a
+    // `skipHooks` destroy, which runs no hooks but must not cascade either.
+    // Recursing through the cascade means a vetoing descendant stops its own
+    // subtree while the destroy that reached it carries on.
+    if (dream['_preventDeletion'])
+        return dream;
     if (cascade) {
         // NOTE: the dependent-destroy tree is loaded lazily, inside
         // destroyAssociatedRecords, so that a cascaded descendant whose
@@ -37,15 +50,56 @@ async function destroyDreamWithTransaction(dream, txn, options) {
         // clone: the hooks and the delete below operate on the original.
         await destroyAssociatedRecords(dream, txn, options);
     }
-    if (!skipHooks) {
-        await runHooksFor('beforeDestroy', dream, true, null, txn);
+    // Sortable preparation runs as a phase after every user beforeDestroy hook,
+    // never as a hook among them: the destroy's whole advisory key set — every
+    // sortable field — is acquired in one sorted pass, and the row's real
+    // position and scope values are read in one snapshot SELECT while the row
+    // still exists. It sits after the cascade so this destroy does not hold the
+    // scope lock across every descendant's destroy — true of the destroy itself,
+    // not of the transaction it runs in: under `Query#destroy({ lock: true })`
+    // the batch's whole key set is already held, taken before any row was
+    // claimed. A destroy that skips hooks performs no compaction, and one a
+    // cascaded descendant's hook has vetoed will not delete, so neither needs
+    // locks or a snapshot.
+    let rowFoundBeforeDelete = true;
+    if (!skipHooks && !dream['_preventDeletion']) {
+        rowFoundBeforeDelete = await prepareSortableFieldsForDestroy(dream, txn);
     }
-    await maybeDestroyDream(dream, txn, reallyDestroy);
-    if (!skipHooks) {
+    const rowsRemoved = await maybeDestroyDream(dream, txn, reallyDestroy);
+    // `preventDeletion` can still arrive after the veto check above has passed:
+    // a cascaded descendant's hook can reach back to this record and call it. The
+    // record is then still present, so neither the after-destroy hooks nor the
+    // reload of a soft deleted row have anything to run against, and the driver
+    // leaves the row alone. A veto that late cannot be made fail-closed against
+    // the cascade — the descendants are already destroyed by the time it lands.
+    const deletionPrevented = dream['_preventDeletion'];
+    // A destroy of a row that is already gone — a second `destroy()` on the same
+    // instance, a job retry, two workers racing — removes nothing, so there is
+    // nothing for the after-destroy hooks to react to and, for a sortable model,
+    // no vacancy to close. Compacting anyway would shift the scope a second time
+    // from the instance's remembered position, moving survivors onto occupied
+    // positions. A veto also removes nothing, and keeps its own path: it is
+    // recognized by the flag above, never by the count.
+    //
+    // Both signals are read because they catch opposite races. The count is the
+    // stronger of the two — a writer outside the sortable path can remove the row
+    // after the snapshot read, and only the count sees that. The snapshot's
+    // existence signal catches the mirror shape: the row was already gone when
+    // the snapshot read ran, so this destroy holds no position to vacate, and a
+    // row that reappeared under the same primary key is what the delete removed.
+    const removedNothing = !deletionPrevented && (rowsRemoved === 0 || !rowFoundBeforeDelete);
+    if (removedNothing)
+        clearSortableFieldsForDestroy(dream);
+    if (!skipHooks && !deletionPrevented && !removedNothing) {
+        // The compaction is a phase before the after-destroy hooks, never a hook
+        // among them, so every user afterDestroy hook observes the compacted scope
+        // regardless of where it was declared — the destroy-side counterpart of
+        // performSortablePositionWork running before the after-save hooks.
+        await performSortableDestroyWork(dream, txn);
         await runHooksFor('afterDestroy', dream, true, null, txn);
         await runHooksFor('afterDestroyCommit', dream, true, null, txn);
     }
-    if (shouldSoftDelete(dream, reallyDestroy)) {
+    if (shouldSoftDelete(dream, reallyDestroy) && !deletionPrevented) {
         await dream.txn(txn).reload();
     }
     return dream;
@@ -62,5 +116,5 @@ function shouldSoftDelete(dream, reallyDestroy) {
  */
 async function maybeDestroyDream(dream, txn, reallyDestroy) {
     const dbDriverClass = DreamApp.getOrFail().dbConnectionQueryDriverClass(dream.connectionName);
-    await dbDriverClass.destroyDream(dream, txn, reallyDestroy);
+    return await dbDriverClass.destroyDream(dream, txn, reallyDestroy);
 }

package/dist/esm/src/dream/internal/saveDream.js

@@ -1,3 +1,8 @@
+import acquireStabilizedSortableScopeLocks from '../../decorators/field/sortable/helpers/acquireStabilizedSortableScopeLocks.js';
+import { clearSortableSaveState } from '../../decorators/field/sortable/helpers/clearCachedSortableValues.js';
+import performSortablePositionWork from '../../decorators/field/sortable/helpers/performSortablePositionWork.js';
+import prepareSortableFieldsForSave from '../../decorators/field/sortable/helpers/prepareSortableFieldsForSave.js';
+import { cacheSortableSnapshots } from '../../decorators/field/sortable/helpers/sortableSnapshot.js';
 import ValidationError from '../../errors/ValidationError.js';
 import sqlAttributes from '../../helpers/sqlAttributes.js';
 import { DateTime } from '../../utils/datetime/DateTime.js';
@@ -13,6 +18,27 @@ export default async function saveDream(dream, txn = null, { skipHooks = false }
             await runHooksFor('beforeCreate', dream, alreadyPersisted, null, txn);
         await runHooksFor('beforeSave', dream, alreadyPersisted, null, txn);
     }
+    // Where this save opens a transaction of its own (below), a failure inside it
+    // rolls the driver write back, so the instance has to be able to go back to
+    // what it was when `save` was called: an instance left holding the primary
+    // key of a rolled-back INSERT — and left clean, so that the retry the failure
+    // invites returns at the `isDirty` check below without writing anything — is
+    // a record whose row does not exist. Captured before the sortable phase
+    // applies its position sentinel, so the retry sees the caller's own position.
+    // Only a model declaring sortable fields can reach that transaction, so a save
+    // of any other model copies nothing.
+    const preSaveState = txn || !dream.constructor['sortableFields'].length
+        ? null
+        : capturePersistenceState(dream);
+    // Sortable computes each record's position under an advisory lock on its sort
+    // scope, and that lock is transaction-scoped, so the write and the position
+    // write that follows it have to commit together. Preparation runs here as a
+    // called phase — after every consumer before-hook, never as a hook among
+    // them — so that a position or scope change a user's own `beforeSave` hook
+    // introduced is inside the boundary regardless of where the hook was
+    // registered. Seated before the change capture, so the position sentinel
+    // lands in `beforeSaveChanges` exactly as it always has.
+    const sortableFieldConfigs = prepareSortableFieldsForSave(dream, { alreadyPersisted, skipHooks });
     const beforeSaveChanges = dream.changes();
     // need to check validations after running before hooks, or else
     // model hooks that might make a model valid cannot run
@@ -20,6 +46,69 @@ export default async function saveDream(dream, txn = null, { skipHooks = false }
         throw new ValidationError(dream['sanitizedConstructorName'], dream.errors);
     if (alreadyPersisted && !dream.isDirty)
         return dream;
+    if (sortableFieldConfigs.length && !txn) {
+        // The self-opened transaction holds only Dream's own work: the scope
+        // locks, the driver write, and the position write, which is its last
+        // statement. COMMIT releases the scope locks before any user after-hook
+        // runs; the after-hook and `*Commit` families then run with no
+        // transaction, exactly as on a save of a non-sortable model, so a hook
+        // that throws cannot roll back the committed row and a slow hook blocks
+        // no other writer of the scope.
+        try {
+            await dream.constructor.transaction(async (sortableTxn) => await writeDream(dream, sortableTxn, { alreadyPersisted, sortableFieldConfigs }));
+        }
+        catch (error) {
+            restorePersistenceState(dream, preSaveState);
+            clearSortableSaveState(dream, sortableFieldConfigs);
+            throw error;
+        }
+        await runAfterSaveHooks(dream, null, { skipHooks, alreadyPersisted, beforeSaveChanges });
+        return dream;
+    }
+    await writeDream(dream, txn, { alreadyPersisted, sortableFieldConfigs });
+    await runAfterSaveHooks(dream, txn, { skipHooks, alreadyPersisted, beforeSaveChanges });
+    return dream;
+}
+/**
+ * Everything a write changes about how the instance answers "am I saved, and
+ * what has changed since?" — the persisted flag, the attributes the driver's
+ * `RETURNING` wrote (the primary key among them), and the three attribute
+ * snapshots the dirty-checking reads.
+ */
+function capturePersistenceState(dream) {
+    return {
+        isPersisted: dream.isPersisted,
+        frozenAttributes: { ...dream['frozenAttributes'] },
+        originalAttributes: { ...dream['originalAttributes'] },
+        attributesFromBeforeLastSave: { ...dream['attributesFromBeforeLastSave'] },
+        currentAttributes: { ...dream['currentAttributes'] },
+    };
+}
+function restorePersistenceState(dream, state) {
+    dream['isPersisted'] = state.isPersisted;
+    dream['frozenAttributes'] = state.frozenAttributes;
+    dream['originalAttributes'] = state.originalAttributes;
+    dream['attributesFromBeforeLastSave'] = state.attributesFromBeforeLastSave;
+    dream['currentAttributes'] = state.currentAttributes;
+}
+async function writeDream(dream, txn, { alreadyPersisted, sortableFieldConfigs, }) {
+    let rowFoundBeforeWrite = true;
+    // A position- or scope-changing update takes its scope locks here, before the
+    // write, because the write overwrites the scope column: after it, neither the
+    // scope the record is moving out of nor its real position is readable from the
+    // row. The locks are therefore held across the update and the position write
+    // that follows it — one transaction, one acquisition — and the snapshot the
+    // position work is computed from is read here, under them.
+    //
+    // A create locks later, around its own position computation: it has no scope
+    // to move out of and no prior row to snapshot, and the deferrable unique
+    // constraint sortable tables carry tolerates two uncommitted rows at the
+    // pre-write position sentinel.
+    if (txn && alreadyPersisted && sortableFieldConfigs.length) {
+        const { rowExists, snapshots } = await acquireStabilizedSortableScopeLocks(dream, txn, sortableFieldConfigs);
+        rowFoundBeforeWrite = rowExists;
+        cacheSortableSnapshots(dream, snapshots);
+    }
     const now = DateTime.now();
     if (!alreadyPersisted && !dream.createdAt && dream.columns().has('createdAt'))
         dream.createdAt = now;
@@ -41,14 +130,27 @@ export default async function saveDream(dream, txn = null, { skipHooks = false }
     dream['freezeAttributes']();
     dream['attributesFromBeforeLastSave'] = dream['originalAttributes'];
     dream['originalAttributes'] = dream.getAttributes();
-    if (!skipHooks) {
-        await runHooksFor('afterSave', dream, alreadyPersisted, beforeSaveChanges, txn);
-        if (alreadyPersisted)
-            await runHooksFor('afterUpdate', dream, alreadyPersisted, beforeSaveChanges, txn);
+    // An update whose row the snapshot read positively found gone holds no
+    // position to move: the vacancy it remembers was closed by whoever removed
+    // the row, and shifting the scope from the instance's remembered position
+    // would move survivors onto occupied ones. The cached values and the empty
+    // snapshot go with it, so a later save of this instance reads the row itself.
+    if (txn && sortableFieldConfigs.length) {
+        if (rowFoundBeforeWrite)
+            await performSortablePositionWork(dream, txn, sortableFieldConfigs, { alreadyPersisted });
         else
-            await runHooksFor('afterCreate', dream, alreadyPersisted, beforeSaveChanges, txn);
-        await runHooksFor(alreadyPersisted ? 'afterUpdateCommit' : 'afterCreateCommit', dream, alreadyPersisted, beforeSaveChanges, txn);
-        await runHooksFor('afterSaveCommit', dream, alreadyPersisted, beforeSaveChanges, txn);
+            clearSortableSaveState(dream, sortableFieldConfigs);
     }
     return dream;
 }
+async function runAfterSaveHooks(dream, txn, { skipHooks, alreadyPersisted, beforeSaveChanges, }) {
+    if (skipHooks)
+        return;
+    await runHooksFor('afterSave', dream, alreadyPersisted, beforeSaveChanges, txn);
+    if (alreadyPersisted)
+        await runHooksFor('afterUpdate', dream, alreadyPersisted, beforeSaveChanges, txn);
+    else
+        await runHooksFor('afterCreate', dream, alreadyPersisted, beforeSaveChanges, txn);
+    await runHooksFor(alreadyPersisted ? 'afterUpdateCommit' : 'afterCreateCommit', dream, alreadyPersisted, beforeSaveChanges, txn);
+    await runHooksFor('afterSaveCommit', dream, alreadyPersisted, beforeSaveChanges, txn);
+}

package/dist/esm/src/dream/internal/similarity/SimilarityBuilder.js

@@ -8,7 +8,8 @@ import namespaceColumn from '../../../helpers/namespaceColumn.js';
 import { TRIGRAM_OPERATORS } from '../../constants.js';
 import similaritySelectSql from './similaritySelectSql.js';
 import similarityWhereSql from './similarityWhereSql.js';
-import { getPostgresQueryDriver } from '../../../decorators/field/sortable/helpers/setPosition.js';
+import DreamApp from '../../../dream-app/index.js';
+import PostgresQueryDriver from '../../QueryDriver/Postgres.js';
 export default class SimilarityBuilder extends ConnectedToDB {
     whereStatement;
     whereNotStatement;
@@ -215,7 +216,7 @@ export default class SimilarityBuilder extends ConnectedToDB {
         const schema = this.dreamClass.prototype.schema;
         const primaryKeyName = this.dreamClass.primaryKey;
         const { tableName, tableAlias, columnName } = similarityStatement;
-        const queryDriverClass = getPostgresQueryDriver(this.dreamInstance.connectionName);
+        const queryDriverClass = postgresQueryDriverForSimilaritySearch(this.dreamInstance.connectionName);
         // eslint-disable-next-line @typescript-eslint/unbound-method
         const { ref } = queryDriverClass.dbFor(this.dreamInstance.connectionName, this.dbConnectionType('select')).dynamic;
         const validatedTableAlias = validateTableAlias(tableAlias);
@@ -247,7 +248,7 @@ export default class SimilarityBuilder extends ConnectedToDB {
             statementType,
         });
         const trigramSearchAlias = this.similaritySearchId(tableAlias, columnName);
-        const queryDriverClass = getPostgresQueryDriver(this.dreamInstance.connectionName);
+        const queryDriverClass = postgresQueryDriverForSimilaritySearch(this.dreamInstance.connectionName);
         const selectQuery = queryDriverClass
             .dbFor(this.dreamInstance.connectionName, this.dbConnectionType('select'))
             .selectFrom(validatedTableAlias)
@@ -261,7 +262,7 @@ export default class SimilarityBuilder extends ConnectedToDB {
         const { columnName, opsStatement, tableName } = similarityStatement;
         const validatedTable = validateTable(schema, tableName);
         const validatedPrimaryKey = validateColumn(schema, tableName, primaryKeyName);
-        const queryDriverClass = getPostgresQueryDriver(this.dreamInstance.connectionName);
+        const queryDriverClass = postgresQueryDriverForSimilaritySearch(this.dreamInstance.connectionName);
         let nestedQuery = queryDriverClass
             .dbFor(this.dreamInstance.connectionName, this.dbConnectionType('select'))
             .selectFrom(tableName)
@@ -314,6 +315,20 @@ export default class SimilarityBuilder extends ConnectedToDB {
         return `${statementType}_rank_${statementIndex + 1}`;
     }
 }
+/**
+ * Trigram similarity search is built on Postgres's `pg_trgm` operators and on
+ * kysely builders taken straight off the Postgres driver, so it resolves the
+ * connection's query driver to that driver — accepting a consumer subclass of
+ * it, which inherits the same operators — and otherwise fails loud rather than
+ * emitting SQL another engine cannot run.
+ */
+function postgresQueryDriverForSimilaritySearch(connectionName) {
+    const queryDriverClass = DreamApp.getOrFail().dbConnectionQueryDriverClass(connectionName);
+    if (queryDriverClass !== PostgresQueryDriver &&
+        !(queryDriverClass.prototype instanceof PostgresQueryDriver))
+        throw new Error(`${queryDriverClass.name} is not the PostgresQueryDriver, nor a subclass of it. Similarity search (similarity, wordSimilarity, strictWordSimilarity) requires the PostgresQueryDriver.`);
+    return queryDriverClass;
+}
 export const SIMILARITY_TYPES = ['where', 'join_and'];
 function removeJoinAndFromObjectHierarchy(obj) {
     if (obj?.isOpsStatement)

package/dist/esm/src/dream/internal/softDeleteDream.js

@@ -1,19 +1,31 @@
 import MissingDeletedAtFieldForSoftDelete from '../../errors/MissingDeletedAtFieldForSoftDelete.js';
 import isDatetimeOrDatetimeArrayColumn from '../../helpers/db/types/isDatetimeOrDatetimeArrayColumn.js';
 import { DateTime } from '../../utils/datetime/DateTime.js';
+/**
+ * @internal
+ *
+ * @returns the number of rows soft deleted — zero when the row is already gone,
+ *   and zero when it is already soft deleted
+ */
 export default async function softDeleteDream(dream, txn) {
     const deletedAtField = dream['_deletedAtField'];
     const dreamClass = dream.constructor;
     if (!isDatetimeOrDatetimeArrayColumn(dreamClass, deletedAtField)) {
         throw new MissingDeletedAtFieldForSoftDelete(dream.constructor);
     }
+    // An already soft deleted row is logically gone, and this UPDATE is what
+    // reports the deletion to the caller: matching such a row again would rewrite
+    // its `deletedAt` and count a deletion this destroy did not perform, running
+    // the after-destroy hooks a second time on a record nothing happened to.
     let query = txn.kyselyTransaction
         .updateTable(dream.table)
         .where(dream['_primaryKey'], '=', dream.primaryKeyValue())
+        .where(deletedAtField, 'is', null)
         .set(dream['_deletedAtField'], DateTime.now());
     dreamClass['sortableFields']?.forEach(sortableFieldMetadata => {
         const positionColumn = sortableFieldMetadata.positionField;
         query = query.set(positionColumn, null);
     });
-    await query.execute();
+    const results = await query.execute();
+    return Number(results[0]?.numUpdatedRows ?? 0);
 }

package/dist/esm/src/dream/internal/undestroyDream.js

@@ -1,4 +1,6 @@
-import { applySortableScopesToQuery } from '../../decorators/field/sortable/helpers/setPosition.js';
+import acquireStabilizedSortableScopeLocks from '../../decorators/field/sortable/helpers/acquireStabilizedSortableScopeLocks.js';
+import filterQueryToScopeValues from '../../decorators/field/sortable/helpers/filterQueryToScopeValues.js';
+import { snapshotScopeValue } from '../../decorators/field/sortable/helpers/sortableSnapshot.js';
 import runHooksFor from './runHooksFor.js';
 /**
  * @internal
@@ -31,11 +33,23 @@ async function undestroyDreamWithTransaction(dream, txn, options) {
     if (!skipHooks) {
         await runHooksFor('beforeUpdate', dream, true, null, txn);
     }
-    await doUndestroyDream(dream, txn);
+    // The cascade runs ahead of the restore, matching `destroyDream`: this
+    // record's own scope lock is taken inside `doUndestroyDream`, so a cascade
+    // seated after it would hold that lock across every descendant's undestroy,
+    // and a parent and its children would take their advisory keys in the
+    // opposite order to the one the destroy side takes them in. The nested select
+    // the cascade builds bypasses the soft-delete scope on this record's own
+    // class (`undestroyOptions`), so it reaches the children while this record is
+    // still deleted.
     if (cascade) {
         await undestroyAssociatedRecords(dream, txn, options);
     }
-    if (!skipHooks) {
+    const restoredRowCount = await doUndestroyDream(dream, txn);
+    // A restore of a row that is not deleted — a second `undestroy()`, a job
+    // retry, or a record that was never destroyed, which `Query#undestroy` reaches
+    // routinely since it lifts the soft-delete scope and walks every match —
+    // matches no row, so there is nothing for the after-update hooks to react to.
+    if (!skipHooks && restoredRowCount > 0) {
         await runHooksFor('afterUpdate', dream, true, null, txn);
         await runHooksFor('afterUpdateCommit', dream, true, null, txn);
     }
@@ -45,22 +59,56 @@ async function undestroyDreamWithTransaction(dream, txn, options) {
 /**
  * @internal
  *
- * Destroys the dream iff it was not blocked from
- * deleting by one of the beforeDestroy model hooks
+ * Clears the record's `deletedAt` and, for a sortable model, gives it a
+ * position at the end of the sort scope its row physically occupies.
+ *
+ * Restoring is conditional on the row still being deleted, and the count of
+ * rows the statement matched is what the caller reads that off. A row that is
+ * already back would otherwise be inside the `max(position)` its new position
+ * is computed from, and would move one past itself on every repeat — a
+ * permanent gap in the scope.
+ *
+ * @returns the number of rows restored: 1, or 0 when the row was not deleted
  */
 async function doUndestroyDream(dream, txn) {
     const updateStatement = txn.kyselyTransaction.updateTable(dream.table);
     let query = updateStatement
         .where(dream['_primaryKey'], '=', dream.primaryKeyValue())
+        .where(dream['_deletedAtField'], 'is not', null)
         .set({ [dream['_deletedAtField']]: null });
     const dreamClass = dream.constructor;
-    dreamClass['sortableFields']?.forEach(sortableFieldMetadata => {
+    const sortableFields = (dreamClass['sortableFields'] ?? []);
+    // Undestroy has no sortable hook of its own — the position is recomputed
+    // inline, below, before `afterUpdate` ever runs — so the scope lock is taken
+    // here, around that recomputation. Without it the `max(position) + 1`
+    // subquery races every other writer of the scope the record is being restored
+    // into.
+    //
+    // The scope this record is being restored into is the one its row physically
+    // carries, not the one the instance was loaded with: another writer may have
+    // moved it between scopes while it was soft deleted, which is what the
+    // stabilized acquisition converges on.
+    const { snapshots } = await acquireStabilizedSortableScopeLocks(dream, txn, sortableFields);
+    sortableFields.forEach(sortableFieldMetadata => {
         const positionColumn = sortableFieldMetadata.positionField;
+        const snapshot = snapshots.get(positionColumn);
         query = query.set(eb => ({
-            [positionColumn]: eb(applySortableScopesToQuery(dream, txn.kyselyTransaction.selectFrom(dream.table), column => dream[column], sortableFieldMetadata.scope).select(eb => eb.fn.max(positionColumn).as(positionColumn + '_max')), '+', 1),
+            [positionColumn]: eb(filterQueryToScopeValues(dream, txn.kyselyTransaction.selectFrom(dream.table), column => snapshotScopeValue(snapshot, column, () => dream[column]), sortableFieldMetadata.scope).select(eb => 
+            // `max` over a scope with no positioned rows left — an empty
+            // scope, or one whose every remaining row is soft deleted and so
+            // carries a NULL position — is NULL, and NULL + 1 is NULL, which
+            // would restore the record with no position at all. Coalescing
+            // before the increment restores it at position 1.
+            eb.fn.coalesce(eb.fn.max(positionColumn), eb.lit(0)).as(positionColumn + '_max')), '+', 1),
         }));
     });
-    return await query.execute();
+    const [result] = await query.execute();
+    // No sortable row cache invalidation here: the restored record took a position
+    // at the end of the scope it was restored into and nothing else moved, so no
+    // other record's cached preflight row went stale, and this record's own cached
+    // row was consumed — destructively — by the snapshot read every sortable field
+    // above goes through.
+    return Number(result?.numUpdatedRows ?? 0);
 }
 /**
  * @internal

package/dist/esm/src/dream-app/index.js

@@ -212,6 +212,24 @@ export default class DreamApp {
     get paginationMaxPageSize() {
         return this._paginationMaxPageSize;
     }
+    /**
+     * How long, in milliseconds, a position-mutating operation on a
+     * `@deco.Sortable` model will wait for another transaction to release the
+     * sort scope it needs before giving up with
+     * `SortableScopeLockWaitTimedOut`. Applied to the lock acquisition statement
+     * alone — the transaction's other lock waits keep whatever `lock_timeout`
+     * the application has configured.
+     *
+     * `0` waits without bound, which is what Postgres's `lock_timeout` means by
+     * it, and holds even on a connection configured with a `lock_timeout` of its
+     * own: the acquisition disables the bound for the duration of the statement.
+     *
+     * Set it with `dreamApp.set('sortableScopeLockTimeout', milliseconds)`.
+     */
+    _sortableScopeLockTimeout = 5000;
+    get sortableScopeLockTimeout() {
+        return this._sortableScopeLockTimeout;
+    }
     _primaryKeyType = 'bigint';
     get primaryKeyType() {
         return this._primaryKeyType;
@@ -492,6 +510,9 @@ export default class DreamApp {
             case 'paginationMaxPageSize':
                 this._paginationMaxPageSize = options;
                 break;
+            case 'sortableScopeLockTimeout':
+                this._sortableScopeLockTimeout = options;
+                break;
             default: {
                 // protection so that if a new ApplyOpt is ever added, this will throw a type error at build time
                 const _never = applyOption;

package/dist/esm/src/errors/SortableBatchRequiresTooManyScopeLocks.js

@@ -0,0 +1,57 @@
+/**
+ * Raised when a batch of a locked `Query#destroy` or `Query#update` on a
+ * sortable model would carry its transaction past the number of advisory
+ * sort-scope locks Dream is willing to hold at once.
+ *
+ * The batched, row-locking query APIs take every advisory scope key the batch
+ * needs before they claim a single row — one key per sort scope the batch's
+ * candidate records occupy, per sortable field the model declares. Advisory
+ * locks live in Postgres's cluster-wide shared lock table, whose size is fixed
+ * at startup (`max_locks_per_transaction` × `max_connections`), and they are
+ * held until the transaction ends. A batch over a table whose sort scope has
+ * very high cardinality can therefore consume a meaningful fraction of a
+ * resource every other connection in the cluster shares, and exhausting it
+ * fails unrelated transactions rather than only this one.
+ *
+ * So the preflight counts first and refuses, before claiming any row. The count
+ * is the whole transaction's: the keys it already holds plus the keys the
+ * refused batch would add, since advisory locks are released only when the
+ * transaction ends. Inside a transaction Dream opens for the batch that is the
+ * batch's own key set and nothing has been locked when this is raised; inside a
+ * transaction you own, it also counts every key the run's earlier batches took,
+ * and those stay held.
+ *
+ * The fix is almost always a smaller `batchSize`: the keys one batch needs are
+ * bounded by how many distinct sort scopes its records span, so halving the
+ * batch size halves the worst case. If the run itself is what accumulates them
+ * — a long multi-batch run inside a transaction you opened — either let Dream
+ * open a transaction per batch (do not pass a transaction of your own) or
+ * commit between runs, which is what releases the locks as it goes.
+ */
+export default class SortableBatchRequiresTooManyScopeLocks extends Error {
+    dreamClassName;
+    keyCount;
+    maxKeyCount;
+    constructor(dreamClassName, keyCount, maxKeyCount) {
+        super();
+        this.dreamClassName = dreamClassName;
+        this.keyCount = keyCount;
+        this.maxKeyCount = maxKeyCount;
+    }
+    get message() {
+        return `\
+A locked batch over ${this.dreamClassName} would leave its transaction holding ${this.keyCount} sort scope locks, and the limit is ${this.maxKeyCount}.
+
+Sortable takes one advisory lock per sort scope a batch touches, per sortable field, before the
+batch claims any row, and holds them until the transaction ends. Advisory locks come out of a
+lock table the whole Postgres cluster shares, so a batch that would carry its transaction past
+this limit is refused rather than risking every other connection's transactions.
+
+Use a smaller batchSize. The keys one batch needs are bounded by the number of distinct sort
+scopes its records span, so a smaller batch takes proportionally fewer. If this operation runs
+inside a transaction you opened, note that the locks of earlier batches are still held while
+later batches preflight, and are counted here; letting Dream open a transaction per batch
+releases them as it goes.
+`;
+    }
+}

package/dist/esm/src/errors/SortableRequiresAdvisoryTransactionLocks.js

@@ -0,0 +1,26 @@
+/**
+ * Raised when a model declaring sortable fields is used on a query driver that
+ * cannot take transaction-scoped advisory locks.
+ *
+ * Sortable computes position values under a lock on the sort scope, without
+ * which concurrent writers collide on the same position. A driver that cannot
+ * provide that lock fails loudly here rather than racing silently.
+ */
+export default class SortableRequiresAdvisoryTransactionLocks extends Error {
+    queryDriverClassName;
+    constructor(queryDriverClassName) {
+        super();
+        this.queryDriverClassName = queryDriverClassName;
+    }
+    get message() {
+        return `\
+${this.queryDriverClassName} cannot be used with the Sortable decorator.
+
+Sortable computes position values under a transaction-scoped advisory lock on the sort
+scope, without which concurrent writers collide on the same position. Implement
+\`acquireAdvisoryTransactionLocks\` on ${this.queryDriverClassName} and set
+\`supportsAdvisoryTransactionLocks = true\`, or use the PostgresQueryDriver for models
+that declare sortable fields.
+`;
+    }
+}