uql-orm 0.66.0 → 0.67.1

package/dist/dialect/abstractSqlDialect.d.ts

@@ -1,5 +1,4 @@
-import { type EntityData, type EntityMeta, type EntityWhereMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryBuildFn, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryContextOptions, type QueryExclude, type QueryFilter, type QueryGroupMap, type QueryGroupOp, type QueryHavingMap, type QueryOptions, type QueryPager, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorNear, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereOptions, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
-import { type ColumnFamily } from '../util/field.util.js';
+import { type ColumnFamily, type EntityData, type EntityMeta, type EntityWhereMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryBuildFn, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryContextOptions, type QueryExclude, type QueryGroupMap, type QueryGroupOp, type QueryHavingMap, type QueryOptions, type QueryPage, type QueryPager, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorNear, type QueryWhere, type QueryWhereArray, type QueryWhereOptions, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
 import type { HydrateKind } from './hydrateColumn.js';
 import { type JsonAccessMode } from './jsonSql.js';
 import { type QueryJoins, type QuerySortOptions } from './queryJoins.js';
@@ -85,17 +84,10 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     abstract readonly escapeIdChar: '"' | '`';
     /**
      * The column type of a database-generated key: only the type, never the key itself, which the table
-     * declares over its columns as one named constraint. SQLite is the exception - see
-     * {@link serialDeclaresPrimaryKey}.
+     * declares over its columns as one named constraint. SQLite is the exception: see
+     * `SqlDialectFeatures.serialDeclaresPrimaryKey`.
      */
     abstract readonly autoIncrementSuffix: string;
-    /**
-     * Whether {@link autoIncrementSuffix} states `PRIMARY KEY` itself, so the table must not state it again.
-     *
-     * True on SQLite alone, where `AUTOINCREMENT` is legal only in the exact phrase
-     * `INTEGER PRIMARY KEY AUTOINCREMENT` - the key cannot be lifted out of the column there.
-     */
-    readonly serialDeclaresPrimaryKey: boolean;
     abstract readonly tableOptions: string;
     abstract readonly beginTransactionCommand: string;
     abstract readonly commitTransactionCommand: string;
@@ -130,24 +122,15 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     getBeginTransactionStatements(isolationLevel?: IsolationLevel): string[];
     createContext(options?: QueryContextOptions): QueryContext;
     /**
-     * Builds SQL text in isolation via `build`, so the caller can embed it inline (e.g.
-     * `"col" = <text>`) instead of appending it at the end of `ctx`. The fragment binds any value
-     * straight into `ctx`'s own values array - shared by reference, not copied - so `addValue` numbers
-     * its placeholder correctly against the real query from the start; a fresh, empty array would
-     * instead number from `1` regardless of how many values `ctx` already has, misnumbering every
-     * bound value on `$n`-placeholder dialects once `ctx` isn't otherwise empty. Generated aliases are
-     * shared for the same reason - see {@link SqlQueryContext}.
+     * The SQL `build` writes, as text to embed rather than appended to `ctx`. It binds into `ctx`'s own values
+     * and aliases, so `$n` placeholders number against the whole statement.
      */
     protected buildFragment(ctx: QueryContext, build: QueryBuildFn): string;
     /** A `raw()` rendered in place, an operand or a projected term: bound, the driver would get the object. */
     protected rawFragment(ctx: QueryContext, value: QueryRaw, prefix?: string, entity?: Type<unknown>): string;
     /**
-     * Each operand rendered into its own fragment, keeping only those that emitted SQL.
-     *
-     * Nothing reaches `ctx` until every one has rendered, because an operand that emits nothing - an
-     * empty `$and`, an `{}` entry - must leave behind neither a dangling separator nor a clause with no
-     * condition after it. How many terms really emit is also what decides the parentheses, which is why
-     * the caller counts what comes back rather than what it passed in.
+     * Each operand rendered on its own, keeping those that emitted SQL: an empty one leaves no dangling
+     * separator, and the count of what emitted decides the parentheses.
      */
     protected renderOperands<T>(ctx: QueryContext, operands: readonly T[], render: (ctx: QueryContext, operand: T) => void): string[];
     addValue(ctx: QueryContext, value: unknown): string;
@@ -162,14 +145,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     normalizeValues(values: unknown[] | undefined): unknown[] | undefined;
     placeholder(_index: number): string;
-    /**
-     * `RETURNING <id column> AS id`, or nothing at all for a composite key.
-     *
-     * The alias names one column, and every column of a composite came from the caller, so there is no
-     * id the statement could report that the payload does not already carry - the same "no id to give"
-     * a `firstId` dialect already answers with. Empty rather than a refusal, so an insert and an upsert
-     * of a composite row both run, and the querier names those rows with `idOf`.
-     */
+    /** `RETURNING <id column> id`, or nothing on a composite key, whose every column the payload already names. */
     returningId<E>(meta: EntityMeta<E>): string;
     /** `<id column> AS id` on its own, for a statement composing a `RETURNING` list of several items. */
     protected returningIdExpression<E>(meta: EntityMeta<E>): string;
@@ -268,16 +244,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     private static readonly LIKE_OPS;
     /**
-     * How this engine matches case-insensitively. One decision, not two: folding the pattern while the
-     * comparison leaves the column alone matches neither case, which is what `$istartsWith: 'Some'`
-     * used to do wherever `LIKE` is case-sensitive.
-     *
-     * - `ilike`: the engine has a case-insensitive operator (`ILIKE`), so the pattern goes through as written.
-     * - `native`: plain `LIKE` already ignores case (SQLite, for ASCII). Folding the pattern in JS would
-     *   only break the non-ASCII characters the engine cannot fold anyway - `'É'` would become an `'é'`
-     *   that matches nothing.
-     * - `fold`: nothing ignores case on its own, so both sides are lowered explicitly. Not indexable as
-     *   such; an expression index over `LOWER(column)` is what makes it so.
+     * How the engine matches case-insensitively: `ilike` has the operator, `native` ignores case already
+     * (SQLite, where folding in JS would break non-ASCII), and `fold` lowers both sides.
      */
     protected readonly caseInsensitiveMatch: 'ilike' | 'native' | 'fold';
     /**
@@ -301,19 +269,11 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * alias exists only when the field was also selected, which `$where` and `$sort` cannot assume.
      */
     private inlinedOperand;
-    compareFieldOperator<E, K extends keyof QueryWhereFieldOperatorMap<E>>(ctx: QueryContext, entity: Type<E>, key: FieldKey<E>, op: K, val: QueryWhereFieldOperatorMap<E>[K], opts?: QueryOptions): void;
+    /** One operator of a field's condition. Both come from the query as data, so neither is trusted. */
+    compareFieldOperator<E>(ctx: QueryContext, entity: Type<E>, key: FieldKey<E>, op: string, val: unknown, opts?: QueryOptions): void;
     /**
-     * `<operand> <op> <value>` for every operator that needs nothing but its left-hand SQL, or
-     * `undefined` when `op` is not one of them.
-     *
-     * One implementation for three callers that each had their own: a WHERE column, a HAVING aggregate
-     * expression, and a `$size` count (whose expression is already in the context, so it passes an
-     * empty operand). They previously disagreed - HAVING carried a second comparison-operator map and
-     * threw `unsupported HAVING operator` on the `$like` that `QueryHavingMap` accepts, and neither of
-     * the other two turned `$eq: null` into `IS NULL` the way the WHERE path does.
-     *
-     * The operators kept out are the ones that need more than an operand: `$not` recurses through the
-     * entity, and `$all`/`$size`/`$elemMatch` address a JSON document.
+     * `<operand> <op> <value>` for every operator that needs only its left-hand SQL, shared by a column, a
+     * `HAVING` expression and a `$size` count; `undefined` for the rest.
      */
     protected operatorCondition(ctx: QueryContext, operand: string, op: string, val: unknown): string | undefined;
     /** {@link operatorCondition}, appended; `false` when `op` needs more than an operand. */
@@ -332,13 +292,9 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     /** `$size`: the length of the JSON array at `jsonField`, compared against `value`. */
     protected abstract jsonSize(ctx: QueryContext, jsonField: string, value: number | QuerySizeComparisonOps): string;
     /**
-     * Explodes the JSON array at `jsonField` into rows, as the `FROM` of an `EXISTS` subquery, under
-     * `alias` (from {@link QueryContext.claimAlias} - a fresh name per call, since `$elemMatch`/`$all`
-     * can recurse into this on a nested array and a fixed, reused alias would let the inner occurrence
-     * shadow the outer one it needs to correlate against). An empty `fields` means the elements are
-     * scalars, in which case `asJson` says whether they are read as JSON or as text; otherwise they
-     * are objects and `fields` are the keys the conditions will read (MySQL needs them upfront for its
-     * `JSON_TABLE` column list).
+     * The JSON array at `jsonField` as rows, the `FROM` of an `EXISTS`, under a fresh `alias` so a nested
+     * one cannot shadow it. `fields` are an object element's keys (MySQL lists them up front), empty for
+     * scalars, which `asJson` reads as JSON rather than text.
      */
     protected abstract jsonElemFrom(jsonField: string, fields: readonly string[], alias: string, asJson?: boolean): string;
     /**
@@ -348,25 +304,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     protected abstract jsonElemRef(alias: string, field?: string, asJson?: boolean): string;
     /**
-     * Whether the dialect's array containment ({@link jsonAll}) matches an object element that merely
-     * *includes* the given keys, as PostgreSQL's `@>` and MySQL's `JSON_CONTAINS` do. SQLite compares
-     * elements as whole JSON text, so it cannot express a partial match and always expands the
-     * per-field form below.
-     */
-    protected readonly jsonContainmentIsPartial: boolean;
-    /**
-     * Whether an exploded *scalar* element keeps its SQL type. SQLite's `JSON_EACH` yields JSON
-     * booleans as `0`/`1` integers and numbers as numbers, so such an element compares directly to a
-     * bound value; PostgreSQL and MySQL explode scalars to text, losing the type, so a non-string
-     * operand there has to compare as JSON (see {@link isJsonbOp}).
-     */
-    protected readonly jsonScalarElemKeepsType: boolean;
-    /**
-     * `$elemMatch`: at least one element of the JSON array satisfies `match`. Three shapes, decided
-     * here so every dialect only supplies {@link jsonElemFrom} / {@link jsonElemRef}:
-     * - keys are operators (`{ $startsWith: 'ad' }`) - scalar elements, conditions on the element;
-     * - a plain object with no nested operators - containment, which is the only form an index serves;
-     * - otherwise - per-field conditions over the exploded objects.
+     * `$elemMatch`: an element satisfies `match`. Operator keys test a scalar element; a plain object is
+     * containment, which an index can serve; anything else tests each exploded object's fields.
      */
     protected jsonElemMatch(ctx: QueryContext, jsonField: string, match: Record<string, unknown>): string;
     /**
@@ -407,16 +346,6 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * {@link MergeSqlDialect} needs: SQL Server refuses to page a statement that has none.
      */
     pager(ctx: QueryContext, opts: QueryPager, _sorted?: boolean): void;
-    /** Whether this engine has row locks at all. The SQLite family locks the database instead. */
-    readonly supportsRowLocks: boolean;
-    /**
-     * Whether a `FOR UPDATE` may share a statement with a window function. The MySQL family runs the
-     * pair; the Postgres family rejects it outright ("FOR UPDATE is not allowed with window functions"),
-     * which is what a paged read carrying its own `COUNT(*) OVER ()` total becomes under a `$lock`.
-     */
-    readonly supportsWindowWithRowLock: boolean;
-    /** MariaDB is the one engine here that cannot narrow a lock to one table of a join. */
-    readonly supportsLockOf: boolean;
     /** Validated before the querier checks for a transaction, so the clearer error wins. */
     assertLockSupported<E>(entity: Type<E>, q: Query<E>, joins?: QueryJoins): void;
     /**
@@ -431,17 +360,18 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * and the other engines quietly widen the lock to the joined rows.
      */
     protected appendLock<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, joins?: QueryJoins, alias?: string): void;
-    count<E>(ctx: QueryContext, entity: Type<E>, q: QueryFilter<E>, opts?: QueryOptions): void;
     /**
-     * How many rows a `$distinct` read returns, which `COUNT(*)` cannot answer: the deduplication
-     * happens after it counts, and a window function is no better - it counts before `DISTINCT` too.
-     * So the deduplicated set is made a derived table and its rows are counted. Every engine here
-     * supports one; MySQL is the reason it is aliased.
-     *
-     * The inner query takes the projection and the filter but never the page: the caller is asking how
-     * many rows there are beyond the page it already has.
+     * `COUNT(*)` over the filter, or over the rows a page settles. The clauses are read off `q` one by one:
+     * `/http` hands it over untyped, and a smuggled `$sort` changes no count.
+     */
+    count<E>(ctx: QueryContext, entity: Type<E>, q: QueryPage<E>, opts?: QueryOptions): void;
+    /**
+     * How many rows a `$distinct` read returns: the deduplication runs after `COUNT(*)` and a window
+     * alike, so the deduplicated set is counted as a derived table, never paged.
      */
     countDistinct<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: QueryOptions): void;
