@rvoh/dream 2.26.0 → 2.28.0

package/dist/cjs/src/decorators/field/sortable/helpers/resortAllRecords.js

@@ -1,35 +1,192 @@
-import getColumnForSortableScope from './getColumnForSortableScope.js';
-import isSortedCorrectly from './isSortedCorrectly.js';
-import scopeArray from './scopeArray.js';
+import { sql } from 'kysely';
+import Query from '../../../../dream/Query.js';
+import SortableRequiresAdvisoryTransactionLocks from '../../../../errors/SortableRequiresAdvisoryTransactionLocks.js';
+import { STI_SCOPE_NAME } from '../../../class/STI.js';
+import acquireSortableScopeLocks from './acquireSortableScopeLocks.js';
+import canonicalScopeValue from './canonicalScopeValue.js';
+import filterQueryToScopeValues from './filterQueryToScopeValues.js';
+import sortableScopeColumns from './sortableScopeColumns.js';
+import sortableScopeLockKey from './sortableScopeLockKey.js';
+/**
+ * The alias and column names the renumbering UPDATE joins its `row_number()`
+ * subquery on. They are namespaced so that no real column of the table being
+ * resorted can collide with them.
+ */
+const RENUMBER_ALIAS = 'dream_resort_renumber';
+const RENUMBER_PRIMARY_KEY = 'dream_resort_primary_key';
+const RENUMBER_POSITION = 'dream_resort_position';
+/**
+ * The aliases the one-row summary of a sort scope's positions comes back under.
+ * They are namespaced for the same reason the renumbering aliases are, and are
+ * lowercase without underscores so that Kysely's CamelCasePlugin passes them
+ * through untouched and each value can be read straight off the result row (the
+ * same alias strategy `pluck` and the grouped aggregates use).
+ */
+const SUMMARY_ROW_COUNT = 'dreamresortrowcount';
+const SUMMARY_DISTINCT_POSITIONS = 'dreamresortdistinctpositions';
+const SUMMARY_MIN_POSITION = 'dreamresortminposition';
+const SUMMARY_MAX_POSITION = 'dreamresortmaxposition';
+/**
+ * @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 async function resortAllRecords(dreamClass, positionField, scope) {
-    const dreams = await dreamClass.order({ [positionField]: 'asc' }).all();
-    const hash = {};
-    for (const dream of dreams) {
-        const foreignKeys = foreignKeysForScope(dream, scope);
-        hash[foreignKeys.join(':')] ||= [];
-        hash[foreignKeys.join(':')].push(dream);
-    }
-    for (const dreamArr of Object.values(hash)) {
-        const dreams = dreamArr;
-        if (isSortedCorrectly(dreams, positionField))
-            continue;
+    const queryDriverClass = Query.dbDriverClass(dreamClass.prototype.connectionName || 'default');
+    if (!queryDriverClass.supportsAdvisoryTransactionLocks)
+        throw new SortableRequiresAdvisoryTransactionLocks(queryDriverClass.name);
+    // every scope value, lock key and group identity below is derived from class
+    // level metadata — the table, the connection, the scope members' columns and
+    // their database types — so one bare instance stands in for every row
+    const derivationRecord = dreamClass.new();
+    for (const scopeValues of await discoverSortScopes(dreamClass, derivationRecord, scope)) {
         await dreamClass.transaction(async (txn) => {
-            let counter = 1;
-            for (const dream of dreams) {
-                await dreamClass
-                    .txn(txn)
-                    .where({ [dream['_primaryKey']]: dream.primaryKeyValue() })
-                    .toKysely('update')
-                    .set({
-                    [positionField]: counter++,
-                })
-                    .execute();
-            }
+            await acquireSortableScopeLocks(derivationRecord, txn, [
+                sortableScopeLockKey(derivationRecord, positionField, scopeValues),
+            ]);
+            if (await scopeIsAlreadyOrdered({ dreamClass, derivationRecord, positionField, scope, scopeValues, txn }))
+                return;
+            await renumberScope({ dreamClass, derivationRecord, positionField, scope, scopeValues, txn });
         });
     }
 }
-function foreignKeysForScope(dream, scope) {
-    return scopeArray(scope)
-        .map(singleScope => getColumnForSortableScope(dream, singleScope))
-        .map(fk => dream[fk]);
+/**
+ * Every physical sort scope the table currently holds, as the `[column, value]`
+ * tuples a lock key is derived from.
+ *
+ * One distinct read over the scope columns alone, which both bounds the cost —
+ * a single round trip returning one row per sort scope, however many rows the
+ * table holds — and makes the answer stable: a walk that windows the table can
+ * be shifted past rows by a concurrent delete, and a sort scope whose only rows
+ * fall in that gap would never be renumbered at all. Each discovered scope's
+ * rows are read again under its own lock before anything is written.
+ *
+ * A sortable field with no scope has exactly one sort scope, the whole table,
+ * so its answer needs no read.
+ */
+async function discoverSortScopes(dreamClass, derivationRecord, scope) {
+    const columns = sortableScopeColumns(derivationRecord, scope);
+    if (columns.length === 0)
+        return [[]];
+    const rows = (await stiUnscopedQuery(dreamClass)
+        .toKysely('select')
+        .clearSelect()
+        .distinct()
+        .select(columns)
+        .execute());
+    // the database's `distinct` is by raw value; two raw values the column's type
+    // treats as one (a citext scope column matching case-insensitively) are one
+    // sort scope under one lock key, and canonicalization is what says so
+    const sortScopes = new Map();
+    for (const row of rows) {
+        const scopeValues = columns.map((column) => [column, row[column]]);
+        const identity = scopeIdentity(derivationRecord, scopeValues);
+        if (!sortScopes.has(identity))
+            sortScopes.set(identity, scopeValues);
+    }
+    return [...sortScopes.values()];
+}
+/**
+ * Whether the sort scope already runs 1..n, decided inside the scope's lock by
+ * one aggregate row rather than by shipping every position in the scope to the
+ * client: a sort scope can hold as many rows as the table does, and this runs
+ * with the scope's lock held.
+ *
+ * A scope of `n` rows is already correct exactly when its positions are `n`
+ * distinct non-null values running from 1 to n. `count(distinct position)`
+ * drops both duplicates and nulls, so it agrees with `count(*)` only when every
+ * row holds a position of its own, and `min`/`max` pin that set to 1..n. An
+ * empty scope — one whose last row was destroyed between its discovery and this
+ * lock — has nothing to renumber.
+ */
+async function scopeIsAlreadyOrdered({ dreamClass, derivationRecord, positionField, scope, scopeValues, txn, }) {
+    const summary = (await scopedSelect({ dreamClass, derivationRecord, scope, scopeValues, txn })
+        .clearSelect()
+        .select([
+        sql `count(*)`.as(SUMMARY_ROW_COUNT),
+        sql `count(distinct ${sql.ref(positionField)})`.as(SUMMARY_DISTINCT_POSITIONS),
+        sql `min(${sql.ref(positionField)})`.as(SUMMARY_MIN_POSITION),
+        sql `max(${sql.ref(positionField)})`.as(SUMMARY_MAX_POSITION),
+    ])
+        .executeTakeFirstOrThrow());
+    // counts come back from some drivers as strings, since a count is a bigint
+    const rowCount = Number(summary[SUMMARY_ROW_COUNT]);
+    if (rowCount === 0)
+        return true;
+    return (Number(summary[SUMMARY_DISTINCT_POSITIONS]) === rowCount &&
+        Number(summary[SUMMARY_MIN_POSITION]) === 1 &&
+        Number(summary[SUMMARY_MAX_POSITION]) === rowCount);
+}
+/**
+ * Renumbers the whole sort scope in one statement, from a `row_number()` taken
+ * over the scope's rows ordered by position, nulls first, ties broken by
+ * primary key. A row already holding the position it is owed is left alone, so
+ * a scope with a single gap in it writes a single row rather than all of them.
+ */
+async function renumberScope({ dreamClass, derivationRecord, positionField, scope, scopeValues, txn, }) {
+    const table = derivationRecord.table;
+    const primaryKey = derivationRecord['_primaryKey'];
+    const renumbered = scopedSelect({ dreamClass, derivationRecord, scope, scopeValues, txn })
+        .clearSelect()
+        .select([
+        sql.ref(primaryKey).as(RENUMBER_PRIMARY_KEY),
+        sql `row_number() over (order by ${sql.ref(positionField)} asc nulls first, ${sql.ref(primaryKey)} asc)`.as(RENUMBER_POSITION),
+    ]);
+    await stiUnscopedQuery(dreamClass)
+        .txn(txn)
+        .toKysely('update')
+        .from(renumbered.as(RENUMBER_ALIAS))
+        .set({ [positionField]: sql.ref(`${RENUMBER_ALIAS}.${RENUMBER_POSITION}`) })
+        .whereRef(`${table}.${primaryKey}`, '=', `${RENUMBER_ALIAS}.${RENUMBER_PRIMARY_KEY}`)
+        .where(sql.ref(`${table}.${positionField}`), 'is distinct from', sql.ref(`${RENUMBER_ALIAS}.${RENUMBER_POSITION}`))
+        .execute();
+}
+/**
+ * A kysely select over the rows of one physical sort scope, carrying the
+ * model's default scopes (a soft-deleted row is not part of any sort scope) but
+ * not the STI scope, and matching a null scope member with `is null`.
+ */
+function scopedSelect({ dreamClass, derivationRecord, scope, scopeValues, txn, }) {
+    const values = new Map(scopeValues);
+    return filterQueryToScopeValues(derivationRecord, stiUnscopedQuery(dreamClass).txn(txn).toKysely('select'), column => values.get(column) ?? null, scope);
+}
+function stiUnscopedQuery(dreamClass) {
+    return dreamClass.query().removeDefaultScope(STI_SCOPE_NAME);
+}
+/**
+ * A collision-free identity for a physical sort scope. Values are canonicalized
+ * against the column's database type by the same function the advisory lock key
+ * uses (null distinct from every string, a pending value agreeing with its
+ * hydrated counterpart) and encoded structurally, so two distinct tuples can
+ * never share an identity and a scope can never disagree with its own lock.
+ */
+function scopeIdentity(derivationRecord, scopeValues) {
+    return JSON.stringify(scopeValues.map(([column, value]) => [column, canonicalScopeValue(derivationRecord, column, value)]));
 }

