@rvoh/dream 2.30.1 → 2.31.0

package/dist/cjs/src/decorators/Decorators.js

@@ -147,18 +147,93 @@ export default class Decorators {
         return Scope(opts);
     }
     /**
-     * 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.
      *
      * ```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 every position write serializes the
+     * writers of its sort scope on one. 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. 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.
+     *
+     * `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/cjs/src/decorators/field/sortable/Sortable.js

@@ -1,36 +1,9 @@
 import scopeArray from './helpers/scopeArray.js';
 /**
- * Marks an integer column as a sortable position: Dream keeps the positions of
- * every record in a sort scope contiguous, starting at 1, as records are
- * created, moved, destroyed and undestroyed.
- *
- * ```ts
- * class Post extends ApplicationModel {
- *   @deco.Sortable({ scope: 'user' })
- *   public position: number
- * }
- *
- * await post.update({ position: 2 }) // the records at 2 and above shift up
- * ```
- *
- * A position past the end of the scope is clamped to the end, and a position
- * below 1 — or none at all — lands the record at the end.
- *
- * **A save that changes the sort scope ignores a position given alongside it.**
- * The record lands at the end of the scope it moves into, whatever position the
- * same `update` supplied:
- *
- * ```ts
- * await post.update({ user: otherUser, position: 1 })
- * // post is now the last record in otherUser's scope, not the first
- * ```
- *
- * Move it in two saves to place it: `await post.update({ user: otherUser })`,
- * then `await post.update({ position: 1 })`.
- *
- * Sortable requires a query driver that supports advisory transaction locks —
- * the `PostgresQueryDriver` does — since every position write serializes the
- * writers of its sort scope on one.
+ * 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 = {}) {
     return function (_, context) {

package/dist/cjs/src/dream/Query.js

@@ -1914,13 +1914,15 @@ export default class Query {
      *   {@link Query.delete | delete} (a single statement, no hooks or cascade)
      *   are the right tools for bulk removal.
      *
+     * To bypass a default scope, chain `removeDefaultScope` onto the Query
+     * before calling this method; it is Query state, not an option, and it
+     * carries through to the cascade.
+     *
      * @param options - Options for destroying the instance
      * @param options.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
      * @param options.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
      * @param options.lock - If true, each batch is re-selected with an exclusive row lock inside its own transaction before being destroyed, making the destroy a compare-and-set. Defaults to false
      * @param options.batchSize - The number of records to process per batch. Must be a positive integer. Defaults to 10 when `lock` is true, and to 1000 otherwise
-     * @param options.bypassAllDefaultScopes - If true, bypasses user-removable default scopes when cascade destroying; an STI child's reserved discriminator remains enforced, including when associations are loaded. Defaults to false
-     * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
      * @returns The number of records that were removed
      * @throws InvalidBatchSize if `batchSize` is not a positive integer
      * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
@@ -2034,11 +2036,12 @@ export default class Query {
      *   transaction ends, so every batch's scope keys are still held when the
      *   next one preflights. That accumulation is bounded — the preflight counts
      *   the keys the transaction already holds along with the ones the batch
-     *   would add, and refuses with `SortableBatchRequiresTooManyScopeLocks`
-     *   rather than letting a long run over a high-cardinality sort scope exhaust
-     *   `max_locks_per_transaction` for the whole cluster — so a run long enough
-     *   raises instead of completing. Letting Dream open a transaction per batch
-     *   releases the keys as it goes and gives each batch the whole budget.
+     *   would add, and raises rather than letting a long run over a
+     *   high-cardinality sort scope exhaust `max_locks_per_transaction` for the
+     *   whole cluster — so a run long enough raises instead of completing. That
+     *   refusal is a sizing failure to fix, not a condition to catch: letting
+     *   Dream open a transaction per batch releases the keys as it goes and gives
+     *   each batch the whole budget, and a smaller `batchSize` takes fewer.
      * - the preflight covers **the claimed rows' own scopes only**. A
      *   `dependent: 'destroy'` cascade under `destroy({ lock: true })` destroys
      *   child records of other tables, and a sortable child takes its own table's
@@ -2116,8 +2119,18 @@ export default class Query {
     }
     /**
      * Destroys all records matching the Query,
-     * ignoring the SoftDelete decorator and
-     * permanently removing records from the database.
+     * permanently removing each matched record from
+     * the database instead of soft deleting it.
+     *
+     * The SoftDelete decorator is bypassed when
+     * deleting each matched record, not when
+     * matching: the Query selects under its default
+     * scopes, `dream:SoftDelete` among them, so on a
+     * SoftDelete model it matches only records that
+     * have not already been soft deleted. Reaching
+     * soft deleted records takes
+     * `removeDefaultScope('dream:SoftDelete')` on
+     * the Query.
      *
      * Calls model hooks and applies cascade destroy
      * to associations with `dependent: 'destroy'`,
@@ -2132,17 +2145,26 @@ export default class Query {
      * // 12
      * ```
      *
+     * ```ts
+     * await User.removeDefaultScope('dream:SoftDelete')
+     *   .where({ email: ops.ilike('%burpcollaborator%') })
+     *   .reallyDestroy()
+     * // 12
+     * ```
+     *
      * A `limit` or `offset` on the Query is incompatible with `reallyDestroy`,
      * exactly as it is with {@link Query.destroy}: a limit- or offset-carrying
      * Query throws at runtime.
      *
+     * To bypass a default scope, chain `removeDefaultScope` onto the Query
+     * before calling this method; it is Query state, not an option, and it
+     * carries through to the cascade.
+     *
      * @param options - Options for destroying the instance
      * @param options.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
      * @param options.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
      * @param options.lock - If true, each batch is re-selected with an exclusive row lock inside its own transaction before being destroyed, making the destroy a compare-and-set. See {@link Query.destroy} for the full semantics. Defaults to false
      * @param options.batchSize - The number of records to process per batch. Must be a positive integer. Defaults to 10 when `lock` is true, and to 1000 otherwise
-     * @param options.bypassAllDefaultScopes - If true, bypasses user-removable default scopes when cascade destroying; an STI child's reserved discriminator remains enforced, including when associations are loaded. Defaults to false
-     * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
      * @returns The number of records that were removed
      * @throws InvalidBatchSize if `batchSize` is not a positive integer
      * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
@@ -2168,11 +2190,13 @@ export default class Query {
      * re-applied to every window — so a limit- or offset-carrying Query throws
      * at runtime.
      *
+     * To bypass a default scope, chain `removeDefaultScope` onto the Query
+     * before calling this method; it is Query state, not an option, and it
+     * carries through to the cascade. The SoftDelete scope is always bypassed.
+     *
      * @param options - Options for undestroying the instance
      * @param options.skipHooks - If true, skips applying model hooks during the undestroy operation. Defaults to false
      * @param options.cascade - If false, skips undestroying associations marked `dependent: 'destroy'`. Defaults to true
-     * @param options.bypassAllDefaultScopes - If true, bypasses user-removable default scopes when cascade undestroying; an STI child's reserved discriminator remains enforced, including when associations are loaded. Defaults to false
-     * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade undestroying (soft delete is always bypassed). Defaults to an empty array
      * @returns The number of records that were removed
      * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
      */

