@quereus/quereus 4.4.0 → 4.5.0

package/dist/src/types/validation.js

@@ -64,6 +64,66 @@ export function validateAndParse(value, type, columnName) {
     // Then validate the parsed result
     return validateValue(parsed, type, columnName);
 }
+/**
+ * Coerce each cell in `row` to its declared column's logical type via
+ * {@link validateAndParse} (INTEGER/REAL affinity, JSON parsing, etc.) — the
+ * shared step every write path (memory tables, the KV store backend, the
+ * isolation overlay) applies before PK extraction, serialization, and index-key
+ * construction. `label` identifies the target for the "too many values" error
+ * (e.g. `` `${schemaName}.${tableName}` `` or `` `INSERT into ${tableName}` ``)
+ * so each call site keeps its own wording.
+ *
+ * @throws QuereusError if `row` has more cells than `columns`, or a cell fails validation/parsing
+ */
+export function coerceRowToSchema(row, columns, label) {
+    if (row.length > columns.length) {
+        throw new QuereusError(`Too many values for ${label}: expected ${columns.length}, got ${row.length}`, StatusCode.ERROR);
+    }
+    return row.map((value, i) => validateAndParse(value, columns[i].logicalType, columns[i].name));
+}
+/**
+ * Build the per-statement conversion step for a DML write. Given the static
+ * logical type of the expression producing each cell (index-aligned with
+ * `columns`) and the target columns, returns a closure that converts exactly
+ * the cells whose producing type is not already the target column's logical
+ * type — or `undefined` when no cell needs converting, so the caller can skip
+ * the per-row work entirely.
+ *
+ * Types are compared by object identity: the type registry hands out one
+ * shared `LogicalType` instance per type, so an expression whose static type
+ * IS the column's type (a reference to a same-typed column — an unassigned
+ * column in an UPDATE, or `insert into b select j from a`) produces values
+ * already in declared form, and those MUST be left alone: conversion is not
+ * repeatable for every type. JSON's `parse` reads a plain JS string as JSON
+ * source, so re-converting a stored JSON text value either changes it (the
+ * text `9` becomes the number 9) or throws (`abc` is not valid JSON source).
+ * An unknown source type (`undefined` entry) converts — the safe historical
+ * behavior for values of unproven provenance.
+ *
+ * The returned closure copies the row and converts via {@link validateAndParse},
+ * so conversion failures carry the same message text the storage layer used to
+ * produce. Cells at or beyond the row's length are left for the storage width
+ * guard, mirroring {@link coerceRowToSchema}'s map-over-present-cells behavior.
+ */
+export function buildRowCoercion(sourceTypes, columns) {
+    const convertIndices = [];
+    for (let i = 0; i < columns.length; i++) {
+        if (sourceTypes[i] !== columns[i].logicalType) {
+            convertIndices.push(i);
+        }
+    }
+    if (convertIndices.length === 0)
+        return undefined;
+    return (row) => {
+        const out = row.slice();
+        for (const i of convertIndices) {
+            if (i >= out.length)
+                break;
+            out[i] = validateAndParse(out[i], columns[i].logicalType, columns[i].name);
+        }
+        return out;
+    };
+}
 /**
  * Check if a value is compatible with a logical type without throwing.
  *

package/dist/src/types/validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/types/validation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC5B,KAAe,EACf,IAAiB,EACjB,UAAmB;IAEnB,uBAAuB;IACvB,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAEhC,2BAA2B;IAC3B,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,gBAAgB,UAAU,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,YAAY,CACrB,gBAAgB,OAAO,cAAc,IAAI,CAAC,IAAI,SAAS,OAAO,KAAK,EAAE,EACrE,UAAU,CAAC,QAAQ,CACnB,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CACzB,KAAe,EACf,IAAiB,EACjB,UAAmB;IAEnB,uBAAuB;IACvB,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAEhC,wBAAwB;IACxB,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAChB,IAAI,CAAC;YACJ,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,gBAAgB,UAAU,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAChE,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,IAAI,YAAY,CACrB,yBAAyB,OAAO,KAAK,OAAO,EAAE,EAC9C,UAAU,CAAC,QAAQ,CACnB,CAAC;QACH,CAAC;IACF,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAC/B,KAAe,EACf,IAAiB,EACjB,UAAmB;IAEnB,4CAA4C;IAC5C,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IAEnD,kCAAkC;IAClC,OAAO,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAe,EAAE,IAAiB;IAChE,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,CAAC,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAe,EAAE,IAAiB;IAC1D,IAAI,CAAC;QACJ,OAAO,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAC;IACb,CAAC;AACF,CAAC"}
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/types/validation.ts"],"names":[],"mappings":"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"}

package/dist/src/util/ast-spine-clone.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Structural ("spine") clone of an AST subtree: plain objects and arrays are
+ * deep-copied, everything else is passed through **by reference**.
+ *
+ * Exists for the in-place AST rewriters (`schema/rename-rewriter.ts`), which
+ * mutate the node graph they are handed and report whether anything changed. A
+ * caller that wants to compute what a rewrite *would* produce — without touching
+ * the live catalog AST — must rewrite a copy instead.
+ *
+ * Why not `structuredClone`: `AST.LiteralExpr.value` is typed
+ * `MaybePromise<SqlValue>`, and a Promise is not structured-cloneable — a live
+ * body carrying one would throw `DataCloneError`. The rewriters only ever assign
+ * to string fields (`.name`, `.schema`, `.table`, `.column`) and replace string
+ * arrays on plain AST nodes, so copying the plain-object/array spine is enough:
+ * every leaf they mutate is freshly owned, and every leaf they do not touch
+ * (primitives, `Uint8Array`, `bigint`, class instances, Promises) can safely stay
+ * shared.
+ *
+ * Frozen inputs are fine — the copy is unfrozen. Assumes a tree (the parser emits
+ * no cycles); a cyclic graph would recurse without bound.
+ */
+export declare function spineCloneAst<T>(node: T): T;
+//# sourceMappingURL=ast-spine-clone.d.ts.map