package/dist/cjs/src/decorators/field/sortable/helpers/setPosition.js

@@ -1,62 +1,116 @@
-import DreamApp from '../../../../dream-app/index.js';
-import PostgresQueryDriver from '../../../../dream/QueryDriver/Postgres.js';
 import range from '../../../../helpers/range.js';
-import getColumnForSortableScope from './getColumnForSortableScope.js';
-import scopeArray from './scopeArray.js';
+import ops from '../../../../ops/index.js';
+import acquireSortableScopeLocks from './acquireSortableScopeLocks.js';
+import canonicalScopeValue from './canonicalScopeValue.js';
+import filterQueryToScopeValues from './filterQueryToScopeValues.js';
+import sortableScopeColumns from './sortableScopeColumns.js';
+import { sortableScopeLockKeyForCurrentScope } from './sortableScopeLockKeys.js';
+import { invalidateSortableRowCache } from './sortableRowCache.js';
+import { snapshotScopeValue } from './sortableSnapshot.js';
 import validPosition from './validPosition.js';
 export default async function setPosition(obj) {
     const { dream, txn } = obj;
-    if (txn) {
-        await applyUpdates({ ...obj, txn });
-        await dream.txn(txn).reload();
-    }
-    else {
-        await dream.constructor.transaction(async (txn) => {
-            await applyUpdates({ ...obj, txn });
-            await dream.txn(txn).reload();
-        });
-    }
+    await applyUpdates(obj);
+    await dream.txn(txn).reload();
 }
 async function applyUpdates(obj) {
-    const position = await validPosition(obj);
-    await updateConflictingRecords({ ...obj, position });
-    await updatePositionForRecord({ ...obj, position });
+    const { dream, positionField, scope, txn } = obj;
+    // Serialize every writer of this sort scope for the rest of the transaction,
+    // before the first position read. The operation-level phase has already
+    // acquired this key in its one sorted pass over every sortable field's keys
+    // (performSortablePositionWork on create; saveDream, before the driver
+    // write, on update), so this asks for a key the transaction holds and issues
+    // no statement at all.
+    await acquireSortableScopeLocks(dream, txn, [
+        sortableScopeLockKeyForCurrentScope(dream, positionField, scope),
+    ]);
+    // A pending scope change that lands on the scope the row already physically
+    // occupies moves the record between no scopes at all, and the rest of the
+    // write has to see it that way: the scope being vacated *is* the destination,
+    // so one source computes a new position from a max the other is about to
+    // shift out from under it. The record still counts toward the destination's
+    // extent — its row is in the scope, holding the position sentinel in place of
+    // the position the snapshot read — so the position write carries that
+    // position through to the clamp, and a record that was already last in the
+    // scope stays last rather than swapping with the record below it.
+    const write = alreadyInDestinationScope(obj)
+        ? { ...obj, changingScope: false, positionUnderSentinel: obj.previousPosition }
+        : obj;
+    const position = await validPosition(write);
+    await updateConflictingRecords({ ...write, position });
+    await updatePositionForRecord({ ...write, position });
+    // the shift above moved rows this transaction may be holding preflight reads
+    // of — every position a locked batch's later records were read with is now a
+    // position they no longer have
+    invalidateSortableRowCache(txn);
+}
+/**
+ * Whether a save that means to change sort scope is really a move within one
+ * scope: the snapshot read under the lock says the row already sits in the
+ * scope the instance is being written into, so nothing joins the destination
+ * and nothing is left behind.
+ *
+ * Values are compared through `canonicalScopeValue`, the same normalization the
+ * advisory lock key is derived from, so two shapes of one physical value — the
+ * pending `'1.00'` and the hydrated `1` — are one scope here exactly as they
+ * are when the key is taken.
+ *
+ * A row whose snapshot position is null holds no position in that scope, so it
+ * is joining the destination's position space and remains a scope change.
+ */
+function alreadyInDestinationScope({ changingScope, dream, previousPosition, scope, snapshot, }) {
+    if (!changingScope || snapshot === undefined)
+        return false;
+    if (previousPosition === undefined || previousPosition === null)
+        return false;
+    const columns = sortableScopeColumns(dream, scope);
+    if (!columns.length)
+        return false;
+    return columns.every(column => snapshot.scopeValues.has(column) &&
+        canonicalScopeValue(dream, column, snapshot.scopeValues.get(column)) ===
+            canonicalScopeValue(dream, column, dream[column]));
 }
 async function updateConflictingRecords(obj) {
-    const { wasNewRecord, position, previousPosition, dream, positionField, query, scope, txn, changingScope } = obj;
+    const { wasNewRecord, position, previousPosition, dream, positionField, query, scope, txn, changingScope, snapshot, } = obj;
+    // A scope move spans two unrelated position spaces: `previousPosition` is a
+    // position in the scope being left, `position` one in the scope being
+    // entered. Only the scope being left is compacted here, and it compacts all
+    // the way up — bounding it by a position from the other space closes nothing
+    // at all whenever the destination is the smaller of the two, leaving a
+    // permanent hole. The destination needs no room made: a scope-changing save
+    // always lands at the end of it, because `afterSortableUpdate` passes no
+    // position and `validPosition` then returns the destination's max + 1.
+    //
+    // A record with no position to vacate — a soft-deleted row, whose position
+    // column is NULL — leaves the scope it is moving out of untouched.
+    if (changingScope && (previousPosition === undefined || previousPosition === null))
+        return;
     const increasing = changingScope ||
         position === undefined ||
         (previousPosition !== undefined && previousPosition !== null && previousPosition < position);
+    const conflictingPositions = changingScope
+        ? ops.greaterThanOrEqualTo(previousPosition)
+        : increasing
+            ? range(previousPosition, position)
+            : range(position, previousPosition);
     let kyselyQuery = query
         .txn(txn)
         .whereNot({ [dream['_primaryKey']]: dream.primaryKeyValue() })
         .where({
-        [positionField]: increasing ? range(previousPosition, position) : range(position, previousPosition),
+        [positionField]: conflictingPositions,
     })
         .toKysely('update')
         .set((eb) => ({
         [positionField]: eb(positionField, increasing ? '-' : '+', 1),
     }));
-    kyselyQuery = applySortableScopesToQuery(dream, kyselyQuery, column => !wasNewRecord && dream.savedChangeToAttribute(column)
+    // the range being compacted belongs to the scope the record is *leaving*, so
+    // the filter has to name that scope's real column values — the snapshot read
+    // under the lock before the write, not what the instance remembers
+    kyselyQuery = filterQueryToScopeValues(dream, kyselyQuery, column => snapshotScopeValue(snapshot, column, () => !wasNewRecord && dream.savedChangeToAttribute(column)
         ? (dream.changes()[column]?.was ?? dream[column])
-        : dream[column], scope);
+        : dream[column]), scope);
     await kyselyQuery.execute();
 }