package/dist/cjs/src/dream/QueryDriver/Kysely.js

@@ -7,7 +7,7 @@
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore
 import pg from 'pg';
-import { PostgresDialect, sql, } from 'kysely';
+import { NoResultError, PostgresDialect, sql, } from 'kysely';
 import pluralize from 'pluralize-esm';
 import { CliFileWriter } from '../../cli/CliFileWriter.js';
 import DreamCLI from '../../cli/index.js';
@@ -30,6 +30,7 @@ import MissingThroughAssociationSource from '../../errors/associations/MissingTh
 import CannotNegateSimilarityClause from '../../errors/CannotNegateSimilarityClause.js';
 import CannotNamespaceAssociationFilterToAnotherTable from '../../errors/CannotNamespaceAssociationFilterToAnotherTable.js';
 import CannotPassUndefinedAsAValueToAWhereClause from '../../errors/CannotPassUndefinedAsAValueToAWhereClause.js';
+import CannotSaveMissingDream from '../../errors/CannotSaveMissingDream.js';
 import ArrayEqualityRequiresArrayColumn from '../../errors/ops/ArrayEqualityRequiresArrayColumn.js';
 import RowLockIncompatibleWithDistinct from '../../errors/RowLockIncompatibleWithDistinct.js';
 import RowLockIncompatibleWithJoinLoad from '../../errors/RowLockIncompatibleWithJoinLoad.js';