+    /** `SELECT COUNT(*)` over the rows `rows` appends, as a derived table. */
+    private countRows;
     /**
      * The statistic the engine already keeps, as a `count` column. Overridden by the dialects that
      * keep one; the rest throw, because falling back to `COUNT(*)` would run exactly the scan the
@@ -481,21 +411,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     private readOptions;
     insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
-    /**
-     * Where the clause reporting an insert's generated ids goes. `suffix` is `RETURNING ...` at the end
-     * of the statement, which every engine here but one spells that way; SQL Server's `OUTPUT` has no
-     * trailing form and sits between the column list and `VALUES`.
-     *
-     * A knob rather than a pair of hooks: one concept decides where the string {@link returningId}
-     * already built ends up, so the two ends cannot disagree.
-     */
+    /** Where an insert's id clause goes: `RETURNING` at the end, or SQL Server's `OUTPUT` before `VALUES`. */
     readonly returningPosition: 'suffix' | 'after-target';
-    /**
-     * Whether a multi-row upsert's `RETURNING` lists its rows in payload order. Where it does not, the
-     * ids are read back by the conflict columns instead, since placing them in order would name the
-     * wrong rows.
-     */
-    readonly upsertReturningOrdered: boolean;
     /**
      * `INSERT INTO ... VALUES (...)` and nothing more. The upsert builders extend this rather than
      * {@link insert}: their own clause has to come before the `RETURNING`, not after it.
@@ -503,13 +420,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected appendInsertValues<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], 
     /** Spliced between the column list and `VALUES`; see {@link returningPosition}. */
     afterTarget?: string): void;
