@rvoh/dream 2.26.0 → 2.28.0

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;

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

@@ -0,0 +1,35 @@
+import Dream from '../../../../Dream.js';
+import { SortableFieldConfig } from '../Sortable.js';
+export interface SortableCache {
+    changingScope: boolean;
+    position: number | undefined;
+    previousPosition: number | undefined;
+    wasNewRecord: boolean;
+}
+/**
+ * @internal
+ *
+ * The sortable preparation phase of a save. Called from `saveDream` after every
+ * consumer before-hook has run — a phase, not a hook among them — so the
+ * decision is made from the final state of the instance: a position or scope
+ * change introduced by a `beforeSave` hook registered after Sortable's gets the
+ * same handling as one made before `save` was called, and a cache is never
+ * carried over from a state an intervening hook has made stale.
+ *
+ * For each sortable field this caches the values the position work needs and
+ * applies the position sentinel, then returns the fields whose position work
+ * this save will perform — the fields that make the save need a transaction of
+ * its own, so that the write and the position write that follows it commit
+ * together under one scope lock.
+ *
+ * - every create on a model with sortable fields performs position work;
+ * - an update performs it only when the save changes the position or one of the
+ *   sortable scope columns.
+ *
+ * A save that skips hooks performs no position work at all, so it needs no
+ * transaction.
+ */
+export default function prepareSortableFieldsForSave(dream: Dream, { alreadyPersisted, skipHooks }: {
+    alreadyPersisted: boolean;
+    skipHooks: boolean;
+}): SortableFieldConfig[];

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

@@ -1,2 +1,34 @@
 import Dream from '../../../../Dream.js';
+/**
+ * @internal
+ *
+ * Renumbers every sort scope of a model so that each one runs 1..n with no gaps.
+ *
+ * Four things make this safe to run against a live table:
+ *
+ * - **A driver that cannot take the scope lock fails before the table is
+ *   read**, rather than succeeding for whichever scopes happen to be contiguous
+ *   and throwing on the first one that is not.
+ * - **The STI scope is stripped**, exactly as every sortable hook strips it. An
+ *   STI hierarchy shares one position space, so renumbering one child's rows in
+ *   isolation would hand them positions its siblings already hold.
+ * - **Groups are identified structurally**, by the scope columns' `[column,
+ *   value]` tuple rather than by joining the values into one string. Joining
+ *   merges scopes whose values differ only in where a delimiter falls, and
+ *   merges a null member with an empty-string one; a merged group is two
+ *   physical sort scopes renumbered as though they were one, and no single lock
+ *   key covers it.
+ * - **Every discovered scope is renumbered under its own scope lock, from a
+ *   read taken inside that lock.** The unlocked pass below only discovers
+ *   *which* sort scopes exist; it decides nothing about their contents, because
+ *   a concurrent create, destroy or raw update between the two reads is
+ *   precisely the case this exists to repair. Whether a scope needs renumbering
+ *   at all is decided under the lock.
+ *
+ * Each scope's transaction is this function's own: `resort` cannot join a
+ * transaction the caller owns, and must not be called from inside one. It would
+ * wait on a connection of its own for a scope lock the caller's transaction may
+ * already hold — a wait no deadlock detector can see, which ends in
+ * `SortableScopeLockWaitTimedOut` rather than in progress.
+ */
 export default function resortAllRecords(dreamClass: typeof Dream, positionField: string, scope?: string | string[]): Promise<void>;

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

@@ -1,20 +1,36 @@
-import { SelectQueryBuilder, UpdateQueryBuilder } from 'kysely';
 import Dream from '../../../../Dream.js';
 import DreamTransaction from '../../../../dream/DreamTransaction.js';
 import Query from '../../../../dream/Query.js';