@@ -806,6 +807,8 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             }
         }
         catch (error) {
+            if (dream.isPersisted && error instanceof NoResultError)
+                throw new CannotSaveMissingDream(dream);
             switch (pgErrorType(error)) {
                 case COLUMN_OVERFLOW:
                     throw new ColumnOverflow(error instanceof Error ? error : new Error('database column overflow'));

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

@@ -3,6 +3,7 @@ import { clearSortableSaveState } from '../../decorators/field/sortable/helpers/
 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 CannotSaveMissingDream from '../../errors/CannotSaveMissingDream.js';
 import ValidationError from '../../errors/ValidationError.js';
 import sqlAttributes from '../../helpers/sqlAttributes.js';
 import { DateTime } from '../../utils/datetime/DateTime.js';
@@ -114,6 +115,14 @@ async function writeDream(dream, txn, { alreadyPersisted, sortableFieldConfigs,
         dream.createdAt = now;
     if (!dream.dirtyAttributes().updatedAt && dream.columns().has('updatedAt'))
         dream.updatedAt = now;
+    // The scope-lock read above positively found the row gone, so there is
+    // nothing to update. Raised here rather than after the write because the
+    // write below would not reach the database at all on a position-only save,
+    // whose attributes Sortable has already cleared; a save that does carry data
+    // raises the equivalent diagnostic from the driver, which sees the update
+    // match no row.
+    if (alreadyPersisted && !rowFoundBeforeWrite)
+        throw new CannotSaveMissingDream(dream);
     const hasUnsavedData = !!Object.keys(sqlAttributes(dream)).length;
     // BeforeSave/Update actions may clear all the data that we intended to save, leaving us with
     // an invalid update command. The Sortable decorator is an example of this.

package/dist/cjs/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/cjs/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/cjs/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/cjs/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/esm/src/decorators/Decorators.js

@@ -147,18 +147,93 @@ export default class Decorators {
         return Scope(opts);
     }
     /**
-     * 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.
      *
      * ```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 every position write serializes the
+     * writers of its sort scope on one. 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. 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.
+     *
+     * `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/esm/src/decorators/field/sortable/Sortable.js

@@ -1,36 +1,9 @@
 import scopeArray from './helpers/scopeArray.js';
 /**
- * Marks an integer column as a sortable position: Dream keeps the positions of
- * every record in a sort scope contiguous, starting at 1, as records are
- * created, moved, destroyed and undestroyed.
- *
- * ```ts
- * class Post extends ApplicationModel {
- *   @deco.Sortable({ scope: 'user' })
- *   public position: number
- * }
- *
- * await post.update({ position: 2 }) // the records at 2 and above shift up
- * ```
- *
- * A position past the end of the scope is clamped to the end, and a position
- * below 1 — or none at all — lands the record at the end.
- *
- * **A save that changes the sort scope ignores a position given alongside it.**
- * The record lands at the end of the scope it moves into, whatever position the
- * same `update` supplied:
- *
- * ```ts
- * await post.update({ user: otherUser, position: 1 })
- * // post is now the last record in otherUser's scope, not the first
- * ```
- *
- * Move it in two saves to place it: `await post.update({ user: otherUser })`,
- * then `await post.update({ position: 1 })`.
- *
- * Sortable requires a query driver that supports advisory transaction locks —
- * the `PostgresQueryDriver` does — since every position write serializes the
- * writers of its sort scope on one.
+ * 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 = {}) {
     return function (_, context) {

package/dist/esm/src/dream/Query.js

@@ -1914,13 +1914,15 @@ export default class Query {
      *   {@link Query.delete | delete} (a single statement, no hooks or cascade)
      *   are the right tools for bulk removal.
      *
+     * To bypass a default scope, chain `removeDefaultScope` onto the Query
+     * before calling this method; it is Query state, not an option, and it
+     * carries through to the cascade.
+     *
      * @param options - Options for destroying the instance
      * @param options.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
      * @param options.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
      * @param options.lock - If true, each batch is re-selected with an exclusive row lock inside its own transaction before being destroyed, making the destroy a compare-and-set. Defaults to false
      * @param options.batchSize - The number of records to process per batch. Must be a positive integer. Defaults to 10 when `lock` is true, and to 1000 otherwise
-     * @param options.bypassAllDefaultScopes - If true, bypasses user-removable default scopes when cascade destroying; an STI child's reserved discriminator remains enforced, including when associations are loaded. Defaults to false
-     * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
      * @returns The number of records that were removed
      * @throws InvalidBatchSize if `batchSize` is not a positive integer
      * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
@@ -2034,11 +2036,12 @@ export default class Query {
      *   transaction ends, so every batch's scope keys are still held when the
      *   next one preflights. That accumulation is bounded — the preflight counts
      *   the keys the transaction already holds along with the ones the batch
-     *   would add, and refuses with `SortableBatchRequiresTooManyScopeLocks`
-     *   rather than letting a long run over a high-cardinality sort scope exhaust
-     *   `max_locks_per_transaction` for the whole cluster — so a run long enough
-     *   raises instead of completing. Letting Dream open a transaction per batch
-     *   releases the keys as it goes and gives each batch the whole budget.
+     *   would add, and raises rather than letting a long run over a
+     *   high-cardinality sort scope exhaust `max_locks_per_transaction` for the
+     *   whole cluster — so a run long enough raises instead of completing. That
+     *   refusal is a sizing failure to fix, not a condition to catch: letting
+     *   Dream open a transaction per batch releases the keys as it goes and gives
+     *   each batch the whole budget, and a smaller `batchSize` takes fewer.
      * - the preflight covers **the claimed rows' own scopes only**. A
      *   `dependent: 'destroy'` cascade under `destroy({ lock: true })` destroys
      *   child records of other tables, and a sortable child takes its own table's
@@ -2116,8 +2119,18 @@ export default class Query {
     }
     /**
      * Destroys all records matching the Query,
-     * ignoring the SoftDelete decorator and
-     * permanently removing records from the database.
+     * permanently removing each matched record from
+     * the database instead of soft deleting it.
+     *
+     * The SoftDelete decorator is bypassed when
+     * deleting each matched record, not when
+     * matching: the Query selects under its default
+     * scopes, `dream:SoftDelete` among them, so on a
+     * SoftDelete model it matches only records that
+     * have not already been soft deleted. Reaching
+     * soft deleted records takes
+     * `removeDefaultScope('dream:SoftDelete')` on
+     * the Query.
      *
      * Calls model hooks and applies cascade destroy
      * to associations with `dependent: 'destroy'`,
@@ -2132,17 +2145,26 @@ export default class Query {
      * // 12
      * ```
      *
+     * ```ts
+     * await User.removeDefaultScope('dream:SoftDelete')
+     *   .where({ email: ops.ilike('%burpcollaborator%') })
+     *   .reallyDestroy()
+     * // 12
+     * ```
+     *
      * A `limit` or `offset` on the Query is incompatible with `reallyDestroy`,
      * exactly as it is with {@link Query.destroy}: a limit- or offset-carrying
      * Query throws at runtime.
      *
+     * To bypass a default scope, chain `removeDefaultScope` onto the Query
+     * before calling this method; it is Query state, not an option, and it
+     * carries through to the cascade.
+     *
      * @param options - Options for destroying the instance
      * @param options.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
      * @param options.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
      * @param options.lock - If true, each batch is re-selected with an exclusive row lock inside its own transaction before being destroyed, making the destroy a compare-and-set. See {@link Query.destroy} for the full semantics. Defaults to false
      * @param options.batchSize - The number of records to process per batch. Must be a positive integer. Defaults to 10 when `lock` is true, and to 1000 otherwise
-     * @param options.bypassAllDefaultScopes - If true, bypasses user-removable default scopes when cascade destroying; an STI child's reserved discriminator remains enforced, including when associations are loaded. Defaults to false
-     * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
      * @returns The number of records that were removed
      * @throws InvalidBatchSize if `batchSize` is not a positive integer
      * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
@@ -2168,11 +2190,13 @@ export default class Query {
      * re-applied to every window — so a limit- or offset-carrying Query throws
      * at runtime.
      *
+     * To bypass a default scope, chain `removeDefaultScope` onto the Query
+     * before calling this method; it is Query state, not an option, and it
+     * carries through to the cascade. The SoftDelete scope is always bypassed.
+     *
      * @param options - Options for undestroying the instance
      * @param options.skipHooks - If true, skips applying model hooks during the undestroy operation. Defaults to false
      * @param options.cascade - If false, skips undestroying associations marked `dependent: 'destroy'`. Defaults to true
-     * @param options.bypassAllDefaultScopes - If true, bypasses user-removable default scopes when cascade undestroying; an STI child's reserved discriminator remains enforced, including when associations are loaded. Defaults to false
-     * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade undestroying (soft delete is always bypassed). Defaults to an empty array
      * @returns The number of records that were removed
      * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
      */