-    /**
-     * The columns an insert writes and the records it writes them from, resolved once.
-     *
-     * Split out of {@link appendInsertValues} because a `MERGE` needs the same rows as a `VALUES` row
-     * source rather than as an `INSERT`, and both have to apply `onInsert` defaults and the
-     * JSON/vector binding rules identically.
-     */
+    /** The columns an insert writes and the rows it writes, resolved once, and shared with a `MERGE`'s row source. */
     protected insertShape<E>(entity: Type<E>, payload: E | E[]): InsertShape<E>;
     /** `(a, b), (c, d)` - the row constructor an INSERT and a MERGE source both write. */
     protected appendValueRows<E>(ctx: QueryContext, { payloads, keys, fields, kinds }: InsertShape<E>): void;
@@ -521,31 +432,17 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected appendDefaultInsertValue(ctx: QueryContext, _field: FieldOptions | undefined): void;
     update<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): void;
     /**
-     * `INSERT ... ON CONFLICT (...) DO UPDATE/NOTHING RETURNING ...`, which SQLite adopted from Postgres
-     * and which every dialect here speaks except the MySQL family (see {@link MysqlLikeSqlDialect}).
-     *
-     * Two orderings matter, and they pull in opposite directions. The assignments are computed *before*
-     * the insert, because `appendInsertValues` fills `onInsert` fields into the payload and a column that
-     * exists only there - `createdAt` - must not join the update set. Their bound values are pushed
-     * *after* it, because a `?` placeholder is positional and the clause comes last in the statement.
-     * {@link PgLikeSqlDialect} overrides this: `$N` placeholders make array order irrelevant, so it can
-     * bind into the main context and skip the second one.
+     * `INSERT ... ON CONFLICT ... DO UPDATE/NOTHING RETURNING`. The assignments are built before the insert
+     * fills `onInsert` columns, which must stay out of them, and their values bound after it, where a `?` reads them.
      */
     upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], 
     /** One more `RETURNING` item, as a bare expression: this joins the list and adds the keyword. */
     extraReturning?: string): void;