package/dist/src/util/ast-spine-clone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-spine-clone.d.ts","sourceRoot":"","sources":["../../../src/util/ast-spine-clone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAE3C"}

package/dist/src/util/ast-spine-clone.js

@@ -0,0 +1,41 @@
+/**
+ * Structural ("spine") clone of an AST subtree: plain objects and arrays are
+ * deep-copied, everything else is passed through **by reference**.
+ *
+ * Exists for the in-place AST rewriters (`schema/rename-rewriter.ts`), which
+ * mutate the node graph they are handed and report whether anything changed. A
+ * caller that wants to compute what a rewrite *would* produce — without touching
+ * the live catalog AST — must rewrite a copy instead.
+ *
+ * Why not `structuredClone`: `AST.LiteralExpr.value` is typed
+ * `MaybePromise<SqlValue>`, and a Promise is not structured-cloneable — a live
+ * body carrying one would throw `DataCloneError`. The rewriters only ever assign
+ * to string fields (`.name`, `.schema`, `.table`, `.column`) and replace string
+ * arrays on plain AST nodes, so copying the plain-object/array spine is enough:
+ * every leaf they mutate is freshly owned, and every leaf they do not touch
+ * (primitives, `Uint8Array`, `bigint`, class instances, Promises) can safely stay
+ * shared.
+ *
+ * Frozen inputs are fine — the copy is unfrozen. Assumes a tree (the parser emits
+ * no cycles); a cyclic graph would recurse without bound.
+ */
+export function spineCloneAst(node) {
+    return spineClone(node);
+}
+function spineClone(value) {
+    if (Array.isArray(value))
+        return value.map(spineClone);
+    if (value === null || typeof value !== 'object')
+        return value;
+    // Anything with a non-plain prototype (Uint8Array, Date, Map, Promise, any
+    // class instance) is a leaf the rewriters never write into — share it.
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        return value;
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+        out[key] = spineClone(v);
+    }
+    return out;
+}
+//# sourceMappingURL=ast-spine-clone.js.map

package/dist/src/util/ast-spine-clone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-spine-clone.js","sourceRoot":"","sources":["../../../src/util/ast-spine-clone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,aAAa,CAAI,IAAO;IACvC,OAAO,UAAU,CAAC,IAAI,CAAM,CAAC;AAC9B,CAAC;AAED,SAAS,UAAU,CAAC,KAAc;IACjC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACvD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,2EAA2E;IAC3E,uEAAuE;IACvE,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC/D,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9C,GAAG,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/src/util/coercion.d.ts

@@ -25,6 +25,19 @@ export declare function coerceToNumberForArithmetic(value: SqlValue): number;
  * BETWEEN emission and will be removed in a future release.
  */
 export declare function coerceForComparison(v1: SqlValue, v2: SqlValue): [SqlValue, SqlValue];
