@rvoh/dream 2.27.0 → 2.28.0

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

@@ -0,0 +1,39 @@
+/**
+ * Raised when a position-mutating operation cannot settle on the sort scope its
+ * record actually occupies.
+ *
+ * A save, destroy, undestroy or locked batch operation locks the sort scopes it
+ * believes it is touching, then reads the rows to find out which scopes they
+ * physically occupy. When another writer has moved a row in between, the
+ * operation takes the additional scope's lock and reads again. A row that keeps
+ * moving exhausts that bound, and the operation raises rather than compacting a
+ * scope the row has already left.
+ *
+ * This is a retryable condition: retrying the operation is the intended
+ * response. One caveat for saves the caller did not wrap in a transaction: the
+ * model's before-hooks run before the transaction this error aborts, so any
+ * effects those hooks had outside the record's own row — writes to other
+ * tables, enqueued work — are not rolled back, and run again on retry.
+ */
+export default class SortableScopeDidNotStabilize extends Error {
+    dreamClassName;
+    rounds;
+    constructor(dreamClassName, rounds) {
+        super();
+        this.dreamClassName = dreamClassName;
+        this.rounds = rounds;
+    }
+    get message() {
+        return `\
+The sort scope of a ${this.dreamClassName} record kept changing while its position was being computed.
+
+Sortable locks the sort scopes an operation touches and then reads the record's actual scope
+under those locks, taking any additional lock the read reveals. After ${this.rounds} rounds the
+record had still been moved to another scope by a competing writer, so the operation was
+abandoned rather than compacting a scope the record no longer occupies. Retrying the operation
+is the intended response; note that on a save the caller did not wrap in a transaction, the
+model's before-hooks ran before the transaction this error aborted, so their effects outside
+the record's own row are not rolled back and run again on retry.
+`;
+    }
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Raised when a position-mutating operation waited too long for another
+ * transaction to release a sort scope.
+ *
+ * Every position-mutating path — a save, a destroy, an undestroy, a locked
+ * batch, `Dream.resort` — computes its positions under an exclusive advisory
+ * lock on the sort scope, held until the transaction that took it ends. A
+ * writer that finds the scope already locked waits, and that wait is bounded:
+ * Dream applies a `lock_timeout` (5 seconds by default, set through the
+ * `sortableScopeLockTimeout` DreamApp option) to the acquisition statement
+ * alone, and restores whatever `lock_timeout` was in effect afterward, so the
+ * transaction's other lock waits — row locks taken by `lock: true`, foreign key
+ * checks — are left exactly as the application configured them.
+ *
+ * This is a retryable condition: the operation touched nothing, and the holder
+ * it was waiting for is a transaction that will end. What has to be retried
+ * depends on who owns the transaction. When Dream opened it — a plain
+ * `save()`, `destroy()`, `undestroy()` or `resort()` — only that call was rolled
+ * back, and retrying the call is the whole response. Inside a transaction the
+ * caller owns, the failed statement aborts **the entire transaction**: nothing
+ * further can run on it, and the caller has to retry the transaction as a whole
+ * rather than the sortable operation inside it.
+ *
+ * Hitting this bound routinely is a signal rather than a transient: it means one
+ * sort scope is being written by more concurrent writers than it can serialize,
+ * or that something slow is running inside a transaction that holds the scope —
+ * on a destroy or an undestroy, that includes your own `afterDestroy` and
+ * `afterUpdate` hooks, which run inside the lock window.
+ */
+export default class SortableScopeLockWaitTimedOut extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super();
+        this.timeoutMs = timeoutMs;
+    }
+    get message() {
+        return `\
+Timed out after ${this.timeoutMs}ms waiting for another transaction to release a sort scope.
+
+Sortable computes positions under an exclusive advisory lock on the sort scope, held until the
+transaction holding it ends. This operation waited the configured bound and gave up rather than
+waiting indefinitely; it changed nothing, and retrying it is the intended response — but if the
+transaction this ran in was one you opened yourself, the whole transaction is aborted and has to
+be retried as a whole.
+
+Change the bound with \`dreamApp.set('sortableScopeLockTimeout', milliseconds)\` in your Dream
+configuration, or set it to 0 to wait without bound.
+`;
+    }
+}

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

@@ -12,6 +12,9 @@ export { default as DecryptionParseError } from '../errors/encrypt/DecryptionPar
 export { default as DecryptionRotationError } from '../errors/encrypt/DecryptionRotationError.js';
 export { default as RecordNotFound } from '../errors/RecordNotFound.js';
 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';
 export { InvalidCalendarDate } from '../utils/datetime/CalendarDate.js';
 export { InvalidClockTime } from '../utils/datetime/ClockTime.js';

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

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

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