-    /**
-     * Whether the upsert's update assignments can bind straight into the statement's own context.
-     *
-     * They cannot on a `?`-placeholder dialect: the assignments are built before the insert but read
-     * after it, so their values have to be pushed afterwards to land in the right positional order.
-     * A `$n` placeholder carries its own index, so there is nothing to reorder - but it also cannot use
-     * the scratch context, whose numbering would restart at `$1` and collide with the insert's.
-     */
+    /** Whether the upsert's assignments bind straight into the statement, as numbered `$n` placeholders can. */
     protected readonly upsertUpdateBindsInPlace: boolean;
     /** How an `ON CONFLICT` assignment reads the row that was being inserted. */
     protected readonly upsertExcluded: (columnName: string) => string;
-    protected getUpsertUpdateAssignments<E>(ctx: QueryContext, meta: EntityMeta<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], callback?: (columnName: string) => string): string;
+    protected getUpsertUpdateAssignments<E>(ctx: QueryContext, meta: EntityMeta<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], callback: (columnName: string) => string): string;
     protected getUpsertConflictPathsStr<E>(meta: EntityMeta<E>, conflictPaths: QueryConflictPaths<E>): string;
     delete<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): void;
     escapeId(val: string | undefined, forbidQualified?: boolean, addDot?: boolean): string;