+/**
+ * Coerces a value for aggregate function arguments.
+ * Most aggregate functions should accept numeric strings as numbers.
+ * For COUNT, no coercion needed. For SUM/AVG, numeric strings should be converted.
+ *
+ * NOTE: this converts a numeric-looking string for min/max too, so `min('5','10')`
+ * over a plain TEXT column returns the NUMBER 5 — disagreeing with
+ * `order by … limit 1`, which keeps text order. Predates the semantic-ordering
+ * min/max binding and is unchanged by it (the emitters skip this call entirely
+ * when every argument type is numeric or carries semantic ordering — see
+ * `computeAggregateSkipCoercion` in runtime/emit/aggregate-setup.ts). Tracked as
+ * backlog `bug-text-minmax-numeric-coercion`.
+ */
 export declare function coerceForAggregate(value: SqlValue, functionName: string): SqlValue;
 /**
  * Determines if a value should be treated as numeric in the given context.

package/dist/src/util/coercion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coercion.d.ts","sourceRoot":"","sources":["../../../src/util/coercion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;GAGG;AAEH;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAU3D;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAWnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAyBpF;AASD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,GAAG,QAAQ,CAWlF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CASvD"}
+{"version":3,"file":"coercion.d.ts","sourceRoot":"","sources":["../../../src/util/coercion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;GAGG;AAEH;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAU3D;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAWnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAyBpF;AAKD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,GAAG,QAAQ,CAWlF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CASvD"}

package/dist/src/util/coercion.js

@@ -69,12 +69,21 @@ export function coerceForComparison(v1, v2) {
     // No coercion needed or possible
     return [v1, v2];
 }
+/** Aggregates that never want their argument read as a number. */
+const NON_NUMERIC_AGGREGATES = new Set(['COUNT', 'GROUP_CONCAT']);
 /**
  * Coerces a value for aggregate function arguments.
  * Most aggregate functions should accept numeric strings as numbers.
  * For COUNT, no coercion needed. For SUM/AVG, numeric strings should be converted.
+ *
+ * NOTE: this converts a numeric-looking string for min/max too, so `min('5','10')`
+ * over a plain TEXT column returns the NUMBER 5 — disagreeing with
+ * `order by … limit 1`, which keeps text order. Predates the semantic-ordering
+ * min/max binding and is unchanged by it (the emitters skip this call entirely
+ * when every argument type is numeric or carries semantic ordering — see
+ * `computeAggregateSkipCoercion` in runtime/emit/aggregate-setup.ts). Tracked as
+ * backlog `bug-text-minmax-numeric-coercion`.
  */