-export function applySortableScopesToQuery(dream, kyselyQuery, whereValueCB, scope) {
-    for (const singleScope of scopeArray(scope)) {
-        const column = getColumnForSortableScope(dream, singleScope);
-        if (column) {
-            const columnValue = whereValueCB(column);
-            if (columnValue === null) {
-                kyselyQuery = kyselyQuery.where(column, 'is', null);
-            }
-            else {
-                kyselyQuery = kyselyQuery.where(column, '=', columnValue);
-            }
-        }
-    }
-    return kyselyQuery;
-}
 async function updatePositionForRecord(obj) {
     const { txn, dream, positionField, position } = obj;
     await txn.kyselyTransaction
@@ -67,13 +121,3 @@ async function updatePositionForRecord(obj) {
     })
         .execute();
 }
-export function getPostgresQueryDriver(connectionName) {
-    const queryDriverClass = DreamApp.getOrFail().dbConnectionQueryDriverClass(connectionName);
-    if (!(queryDriverClass === PostgresQueryDriver)) {
-        throw new Error(`
-      ${queryDriverClass.name} is not an instance of PostgresQueryDriver.
-      You must be using the PostgresQueryDriver when leveraging the Sortable decorator
-      `);
-    }
-    return queryDriverClass;
-}

package/dist/cjs/src/decorators/field/sortable/helpers/sortableRowCache.js

