uql-orm 0.76.0 → 0.77.1

package/dist/dialect/queryJoins.js

@@ -1,5 +1,6 @@
 import { getMeta, relationOf } from '../entity/index.js';
 import { getKeys, getRelationRequestSummary, hasKeys, isRecord, isToManyRelation, isVectorSearch, parseRelationAtKey, parseRelationSize, parseSortByCount, } from '../util/index.js';
+import { UqlUsageError } from '../util/uqlError.js';
 export const NO_JOINS = new Map();
 /**
  * What the statement joins, from `$populate` and from a `$sort` by a to-one relation's field, so the
@@ -49,7 +50,7 @@ export function groupPathField(joins, path) {
     }
     const join = joins.get(path.slice(0, -1).join('.'));
     if (!join) {
-        throw new TypeError(`cannot $group by '${path.join('.')}': only a to-one relation's field groups, since a to-many multiplies the rows it joins`);
+        throw new UqlUsageError(`cannot $group by '${path.join('.')}': only a to-one relation's field groups, since a to-many multiplies the rows it joins`);
     }
     return { key, join };
 }
@@ -149,14 +150,14 @@ function addPathJoins(joins, claimAlias, meta, map, required, parent) {
 /** The join a sort may address at `path` with the relation's own sort map, or why it may not; `unjoinable` is the dialect's remedy. */
 export function resolveSortableJoin(relation, path, value, joins, unjoinable) {
     if (isToManyRelation(relation)) {
-        throw new TypeError(`cannot $sort by '${path}': a parent has many of them, so there is no single value to order by. Sort the relation's own rows inside $populate instead.`);
+        throw new UqlUsageError(`cannot $sort by '${path}': a parent has many of them, so there is no single value to order by. Sort the relation's own rows inside $populate instead.`);
     }
     if (!isSortMap(value)) {
-        throw new TypeError(`$sort by relation '${path}' expects a map of its fields, got ${String(value)}`);
+        throw new UqlUsageError(`$sort by relation '${path}' expects a map of its fields, got ${String(value)}`);
     }
     const join = joins.get(path);
     if (!join) {
-        throw new TypeError(unjoinable);
+        throw new UqlUsageError(unjoinable);
     }
     return { join, sort: value };
 }
@@ -177,7 +178,7 @@ export function relationSortTerms(relKey, path, value) {
             return [];
         }
         if (search.$project !== undefined) {
-            throw new TypeError(`cannot $project the distance of relation '${path}': it ranks the parent, and no one row answers under it`);
+            throw new UqlUsageError(`cannot $project the distance of relation '${path}': it ranks the parent, and no one row answers under it`);
         }
         return [{ spec: { relation: relKey, op: '$min', field, search }, direction: undefined }];
     });

package/dist/dialect/vectorSqlDialect.js

@@ -1,5 +1,6 @@
 import { unsupportedVectorMetric } from '../type/vector.js';
 import { findVectorIndex, findVectorSort, vectorCandidates, vectorDistanceOf } from '../util/dialect.util.js';