-const NON_NUMERIC_AGGREGATES = new Set(['COUNT', 'GROUP_CONCAT']);
 export function coerceForAggregate(value, functionName) {
     const upperName = functionName.toUpperCase();
     if (NON_NUMERIC_AGGREGATES.has(upperName) || upperName.startsWith('JSON_')) {

package/dist/src/util/coercion.js.map

@@ -1 +1 @@
-{"version":3,"file":"coercion.js","sourceRoot":"","sources":["../../../src/util/coercion.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"coercion.js","sourceRoot":"","sources":["../../../src/util/coercion.ts"],"names":[],"mappings":"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"}

package/dist/src/util/comparison.d.ts

@@ -173,6 +173,120 @@ export declare function compareWithOrderByFast(a: SqlValue, b: SqlValue, directi
  * @returns An optimized comparison function
  */
 export declare function createOrderByComparatorFast(direction?: 'asc' | 'desc', nullsOrdering?: 'first' | 'last', collationFunc?: CollationFunction): (a: SqlValue, b: SqlValue) => number;
+/**
+ * True when a logical type's `compare` defines an order that observably differs from
+ * storage-class + collation ordering (see {@link LogicalType.semanticOrdering}). This
+ * is the routing predicate for user-visible ordering/identity sites: ORDER BY,
+ * comparison operators, range-scan bound filters, and DISTINCT/GROUP BY identity use
+ * the type's `compare` exactly when this returns true.
+ */
+export declare function hasSemanticOrdering(type: LogicalType | undefined): type is LogicalType;
+/**
+ * True when two logical types order values differently — i.e. the comparators
+ * {@link createTypedComparator} builds for them are not interchangeable, so any structure
+ * keyed by one has to be re-sorted (and its uniqueness re-judged) to move to the other.
+ *
+ * `createTypedComparator(type, coll)` is fully determined by `type.compare`: present → the
+ * type's own `compare`; absent → `compareSqlValuesFast` under the collation. So comparing
+ * the two `compare` identities is exactly the question, and it catches more than a
+ * {@link hasSemanticOrdering} check would:
+ *
+ *  - TEXT ↔ TIMESPAN — TIMESPAN's `compare` ranks by elapsed time, so 'PT1H', 'PT60M' and
+ *    'PT3600S' are one value where text sees three.
+ *  - TEXT ↔ JSON — JSON's `compare` ranks by canonical structure, so '{"a":1}' and
+ *    '{ "a" : 1 }' are one value.
+ *  - TEXT ↔ DATE / TIME / DATETIME — these carry their own `compare` hard-wired to
+ *    BINARY_COLLATION, ignoring the column's declared collation, so `text collate nocase →
+ *    date` really does re-order even though both orderings are "textual".
+ *
+ * A retype that flattens to the SAME logical type object (`text → varchar(50)`,
+ * `integer → bigint`) shares one `compare` and is correctly reported as no change.
+ *
+ * NOTE: deliberately conservative — it answers "may the order move", not "does it". The
+ * DATE / TIME / DATETIME family compares exactly as BINARY text does, so under the only
+ * collation those types legally accept (BINARY — `supportedCollations: []`) a `text → date`
+ * retype re-sorts every structure into the order it was already in. Harmless but O(rows);
+ * if a retype on a large table ever shows up as slow, narrow the predicate to a probe of the
+ * two comparators over a representative value set, or special-case the BINARY-equivalent
+ * comparators by identity.
+ */
+export declare function comparisonSemanticsDiffer(a: LogicalType, b: LogicalType): boolean;
+/**
+ * True when two declared logical types may share ONE physical equi-join key — i.e. when
+ * comparing their values with a single type-blind comparator (a serialized hash key, a
+ * merge co-walk) reproduces what `=` says about them.
+ *
+ * The admissible shapes are "neither side declares a semantic-ordering type" or "both
+ * declare the SAME one". A **mixed** pair (`timespan` ↔ `text`) is the defect this gates:
+ * `=` runs the generic comparison path, which applies a runtime duration check whenever
+ * either side is temporal, so 'PT1H' = 'PT60M'; a hash or merge join comparing raw text
+ * disagrees and silently drops the row. Merge join cannot be rescued by canonicalizing
+ * the key either — it needs both inputs physically sorted in its comparator's order, and
+ * a `timespan` side is sorted by elapsed time while a `text` side is sorted by text, so
+ * no single comparator merges the two. Declining is the only sound answer; the pair
+ * demotes to the residual / generic join, where `=`'s own semantics apply.
+ *
+ * NOT {@link comparisonSemanticsDiffer}, which asks a different question (may an ordered
+ * structure keyed under `a` be reused under `b`) by comparing `compare` identity. EVERY
+ * builtin type carries its own `compare`, so that predicate reports "differ" for an
+ * ordinary `integer` ↔ `real` join key and would cost a hash join for no correctness
+ * gain. This one keys on the `semanticOrdering` flag, which is exactly the set of types
+ * whose order is not reproducible from storage class + collation.
+ *
+ * See `docs/types.md` § "Semantic ordering".
+ */
+export declare function semanticOrderingsAgree(a: LogicalType | undefined, b: LogicalType | undefined): boolean;
+/**
+ * Canonical key-identity transform for a declared logical type, or undefined when raw
+ * values already key faithfully. Defined exactly when the type carries semantic ordering
+ * AND a `groupKey` hook (TIMESPAN — its stored text is not canonical for equality:
+ * 'PT1H' ≡ 'PT60M'); JSON has semantic ordering but its canonical text is already
+ * identity-faithful, so it takes no transform. Every hash-, set-, or byte-keyed identity
+ * site (GROUP BY, hash joins, IN membership, the persistent store's PK/index key encoding,
+ * the isolation overlay's shadowing keys) must run values through this before serializing, or two
+ * values the type's `compare` calls equal land on distinct keys.
+ */
+export declare function semanticKeyTransform(type: LogicalType | undefined): ((value: SqlValue) => SqlValue) | undefined;
+/**
+ * ORDER BY comparator for one sort key of a declared logical type. When the type
+ * carries semantic ordering (see {@link hasSemanticOrdering}), non-NULL pairs are
+ * ranked by the type's `compare` (via {@link createTypedComparator}, which keeps the
+ * storage-class-mismatch fallback so a probe of a different storage class never
+ * falsely equals); otherwise this is exactly {@link createOrderByComparatorFast}.
+ *
+ * NULL placement is handled HERE, never delegated to `type.compare` — the type
+ * convention (NULL smallest, always) differs from ORDER BY's NULLS FIRST/LAST and
+ * default rules, which {@link orderByNullResult} implements.
+ */
+export declare function createTypedOrderByComparator(type: LogicalType | undefined, direction?: 'asc' | 'desc', nullsOrdering?: 'first' | 'last', collationFunc?: CollationFunction): (a: SqlValue, b: SqlValue) => number;
+/**
+ * The comparator an ordering site uses for a single value of `type` under
+ * `collation`: the type's own `compare` when it carries semantic ordering
+ * ({@link hasSemanticOrdering}), else storage-class + collation ordering. The
+ * scalar form of {@link createSemanticRowComparator}'s per-column routing — one
+ * copy of the routing rule, shared by row identity (DISTINCT/set operations) and
+ * the min/max aggregate binding (`bindArgs` in func/builtins/aggregate.ts).
+ *
+ * `type` may be undefined (untyped/ANY) — such values use the collation
+ * comparator, byte-identical to the historical BINARY default when no collation
+ * is passed. Safe for runtime type drift: the typed path's
+ * storage-class-mismatch guard (see {@link createTypedComparator}) falls back to
+ * storage-class ordering rather than mis-parsing.
+ */
+export declare function createSemanticValueComparator(type: LogicalType | undefined, collation?: CollationFunction): (a: SqlValue, b: SqlValue) => number;
+/**
+ * Row comparator for identity checks (DISTINCT, set operations) that routes each
+ * column through its declared logical type's `compare` when — and only when — that
+ * type carries semantic ordering ({@link hasSemanticOrdering}); all other columns
+ * keep the storage-class + collation comparison of
+ * {@link createCollationRowComparator}. This makes row identity agree with `=`
+ * (e.g. TIMESPAN 'PT1H' ≡ 'PT60M' collapses) without perturbing collation-aware
+ * text identity on ANY/TEXT columns, whose declared `compare` is not
+ * collation-aware and must not be consulted here.
+ *
+ * Per-column routing is {@link createSemanticValueComparator}.
+ */
+export declare function createSemanticRowComparator(types: readonly (LogicalType | undefined)[], collations: readonly CollationFunction[]): (a: Row, b: Row) => number;
 /**
  * Determines if a SqlValue is truthy for filter purposes.
  * In SQL semantics (numeric truthiness):

package/dist/src/util/comparison.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"comparison.d.ts","sourceRoot":"","sources":["../../../src/util/comparison.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"comparison.d.ts","sourceRoot":"","sources":["../../../src/util/comparison.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAGxD,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAKlG,YAAY,EAAE,iBAAiB,EAAE,CAAC;AASlC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAkB9D;AAsBD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,iBAE9B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,iBAE9B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,iBAQ7B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAOpF;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D;AAgCD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CActG;AA0GD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAEjE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,SAAS,QAAQ,EAAE,EAAE,CAAC,EAAE,SAAS,QAAQ,EAAE,GAAG,OAAO,CAM1F;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,OAAO,CAEnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,GACpC,iBAAiB,EAAE,CAErB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAE,iBAAiB,GAAG,MAAM,CAmBvG;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO,CAEvD;AAED;;GAEG;AACH,0BAAkB,aAAa;IAC9B,GAAG,IAAI;IACP,IAAI,IAAI;CACR;AAED;;GAEG;AACH,0BAAkB,aAAa;IAC9B,OAAO,IAAI,CAAG,gEAAgE;IAC9E,KAAK,IAAI;IACT,IAAI,IAAI;CACR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACrC,CAAC,EAAE,QAAQ,EACX,CAAC,EAAE,QAAQ,EACX,SAAS,EAAE,aAAa,EACxB,aAAa,EAAE,aAAa,EAC5B,aAAa,EAAE,iBAAiB,GAC9B,MAAM,CAQR;AAeD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAC1C,SAAS,GAAE,KAAK,GAAG,MAAc,EACjC,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,EAChC,aAAa,GAAE,iBAAoC,GACjD,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,KAAK,MAAM,CAYtC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,IAAI,WAAW,CAEtF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAEjF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,sBAAsB,CACrC,CAAC,EAAE,WAAW,GAAG,SAAS,EAC1B,CAAC,EAAE,WAAW,GAAG,SAAS,GACxB,OAAO,CAKT;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,CAAC,CAAC,KAAK,EAAE,QAAQ,KAAK,QAAQ,CAAC,GAAG,SAAS,CAI/G;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC3C,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,SAAS,GAAE,KAAK,GAAG,MAAc,EACjC,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,EAChC,aAAa,GAAE,iBAAoC,GACjD,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,KAAK,MAAM,CAmBtC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,6BAA6B,CAC5C,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,SAAS,GAAE,iBAAoC,GAC7C,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,KAAK,MAAM,CAItC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAC1C,KAAK,EAAE,SAAS,CAAC,WAAW,GAAG,SAAS,CAAC,EAAE,EAC3C,UAAU,EAAE,SAAS,iBAAiB,EAAE,GACtC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,KAAK,MAAM,CAY5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAuBjD;AACD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,CAalD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CACjC,CAAC,EAAE,QAAQ,EACX,CAAC,EAAE,QAAQ,EACX,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,WAAW,EAClB,SAAS,CAAC,EAAE,iBAAiB,GAC3B,MAAM,CAsBR;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,WAAW,EACjB,SAAS,CAAC,EAAE,iBAAiB,GAC3B,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,KAAK,MAAM,CA0BtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACvC,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,UAAU,CAAC,EAAE,SAAS,CAAC,iBAAiB,GAAG,SAAS,CAAC,EAAE,GACrD,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,KAAK,MAAM,CAa5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC3C,UAAU,EAAE,SAAS,iBAAiB,EAAE,GACtC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,KAAK,MAAM,CAU5B"}

package/dist/src/util/comparison.js

@@ -221,8 +221,14 @@ function compareNumbers(a, b) {
  *
  * Their ORDERINGS are unrelated and always have been: this branch compares canonical JSON
  * *syntax* (braces, quotes, commas included), while `deepCompareJson` ranks by JSON type,
- * then key list, then values. Only this branch's order is load-bearing — it is what the
- * store's `encodeObject` writes as UTF-8 and physically sorts by.
+ * then key list, then values. This branch's order is what the store's `encodeObject`
+ * writes as UTF-8 and physically sorts by.
+ *
+ * This branch is reached only where an OBJECT value is ordered WITHOUT a declared JSON
+ * logical type to route it. A declared JSON column is compared through
+ * `createTypedComparator(JSON_TYPE, …)` everywhere it is ordered — the memory BTree's key
+ * comparator, `<`/`>`/BETWEEN at runtime, and ORDER BY — so an indexed JSON range seek
+ * walks exactly the window the operators evaluate.
  *
  * NOTE: assumes OBJECT-class values are treated as immutable — the string is cached on
  * first serialization and never invalidated, so mutating a value in place after it has
@@ -407,34 +413,27 @@ export var NullsOrdering;
  * @returns -1 if a < b, 0 if a === b, 1 if a > b (after applying direction and null ordering)
  */
 export function compareWithOrderByFast(a, b, direction, nullsOrdering, collationFunc) {
-    let comparison;
     // Fast path: both values are non-NULL (most common case)
     if (a !== null && b !== null) {
-        comparison = compareSqlValuesFast(a, b, collationFunc);
-    }
-    else if (a === null && b === null) {
-        comparison = 0;
-    }
-    else if (a === null) {
-        // Explicit NULLS ordering is absolute — not affected by ASC/DESC
-        if (nullsOrdering === NullsOrdering.FIRST)
-            return -1;
-        if (nullsOrdering === NullsOrdering.LAST)
-            return 1;
-        // Default behavior: nulls always first (both ASC and DESC)
-        comparison = direction === SortDirection.DESC ? 1 : -1;
-    }
-    else { // b === null
-        // Explicit NULLS ordering is absolute — not affected by ASC/DESC
-        if (nullsOrdering === NullsOrdering.FIRST)
-            return 1;
-        if (nullsOrdering === NullsOrdering.LAST)
-            return -1;
-        // Default behavior: nulls always first (both ASC and DESC)
-        comparison = direction === SortDirection.DESC ? -1 : 1;
+        const comparison = compareSqlValuesFast(a, b, collationFunc);
+        // Apply DESC direction (branchless when direction is ASC)
+        return direction === SortDirection.DESC ? -comparison : comparison;
     }
-    // Apply DESC direction (branchless when direction is ASC)
-    return direction === SortDirection.DESC ? -comparison : comparison;
+    return orderByNullResult(a, b, nullsOrdering);
+}
+/**
+ * Final ORDER BY verdict for a pair with at least one NULL. NULL placement is
+ * absolute — never affected by ASC/DESC: explicit NULLS FIRST/LAST pin the ends,
+ * and the default places NULLs first for both directions (SQLite-compatible; the
+ * historical direction-conditioned form in {@link compareWithOrderByFast} negated
+ * itself back to the same result).
+ */
+function orderByNullResult(a, b, nullsOrdering) {
+    if (a === null && b === null)
+        return 0;
+    if (a === null)
+        return nullsOrdering === NullsOrdering.LAST ? 1 : -1;
+    return nullsOrdering === NullsOrdering.LAST ? -1 : 1;
 }
 /**
  * Factory function that takes a pre-resolved collation function.
@@ -457,6 +456,167 @@ export function createOrderByComparatorFast(direction = 'asc', nullsOrdering, co
         return compareWithOrderByFast(a, b, directionFlag, nullsFlag, collationFunc);
     };
 }
+/**
+ * True when a logical type's `compare` defines an order that observably differs from
+ * storage-class + collation ordering (see {@link LogicalType.semanticOrdering}). This
+ * is the routing predicate for user-visible ordering/identity sites: ORDER BY,
+ * comparison operators, range-scan bound filters, and DISTINCT/GROUP BY identity use
+ * the type's `compare` exactly when this returns true.
+ */
+export function hasSemanticOrdering(type) {
+    return type?.semanticOrdering === true && typeof type.compare === 'function';
+}
+/**
+ * True when two logical types order values differently — i.e. the comparators
+ * {@link createTypedComparator} builds for them are not interchangeable, so any structure
+ * keyed by one has to be re-sorted (and its uniqueness re-judged) to move to the other.
+ *
+ * `createTypedComparator(type, coll)` is fully determined by `type.compare`: present → the
+ * type's own `compare`; absent → `compareSqlValuesFast` under the collation. So comparing
+ * the two `compare` identities is exactly the question, and it catches more than a
+ * {@link hasSemanticOrdering} check would:
+ *
+ *  - TEXT ↔ TIMESPAN — TIMESPAN's `compare` ranks by elapsed time, so 'PT1H', 'PT60M' and
+ *    'PT3600S' are one value where text sees three.
+ *  - TEXT ↔ JSON — JSON's `compare` ranks by canonical structure, so '{"a":1}' and
+ *    '{ "a" : 1 }' are one value.
+ *  - TEXT ↔ DATE / TIME / DATETIME — these carry their own `compare` hard-wired to
+ *    BINARY_COLLATION, ignoring the column's declared collation, so `text collate nocase →
+ *    date` really does re-order even though both orderings are "textual".
+ *
+ * A retype that flattens to the SAME logical type object (`text → varchar(50)`,
+ * `integer → bigint`) shares one `compare` and is correctly reported as no change.
+ *
+ * NOTE: deliberately conservative — it answers "may the order move", not "does it". The
+ * DATE / TIME / DATETIME family compares exactly as BINARY text does, so under the only
+ * collation those types legally accept (BINARY — `supportedCollations: []`) a `text → date`
+ * retype re-sorts every structure into the order it was already in. Harmless but O(rows);
+ * if a retype on a large table ever shows up as slow, narrow the predicate to a probe of the
+ * two comparators over a representative value set, or special-case the BINARY-equivalent
+ * comparators by identity.
+ */
+export function comparisonSemanticsDiffer(a, b) {
+    return a.compare !== b.compare;
+}
+/**
+ * True when two declared logical types may share ONE physical equi-join key — i.e. when
+ * comparing their values with a single type-blind comparator (a serialized hash key, a
+ * merge co-walk) reproduces what `=` says about them.
+ *
+ * The admissible shapes are "neither side declares a semantic-ordering type" or "both
+ * declare the SAME one". A **mixed** pair (`timespan` ↔ `text`) is the defect this gates:
+ * `=` runs the generic comparison path, which applies a runtime duration check whenever
+ * either side is temporal, so 'PT1H' = 'PT60M'; a hash or merge join comparing raw text
+ * disagrees and silently drops the row. Merge join cannot be rescued by canonicalizing
+ * the key either — it needs both inputs physically sorted in its comparator's order, and
+ * a `timespan` side is sorted by elapsed time while a `text` side is sorted by text, so
+ * no single comparator merges the two. Declining is the only sound answer; the pair
+ * demotes to the residual / generic join, where `=`'s own semantics apply.
+ *
+ * NOT {@link comparisonSemanticsDiffer}, which asks a different question (may an ordered
+ * structure keyed under `a` be reused under `b`) by comparing `compare` identity. EVERY
+ * builtin type carries its own `compare`, so that predicate reports "differ" for an
+ * ordinary `integer` ↔ `real` join key and would cost a hash join for no correctness
+ * gain. This one keys on the `semanticOrdering` flag, which is exactly the set of types
+ * whose order is not reproducible from storage class + collation.
+ *
+ * See `docs/types.md` § "Semantic ordering".
+ */
+export function semanticOrderingsAgree(a, b) {
+    const semA = hasSemanticOrdering(a);
+    const semB = hasSemanticOrdering(b);
+    if (!semA && !semB)
+        return true;
+    return semA && semB && a === b;
+}
+/**
+ * Canonical key-identity transform for a declared logical type, or undefined when raw
+ * values already key faithfully. Defined exactly when the type carries semantic ordering
+ * AND a `groupKey` hook (TIMESPAN — its stored text is not canonical for equality:
+ * 'PT1H' ≡ 'PT60M'); JSON has semantic ordering but its canonical text is already
+ * identity-faithful, so it takes no transform. Every hash-, set-, or byte-keyed identity
+ * site (GROUP BY, hash joins, IN membership, the persistent store's PK/index key encoding,
+ * the isolation overlay's shadowing keys) must run values through this before serializing, or two
+ * values the type's `compare` calls equal land on distinct keys.
+ */
+export function semanticKeyTransform(type) {
+    return hasSemanticOrdering(type) && type.groupKey
+        ? (value) => type.groupKey(value)
+        : undefined;
+}
+/**
+ * ORDER BY comparator for one sort key of a declared logical type. When the type
+ * carries semantic ordering (see {@link hasSemanticOrdering}), non-NULL pairs are
+ * ranked by the type's `compare` (via {@link createTypedComparator}, which keeps the
+ * storage-class-mismatch fallback so a probe of a different storage class never
+ * falsely equals); otherwise this is exactly {@link createOrderByComparatorFast}.
+ *
+ * NULL placement is handled HERE, never delegated to `type.compare` — the type
+ * convention (NULL smallest, always) differs from ORDER BY's NULLS FIRST/LAST and
+ * default rules, which {@link orderByNullResult} implements.
+ */
+export function createTypedOrderByComparator(type, direction = 'asc', nullsOrdering, collationFunc = BINARY_COLLATION) {
+    if (!hasSemanticOrdering(type)) {
+        return createOrderByComparatorFast(direction, nullsOrdering, collationFunc);
+    }
+    const negate = direction === 'desc';
+    const nullsFlag = nullsOrdering === 'first'
+        ? NullsOrdering.FIRST
+        : nullsOrdering === 'last'
+            ? NullsOrdering.LAST
+            : NullsOrdering.DEFAULT;
+    const typedCompare = createTypedComparator(type, collationFunc);
+    return (a, b) => {
+        if (a !== null && b !== null) {
+            const comparison = typedCompare(a, b);
+            return negate ? -comparison : comparison;
+        }
+        return orderByNullResult(a, b, nullsFlag);
+    };
+}
+/**
+ * The comparator an ordering site uses for a single value of `type` under
+ * `collation`: the type's own `compare` when it carries semantic ordering
+ * ({@link hasSemanticOrdering}), else storage-class + collation ordering. The
+ * scalar form of {@link createSemanticRowComparator}'s per-column routing — one
+ * copy of the routing rule, shared by row identity (DISTINCT/set operations) and
+ * the min/max aggregate binding (`bindArgs` in func/builtins/aggregate.ts).
+ *
+ * `type` may be undefined (untyped/ANY) — such values use the collation
+ * comparator, byte-identical to the historical BINARY default when no collation
+ * is passed. Safe for runtime type drift: the typed path's
+ * storage-class-mismatch guard (see {@link createTypedComparator}) falls back to
+ * storage-class ordering rather than mis-parsing.
+ */
+export function createSemanticValueComparator(type, collation = BINARY_COLLATION) {
+    return hasSemanticOrdering(type)
+        ? createTypedComparator(type, collation)
+        : (a, b) => compareSqlValuesFast(a, b, collation);
+}
+/**
+ * Row comparator for identity checks (DISTINCT, set operations) that routes each
+ * column through its declared logical type's `compare` when — and only when — that
+ * type carries semantic ordering ({@link hasSemanticOrdering}); all other columns
+ * keep the storage-class + collation comparison of
+ * {@link createCollationRowComparator}. This makes row identity agree with `=`
+ * (e.g. TIMESPAN 'PT1H' ≡ 'PT60M' collapses) without perturbing collation-aware
+ * text identity on ANY/TEXT columns, whose declared `compare` is not
+ * collation-aware and must not be consulted here.
+ *
+ * Per-column routing is {@link createSemanticValueComparator}.
+ */
+export function createSemanticRowComparator(types, collations) {
+    const comparators = types.map((type, i) => createSemanticValueComparator(type, collations[i] ?? BINARY_COLLATION));
+    const len = comparators.length;
+    return (a, b) => {
+        for (let i = 0; i < len; i++) {
+            const cmp = comparators[i](a[i], b[i]);
+            if (cmp !== 0)
+                return cmp;
+        }
+        return 0;
+    };
+}
 /**
  * Determines if a SqlValue is truthy for filter purposes.
  * In SQL semantics (numeric truthiness):