@@ -562,52 +459,20 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * every INSERT/UPDATE.
      */
     protected formatPersistableValue(ctx: QueryContext, field: FieldOptions | undefined, value: unknown): void;
-    /**
-     * How a column's values are written. A function of the column, not of the value, so a bulk insert
-     * classifies each column once instead of re-deciding per row: a 20-row, 6-column insert used to ask
-     * 120 times to get the same six answers.
-     */
+    /** How a column's values are written: a function of the column, so a bulk insert classifies each once. */
     protected persistKind(field: FieldOptions | undefined): PersistKind;
     /**
-     * Which of an entity's columns need decoding on READ, and how: the inverse of {@link persistKind},
-     * cached per entity for the same reason it classifies per column. A 1000-row read of a 10-field
-     * entity otherwise asks {@link columnFamily} (which lowercases a string on every call) 10,000 times
-     * to get the same ten answers. Most entities land here for their numeric columns alone, where the
-     * per-row cost is one `typeof` against a value the driver usually decoded already.
-     *
-     * Dialect-aware exactly like {@link supportedVectorType}, because it has to be: a `sparsevec` field
-     * is written as a plain dense vector everywhere but Postgres, so reading it back by the field's own
-     * declared cast would look for a sparse literal that was never stored.
-     *
-     * A type lands here rather than at the driver when the wire type alone cannot decide it, and only
-     * the declaration can: `Boolean` is 0/1 in a SQLite INTEGER and a MySQL `TINYINT(1)`, both
-     * indistinguishable from a genuine small integer; a decimal is text from pg *and* mysql2, and only
-     * the field says it was meant as a number; and `type: BigInt` shares BIGINT with `type: Number`, so
-     * the wire decode has to be undone for it. All are no-ops where the driver already decoded.
-     *
-     * Classified through the same {@link columnFamily} the rest of the library uses, not against the
-     * constructors: `type` accepts a string logical type for every one of these (`@Field({ type:
-     * 'decimal' })`), and matching `=== Number` alone left those reading back as text.
+     * The columns a read decodes, and how, cached per entity and revision. They are the ones the wire cannot
+     * decide alone: a boolean stored as an integer, a decimal read as text, a `BigInt`, and a related row's
+     * values, which cross JSON as text.
      */
     hydratableFields<E>(entity: Type<E>): readonly HydratableField[];
     /**
-     * The same classification for an aggregate row. Not cached, because these columns are a shape of the
-     * query rather than of the entity, and it is computed once per call either way.
-     *
-     * Mirrors `QueryAggregateFnResult`, which is the contract callers already compile against:
-     * `$count`/`$sum`/`$avg` are a number whatever they aggregate, while `$min`/`$max` and every
-     * `$group` column keep the aggregated field's own type, so they decode as that field would. Without
-     * it a `$sum` over a BIGINT column came back as `'500'` from a result type that says `number`, since
-     * Postgres widens that sum to NUMERIC and no driver can know it was meant as a JS number.
+     * The same for an aggregate's row, per query: a count or total is a number however the engine widened
+     * it, and `$min`/`$max` or a grouped column decodes as its field does.
      */
     hydratableAggregates<E, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>): readonly HydratableField[];
-    /**
-     * The mirror of {@link persistKind}: what one column decodes as, or nothing if it needs no decode. A
-     * date and bytes decode because a related row crosses JSON, which spells both as text.
-     *
-     * `BigInt` is asked first because it shares the numeric family with `Number`: let the switch answer
-     * it and every `type: BigInt` property silently decodes to a JS number again.
-     */
+    /** What one column decodes as, the inverse of {@link persistKind}. `BigInt` first, since it shares the numeric family. */
     protected hydrateKind(field: FieldOptions | undefined): HydrateKind | undefined;
     private readonly hydratable;
     /** The one type dispatch for a persisted value, over a column kind decided by the caller. */