+import { UqlUsageError } from '../util/uqlError.js';
 import { AbstractDialect } from './abstractDialect.js';
 import { encodeFloat32s } from './vectorCast.js';
 /**
@@ -70,7 +71,7 @@ export class VectorSqlDialect extends AbstractDialect {
      */
     appendVectorDistance(ctx, meta, key, search, prefix) {
         if (this.vectorMetrics.size === 0) {
-            throw new TypeError(`${this.dialectName} does not support vector similarity search. Use raw() for vector queries.`);
+            throw new UqlUsageError(`${this.dialectName} does not support vector similarity search. Use raw() for vector queries.`);
         }
         const { colName, distance, field } = this.resolveVectorDistance(meta, key, search);
         const metric = this.vectorMetrics.get(distance);

package/dist/http/query.js

@@ -5,6 +5,8 @@ import { QUERY_BOOLEAN_CLAUSES, QUERY_NUMBER_CLAUSES, QUERY_OBJECT_CLAUSES, QUER
 import { RAW_VALUE } from '../type/queryRaw.js';
 // the specific util module, not the barrel, so the browser bundle does not pull in entity metadata
 import { getKeys, isWhereMap } from '../util/object.util.js';
+// the error class alone, from its own leaf module: `queryError.ts` carries every driver's code map
+import { UqlUsageError } from '../util/uqlError.js';
 /**
  * Keys accepted from the wire - query structure ({@link Query}) plus the `hardDelete`/`count` scalar
  * flags. Anything else (e.g. `filters`, `context`, `$entity`) is dropped so a remote client can't
@@ -35,7 +37,7 @@ export function parseQueryParams(params = {}) {
     const query = {};
     for (const key of getKeys(params)) {
         if (REJECTED_QUERY_KEYS.has(key)) {
-            throw Object.assign(new TypeError(`'${key}' is not supported over HTTP`), { status: 400 });
+            throw new UqlUsageError(`'${key}' is not supported over HTTP`);
         }
         if (ALLOWED_QUERY_KEYS.has(key)) {
             query[key] = params[key];
@@ -54,7 +56,7 @@ export function parseQueryParams(params = {}) {
     }
     query['$where'] ??= {};
     if (!isWhereMap(query['$where'])) {
-        throw Object.assign(new TypeError("'$where' must be a JSON object"), { status: 400 });
+        throw new UqlUsageError("'$where' must be a JSON object");
     }
     // A query string carries every value as text, so what decodes a clause is the shape its group
     // declares. `'false'` is the reason the boolean pass exists rather than the raw value being taken:

package/dist/index.d.ts

@@ -8,3 +8,4 @@ export { withDeleted } from './util/filters.util.js';
 export type { HookContext } from './util/hook.util.js';
 export { DefaultLogger } from './util/logger.js';
 export { raw, refs } from './util/raw.js';
+export * from './util/uqlError.js';

package/dist/index.js

@@ -7,3 +7,4 @@ export * from './type/index.js';
 export { withDeleted } from './util/filters.util.js';
 export { DefaultLogger } from './util/logger.js';
 export { raw, refs } from './util/raw.js';
+export * from './util/uqlError.js';

package/dist/maria/mariaDialect.js

@@ -1,6 +1,6 @@
 import { relationTermKey } from '../dialect/abstractSqlDialect.js';
 import { jsonPath } from '../dialect/jsonSql.js';
-import { MYSQL_FEATURES, MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
+import { MYSQL_FEATURES, MYSQL_ROW_LOCKS, MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
 import { getMeta } from '../entity/index.js';
 import { columnFamily } from '../util/field.util.js';
 export class MariaDialect extends MysqlLikeSqlDialect {
@@ -18,7 +18,7 @@ export class MariaDialect extends MysqlLikeSqlDialect {
         vectorBytes: true,
         vectorIndexRequiresNotNull: true,
         indexIfNotExists: true,
-        rowLockOf: false,
+        rowLocks: { ...MYSQL_ROW_LOCKS, of: false },
     };
     /**
      * A derived table here reads no column of the statement around it, so the aggregate reads the

package/dist/mongo/mongoDialect.d.ts

@@ -95,12 +95,6 @@ export declare class MongoDialect extends AbstractDialect {
     private static compareCount;
     /** Whether a query subtracts `key` from the projection, via `$exclude` or a negative `$select`. */
     private subtractsKey;
-    /**
-     * MongoDB has no row-level lock to map `$lock` onto: its concurrency control is the transaction
-     * plus atomic document updates. Rejected rather than ignored, like `raw()` below, since a dropped
-     * lock silently removes the mutual exclusion the caller asked for.
-     */
-    assertNoLock<E>(q: Query<E>): void;
     /** `raw()` renders SQL, so it has no MongoDB equivalent - say so instead of emitting `{}`. */
     private assertNoRaw;
     /**

package/dist/mongo/mongoDialect.js

@@ -6,6 +6,7 @@ import { assertSoleId, fieldOf, getMeta, relationOf, soleIdOf } from '../entity/
 import { COUNT_RESULT_KEY } from '../type/query.js';
 import { QueryRaw } from '../type/queryRaw.js';
 import { aggregateOf, asSelectMap, assertAggregateColumns, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fieldUpdateOf, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, rankedTextSearch, someKey, targetKeyColumns, textSortOf, vectorDistanceOf, } from '../util/index.js';
+import { UqlUsageError } from '../util/uqlError.js';
 import { decodeBigIntsExcept } from '../util/wideNumber.js';
 import { textLanguage } from './textLanguage.js';
 import { vectorDistanceExpr } from './vectorDistance.js';
@@ -30,6 +31,7 @@ export const mongoDialectFeatures = {
     supportsUnsigned: false,
     serverSideCursors: false,
     correlatedWrites: false,
+    rowLocks: false, // its concurrency control is the transaction plus atomic document updates
 };
 /** What `toWireId` converts: the hex spelling of an `ObjectId`, and nothing looser. */
 const HEX_24 = /^[0-9a-f]{24}$/i;
@@ -109,7 +111,7 @@ export class MongoDialect extends AbstractDialect {
             else if (meta.relations[key]) {
                 this.assertNoRaw(val);
                 if (!lookups) {
-                    throw new TypeError(`filtering by relation '${key}' is not supported here on MongoDB`);
+                    throw new UqlUsageError(`filtering by relation '${key}' is not supported here on MongoDB`);
                 }
                 this.appendRelationLookup(filter, meta, key, val, lookups);
             }
@@ -118,7 +120,7 @@ export class MongoDialect extends AbstractDialect {
                 this.assertKnownPathRoot(meta, key);
                 if (aggregateOf(meta.fields[key])) {
                     if (!lookups) {
-                        throw new TypeError(`filtering by relation aggregate '${key}' is not supported here on MongoDB`);
+                        throw new UqlUsageError(`filtering by relation aggregate '${key}' is not supported here on MongoDB`);
                     }
                     this.appendAggregateField(meta, key, lookups);
                 }
@@ -270,7 +272,7 @@ export class MongoDialect extends AbstractDialect {
             ? [{ $gte: [count, bound[0]] }, { $lte: [count, bound[1]] }]
             : [{ [op]: [count, bound] }]);
         if (!comparisons.length) {
-            throw new TypeError('$size needs at least one comparison');
+            throw new UqlUsageError('$size needs at least one comparison');
         }
         return comparisons.length === 1 ? comparisons[0] : { $and: comparisons };
     }
@@ -279,20 +281,10 @@ export class MongoDialect extends AbstractDialect {
         const at = (map) => map?.[key];
         return at(exclude) === true || at(select) === false;
     }
-    /**
-     * MongoDB has no row-level lock to map `$lock` onto: its concurrency control is the transaction
-     * plus atomic document updates. Rejected rather than ignored, like `raw()` below, since a dropped
-     * lock silently removes the mutual exclusion the caller asked for.
-     */
-    assertNoLock(q) {
-        if (q.$lock) {
-            throw new TypeError('$lock (row-level locking) is not supported on MongoDB');
-        }
-    }
     /** `raw()` renders SQL, so it has no MongoDB equivalent - say so instead of emitting `{}`. */
     assertNoRaw(value) {
         if (value instanceof QueryRaw) {
-            throw new TypeError('raw() in $where is not supported on MongoDB');
+            throw new UqlUsageError('raw() in $where is not supported on MongoDB');
         }
     }
     /**
@@ -305,7 +297,7 @@ export class MongoDialect extends AbstractDialect {
         if (root === MongoDialect.ID_KEY || meta.fields[root]) {
             return;
         }
-        throw new TypeError(`path ${key} does not exist in ${entityName(meta)}`);
+        throw new UqlUsageError(`path ${key} does not exist in ${entityName(meta)}`);
     }
     /** String operators -> { pattern: (v) => regex, caseInsensitive } */
     static REGEX_OP_MAP = new Map([
@@ -383,7 +375,7 @@ export class MongoDialect extends AbstractDialect {
                 case '$near':
                     // Atlas offers only a similarity threshold, on the index's own scale, which UQL neither emits nor
                     // reads: converting a distance would mean guessing the metric, so this refuses.
-                    throw new TypeError('$near is not supported on MongoDB: Atlas scores by index-defined similarity, not distance. ' +
+                    throw new UqlUsageError('$near is not supported on MongoDB: Atlas scores by index-defined similarity, not distance. ' +
                         "Project the score with $sort's $project and filter on it instead.");
                 default:
                     result[op] = val;
@@ -430,7 +422,7 @@ export class MongoDialect extends AbstractDialect {
             return {};
         }
         if (Array.isArray(select)) {
-            throw new TypeError('raw $select is not supported on MongoDB');
+            throw new UqlUsageError('raw $select is not supported on MongoDB');
         }
         const selectMap = asSelectMap(select);
         // Projected by column, not by field key; `normalizeId` maps them back on the way out.
@@ -497,7 +489,7 @@ export class MongoDialect extends AbstractDialect {
             const relation = meta.relations[key];
             if (key === '$text') {
                 if (path) {
-                    throw new TypeError(`$sort by $text is only supported on the queried entity, not on relation '${path.slice(0, -1)}'`);
+                    throw new UqlUsageError(`$sort by $text is only supported on the queried entity, not on relation '${path.slice(0, -1)}'`);
                 }
                 const { order, project } = textSortOf(sort);
                 out[project ?? TEXT_SCORE_ALIAS] = sortDirection(order);
@@ -508,7 +500,7 @@ export class MongoDialect extends AbstractDialect {
                 // so one reaching it is a second. `sortDirection` would read the operator object as "ascending"
                 // and order by the raw vector column instead, a silent answer where the caller asked for a rank.
                 if (isVectorSearch(value)) {
-                    throw new TypeError(`cannot $sort by a second vector '${key}' on MongoDB: $vectorSearch ranks by one`);
+                    throw new UqlUsageError(`cannot $sort by a second vector '${key}' on MongoDB: $vectorSearch ranks by one`);
                 }
                 const docPath = path + this.pathOf(meta, key);
                 const nulls = sortNulls(value);
@@ -530,7 +522,7 @@ export class MongoDialect extends AbstractDialect {
                 // own pipeline has: a nested one is built inside its parent's `$lookup`, where there is no
                 // parent document left to hang it off.
                 if (path) {
-                    throw new TypeError(`$sort by '${relPath}.${spec.field ?? '$count'}' is only supported on the queried entity`);
+                    throw new UqlUsageError(`$sort by '${relPath}.${spec.field ?? '$count'}' is only supported on the queried entity`);
                 }
                 if (spec.search) {
                     nearest[sortAggregateField(spec)] = 1;
@@ -773,10 +765,10 @@ export class MongoDialect extends AbstractDialect {
         // that reads a lookup those columns do not carry. Refused rather than answered all-equal, and in
         // the same terms the SQL dialects refuse `SELECT DISTINCT` ordered by an unselected column.
         if (q.$distinct && aggregated.fields.length) {
-            throw new TypeError(`cannot $sort by a relation's aggregate with $distinct: the grouping keeps only the columns it projects`);
+            throw new UqlUsageError(`cannot $sort by a relation's aggregate with $distinct: the grouping keeps only the columns it projects`);
         }
         if (q.$distinct && sortOnly.length) {
-            throw new TypeError(`cannot $sort by relation '${sortOnly[0]}' with $distinct unless '${sortOnly[0]}' is populated: the grouping keeps only the columns it projects`);
+            throw new UqlUsageError(`cannot $sort by relation '${sortOnly[0]}' with $distinct unless '${sortOnly[0]}' is populated: the grouping keeps only the columns it projects`);
         }
         // `$distinct` inverts the usual order twice over: the projection decides which columns make two
         // rows the same, so it has to run *before* the grouping, and the grouping collapses rows, so the
@@ -1141,7 +1133,7 @@ export class MongoDialect extends AbstractDialect {
      */
     buildGroupSpec(meta, groupEntries, joins) {
         if (!groupEntries.length) {
-            throw new TypeError('aggregate requires at least one $group column or $select function');
+            throw new UqlUsageError('aggregate requires at least one $group column or $select function');
         }
         const groupId = {};
         const accumulators = {};
@@ -1204,7 +1196,7 @@ export class MongoDialect extends AbstractDialect {
             return this.columnOf(meta, key);
         }
         if (aggregateOf(join.meta.fields[key])) {
-            throw new TypeError(`cannot $group by '${path.join('.')}' on MongoDB: a joined row's relation aggregate is not read`);
+            throw new UqlUsageError(`cannot $group by '${path.join('.')}' on MongoDB: a joined row's relation aggregate is not read`);
         }
         return `${join.path}.${this.columnOf(join.meta, key)}`;
     }
@@ -1221,14 +1213,14 @@ export class MongoDialect extends AbstractDialect {
                 const { join, negate } = MongoDialect.GROUP_OPS[key];
                 const clauses = MongoDialect.groupClauses(key, where[key]).map((clause) => {
                     if (clause instanceof QueryRaw) {
-                        throw new TypeError('raw SQL is not supported in an aggregate $where on MongoDB');
+                        throw new UqlUsageError('raw SQL is not supported in an aggregate $where on MongoDB');
                     }
                     return this.whereExpression(meta, clause, named);
                 });
                 return negate ? { $not: [{ [join]: clauses }] } : { [join]: clauses };
             }
             if (key.startsWith('$')) {
-                throw new TypeError(`aggregate $where operator '${key}' is not supported on MongoDB`);
+                throw new UqlUsageError(`aggregate $where operator '${key}' is not supported on MongoDB`);
             }
             const val = where[key];
             named.push(key);
@@ -1271,7 +1263,7 @@ export class MongoDialect extends AbstractDialect {
                 case '$isNotNull':
                     return operand ? present : MongoDialect.isNullExpr(ref);
                 default:
-                    throw new TypeError(`aggregate $where operator '${op}' is not supported on MongoDB`);
+                    throw new UqlUsageError(`aggregate $where operator '${op}' is not supported on MongoDB`);
             }
         });
         return terms.length === 1 ? terms[0] : { $and: terms };
@@ -1326,12 +1318,12 @@ export class MongoDialect extends AbstractDialect {
         const meta = getMeta(entity);
         const field = meta.fields[key];
         if (!field) {
-            throw new TypeError(`Field '${key}' not found in entity '${meta.name}'`);
+            throw new UqlUsageError(`Field '${key}' not found in entity '${meta.name}'`);
         }
         const colName = this.resolveColumnName(key, field);
         const indexName = this.vectorSearchIndexName(findVectorIndex(meta, key)?.name, colName);
         if (!limit) {
-            throw new TypeError(`$vectorSearch requires $limit (vector sort on '${key}' of '${meta.name}')`);
+            throw new UqlUsageError(`$vectorSearch requires $limit (vector sort on '${key}' of '${meta.name}')`);
         }
         const stage = {
             index: indexName,

package/dist/mongo/mongodbQuerier.js

@@ -58,7 +58,6 @@ export class MongodbQuerier extends AbstractQuerier {
      * for a read and a stream alike, so both load the same relations.
      */
     readCursor(entity, q, opts) {
-        this.dialect.assertNoLock(q);
         const vectorSort = this.dialect.extractVectorSort(q.$sort);
         const pipeline = vectorSort
             ? this.buildVectorPipeline(entity, q, vectorSort, opts)

package/dist/mssql/mssqlDialect.d.ts

@@ -69,11 +69,7 @@ export declare class MsSqlDialect extends MergeSqlDialect {
     returningId<E>(meta: EntityMeta<E>): string;
     protected returningIdExpression<E>(meta: EntityMeta<E>): string;
     protected mergeReturning(expression: string): string;
-    /**
-     * A row lock is a hint on the table here, not a clause at the end of the statement, so
-     * {@link lockHint} emits it and this only keeps the guard - see the base declaration.
-     */
-    protected appendLock<E>(_ctx: QueryContext, entity: Type<E>, q: Query<E>): void;
+    /** A row lock is a hint on the table here, which `rowLocks.placement` says instead of a trailing clause. */
     protected lockHint<E>(q: Query<E>): string;
     /**
      * `N'...'`, always. A bare literal is `VARCHAR`, whose codepage silently destroys anything outside

package/dist/mssql/mssqlDialect.js

@@ -10,6 +10,7 @@ import { parseQueryLock } from '../type/index.js';
 import { isAutoIncrement } from '../util/field.util.js';
 import { assertNonNegativeInteger } from '../util/index.js';
 import { escapeSingleQuotes } from '../util/sqlLiteral.js';
+import { UqlUsageError } from '../util/uqlError.js';
 /** What SQL Server has. */
 const MSSQL_FEATURES = {
     // Neither object takes an `IF NOT EXISTS`; both need a `sys` catalogue lookup around them, which
@@ -31,10 +32,8 @@ const MSSQL_FEATURES = {
     supportsUnsigned: false,
     serverSideCursors: false,
     correlatedWrites: true,
-    rowLocks: true,
-    rowLockWithWindow: true,
+    rowLocks: { of: true, withWindow: true, placement: 'tableHint' },
     nullsOrdering: 'case',
-    rowLockOf: true,
     textScoreIndexes: false,
     orderedUpsertReturning: false,
     orderedJsonAggregates: true,
@@ -164,13 +163,7 @@ export class MsSqlDialect extends MergeSqlDialect {
     mergeReturning(expression) {
         return `OUTPUT ${expression}`;
     }
-    /**
-     * A row lock is a hint on the table here, not a clause at the end of the statement, so
-     * {@link lockHint} emits it and this only keeps the guard - see the base declaration.
-     */
-    appendLock(_ctx, entity, q) {
-        this.assertLockSupported(entity, q);
-    }
+    /** A row lock is a hint on the table here, which `rowLocks.placement` says instead of a trailing clause. */
     lockHint(q) {
         const wait = parseQueryLock(q.$lock);
         if (!wait) {
@@ -324,7 +317,7 @@ export class MsSqlDialect extends MergeSqlDialect {
     jsonSet(ctx, expr, set, _field) {
         for (const [key, value] of Object.entries(set)) {
             if (value === null) {
-                throw new TypeError(`mssql cannot $set '${key}' to null: JSON_MODIFY deletes the key instead. Use $unset, or store a JSON null through a whole-column write.`);
+                throw new UqlUsageError(`mssql cannot $set '${key}' to null: JSON_MODIFY deletes the key instead. Use $unset, or store a JSON null through a whole-column write.`);
             }
         }
         return Object.entries(set).reduce((acc, [key, value]) => `JSON_MODIFY(${acc}, ${jsonPath(key)}, ${this.jsonWriteParam(ctx, value)})`, `COALESCE(${expr}, '{}')`);

package/dist/querier/abstractQuerier.d.ts

@@ -18,7 +18,14 @@ export declare abstract class AbstractQuerier implements Querier {
     protected readonly logger: LoggerWrapper;
     abstract readonly dialect: AbstractDialect;
     constructor(extra?: ExtraOptions | undefined);
-    protected validateProjectionQuery<E extends object>(entity: Type<E>, q: Query<E>): void;
+    /** What every read is checked for before it runs, whichever backend runs it. */
+    protected validateReadQuery<E extends object>(entity: Type<E>, q: Query<E>): void;
+    /**
+     * Refuses a `$lock` the engine cannot take, then one outside a transaction, where the lock would
+     * drop as the statement commits: only the querier knows whether one is open. Here rather than in
+     * each backend's read, so the rule reaches a find, a stream and a paged count alike.
+     */
+    private assertLockable;
     private validateProjectionQueryRecursive;
     /** `[entity, query, opts]` from either call form, `(entity, q, opts)` or `({ $entity, ...q }, opts)`. */
     protected resolveEntityQuery<E extends object, Q extends object>(entityOrQuery: Type<E> | (Q & {
@@ -87,8 +94,14 @@ export declare abstract class AbstractQuerier implements Querier {
     /** Settles the rows first where the update cascades, so a payload changing what `$where` reads still names them. */
     updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
     /**
-     * Why an update matched no row: another writer moved the version on, or the row is gone. One read
-     * without the version predicate answers it, and it runs only on the failure, so the happy path
+     * The write every update runs, matching the version `lockKey` names where one is being held. Only a
+     * restore passes none: it writes no content, so there is no update of anyone's to lose.
+     */
+    private updateRows;
+    /**
+     * Why an update matched no row. The filter named the row by its id, so reading by that id alone
+     * separates the three: the row is gone, another writer moved the version on, or the rest of the
+     * filter excluded a row still at that version. One read, only on the failure, so the happy path
      * still costs one statement. Best effort by nature - the row can change again while we ask.
      */
     private throwStaleVersion;