@@ -3,6 +3,7 @@ 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";
 export declare const COLUMN_OVERFLOW = "COLUMN_OVERFLOW";
+export declare const LOCK_NOT_AVAILABLE = "LOCK_NOT_AVAILABLE";
 export declare const NOT_NULL_VIOLATION = "NOT_NULL_VIOLATION";
 export declare const RESTRICT_VIOLATION = "RESTRICT_VIOLATION";
 export declare const UNIQUE_VIOLATION = "UNIQUE_VIOLATION";
@@ -17,6 +18,7 @@ export declare const PG_ERRORS: {
     readonly '23000': "INTEGRITY_CONSTRAINT_VIOLATION";
     readonly '23001': "RESTRICT_VIOLATION";
     readonly '23503': "FOREIGN_KEY_VIOLATION";
+    readonly '55P03': "LOCK_NOT_AVAILABLE";
 };
 type PgErrorType = (typeof PG_ERRORS)[keyof typeof PG_ERRORS];
 export declare function pgErrorType(error: any): PgErrorType | null;

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

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

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

@@ -0,0 +1,25 @@
+import Dream from '../../../../Dream.js';
+import DreamTransaction from '../../../../dream/DreamTransaction.js';
+/**
+ * @internal
+ *
+ * Serializes every writer of a set of sort scopes by taking those scopes'
+ * transaction-scoped advisory locks. They are released when the enclosing
+ * transaction ends, so there is nothing to release here.
+ *
+ * Keys this transaction already holds are dropped rather than re-acquired: the
+ * lock is held to the end of the transaction either way, so the statement would
+ * do nothing but cost a round trip inside the lock window. Whatever is left is
+ * taken in the order given — callers that need more than one sort them first,
+ * so that two operations touching the same pair of scopes cannot deadlock
+ * against each other — and in one statement, on drivers that can express it.
+ *
+ * Waiting for a key another transaction holds is bounded by the driver, which
+ * raises `SortableScopeLockWaitTimedOut` rather than waiting forever; see
+ * `QueryDriverBase.acquireAdvisoryTransactionLocks`.
+ *
+ * @param dream - the record whose connection provides the driver
+ * @param txn - the transaction the locks are scoped to
+ * @param keys - the scope keys to acquire, in acquisition order
+ */
+export default function acquireSortableScopeLocks(dream: Dream, txn: DreamTransaction<any>, keys: bigint[]): Promise<void>;

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