@@ -620,17 +485,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     protected jsonCast(operand: string): string;
     /**
-     * Generate the full `"col" = <expression>` assignment for a JSON update operator payload.
-     * Called from `update()` when a field value is a {@link JsonUpdateOp}.
-     *
-     * Each operator wraps the expression built so far, innermost-first in the order stated on
-     * {@link JsonUpdateOp} (`$pull` -> `$set` -> `$push` -> `$unset`), so dialects only supply the
-     * four SQL fragments below. Two invariants keep every dialect consistent and keep bound values in
-     * step with their placeholders:
-     * - `$pull` is innermost and its subquery reads `escapedCol`, so its value binds exactly once.
-     * - Later fragments reference `expr` at most once, so a `$pull` subquery is never duplicated
-     *   (which would bind its value twice on positional-placeholder dialects). PostgreSQL's `$push`
-     *   is the one exception, and is safe there because its placeholders are numbered.
+     * `"col" = <expr>` for a JSON update, each operator wrapping the last: `$pull`, `$set`, `$push`, `$unset`.
+     * `$pull` reads the column and every later one its expression once, so no value binds twice.
      */
     protected formatJsonUpdate(ctx: QueryContext, escapedCol: string, value: JsonUpdateOp, field?: FieldOptions): void;
     /**
@@ -747,11 +603,6 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * correlate a derived table. [The design](../../../../architecture/relations-in-one-statement.md).
      */
     protected abstract appendRelationArray(ctx: QueryContext, rows: RelationRows): void;
-    /**
-     * Whether the engine's JSON aggregate takes an `ORDER BY` of its own. Where it does not, a relation's
-     * rows carry no sort term out and keep their own order, which a derived table hands its aggregate.
-     */
-    protected readonly orderedAggregates: boolean;
     /**
      * The rows read as a derived table, their values crossing JSON and, where the aggregate orders, each
      * sort term carried out beside them for it to order by, since a derived table's order is not promised
@@ -784,24 +635,11 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * @param sizeExprFn - function that appends the size expression to ctx (e.g. `JSONB_ARRAY_LENGTH("col")`)
      */
     protected buildSizeComparison(ctx: QueryContext, sizeExprFn: () => void, sizeVal: number | QuerySizeComparisonOps): void;
-    /**
-     * `<distance expr> <op> ?` - the `$where` half of vector search, where `$sort` is the ranking half.
-     *
-     * The bounds are validated here rather than left to the shared renderer, which also knows `$like`
-     * and `$in`; and `$eq`/`$ne` are absent on purpose, since a distance is a float. `/http` casts
-     * client JSON straight to `Query`, so an unknown key has to be refused rather than ignored.
-     */
+    /** `<distance> <op> ?`, the `$where` half of a vector search, its bounds checked here since `/http` input is untyped. */
     protected compareVectorNear<E>(ctx: QueryContext, meta: EntityMeta<E>, key: string, near: QueryVectorNear): void;
     /** The runtime half of {@link QuerySizeComparisonOps}: what a count can sensibly be compared with. */
     private static readonly SIZE_COMPARE_OPS;
-    /**
-     * Append a single size comparison operator and value. No operand: the count expression is already
-     * in the context, so this contributes only the ` <op> <value>` tail.
-     *
-     * Gated on {@link SIZE_COMPARE_OPS} rather than on whatever the shared renderer accepts, because
-     * that renderer also knows `$like`, `$regex` and `$in`, none of which mean anything against a
-     * count. `$size: { $like: 5 }` has to stay the error it always was.
-     */
+    /** ` <op> <value>` after a count already written, refusing any operator a count cannot be compared with. */
     private appendSizeOp;
     /** ANSI-style single-quote escaping. MySQL-family dialects override this for backslash escaping. */
     escape(value: unknown): string;
@@ -820,11 +658,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     protected get neOp(): string;
     protected neExpr(field: string, ph: string): string;
-    /**
-     * Formats an IN/NOT IN expression, binding each value individually.
-     * Postgres overrides to use `= ANY($1)` / `<> ALL($1)` with a single array parameter.
-     */
-    protected formatIn(ctx: QueryContext, values: unknown[], negate: boolean): string;
+    /** `operand IN (...)` binding each value, or the constant an empty set reduces to: no value is in it. */
+    protected formatIn(ctx: QueryContext, operand: string, values: unknown[], negate: boolean): string;
     /** Reads extracted JSON text as a number, which every engine spells its own way. */
     protected abstract numericCast(expr: string): string;
     toString(): string;