-import PostgresQueryDriver from '../../../../dream/QueryDriver/Postgres.js';
-import { SortableCache } from '../hooks/beforeSortableSave.js';
-interface SortableCacheWithOptionalTransaction extends SortableCache {
+import { SortableCache } from './prepareSortableFieldsForSave.js';
+import { SortableSnapshot } from './sortableSnapshot.js';
+/**
+ * @internal
+ *
+ * Everything one sortable field's position write needs. The transaction is
+ * required: every path into `setPosition` runs from
+ * `performSortablePositionWork`, which is called by `saveDream` inside the
+ * transaction that holds the scope lock, and a position write that opened a
+ * transaction of its own would block on a key its own caller holds.
+ */
+export interface SortablePositionWrite extends SortableCache {
     dream: Dream;
     positionField: string;
     query: Query<Dream>;
     scope: string | string[] | undefined;
-    txn?: DreamTransaction<any> | undefined;
-}
-export interface SortableCacheWithRequiredTransaction extends SortableCacheWithOptionalTransaction {
     txn: DreamTransaction<any>;
+    /**
+     * The record's physical position and sort scope values, read from the row
+     * under the scope lock before the driver write. Present on the update path;
+     * absent on create, which has no prior row.
+     */
+    snapshot?: SortableSnapshot | undefined;
+    /**
+     * The position the record holds in the scope its position is being computed
+     * over, where the driver write has replaced it on the row with the position
+     * sentinel. Set only for a save that lands in the scope the row already
+     * occupies; on every other path the scope's own rows carry their real
+     * positions, or the record is joining the scope rather than already in it.
+     */
+    positionUnderSentinel?: number | undefined;
 }
-export default function setPosition(obj: SortableCacheWithOptionalTransaction): Promise<void>;
-export declare function applySortableScopesToQuery<QB extends UpdateQueryBuilder<any, any, any, any> | SelectQueryBuilder<any, any, any>>(dream: Dream, kyselyQuery: QB, whereValueCB: (column: string) => any, scope?: string | string[]): QB;
-export declare function getPostgresQueryDriver(connectionName: string): typeof PostgresQueryDriver;
-export {};
+export default function setPosition(obj: SortablePositionWrite): Promise<void>;

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

@@ -0,0 +1,48 @@
+import DreamTransaction from '../../../../dream/DreamTransaction.js';
+/**
+ * @internal
+ *
+ * Stashes rows a locked batch's preflight read under the batch's scope locks,
+ * so that the per-record position work that follows does not read them a second
+ * time. The preflight reads every candidate's position and sort scope columns
+ * to derive the key set; each record's own snapshot read then asks the same
+ * question of the same row, in the same transaction, under the same locks.
+ *
+ * Called once per preflight, with the rows of the pass that converged: an
+ * earlier pass read before some of the locks were held, and a preflight that
+ * raised holds no lock the rest of the transaction can rely on. The rows are
+ * consumed one at a time and the whole entry is dropped by the first position
+ * write of the batch, since a compaction moves rows this holds stale positions
+ * for — so what it saves is the snapshot reads of the records walked before
+ * that first write.
+ *
+ * @param txn - the batch's transaction
+ * @param table - the table the rows came from
+ * @param primaryKey - the column the rows are keyed by
+ * @param rows - the rows read, carrying at least the position and scope columns
+ */
+export declare function cacheSortableRowsReadUnderLock(txn: DreamTransaction<any>, table: string, primaryKey: string, rows: Record<string, unknown>[]): void;
+/**
+ * @internal
+ *
+ * The cached row for one record, removed from the cache as it is handed over.
+ *
+ * Consuming is destructive because the consumer is a position-mutating
+ * operation: it is about to compact or renumber the scope the row sits in, and
+ * a second read of the same cached row would see the position the row had
+ * before that. {@link invalidateSortableRowCache} covers the same hazard for
+ * the *other* records a compaction moves.
+ */
+export declare function takeCachedSortableRow(txn: DreamTransaction<any>, table: string, primaryKeyValue: unknown): Record<string, unknown> | undefined;
+/**
+ * @internal
+ *
+ * Discards everything cached for this transaction. Called for two reasons: a
+ * position write just moved rows the cache cannot identify — a compaction
+ * shifts every row in one sort scope above a position, and the cache holds no
+ * index by scope — and the batch the rows were read for has finished, after
+ * which they describe nothing the rest of a caller-owned transaction should
+ * trust. The records still to be walked read their own rows again, which is
+ * what they did before the cache existed.
+ */
+export declare function invalidateSortableRowCache(txn: DreamTransaction<any>): void;

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

@@ -0,0 +1,30 @@
+import Dream from '../../../../Dream.js';
+/**
+ * @internal
+ *
+ * The scope members of a sortable field paired with the database columns they
+ * resolve to. A member names either the column itself or the BelongsTo
+ * association whose foreign key backs it, and a caller matching incoming
+ * attributes needs both spellings; a member that resolves to no column is
+ * dropped.
+ *
+ * Every sortable path resolves its scope columns through this one function, so
+ * that a lock key, a snapshot read, a group identity and a scope filter can
+ * never disagree about which columns a sort scope is made of.
+ */
+export declare function sortableScopeColumnPairs(dream: Dream, scope: string | string[] | undefined): [string, string][];
+/**
+ * @internal
+ *
+ * The database columns a sortable field's scope resolves to.
+ */
+export default function sortableScopeColumns(dream: Dream, scope: string | string[] | undefined): string[];
+/**
+ * @internal
+ *
+ * The sort scope as `[column, value]` pairs — the shape a lock key is derived
+ * from and a group is identified by. The value for each column comes from the
+ * caller, which decides whether it is reading the in-memory instance or a
+ * snapshot of the row.
+ */
+export declare function sortableScopeValues(dream: Dream, scope: string | string[] | undefined, valueForColumn: (column: string) => unknown): [string, unknown][];

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

@@ -0,0 +1,44 @@
+import Dream from '../../../../Dream.js';
+/**
+ * @internal
+ *
+ * Derives the advisory lock key that makes one sort scope's position
+ * computation exclusive. Every position-mutating path derives it the same way,
+ * since two paths that disagree about the key do not exclude each other.
+ *
+ * The key covers:
+ *
+ * - the **physical database name**, because Postgres advisory locks are scoped
+ *   to the cluster rather than to a database. Without it, two unrelated
+ *   databases in one cluster — including this repo's own parallel test
+ *   databases — would contend on the same key, and that contention shows up
+ *   only as writers of unrelated scopes queueing behind each other.
+ * - the table and the position field, since a model can declare several
+ *   sortable fields, each with its own position space.
+ * - the scope column values, which are what a "sort scope" actually is.
+ *
+ * Values are encoded structurally rather than joined into a string, so a null
+ * member is distinct from an empty string and no combination of delimiters in
+ * one member can be mistaken for a different tuple. They are also canonicalized
+ * against the column's database type (`canonicalScopeValue`), so a writer
+ * holding a pending JavaScript value and a writer holding the value Postgres
+ * hydrated derive one key rather than two.
+ *
+ * **Scope values are assumed non-adversarial.** The hash is FNV-1a, which is
+ * unkeyed: anyone who can choose a scope column's value — where that column
+ * holds user-supplied text rather than a foreign key — can compute a value
+ * whose key equals another scope's, and share that scope's lock with it. A
+ * collision costs contention and never correctness, since a shared lock
+ * over-serializes rather than under-locking, and the bounded wait
+ * (`sortableScopeLockTimeout`) caps what a deliberate one can achieve at
+ * stalls rather than at hangs. A keyed digest would make deliberate collisions
+ * expensive, and is not used: changing the derivation would give old and new
+ * processes different keys for one scope during a rolling deploy, which is the
+ * race this lock exists to eliminate.
+ *
+ * @param dream - the record whose scope is being locked
+ * @param positionField - the sortable position column
+ * @param scopeValues - `[column, value]` pairs for the scope being locked
+ * @returns a 64-bit signed key
+ */
+export default function sortableScopeLockKey(dream: Dream, positionField: string, scopeValues: [string, unknown][]): bigint;

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

@@ -0,0 +1,51 @@
+import Dream from '../../../../Dream.js';
+import { SortableFieldConfig } from '../Sortable.js';
+import { SortableSnapshots } from './sortableSnapshot.js';
+/**
+ * @internal
+ *
+ * The single key for the scope the record currently occupies — the scope its
+ * position is about to be computed within. Used by the position write itself,
+ * where the record already carries its final scope values.
+ */
+export declare function sortableScopeLockKeyForCurrentScope(dream: Dream, positionField: string, scope: string | string[] | undefined): bigint;
+/**
+ * @internal
+ *
+ * Every key a create's position work needs — one per sortable field, derived
+ * from the scope values the row now carries — sorted and deduplicated, so that
+ * a multi-sortable-field create acquires in the same global order as every
+ * other position-mutating operation. Declaration order cannot serve: the keys
+ * hash the runtime scope values, so which field's key sorts first varies from
+ * record to record.
+ */
+export declare function sortableCurrentScopeLockKeys(dream: Dream, configs: SortableFieldConfig[]): bigint[];
+/**
+ * @internal
+ *
+ * Every key a per-record position-mutating operation needs, sorted and
+ * deduplicated. A save that moves a record between sort scopes compacts the
+ * scope it leaves and makes room in the scope it enters, so it needs both keys;
+ * a save within one scope needs one, and so do a destroy and an undestroy, which
+ * write no scope values at all.
+ *
+ * The *new*-scope key comes from the values being written. The *old*-scope key
+ * comes from the database snapshot of the record's physical scope columns when
+ * one is available, and only falls back to the instance's pending changes when
+ * it is not — which is the case exactly once per save, on the first
+ * acquisition, because the snapshot cannot be read until something is locked.
+ * The caller closes that window by re-reading under the lock and calling this
+ * again with the snapshot; see `acquireStabilizedSortableScopeLocks`.
+ *
+ * A pending change is only an *old* scope when it has a previous persisted
+ * value. A record created earlier in this process reports every column as
+ * changed with `was === undefined` (`Dream#changes` compares against the
+ * pre-save state), which is not a scope the row was ever in: reading it as one
+ * would take a second, bogus lock — and, since every such record produces the
+ * same all-null scope tuple, it would be the *same* bogus key for every record
+ * in the table, serializing writers that touch unrelated scopes.
+ *
+ * Either way this must be called *before* the driver write overwrites the
+ * record's scope columns.
+ */
+export declare function sortableSaveLockKeys(dream: Dream, configs: SortableFieldConfig[], snapshots?: SortableSnapshots): bigint[];