@@ -0,0 +1,91 @@
+import Dream from '../../../../Dream.js';
+import DreamTransaction from '../../../../dream/DreamTransaction.js';
+/**
+ * The most advisory sort-scope locks a batch preflight will let one transaction
+ * hold.
+ *
+ * Advisory locks are entries in a cluster-wide shared lock table sized at
+ * startup (`max_locks_per_transaction` × `max_connections`, 6400 entries under
+ * the stock settings), and a transaction holds every key it takes until it
+ * ends. `batchSize` is the caller's to choose and nothing bounds the number of
+ * distinct sort scopes a batch's records span, so without a limit a wide enough
+ * batch over a high-cardinality scope can starve every other connection in the
+ * cluster of a resource they all draw on — a failure that lands on unrelated
+ * transactions rather than on the one that caused it.
+ *
+ * The count is **cumulative over the transaction**: each preflight round counts
+ * the keys the transaction already holds together with the keys that round
+ * would add. So the bound holds across the rounds of one stabilization loop
+ * (each of which can discover a different set of scopes), and across the
+ * batches of a multi-batch run inside a caller-owned transaction, where
+ * advisory locks are released only when the caller commits.
+ *
+ * The headroom this leaves: the locked-batch defaults are ten records per batch
+ * (`Query.BATCH_SIZES.LOCKED_DESTROY` / `LOCKED_UPDATE`), so reaching the bound
+ * takes a caller who raises `batchSize` by two orders of magnitude and whose
+ * records each occupy a sort scope of their own — or a long run of such batches
+ * inside one transaction. Two shapes consume the budget faster than one key per
+ * record: a model declaring more than one sortable field needs one key per
+ * field, and the attribute form of `update` needs up to two per record per
+ * field, since the record's current scope and its destination scope are
+ * different keys.
+ *
+ * Only the batch preflight enforces this. A per-record save, destroy or
+ * undestroy takes its keys without counting them, so what they take is counted
+ * by the next preflight in the same transaction but cannot itself raise.
+ */
+export declare const MAX_SORTABLE_BATCH_SCOPE_LOCKS = 1000;
+/**
+ * @internal
+ *
+ * The operation-level scope-lock preflight for the batched, row-locking query
+ * APIs — `Query#destroy({ lock: true })` and the attribute form of
+ * `Query#update(attributes, { lock: true })`.
+ *
+ * Why it exists: those operations take *row* locks (`takeAll({ lock: true })`)
+ * and then run per-record sortable work that takes *advisory* scope locks. Two
+ * transactions running in that order can each hold what the other is waiting
+ * for. Acquiring every advisory key the batch needs — across every sortable
+ * field and every candidate record — in one sorted pass, before a single row is
+ * claimed, removes the inversion: the advisory locks are always taken first, and
+ * always in the same order.
+ *
+ * The key set cannot simply be read once: `Query.lockedBatches` plucks only
+ * primary keys, so the candidates' scope columns have to be read separately, and
+ * that first read is not protected by any lock. So the read is stabilized the
+ * same way the per-record paths stabilize theirs, through the same
+ * `stabilizeSortableScopeLocks` protocol — acquire on what the unlocked read
+ * implies, re-read under those locks, take any additional key the re-read
+ * reveals — with the same bound, and the same `SortableScopeDidNotStabilize`
+ * when a batch of rows keeps moving between scopes faster than it can be read.
+ *
+ * A model with no sortable fields never reaches the driver seam, so this is
+ * inert — and free — for every other model.
+ *
+ * How many keys the transaction may hold is bounded — see
+ * {@link MAX_SORTABLE_BATCH_SCOPE_LOCKS} — and a batch that would carry it past
+ * the bound is refused before it claims any row. The first round refuses before
+ * anything at all is locked; a later round refuses after that loop's earlier
+ * rounds took their keys, which stay held until the transaction ends like every
+ * advisory lock this branch takes.
+ *
+ * What the preflight can and cannot see: `incomingScopeValue` recognizes an
+ * attribute that names a scope column directly or the BelongsTo association
+ * backing it. A destination scope produced any other way — by a custom setter,
+ * a virtual attribute, or a `beforeSave` hook that moves the record between
+ * scopes during the per-record save — is invisible here, and those shapes are
+ * preflight fallbacks like the callback form of `update` and a multi-batch run
+ * inside a caller-owned transaction: the missing key is taken as the
+ * per-record save reaches it, after this batch's row locks, and the residual
+ * failure is Postgres's `40P01` deadlock error — a visible, retryable failure
+ * rather than a silent wrong ordering.
+ *
+ * @param dreamInstance - a bare instance of the Query's model, used for the
+ *   table, the connection, and the scope column resolution
+ * @param txn - the batch's transaction; the locks live until it ends
+ * @param primaryKeyValues - the candidate records this batch will try to claim
+ * @param incomingAttributes - the attributes the operation will write, when they
+ *   are knowable before the claim (the attribute form of `update`); a scope
+ *   column among them means the batch also needs the destination scope's key
+ */
+export default function acquireStabilizedSortableBatchLocks(dreamInstance: Dream, txn: DreamTransaction<any>, primaryKeyValues: unknown[], incomingAttributes?: Record<string, unknown>): Promise<void>;

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

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

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

