@rvoh/dream 2.30.1 → 2.32.0

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

@@ -1,15 +1,21 @@
+import { SOFT_DELETE_SCOPE_NAME } from '../../decorators/class/SoftDelete.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 { consumeSortableCascadeEdge, markSortableCascadeEdge, } from '../../decorators/field/sortable/helpers/sortableCascadeEdge.js';
+import { readSortableSnapshots, snapshotScopeValue, } from '../../decorators/field/sortable/helpers/sortableSnapshot.js';
+import associationUpdateQuery from './associations/associationUpdateQuery.js';
 import runHooksFor from './runHooksFor.js';
+import withConcurrentWriterRetry from './withConcurrentWriterRetry.js';
 /**
  * @internal
  *
- * Destroys the Dream and any `dependent: 'destroy'` associations
+ * Undestroys the Dream and any `dependent: 'destroy'` associations
  * within a transaction. If a transaction is passed, it will be used.
- * Otherwise, a new transaction will be created automatically.
- * If any of the nested associations fails to destroy, then this
- * record will also fail to destroy. If skipHooks is true, model hooks
+ * Otherwise, a new transaction will be created automatically, and the
+ * whole undestroy is run again if that transaction is undone by a
+ * concurrent writer (see `withConcurrentWriterRetry`).
+ * If any of the nested associations fails to undestroy, then this
+ * record will also fail to undestroy. If skipHooks is true, model hooks
  * will be bypassed.
  */
 export default async function undestroyDream(dream, txn = null, options) {
@@ -18,33 +24,35 @@ export default async function undestroyDream(dream, txn = null, options) {
     }
     else {
         const dreamClass = dream.constructor;
-        return await dreamClass.transaction(async (txn) => await undestroyDreamWithTransaction(dream, txn, options));
+        return await withConcurrentWriterRetry(dreamClass, async (txn) => await undestroyDreamWithTransaction(dream, txn, options));
     }
 }
 /**
  * @internal
  *
- * Given a transaction, applies the destroy query,
+ * Given a transaction, applies the undestroy query,
  * including cascading to child associations and
  * model hooks.
  */
 async function undestroyDreamWithTransaction(dream, txn, options) {
     const { cascade, skipHooks } = options;
+    // Whether a `dependent: 'destroy'` cascade reached this record, which decides
+    // whether its restore takes the scope lock. Consumed first, before a hook or
+    // the cascade below can re-enter this function for the same instance.
+    const cascaded = consumeSortableCascadeEdge(dream) !== null;
     if (!skipHooks) {
         await runHooksFor('beforeUpdate', dream, true, null, 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.
+    // The cascade runs ahead of the restore, matching `destroyDream`: a direct
+    // undestroy takes this record's own scope lock inside `doUndestroyDream`, so
+    // a cascade seated after it would hold that lock across every descendant's
+    // undestroy. 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);
     }
-    const restoredRowCount = await doUndestroyDream(dream, txn);
+    const restoredRowCount = await doUndestroyDream(dream, txn, { lock: !cascaded });
     // 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 —
@@ -68,9 +76,16 @@ async function undestroyDreamWithTransaction(dream, txn, options) {
  * is computed from, and would move one past itself on every repeat — a
  * permanent gap in the scope.
  *
+ * @param lock - whether to take each sortable field's scope lock around the
+ *   position computation. A direct undestroy does; a cascaded one does not,
+ *   since a cascade would otherwise hold one lock per distinct sort scope it
+ *   restores into until the root transaction commits. Without the lock the
+ *   `max(position) + 1` below can race a concurrent writer of the scope onto the
+ *   same position, which the scope's deferrable unique constraint refuses at
+ *   COMMIT; see `withConcurrentWriterRetry`.
  * @returns the number of rows restored: 1, or 0 when the row was not deleted
  */
-async function doUndestroyDream(dream, txn) {
+async function doUndestroyDream(dream, txn, { lock }) {
     const updateStatement = txn.kyselyTransaction.updateTable(dream.table);
     let query = updateStatement
         .where(dream['_primaryKey'], '=', dream.primaryKeyValue())
@@ -79,16 +94,16 @@ async function doUndestroyDream(dream, txn) {
     const dreamClass = dream.constructor;
     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.
+    // inline, below, before `afterUpdate` ever runs — so a direct undestroy takes
+    // the scope lock here, around that recomputation.
     //
     // 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);
+    // moved it between scopes while it was soft deleted. The stabilized
+    // acquisition converges on that scope; the unlocked read simply reads it.
+    const { snapshots } = lock
+        ? await acquireStabilizedSortableScopeLocks(dream, txn, sortableFields)
+        : await readSortableSnapshots(dream, txn, sortableFields);
     sortableFields.forEach(sortableFieldMetadata => {
         const positionColumn = sortableFieldMetadata.positionField;
         const snapshot = snapshots.get(positionColumn);
@@ -113,22 +128,30 @@ async function doUndestroyDream(dream, txn) {
 /**
  * @internal
  *
- * Destroys all HasOne/HasMany associations on this
- * dream that are marked as `dependent: 'destroy'`
+ * Undestroys all HasOne/HasMany associations on this dream that are marked as
+ * `dependent: 'destroy'`: the walk `Query#undestroy` makes, with each record
+ * marked as reached by this cascade before its own undestroy runs, so that its
+ * restore takes no scope lock.
  */
 async function undestroyAssociatedRecords(dream, txn, options) {
     const dreamClass = dream.constructor;
     for (const associationName of dreamClass['dependentDestroyAssociationNames']()) {
-        const associationMetadata = dreamClass['associationMetadataMap']()[associationName];
-        const associatedClass = associationMetadata?.modelCB?.();
+        const association = dreamClass['associationMetadataMap']()[associationName];
+        const associatedClass = association?.modelCB?.();
         if (Array.isArray(associatedClass)) {
             // TODO: decide how to handle polymorphic associations with dependent: destroy
             // raise?
         }
-        else {
-            if (associatedClass?.['softDelete']) {
-                await dream.txn(txn).undestroyAssociation(associationName, options);
-            }
+        else if (association && associatedClass?.['softDelete']) {
+            const query = associationUpdateQuery(dream, txn, associationName, {
+                joinAndStatements: {},
+                bypassAllDefaultScopes: options.bypassAllDefaultScopes ?? false,
+                defaultScopesToBypass: (options.defaultScopesToBypass ?? []),
+            });
+            await query.removeDefaultScope(SOFT_DELETE_SCOPE_NAME).findEach(async (record) => {
+                markSortableCascadeEdge(record, association);
+                await record.txn(txn).undestroy(options);
+            });
         }
     }
 }

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

@@ -0,0 +1,64 @@
+import DreamApp from '../../dream-app/index.js';
+/**
+ * How many times a destroy or undestroy that opened its own transaction runs
+ * before a failure caused by a concurrent writer escapes. One such failure
+ * needs another writer of the same rows or sort scope during the operation;
+ * three in a row is contention past the point of retrying.
+ */
+export const MAX_CONCURRENT_WRITER_ATTEMPTS = 3;
+/**
+ * @internal
+ *
+ * Runs `callback` in a transaction of the model's own, and runs it again when
+ * that transaction is undone by a concurrent writer: a deadlock, or a unique
+ * constraint refusing the COMMIT.
+ *
+ * A cascaded destroy or undestroy does its sortable position work without the
+ * scope lock a direct one takes (see `@deco.Sortable`), so a concurrent writer
+ * of the same sort scope can leave two live rows sharing a position, which the
+ * scope's deferrable unique constraint refuses at COMMIT — or, when both
+ * writers reach COMMIT together, as a deadlock between their two checks. A
+ * cascade holding row locks can deadlock against another writer of the same
+ * rows mid-statement as well. Either way the database has undone the whole
+ * transaction, nothing has committed and no commit hook has run, so running
+ * the operation again reads the rows as the other writer left them. The last
+ * attempt's error is the adapter's own.
+ *
+ * A unique violation raised by a statement inside the callback is not a
+ * collision but a write that violates a constraint outright, and is not
+ * retried; only a refusal of the COMMIT itself is, which is why the callback
+ * having resolved is part of the test.
+ *
+ * Only a transaction Dream opens is retried. Inside a caller's transaction the
+ * failure is the caller's, and the caller retries the whole transaction.
+ *
+ * Saves are deliberately not run through this. When a direct save and a
+ * cascade collide, the loser is whichever transaction waits first at COMMIT,
+ * and that is usually the save, which is short and reaches COMMIT while the
+ * cascade is still working: it fails with the adapter's deadlock error after
+ * `deadlock_timeout`. That bounded, occasional failure is the accepted price of
+ * cascades holding no scope locks, and the save path's state restore
+ * (`saveDream`) already makes calling `save` again correct. The collision needs
+ * a position write into the same sort scope inside the cascade's window that
+ * picks the same position, which a cascade destroying a scope's owner never
+ * exposes since it writes no position at all.
+ */
+export default async function withConcurrentWriterRetry(dreamClass, callback) {
+    const queryDriverClass = DreamApp.getOrFail().dbConnectionQueryDriverClass(dreamClass.prototype.connectionName);
+    for (let attempt = 1;; attempt++) {
+        let callbackResolved = false;
+        try {
+            return await dreamClass.transaction(async (txn) => {
+                const result = await callback(txn);
+                callbackResolved = true;
+                return result;
+            });
+        }
+        catch (error) {
+            const undoneByConcurrentWriter = queryDriverClass.isDeadlock(error) ||
+                (callbackResolved && queryDriverClass.isUniqueConstraintViolation(error));
+            if (!undoneByConcurrentWriter || attempt === MAX_CONCURRENT_WRITER_ATTEMPTS)
+                throw error;
+        }
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Raised when saving a persisted instance whose database row no longer exists —
+ * the row was deleted between the moment the instance was loaded and the moment
+ * the save reached the database.
+ *
+ * This is the write-side counterpart of `RecordNotFound`, and applications catch
+ * it for the same reasons: a request updating a record another request has since
+ * deleted should answer 404 or 409 rather than 500, and a background job holding
+ * a stale instance should usually drop the work rather than fail loudly. Nothing
+ * is written when it is raised.
+ *
+ * It does not mean the save was rejected — a save that fails validation raises
+ * `ValidationError`, and a constraint violation raises its own error. It means
+ * the row that the instance stands for is gone.
+ *
+ * Dream raises it from the query driver, so a custom driver overriding
+ * `saveDream` translates its own adapter's empty-result error the same way, as
+ * the test-app MySQL driver does.
+ */
+export default class CannotSaveMissingDream extends Error {
+    constructor(dream) {
+        super(`Cannot save ${dream.sanitizedConstructorName} with primary key ${String(dream.primaryKeyValue())} because its persisted database row no longer exists.`);
+    }
+}

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

@@ -1,4 +1,6 @@
 /**
+ * @internal
+ *
  * 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.
@@ -27,6 +29,11 @@
  * — 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.
+ *
+ * Not exported from `@rvoh/dream/errors`. Exceeding the bound is a sizing
+ * mistake in the calling code, not a runtime condition an application can
+ * recover from, so there is nothing for a consumer to catch: the fix is a
+ * smaller batch or a narrower transaction, never a retry.
  */
 export default class SortableBatchRequiresTooManyScopeLocks extends Error {
     dreamClassName;

package/dist/esm/src/errors/associations/MissingRequiredBelongsToAssociation.js

@@ -48,10 +48,15 @@ export default class MissingRequiredBelongsToAssociation extends Error {
 Attempting to access required BelongsTo association \`${this.associationName}\` on an instance of \`${this.dreamClass.sanitizedName}\`,
 but the loaded association is null.
 
-${this.foreignKeyMessage}
-
-If the associated record was deleted, check whether the inverse HasOne/HasMany association should specify dependent: 'destroy'.
+${this.foreignKeyMessage}${this.populatedForeignKeyDiagnosticMessage}
 `;
+    }
+    get populatedForeignKeyDiagnosticMessage() {
+        if (this.foreignKeyValue === null || this.foreignKeyValue === undefined)
+            return '';
+        return `
+
+The associated record may have been deleted (including soft-deleted), or it may not match this association’s target—for example, its STI type may differ from the targeted STI child. If the record was deleted unexpectedly, check whether the inverse HasOne/HasMany association should specify \`dependent: 'destroy'\`.`;
     }
     get foreignKeyMessage() {
         if (this.foreignKeyValue === null || this.foreignKeyValue === undefined) {

package/dist/esm/src/package-exports/errors.js

@@ -1,18 +1,27 @@
 export { pgErrorType } from '../db/errors.js';
 export { default as NonLoadedAssociation } from '../errors/associations/NonLoadedAssociation.js';
+export { default as CannotSaveMissingDream } from '../errors/CannotSaveMissingDream.js';
 export { default as CreateOrFindByFailedToCreateAndFind } from '../errors/CreateOrFindByFailedToCreateAndFind.js';
 export { default as CheckConstraintViolation } from '../errors/db/CheckConstraintViolation.js';
 export { default as ColumnOverflow } from '../errors/db/ColumnOverflow.js';
 export { default as DataIncompatibleWithDatabaseField } from '../errors/db/DataIncompatibleWithDatabaseField.js';
 export { default as DataTypeColumnTypeMismatch } from '../errors/db/DataTypeColumnTypeMismatch.js';
 export { default as NotNullViolation } from '../errors/db/NotNullViolation.js';
+// Raised by the framework packages layered on Dream, not only by Dream: psychic
+// (`src/controller/index.ts`) raises it for a controller's global name, and
+// psychic-workers (`src/background/BaseBackgroundedService.ts`,
+// `src/background/BaseScheduledService.ts`) for service global names. Both reach it
+// through this entry point, so unexporting it breaks the build of every application
+// that installs either package.
 export { default as GlobalNameNotSet } from '../errors/dream-app/GlobalNameNotSet.js';
 export { default as DecryptionError } from '../errors/encrypt/DecryptionError.js';
 export { default as DecryptionParseError } from '../errors/encrypt/DecryptionParseError.js';
 export { default as DecryptionRotationError } from '../errors/encrypt/DecryptionRotationError.js';
 export { default as RecordNotFound } from '../errors/RecordNotFound.js';
+// Caught through this entry point by psychic
+// (`test-app/src/app/controllers/SerializerTestsController.ts`), which distinguishes it
+// to prove a controller can render a missing-serializers failure as a response.
 export { default as MissingSerializersDefinition } from '../errors/serializers/MissingSerializersDefinition.js';
-export { default as SortableBatchRequiresTooManyScopeLocks } from '../errors/SortableBatchRequiresTooManyScopeLocks.js';
 export { default as SortableScopeDidNotStabilize } from '../errors/SortableScopeDidNotStabilize.js';
 export { default as SortableScopeLockWaitTimedOut } from '../errors/SortableScopeLockWaitTimedOut.js';
 export { default as ValidationError } from '../errors/ValidationError.js';

package/dist/types/src/Dream.d.ts

@@ -1488,16 +1488,20 @@ 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.
+     * Each sort scope is renumbered in its own transaction, under the advisory
+     * lock every direct position-mutating path takes on that scope, from a read
+     * of the scope taken inside that lock — so a concurrent create or direct
+     * destroy cannot make the renumbering land on positions it never read. A
+     * cascaded destroy or undestroy takes no scope lock (see `@deco.Sortable`),
+     * so one running at the same moment can still change a scope under `resort`;
+     * a later `resort` repairs whatever that leaves.
      *
      * **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 —
+     * direct position-mutating write to that scope earlier in the transaction
+     * takes it; a cascaded destroy or undestroy takes none —
      * `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`.

package/dist/types/src/db/errors.d.ts

@@ -1,4 +1,5 @@
 export declare const CHECK_VIOLATION = "CHECK_VIOLATION";
+export declare const DEADLOCK_DETECTED = "DEADLOCK_DETECTED";
 export declare const FOREIGN_KEY_VIOLATION = "FOREIGN_KEY_VIOLATION";
 export declare const INTEGRITY_CONSTRAINT_VIOLATION = "INTEGRITY_CONSTRAINT_VIOLATION";
 export declare const INVALID_INPUT_SYNTAX = "INVALID_INPUT_SYNTAX";
@@ -19,6 +20,7 @@ export declare const PG_ERRORS: {
     readonly '23001': "RESTRICT_VIOLATION";
     readonly '23503': "FOREIGN_KEY_VIOLATION";
     readonly '55P03': "LOCK_NOT_AVAILABLE";
+    readonly '40P01': "DEADLOCK_DETECTED";
 };
 type PgErrorType = (typeof PG_ERRORS)[keyof typeof PG_ERRORS];
 export declare function pgErrorType(error: any): PgErrorType | null;

package/dist/types/src/decorators/Decorators.d.ts

@@ -63,18 +63,133 @@ export default class Decorators<TD extends typeof Dream, T extends Dream = Insta
         default?: boolean;
     }): any;
     /**
-     * The Sortable decorator automatically adjusts the value of the columns
-     * corresponding to the decorated field.
-     *
-     * NOTE: the Sortable decorator may not be used in STI child models (it may be used in the STI base class)
+     * 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. A concurrent write racing a
+     * cascaded destroy or undestroy, under **Cascaded destroy and undestroy**
+     * below, is the one thing that can leave a scope with a gap;
+     * `Model.resort('position')` closes it.
      *
      * ```ts
-     * class Balloon {
+     * class Post extends ApplicationModel {
      *   @deco.Sortable({ scope: 'user' })
-     *   public position: DreamColumn<Balloon, 'position'>
+     *   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 a position write serializes the
+     * writers of its sort scope on one, apart from the cascades described below.
+     * This concurrency guarantee first shipped
+     * in Dream 2.28.0 and begins only after every writer is running a lock-aware
+     * release. During the first rolling deployment, older processes take no
+     * advisory locks and can still race the upgraded processes.
+     *
+     * All participating Dream writers of one hot scope serialize. Ordinary saves
+     * and destroys with `skipHooks`, direct query writes, raw SQL, and older
+     * pre-lock Dream processes bypass Sortable maintenance and do not participate
+     * in its locking protocol; a cascaded destroy or undestroy performs its
+     * maintenance but does not participate either. A direct undestroy still
+     * performs stabilized Sortable maintenance and acquires scope locks with
+     * `skipHooks: true`; locked query
+     * batches likewise acquire their scope locks during preflight, before any
+     * per-record callbacks, even when those callbacks skip hooks. A waiter that
+     * enters the protocol holds a pooled connection until the holder finishes or
+     * `sortableScopeLockTimeout` expires; sustained contention can therefore
+     * produce latency waves, timeouts, and pool starvation. Keep database work
+     * inside the lock window short, and avoid cross-region database latency for
+     * hot scopes.
+     *
+     * **Cascaded destroy and undestroy take no scope lock.** A record destroyed or
+     * undestroyed because its owner was — reached through a `dependent: 'destroy'`
+     * association, or through the undestroy that restores one — does its position
+     * work without the advisory lock, so a cascade holds no lock per sort scope it
+     * touches, however many scopes that is. Calling `destroy()` or `undestroy()`
+     * on a record yourself is unchanged. Where the cascade is destroying the owner
+     * of a sort scope — a `HasMany` whose foreign key is one of the field's scope
+     * columns, with no condition and not `through`, not polymorphic, whose target
+     * is not an STI child and declares no default scope other than
+     * `@deco.SoftDelete` — every row of that scope goes with it, and the cascade
+     * neither reads nor compacts it. Any other cascaded destroy compacts the
+     * scope it vacates, and every cascaded undestroy appends at the end of its
+     * scope, exactly as the direct operations do, only without the lock.
+     *
+     * Without the lock, a writer of the same sort scope during the cascade — a
+     * create, a move, a destroy, a `resort` — is not kept out, which costs one of
+     * two things. A gap: positions stay unique and correctly ordered, and
+     * `Model.resort('position')` closes it. Or two live rows sharing a position,
+     * which the deferrable unique constraint refuses when the later of the two
+     * transactions reaches COMMIT — as a unique violation, or as a deadlock when
+     * both reach it together — so nothing half-done commits and no commit hook
+     * runs. A `destroy()` or `undestroy()` whose transaction Dream opened runs the
+     * whole operation again on such a refusal, up to three times, before letting
+     * the adapter's error escape. Inside a transaction you opened, that error is
+     * your COMMIT failing: retry the transaction from the beginning, as for a
+     * deadlock. The other writer can lose the same race and fail at its own
+     * COMMIT instead, an ordinary `create` or `update` included, and Dream does
+     * not run those again: a bounded, occasional failed request in one contended
+     * scope is the deliberate price of cascades that hold no locks, where the
+     * lock count would otherwise be set by the data. A sort scope with a
+     * nullable column has no such backstop unless its constraint is declared
+     * `NULLS NOT DISTINCT`, since a plain unique constraint never sees two NULLs
+     * as equal.
+     *
+     * `SortableScopeDidNotStabilize` and `SortableScopeLockWaitTimedOut` are the
+     * expected Dream errors an application may choose to retry. Database deadlocks
+     * remain native adapter errors (for example PostgreSQL code `40P01` or MySQL
+     * errno `1213`) so their driver fields and stacks remain intact. A database
+     * deadlock aborts the whole transaction: retry by starting the transaction
+     * again from the beginning, never by continuing it or retrying only the failed
+     * statement. Recurrent deadlocks call for shorter transactions or a consistent
+     * multi-resource acquisition order; they do not by themselves prove Sortable
+     * caused the cycle.
+     *
+     * ```ts
+     * import {
+     *   SortableScopeDidNotStabilize,
+     *   SortableScopeLockWaitTimedOut,
+     * } from '@rvoh/dream/errors'
+     *
+     * const runTransaction = async () =>
+     *   await ApplicationModel.transaction(async txn => {
+     *     // bind every operation in the attempt to txn
+     *   })
+     *
+     * try {
+     *   await runTransaction()
+     * } catch (error) {
+     *   const adapterDeadlock =
+     *     (error as { code?: string }).code === '40P01' ||
+     *     (error as { errno?: number }).errno === 1213
+     *   const retryable =
+     *     error instanceof SortableScopeDidNotStabilize ||
+     *     error instanceof SortableScopeLockWaitTimedOut ||
+     *     adapterDeadlock
+     *   if (!retryable) throw error
+     *
+     *   await runTransaction() // one whole-transaction retry
      * }
      * ```
      *
+     * NOTE: the Sortable decorator may not be used in STI child models (it may be used in the STI base class)
+     *
      * @param opts - Configuration options for the sortable decorator
      * @param opts.scope - The column, association, or combination thereof which you would like to restrict the incrementing logic to. Can be a single column name, a single belongs-to association name, or an array of column/association names
      * @returns A Sortable decorator

package/dist/types/src/decorators/field/sortable/Sortable.d.ts

@@ -1,35 +1,8 @@
 /**
- * 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.
+ * The implementation behind `@deco.Sortable`. The decorator's semantics —
+ * position clamping, what a scope-changing save does with a position given
+ * alongside it, and the advisory-lock concurrency protocol — are documented on
+ * `Decorators#Sortable`, which is where a consumer reads them.
  */
 export default function Sortable(opts?: SortableOpts): any;
 interface SortableOpts {

package/dist/types/src/decorators/field/sortable/helpers/cascadeReachesEveryRowInSortScope.d.ts

@@ -0,0 +1,39 @@
+import Dream from '../../../../Dream.js';
+import { SortableFieldConfig } from '../Sortable.js';
+import { SortableCascadeEdge } from './sortableCascadeEdge.js';
+/**
+ * @internal
+ *
+ * Whether a cascade reaching this record through `edge` reaches, and so
+ * destroys, every live row of the sortable field's sort scope. Such a scope is
+ * left with no survivor, so
+ * the compaction a destroy performs would close a vacancy nothing can observe,
+ * and the cascade skips it along with the snapshot read it needs. Every clause
+ * fails closed: a shape not positively recognized here compacts as a direct
+ * destroy does, unlocked, which costs statements and never a lock.
+ *
+ * The edge is the `dependent: 'destroy'` association the cascade destroyed
+ * through, the only kind the caller passes, and the answer is about that edge
+ * alone: another dependent edge of the same owner may reach the rows this one
+ * does not, and this fails closed rather than look for it.
+ *
+ * 1. The edge is a `HasMany`. A `HasOne` reaches one row of a scope that may
+ *    hold others.
+ * 2. The edge is not polymorphic, is not a `through` association, and carries
+ *    no `and`, `andNot`, `andAny`, `selfAnd` or `selfAndNot`. Each of those
+ *    reaches a subset of the rows sharing the foreign key, and the rest can
+ *    stay live: a soft-deleted owner's row remains, so no foreign key forces
+ *    them out, and they keep their positions in a scope the cascade did not
+ *    empty. (A hard destroy under a database foreign key would have refused to
+ *    leave them, and compacting there is the harmless direction to be wrong in.)
+ * 3. The target is not an STI child, whose rows share a sort scope with its
+ *    siblings' rows.
+ * 4. The target declares no default scope other than SoftDelete, since any
+ *    other hides rows from the cascade's own load. A soft-deleted row holds no
+ *    position and so is in no sort scope to begin with.
+ * 5. The edge's foreign key is one of the field's scope columns: every row the
+ *    cascade destroys carries the owner's key, and so does every row of any sort
+ *    scope that includes that column. Further scope members only partition that
+ *    same set.
+ */
+export default function cascadeReachesEveryRowInSortScope(dream: Dream, config: SortableFieldConfig, edge: SortableCascadeEdge): boolean;

package/dist/types/src/decorators/field/sortable/helpers/performSortableDestroyWork.d.ts

@@ -1,5 +1,6 @@
 import Dream from '../../../../Dream.js';
 import DreamTransaction from '../../../../dream/DreamTransaction.js';
+import { SortableFieldConfig } from '../Sortable.js';
 /**
  * @internal
  *
@@ -10,5 +11,9 @@ import DreamTransaction from '../../../../dream/DreamTransaction.js';
  * `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.
+ *
+ * @param sortableFields - the fields the preparation phase read a snapshot for,
+ *   which on a cascaded destroy excludes every field whose whole sort scope the
+ *   cascade is destroying
  */
-export default function performSortableDestroyWork(dream: Dream, txn: DreamTransaction<any>): Promise<void>;
+export default function performSortableDestroyWork(dream: Dream, txn: DreamTransaction<any>, sortableFields: SortableFieldConfig[]): Promise<void>;