@@ -0,0 +1,73 @@
+// The cached rows of every live transaction, keyed by the `DreamTransaction`
+// object itself. Module-level state is safe here because the key is an object
+// identity: every transaction — including a nested one — is its own
+// `DreamTransaction` instance, so no lookup can ever see rows stashed by
+// another transaction, whatever request or async flow it belongs to. The keys
+// are held weakly, so an entry becomes collectible with its transaction and
+// nothing accumulates for the life of the process. (The lock ledger in
+// `heldSortableScopeLockKeys.ts` relies on the same properties.)
+const rowsByTransaction = new WeakMap();
+// a JSON tuple rather than a joined string, so that no table name and no
+// primary key value can combine into another pair's key
+function cacheKey(table, primaryKeyValue) {
+    return JSON.stringify([table, String(primaryKeyValue)]);
+}
+/**
+ * @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 function cacheSortableRowsReadUnderLock(txn, table, primaryKey, rows) {
+    rowsByTransaction.set(txn, new Map(rows.map(row => [cacheKey(table, row[primaryKey]), row])));
+}
+/**
+ * @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 function takeCachedSortableRow(txn, table, primaryKeyValue) {
+    const rows = rowsByTransaction.get(txn);
+    if (!rows)
+        return undefined;
+    const key = cacheKey(table, primaryKeyValue);
+    const row = rows.get(key);
+    rows.delete(key);
+    return row;
+}
+/**
+ * @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 function invalidateSortableRowCache(txn) {
+    rowsByTransaction.delete(txn);
+}

package/dist/cjs/src/decorators/field/sortable/helpers/sortableScopeColumns.js

@@ -0,0 +1,42 @@
+import getColumnForSortableScope from './getColumnForSortableScope.js';
+import scopeArray from './scopeArray.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 function sortableScopeColumnPairs(dream, scope) {
+    return scopeArray(scope).reduce((acc, singleScope) => {
+        const column = getColumnForSortableScope(dream, singleScope);
+        if (column)
+            acc.push([singleScope, column]);
+        return acc;
+    }, []);
+}
+/**
+ * @internal
+ *
+ * The database columns a sortable field's scope resolves to.
+ */
+export default function sortableScopeColumns(dream, scope) {
+    return sortableScopeColumnPairs(dream, scope).map(([, column]) => column);
+}
+/**
+ * @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 function sortableScopeValues(dream, scope, valueForColumn) {
+    return sortableScopeColumns(dream, scope).map(column => [column, valueForColumn(column)]);
+}

package/dist/cjs/src/decorators/field/sortable/helpers/sortableScopeLockKey.js

@@ -0,0 +1,99 @@
+import DreamApp from '../../../../dream-app/index.js';
+import canonicalScopeValue from './canonicalScopeValue.js';
+const FNV_OFFSET_BASIS = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x100000001b3n;
+const UINT64_MASK = 0xffffffffffffffffn;
+const INT64_SIGN_BIT = 0x8000000000000000n;
+const UINT64_MODULUS = 0x10000000000000000n;
+const UTF8 = new TextEncoder();
+/**
+ * The hash of the part of the key that cannot vary for one sortable field —
+ * database, table, position field — so that a path deriving a key per row, per
+ * field, per stabilization round only ever serializes and hashes the scope
+ * values. Keyed by the serialization of those three, so a `DreamApp` whose
+ * database name changes derives a new key rather than reusing a stale one.
+ */
+const invariantPrefixHashes = new Map();
+/**
+ * @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, positionField, scopeValues) {
+    const databaseName = DreamApp.getOrFail().dbName(dream.connectionName || 'default', 'primary');
+    const normalizedScopeValues = [...scopeValues]
+        .sort(([columnA], [columnB]) => (columnA < columnB ? -1 : columnA > columnB ? 1 : 0))
+        .map(([column, value]) => [column, canonicalScopeValue(dream, column, value)]);
+    // the hashed text is exactly
+    // `JSON.stringify([databaseName, table, positionField, normalizedScopeValues])`,
+    // hashed in two halves so the invariant half is hashed once per sortable
+    // field rather than once per row. FNV-1a is a streaming hash, so resuming
+    // from the cached state gives the same key byte for byte
+    return toSignedKey(fnv1a64(JSON.stringify(normalizedScopeValues) + ']', invariantPrefixHash(databaseName, dream.table, positionField)));
+}
+function invariantPrefixHash(databaseName, table, positionField) {
+    // the serialization of the first three members, with the array's closing
+    // bracket replaced by the separator the scope values follow. It is also the
+    // memo key: a JSON array of the three members is unambiguous, where any
+    // joined form would need a delimiter no member could contain
+    const prefix = JSON.stringify([databaseName, table, positionField]).slice(0, -1) + ',';
+    const cached = invariantPrefixHashes.get(prefix);
+    if (cached !== undefined)
+        return cached;
+    const hash = fnv1a64(prefix, FNV_OFFSET_BASIS);
+    invariantPrefixHashes.set(prefix, hash);
+    return hash;
+}
+/**
+ * 64-bit FNV-1a, resumed from a previously hashed prefix.
+ */
+function fnv1a64(value, hash) {
+    for (const byte of UTF8.encode(value)) {
+        hash = ((hash ^ BigInt(byte)) * FNV_PRIME) & UINT64_MASK;
+    }
+    return hash;
+}
+/**
+ * Folds the unsigned hash into the signed range Postgres's
+ * `pg_advisory_xact_lock(bigint)` accepts.
+ */
+function toSignedKey(hash) {
+    return hash >= INT64_SIGN_BIT ? hash - UINT64_MODULUS : hash;
+}