@@ -0,0 +1,85 @@
+import Dream from '../../../../Dream.js';
+/**
+ * @internal
+ *
+ * The canonical text form of one sort-scope value — the thing an advisory lock
+ * key and a resort group identity are actually built from.
+ *
+ * Two writers of the same physical sort scope have to derive the same key, and
+ * they do not always hold the value in the same JavaScript shape. A save that
+ * has not been written yet holds the *pending* value the caller supplied
+ * (`'1.00'`, an uppercase UUID, an object whose keys are in source order),
+ * while a snapshot read, a create's post-INSERT read and `resort`'s table read
+ * hold the value Postgres *hydrated* (`1`, a lowercase UUID, an object whose
+ * keys are in jsonb's own order). Postgres considers those pairs one value;
+ * `typeof`-only normalization considers them two, and two keys do not exclude
+ * each other.
+ *
+ * So canonicalization is keyed on the column's runtime `dbType`, and the
+ * canonical form of each type is **the form the hydrated value already takes**.
+ * That anchoring is what makes this safe to ship without a migration or a
+ * coordinated deploy: no key derived from a database-hydrated value moves, and
+ * the pending-side keys that do move are exactly the ones that disagree with
+ * every hydrated-path writer of the same scope today.
+ *
+ * The classes handled, and what the hydrated value looks like:
+ *
+ * - `uuid` — Postgres renders UUIDs lowercase, so the canonical form is
+ *   lowercase.
+ * - `numeric` / `real` / `double precision` — hydrated through
+ *   `parsePostgresDecimal`, i.e. `parseFloat`, so `'1.00'` and `1` both
+ *   canonicalize to `'1'`.
+ * - `jsonb` — hydrated by `JSON.parse` of jsonb's own output, whose object keys
+ *   are ordered by key length and then bytewise. Objects are re-emitted in that
+ *   order, recursively, so property insertion order stops mattering.
+ * - `boolean` — hydrated as a JavaScript boolean; Postgres's own input literals
+ *   (`'t'`, `'yes'`, `'0'`, …) canonicalize to `'true'`/`'false'`.
+ * - `date` and the four timestamp/time types — hydrated as `CalendarDate`,
+ *   `DateTime`, `ClockTime` or `ClockTimeTz`, whose JSON form is the quoted ISO
+ *   string. Strings are quoted the same way so a pending `'2026-02-07'` and a
+ *   hydrated `CalendarDate` agree.
+ *
+ * Everything else — `bigint` and `character varying`, which is to say the
+ * foreign keys and text columns nearly every sort scope is made of — is left on
+ * the untyped normalization below, unchanged.
+ *
+ * Two residuals are known and accepted rather than fixed:
+ *
+ * - **`citext`**: Postgres stores the case a row was written with while
+ *   comparing case-insensitively, so two rows of one physical scope hydrate to
+ *   values that differ in case and split the key on their own. Lowercasing
+ *   would fix the split but would *move* hydrated keys, which is the one thing
+ *   this design refuses to do.
+ * - **Temporal values that agree on the instant but not on the text**: a zone
+ *   offset or a fractional-second precision that differs from the hydrated
+ *   rendering still yields a different key. Only the string-vs-object quoting
+ *   mismatch is canonicalized.
+ *
+ * Both are over-serialization or a missed exclusion between two *pending*-side
+ * writers, never a corrupt position under a key two writers do share.
+ *
+ * @param dream - the record whose scope column is being canonicalized
+ * @param column - the physical database column
+ * @param value - the pending or hydrated value held for that column
+ * @returns the canonical text form, or `null` for an absent value
+ */
+export default function canonicalScopeValue(dream: Dream, column: string, value: unknown): string | null;
+/**
+ * @internal
+ *
+ * The type-blind fallback, and the shape every unrecognized `dbType` keeps:
+ * the same foreign key can arrive as a string or a number depending on the path
+ * that loaded it, so values are rendered as text and null is kept distinct from
+ * every string, including the empty one.
+ */
+export declare function untypedScopeValue(value: unknown): string | null;
+/**
+ * @internal
+ *
+ * Postgres's own boolean input literals, lower-cased and trimmed, which a
+ * pending value may hold while the hydrated value is a JavaScript boolean.
+ * Exported so the spec drives its cases from the sets themselves rather than
+ * from a hand-copied list that can silently drift out of step with them.
+ */
+export declare const BOOLEAN_TRUE_LITERALS: ReadonlySet<string>;
+export declare const BOOLEAN_FALSE_LITERALS: ReadonlySet<string>;

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

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

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

@@ -1,8 +1,15 @@
 import Dream from '../../../../Dream.js';
 import Query from '../../../../dream/Query.js';
-export default function decrementPositionForScopedRecordsGreaterThanPosition(position: number, { dream, positionField, query, scope, }: {
+import { SortableSnapshot } from './sortableSnapshot.js';
+export default function decrementPositionForScopedRecordsGreaterThanPosition(position: number, { dream, positionField, query, scope, snapshot, }: {
     dream: Dream;
     positionField: string;
     query: Query<Dream>;
     scope: string | string[] | undefined;
+    /**
+     * The destroyed row's real scope values, read before the delete. The scope
+     * being compacted is the one the row physically occupied, which is not
+     * necessarily the one the instance was loaded from.
+     */
+    snapshot?: SortableSnapshot | undefined;
 }): Promise<void>;

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

@@ -0,0 +1,24 @@
+import Dream from '../../../../Dream.js';
+import Query from '../../../../dream/Query.js';
+/**
+ * @internal
+ *
+ * Narrows a Dream `Query` to one sort scope, **reading the scope values off the
+ * in-memory instance**. That is only the scope the row physically occupies when
+ * the instance is known to agree with the row — inside a transaction that has
+ * just written those values, or on a record read under the scope lock.
+ *
+ * Where the row may have been moved by another writer, the caller wants
+ * `filterQueryToScopeValues` instead, which takes each column's value from the
+ * caller (the snapshot read under the lock) rather than from the instance.
+ */
+export default function filterQueryToInstanceScope(query: Query<Dream>, dream: Dream, scope?: string | string[]): Query<Dream, Readonly<{
+    joinedAssociations: Readonly<[]>;
+    rootTableName: string;
+    rootTableAlias: string;
+    allowPreload: true;
+    allowLeftJoinPreload: true;
+    allowLimit: true;
+    allowOffset: true;
+    allowPaginate: true;
+}>>;

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

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

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

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

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

@@ -0,0 +1,14 @@
+import Dream from '../../../../Dream.js';
+import DreamTransaction from '../../../../dream/DreamTransaction.js';
+/**
+ * @internal
+ *
+ * The compaction of a sortable destroy: closes the vacancy each sortable
+ * field's sort scope is left with, computed from the snapshot the preparation
+ * phase (`prepareSortableFieldsForDestroy`) read before the delete. Called
+ * directly from `destroyDream` after the delete and before any user
+ * `afterDestroy` hook — never registered as a hook among them — so every
+ * after-destroy hook observes the compacted scope regardless of where it was
+ * declared, exactly as every after-save hook observes the computed position.
+ */
+export default function performSortableDestroyWork(dream: Dream, txn: DreamTransaction<any>): Promise<void>;

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

@@ -0,0 +1,15 @@
+import Dream from '../../../../Dream.js';
+import DreamTransaction from '../../../../dream/DreamTransaction.js';
+import { SortableFieldConfig } from '../Sortable.js';
+/**
+ * @internal
+ *
+ * The position work of a sortable save: computes each sortable field's real
+ * position under the scope lock and writes it. Called directly from
+ * `saveDream` after the driver write — never registered as an after-hook — so
+ * no user hook code can interleave with it while the scope lock is held, and
+ * on a self-opened save it is the last work before COMMIT releases the lock.
+ */
+export default function performSortablePositionWork(dream: Dream, txn: DreamTransaction<any>, sortableFieldConfigs: SortableFieldConfig[], { alreadyPersisted }: {
+    alreadyPersisted: boolean;
+}): Promise<void>;

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

@@ -0,0 +1,41 @@
+import Dream from '../../../../Dream.js';
+import DreamTransaction from '../../../../dream/DreamTransaction.js';
+/**
+ * @internal
+ *
+ * The sortable preparation phase of a destroy. Called from `destroyDream` after
+ * every user `beforeDestroy` hook has run and before the delete — a phase, not
+ * a hook among them — so the operation's whole advisory key set, across every
+ * sortable field, is taken in one sorted stabilized acquisition, with one
+ * snapshot SELECT covering all fields. Per-field acquisition would take
+ * multi-field keys in declaration order, which deadlocks against the paths
+ * that acquire sorted.
+ *
+ * Pre-delete is the only seat available for the snapshot read: on a hard
+ * destroy the row is gone afterwards, and a soft destroy nulls the position
+ * columns in the same UPDATE as `deletedAt`. The lock is taken around the read
+ * so the snapshot cannot be invalidated between the read and the compaction;
+ * it is transaction-scoped, and `destroyDream` opens a transaction that spans
+ * the delete and the after-destroy hooks, so one acquisition covers both.
+ *
+ * The per-field compactions (`performSortableDestroyWork`) consume the cached
+ * snapshots.
+ *
+ * @returns false when the snapshot read found no row — this destroy has nothing
+ *   to vacate, and compacting from the instance's remembered position would
+ *   shift a scope some other writer has already closed. The delete's own
+ *   affected-row count is the stronger signal (a writer outside the sortable
+ *   path can remove the row after this read), so the caller checks both.
+ */
+export default function prepareSortableFieldsForDestroy(dream: Dream, txn: DreamTransaction<any>): Promise<boolean>;
+/**
+ * @internal
+ *
+ * Discards what the preparation phase stashed on the instance. The per-field
+ * compaction clears its own snapshot as it consumes it, so this
+ * exists for the path where that compaction never runs: a destroy that removed
+ * nothing leaves the snapshot behind, and a later save or destroy of the same
+ * instance would compute its shift from a reading of a row this operation
+ * already found gone.
+ */
+export declare function clearSortableFieldsForDestroy(dream: Dream): void;