@quereus/store 4.4.0 → 4.5.0

package/dist/src/common/store-table.js

@@ -9,11 +9,12 @@
  *   - Index stores: {schema}.{table}_idx_{name} - one per secondary index
  *   - Stats store: __stats__ - unified store for all table statistics, keyed by {schema}.{table}
  */
-import { VirtualTable, IndexConstraintOp, ConflictResolution, QuereusError, StatusCode, compareSqlValues, compareSqlValuesFast, resolveUniqueEnforcementCollations, BINARY_COLLATION, rowsValueIdentical, validateAndParse, compilePredicate, decodeIdxStr, maintainedTableUniqueViolationError, uniqueEnforcementCollations, logicalTypeCanHoldText, pkKeyCollationName, } from '@quereus/quereus';
+import { VirtualTable, IndexConstraintOp, ConflictResolution, QuereusError, StatusCode, compareSqlValues, compareSqlValuesFast, createTypedComparator, hasSemanticOrdering, semanticKeyTransform, resolveUniqueEnforcementCollations, uniqueEnforcementComparators, BINARY_COLLATION, rowsValueIdentical, coerceRowToSchema, compilePredicate, decodeIdxStr, planKindFromCode, maintainedTableUniqueViolationError, uniqueEnforcementCollations, logicalTypeCanHoldText, pkKeyCollationName, JSON_TYPE, } from '@quereus/quereus';
 import { bytesEqual, bytesToHex, compareBytes } from './bytes.js';
 import { StoreConnection } from './store-connection.js';
 import { buildDataKey, buildIndexKey, buildIndexPrefixBounds, buildFullScanBounds, buildPkPrefixBounds, buildStatsKey, } from './key-builder.js';
 import { serializeRow, deserializeRow, serializeStats, deserializeStats, } from './serialization.js';
+import { jsonStructuralKey } from './json-key.js';
 /** Number of mutations before persisting statistics. */
 const STATS_FLUSH_INTERVAL = 100;
 /** True when `key` falls within the (gte/gt/lte/lt) window of `bounds`. */
@@ -87,6 +88,76 @@ export function resolvePkKeyCollations(pkDef, columns, fallback) {
         return name === undefined ? undefined : (name || fallback).toUpperCase();
     });
 }
+/**
+ * The store's per-type key VALUE TRANSFORM for a semantic-ordering logical type, or
+ * `undefined` when raw values already key faithfully.
+ *
+ * The contract is TWO-sided — identity AND order. `StoreTable` implements no
+ * `comparePrimaryKey`, so the isolation layer merges overlay against underlying with
+ * its own fallback comparator (the PK type's `compare` via `createTypedComparator`)
+ * and needs this table's key BYTE order to agree with it; and byte equality must be
+ * exactly the type's equality, or two spellings of one value land on two keys.
+ *
+ *  - JSON → the store-local structural encoder ({@link jsonStructuralKey}): a
+ *    `Uint8Array` whose memcmp order reproduces the type's structural `compare`
+ *    (canonical-text bytes are identity-faithful but sort `[10]` before `[2]`,
+ *    which broke overlay shadowing — see json-key.ts).
+ *  - Everything else → the engine's {@link semanticKeyTransform} (the type's
+ *    `groupKey`). Today that is TIMESPAN: total seconds against the same reference
+ *    date as `TIMESPAN.compare`, so 'PT1H' and 'PT60M' collide on one key AND byte
+ *    order is elapsed-time order.
+ *
+ * JSON deliberately gets NO engine `groupKey` — `groupKey` also drives GROUP BY /
+ * `IN` / hash-join identity, where canonical-text identity is already correct and a
+ * `Uint8Array` key would be a behaviour change for no benefit. Hence this
+ * store-local seam. A semantic-ordering type with NEITHER a `groupKey` nor an entry
+ * here cannot key a persisted structure soundly; `StoreTable` rejects it at DDL time
+ * (see `validateSemanticKeyTransforms`).
+ */
+export function storeSemanticKeyTransform(type) {
+    // Matched by NAME, not object identity (`type === JSON_TYPE`): the engine and this
+    // package can be loaded as two module instances (e.g. the logic suite runs the
+    // engine from src via ts-node while the store resolves `@quereus/quereus` to dist),
+    // and each instance carries its own JSON_TYPE singleton. The `hasSemanticOrdering`
+    // gate keeps a hypothetical plain custom type named 'JSON' out of this branch.
+    if (hasSemanticOrdering(type) && type.name === JSON_TYPE.name)
+        return jsonStructuralKey;
+    return semanticKeyTransform(type);
+}
+/**
+ * Resolve the per-column key value transform for each primary-key column —
+ * {@link storeSemanticKeyTransform} of the member's logical type. One entry per PK
+ * member in `pkDef` order; `undefined` for every type whose raw value already keys
+ * faithfully. The companion of {@link resolvePkKeyCollations}: every call site that
+ * threads the collations MUST thread these too, or key identity/order drifts
+ * between the write path and the rebuild/lookup path.
+ */
+export function resolvePkKeyTransforms(pkDef, columns) {
+    return pkDef.map(def => storeSemanticKeyTransform(columns[def.index]?.logicalType));
+}
+/**
+ * Per-column key value transforms for a secondary index's OWN columns (the
+ * index half of `buildIndexKey`), positionally aligned with `index.columns`.
+ * Same rule as {@link resolvePkKeyTransforms}: a semantic-ordering member
+ * canonicalizes through {@link storeSemanticKeyTransform}, everything else
+ * encodes raw.
+ */
+export function resolveIndexKeyTransforms(index, columns) {
+    return index.columns.map(col => storeSemanticKeyTransform(columns[col.index]?.logicalType));
+}
+/**
+ * Per-PK-column typed equality comparator for semantic-ordering members, `undefined`
+ * elsewhere. Backs {@link StoreTable.keysEqual}: two PK arrays naming the same
+ * physical key under {@link resolvePkKeyTransforms} ('PT1H' / 'PT60M') must also
+ * answer "same row" here, or self-PK exclusion in the UNIQUE checks false-conflicts
+ * a row against its own differently-spelled image.
+ */
+function resolvePkSemanticEquality(pkDef, columns) {
+    return pkDef.map(def => {
+        const logicalType = columns[def.index]?.logicalType;
+        return hasSemanticOrdering(logicalType) ? createTypedComparator(logicalType) : undefined;
+    });
+}
 /**
  * True when `col` can produce a TEXT value at runtime, and so when its physical
  * key bytes are produced by a collation normalizer rather than a type-native
@@ -128,6 +199,17 @@ export function columnCanHoldText(col) {
  * "mark handled" and "build a window" decisions can never disagree.
  */
 export function keyOrderMatchesCollation(db, column, keyCollation, compareCollation) {
+    // A semantic-ordering logical type (TIMESPAN, JSON — see docs/types.md "Semantic
+    // ordering") is ordered by its `compare` (elapsed time / structural), which the
+    // engine's Sort, comparison operators, and the memory backend all use. Both types'
+    // key bytes now encode through an order-preserving transform (TIMESPAN's `groupKey`
+    // total seconds; JSON's structural encoding — see `storeSemanticKeyTransform`), so
+    // byte order DOES match the type's `compare` for every well-formed value and this
+    // blanket decline is conservative, costing the seek/sort-elision, never a row.
+    // Re-opening the window/advertisement (and the byte-EQ arms in `analyzePKAccess` /
+    // `analyzeIndexAccess`) is tracked in backlog `feat-reopen-timespan-store-seeks`.
+    if (hasSemanticOrdering(column?.logicalType))
+        return false;
     if (!columnCanHoldText(column))
         return true;
     if (compareCollation.toUpperCase() !== keyCollation.toUpperCase())
@@ -145,13 +227,12 @@ export function keyOrderMatchesCollation(db, column, keyCollation, compareCollat
  * already aligned with the key collation for every *textual* PK member.
  *
  * What the advertisement is measured against is the order the planner's `Sort` would have
- * produced, and `Sort` (like every scalar comparison) orders under the operand's COLLATION via
- * `compareSqlValuesFast` — never through `logicalType.compare`. So a collation match is the
- * whole question, even for a member whose type declares a `compare` that orders differently
- * (`TIMESPAN.compare` ranks by `Temporal.Duration` total, `JSON_TYPE.compare` structurally).
- * `MemoryTable`, whose primary-key BTree *is* keyed by `createTypedComparator`, advertises the
- * type's order instead and so disagrees with its own `Sort` — tracked as
- * `bug-memory-pk-btree-orders-by-logical-type-compare`, not something the store should copy.
+ * produced. For most members Sort orders under the operand's COLLATION, so a collation match
+ * is the question; for a member whose logical type carries SEMANTIC ordering (TIMESPAN, JSON
+ * — see docs/types.md "Semantic ordering") Sort now ranks by `logicalType.compare`, which no
+ * text-byte encoding reproduces, and {@link keyOrderMatchesCollation} closes the gate for
+ * such members outright (the memory backend's typed BTree order is the canonical order under
+ * that ruling; the store declines rather than advertising a divergent byte order).
  *
  * `0` ⇒ even the leading member is unsafe: no range seek, no PK-order advertisement.
  * A prefix shorter than the PK truncates the ordering advertisement rather than voiding it.
@@ -279,6 +360,21 @@ export class StoreTable extends VirtualTable {
      * {@link updateSchema} (an ALTER COLUMN SET COLLATE on a PK member changes it).
      */
     pkKeyCollations;
+    /**
+     * Per-PK-column key-identity value transform (see {@link resolvePkKeyTransforms}).
+     * Threaded alongside {@link pkKeyCollations} into every data-key / PK-suffix /
+     * PK-prefix-bounds encode, so a semantic-ordering PK member (TIMESPAN) keys
+     * semantically-equal spellings to one physical key. Recomputed on every
+     * {@link updateSchema}.
+     */
+    pkKeyTransforms;
+    /**
+     * Per-PK-column typed EQUALITY comparator for the semantic-ordering members only —
+     * `undefined` for every other member, which {@link keysEqual} still compares with
+     * strict `!==` as before. Keeps self-PK exclusion and PK-identity questions in
+     * agreement with the physical key identity above ('PT1H' row IS the 'PT60M' row).
+     */
+    pkSemanticEquality;
     /**
      * `db.getCollationResolver()`, bound once at construction. Every collation-aware
      * VALUE comparison this table makes — pushed-constraint re-check, UNIQUE conflict
@@ -345,9 +441,12 @@ export class StoreTable extends VirtualTable {
         };
         this.pkDirections = tableSchema.primaryKeyDefinition.map(pk => !!pk.desc);
         this.pkKeyCollations = resolvePkKeyCollations(tableSchema.primaryKeyDefinition, tableSchema.columns, this.encodeOptions.collation ?? 'NOCASE');
+        this.pkKeyTransforms = resolvePkKeyTransforms(tableSchema.primaryKeyDefinition, tableSchema.columns);
+        this.pkSemanticEquality = resolvePkSemanticEquality(tableSchema.primaryKeyDefinition, tableSchema.columns);
         // Validate the MATERIALIZED schema, so a `_uc_*` over a text column that needs the
         // table key collation K is rejected up front just like an explicit index would be.
         this.validateKeyCollations(this.materializedSchema, this.pkKeyCollations);
+        this.validateSemanticKeyTransforms(this.materializedSchema);
         this.ddlSaved = isConnected;
     }
     /**
@@ -397,6 +496,47 @@ export class StoreTable extends VirtualTable {
                 + `— pass { normalizer } to registerCollation`, StatusCode.ERROR);
         }
     }
+    /**
+     * Reject, at DDL time, a key member whose semantic-ordering logical type has no
+     * store key transform — before a single row is keyed under bytes whose order the
+     * type's `compare` (and so the isolation merge, the memory oracle, and Sort)
+     * disagrees with.
+     *
+     * A semantic-ordering type keys soundly only through an order- and
+     * identity-preserving transform ({@link storeSemanticKeyTransform}: the type's
+     * `groupKey`, or a store-local encoder like JSON's structural one). This gap used
+     * to be undetectable — JSON sat here transform-less for a release, keying in
+     * canonical-text order while every comparator ordered structurally, and the only
+     * symptom was a misaligned overlay merge deep inside a transaction. Unreachable
+     * today (TIMESPAN and JSON are both covered); it exists so the NEXT
+     * semantic-ordering type fails loudly at CREATE TABLE instead.
+     *
+     * Checked over the same materialized schema as {@link validateKeyCollations}:
+     * every PK member and every (explicit or hidden `_uc_*`) index column.
+     *
+     * CAVEAT: this can only check that a transform EXISTS — a `groupKey` that is
+     * identity-faithful but not order-preserving passes undetected, so a new type's
+     * transform still needs its byte order argued against its `compare` (see
+     * json-key.ts for the shape of that argument).
+     */
+    validateSemanticKeyTransforms(schema) {
+        const check = (colIndex, member) => {
+            const col = schema.columns[colIndex];
+            const type = col?.logicalType;
+            if (!hasSemanticOrdering(type) || storeSemanticKeyTransform(type) !== undefined)
+                return;
+            throw new QuereusError(`column ${col?.name ?? String(colIndex)} (${member}): semantic-ordering type `
+                + `${type.name} cannot key a persisted structure: its raw encoding would not `
+                + `reproduce the type's compare order — the type needs an order-preserving `
+                + `groupKey or a store key encoder (see storeSemanticKeyTransform)`, StatusCode.ERROR);
+        };
+        for (const def of schema.primaryKeyDefinition)
+            check(def.index, 'primary key');
+        for (const index of schema.indexes ?? []) {
+            for (const col of index.columns)
+                check(col.index, `index ${index.name}`);
+        }
+    }
     /** Get the table configuration. */
     getConfig() {
         return this.config;
@@ -427,10 +567,13 @@ export class StoreTable extends VirtualTable {
         const materialized = withImplicitUniqueIndexes(newSchema);
         const pkKeyCollations = resolvePkKeyCollations(newSchema.primaryKeyDefinition, newSchema.columns, this.encodeOptions.collation ?? 'NOCASE');
         this.validateKeyCollations(materialized, pkKeyCollations);
+        this.validateSemanticKeyTransforms(materialized);
         this.tableSchema = newSchema;
         this.materializedSchema = materialized;
         this.pkDirections = newSchema.primaryKeyDefinition.map(pk => !!pk.desc);
         this.pkKeyCollations = pkKeyCollations;
+        this.pkKeyTransforms = resolvePkKeyTransforms(newSchema.primaryKeyDefinition, newSchema.columns);
+        this.pkSemanticEquality = resolvePkSemanticEquality(newSchema.primaryKeyDefinition, newSchema.columns);
     }
     /**
      * Mark the table's DDL as already persisted to the catalog, so the lazy
@@ -566,9 +709,13 @@ export class StoreTable extends VirtualTable {
         const bounds = buildFullScanBounds();
         const newPkDirections = newPkDef.map(pk => !!pk.desc);
         const newPkCollations = resolvePkKeyCollations(newPkDef, newColumns, this.encodeOptions.collation ?? 'NOCASE');
+        // Post-ALTER key-identity transforms too: an ALTER PRIMARY KEY onto (or a SET
+        // DATA TYPE creating) a semantic-ordering member must collapse equal spellings
+        // — pass 1 then rejects 'PT1H'/'PT60M' as a duplicate PK, all-or-nothing.
+        const newPkTransforms = resolvePkKeyTransforms(newPkDef, newColumns);
         // Both passes key rows through this one helper, so a collision judged in pass 1
         // is byte-identical to the key pass 2 writes.
-        const computeNewKey = (row) => buildDataKey(newPkDef.map(pk => row[pk.index]), this.encodeOptions, newPkDirections, newPkCollations);
+        const computeNewKey = (row) => buildDataKey(newPkDef.map(pk => row[pk.index]), this.encodeOptions, newPkDirections, newPkCollations, newPkTransforms);
         // Pass 1 — collision detection only. Hold one hex signature per new key, never
         // the row or old key. On a repeat, reject before any write; the store is
         // untouched on rejection.
@@ -783,11 +930,7 @@ export class StoreTable extends VirtualTable {
      * objects before PK extraction, serialization, and index-key construction.
      */
     coerceRow(row) {
-        const cols = this.tableSchema.columns;
-        if (row.length > cols.length) {
-            throw new QuereusError(`Too many values for ${this.schemaName}.${this.tableName}: expected ${cols.length}, got ${row.length}`, StatusCode.ERROR);
-        }
-        return row.map((v, i) => validateAndParse(v, cols[i].logicalType, cols[i].name));
+        return coerceRowToSchema(row, this.tableSchema.columns, `${this.schemaName}.${this.tableName}`);
     }
     /**
      * Query the table with optional filters.
@@ -800,6 +943,16 @@ export class StoreTable extends VirtualTable {
      */
     async *query(filterInfo) {
         const store = await this.ensureStore();
+        // Multi-seek (`plan=5`, an IN-list served as N point seeks) dispatches FIRST —
+        // before analyzePKAccess: the FilterInfo carries N*W EQ constraints, so on a
+        // table whose PK column is also the leading column of the chosen index,
+        // analyzePKAccess would match the FIRST equality and answer a single-value
+        // point lookup — one list value's rows, a silent wrong result.
+        const idxSpec = decodeIdxStr(filterInfo.idxStr);
+        if (idxSpec && planKindFromCode(idxSpec.plan) === 'multiSeek') {
+            yield* this.scanMultiSeek(idxSpec, filterInfo);
+            return;
+        }
         const pkAccess = this.analyzePKAccess(filterInfo);
         if (pkAccess.type === 'point') {
             const row = await this.readLiveRowByPk(pkAccess.values);
@@ -891,6 +1044,22 @@ export class StoreTable extends VirtualTable {
     leadingPkRangeIsOrderSafe() {
         return pkOrderPreservingPrefixLength(this.db, this.tableSchema, this.pkKeyCollations, this.encodeOptions.collation ?? 'NOCASE') >= 1;
     }
+    /**
+     * True when some PK member's logical type carries semantic ordering (TIMESPAN,
+     * JSON). Such PKs decline the point arm and full-scan, where
+     * {@link matchesFilters} applies the type's compare. Historically required —
+     * byte-key equality was a strict subset of the type's equality ('PT1H' ≡
+     * 'PT60M' elapsed-time-equal, byte-distinct) and a point window under-fetched
+     * with no residual able to resurrect a skipped row. Both types' key transforms
+     * (see {@link storeSemanticKeyTransform}) now make byte equality the type's
+     * equality, so the decline is conservative; re-opening is tracked in backlog
+     * `feat-reopen-timespan-store-seeks`. (Range windows and ordering
+     * advertisements are already declined by {@link keyOrderMatchesCollation}.)
+     */
+    pkHasSemanticOrderingMember() {
+        const schema = this.tableSchema;
+        return schema.primaryKeyDefinition.some(def => hasSemanticOrdering(schema.columns[def.index]?.logicalType));
+    }
     /** Analyze filter info to determine PK access pattern. */
     analyzePKAccess(filterInfo) {
         const schema = this.tableSchema;
@@ -912,7 +1081,7 @@ export class StoreTable extends VirtualTable {
                 break;
             }
         }
-        if (allEq) {
+        if (allEq && !this.pkHasSemanticOrderingMember()) {
             return { type: 'point', values: eqValues };
         }
         // Check for range constraints on first PK column
@@ -1068,9 +1237,14 @@ export class StoreTable extends VirtualTable {
             return null;
         const indexCols = index.columns.map(c => c.index);
         const indexDirections = index.columns.map(c => !!c.desc);
-        // Contiguous leading-prefix EQ → point/prefix window.
+        // Contiguous leading-prefix EQ → point/prefix window. A prefix member whose
+        // logical type carries semantic ordering stops the prefix: its byte-equality
+        // window under-fetches the type's equality (see pkHasSemanticOrderingMember),
+        // and a skipped row cannot be resurrected by the residual.
         const eqValues = [];
         for (let i = 0; i < indexCols.length; i++) {
+            if (hasSemanticOrdering(this.tableSchema.columns[indexCols[i]]?.logicalType))
+                break;
             const eq = filterInfo.constraints?.find(c => c.constraint.iColumn === indexCols[i]
                 && c.constraint.op === IndexConstraintOp.EQ
                 && c.argvIndex > 0);
@@ -1170,12 +1344,13 @@ export class StoreTable extends VirtualTable {
      * a superset, and a stale entry whose indexed column no longer matches is
      * dropped).
      */
-    async *scanIndex(indexStore, access, filterInfo) {
+    async *scanIndex(indexStore, access, filterInfo, multi) {
         // Re-check each resolved row under the INDEX's per-column collation (see
         // matchesFilters): the planner dropped the residual based on the index
         // column's collation, which an explicit index `COLLATE` can make differ from
         // the table column's declared collation.
-        const indexCollations = this.resolveFilterCollations(filterInfo, this.indexColumnCollations(access.index));
+        const indexCollations = multi?.collations
+            ?? this.resolveFilterCollations(filterInfo, this.indexColumnCollations(access.index));
         for await (const entry of this.iterateEffective(indexStore, access.bounds)) {
             // NOTE: a legacy index store (written before index values carried the data
             // key) holds EMPTY values; a zero-length data key is not a row key, so skip
@@ -1190,6 +1365,14 @@ export class StoreTable extends VirtualTable {
             // fall back to a full scan the first time an empty value is seen.
             if (entry.value.length === 0)
                 continue;
+            // Cross-window dedup for a multi-seek: a data key an earlier window already
+            // YIELDED is skipped before the data-store read, so a duplicate costs no
+            // extra `get`. The seen-set is only ever ADDED to on a yield (below) — adding
+            // at visit time would let a stale index entry that fails its residual poison
+            // the set and suppress the row's live entry in a later window.
+            const dataKeyHex = multi ? bytesToHex(entry.value) : undefined;
+            if (dataKeyHex !== undefined && multi.seen.has(dataKeyHex))
+                continue;
             // NOTE: one extra data-store `get` per matched index entry — the row lives
             // in the data store, not the index (the index value carries only the data
             // key, no covering payload). Fine now; if index-covered scans ever dominate
@@ -1197,7 +1380,204 @@ export class StoreTable extends VirtualTable {
             // at the cost of an index rewrite on EVERY column change (not just indexed
             // columns) — deliberately not done here.
             const row = await this.readEffectiveRowByKey(entry.value);
-            if (row && this.matchesFilters(row, filterInfo, indexCollations)) {
+            if (!row)
+                continue;
+            if (this.matchesFilters(row, filterInfo, indexCollations)
+                || (multi !== undefined && multi.extraTuples.some(fi => this.matchesFilters(row, fi, indexCollations)))) {
+                if (dataKeyHex !== undefined)
+                    multi.seen.add(dataKeyHex);
+                yield row;
+            }
+        }
+    }
+    /**
+     * Fail loudly on a multi-seek FilterInfo this table cannot serve. The plan already
+     * dropped the residual Filter, and {@link matchesFilters} ANDs every pushed
+     * constraint — so falling through to the scan arm would AND N mutually-exclusive
+     * equalities and return zero rows: a silent wrong answer, not a slow one.
+     */
+    multiSeekMalformed(filterInfo, why) {
+        throw new QuereusError(`Malformed multi-seek FilterInfo (idxStr '${filterInfo.idxStr}') on ${this.schemaName}.${this.tableName}: ${why}`, StatusCode.INTERNAL);
+    }
+    /**
+     * Decode a multi-seek FilterInfo into its N seek tuples of width W. Tuple i pairs
+     * `args[i*W … i*W+W-1]` with the same slice of `constraints` (argvIndex runs
+     * 1…N*W in order — see rule-select-access-path's multiSeek emission). A tuple with
+     * a NULL/undefined component is dropped: IN is set membership and a NULL component
+     * matches nothing. The planner pre-reduces literal lists, but a parameter-bound /
+     * mixed-binding list reaches here unreduced, so this skip is the only line of
+     * defense for those.
+     */
+    decodeMultiSeekTuples(spec, filterInfo) {
+        const seekWidth = Number.parseInt(spec.params.get('seekWidth') ?? '1', 10);
+        const inCount = Number.parseInt(spec.params.get('inCount') ?? '0', 10);
+        if (!Number.isInteger(seekWidth) || seekWidth < 1) {
+            this.multiSeekMalformed(filterInfo, `seekWidth=${spec.params.get('seekWidth')}`);
+        }
+        if (!Number.isInteger(inCount) || inCount < 1) {
+            this.multiSeekMalformed(filterInfo, `inCount=${spec.params.get('inCount')}`);
+        }
+        const constraints = filterInfo.constraints ?? [];
+        if (constraints.length < inCount * seekWidth) {
+            this.multiSeekMalformed(filterInfo, `${constraints.length} constraints for ${inCount}×${seekWidth} seek keys`);
+        }
+        if (filterInfo.args.length < inCount * seekWidth) {
+            this.multiSeekMalformed(filterInfo, `${filterInfo.args.length} args for ${inCount}×${seekWidth} seek keys`);
+        }
+        const tuples = [];
+        for (let t = 0; t < inCount; t++) {
+            const entries = constraints.slice(t * seekWidth, (t + 1) * seekWidth);
+            if (entries.some(e => e.constraint.op !== IndexConstraintOp.EQ || e.argvIndex <= 0)) {
+                this.multiSeekMalformed(filterInfo, `seek tuple ${t} carries a non-EQ or unbound constraint`);
+            }
+            const values = entries.map(e => filterInfo.args[e.argvIndex - 1]);
+            if (values.some(v => v === null || v === undefined))
+                continue;
+            tuples.push({ entries, values });
+        }
+        return { tuples, seekWidth };
+    }
+    /**
+     * Order one tuple's values to match `keyCols` (the leading index columns, or the
+     * PK definition) using each constraint entry's column. The plan's seek columns and
+     * the constraint list must agree; a tuple that does not cover exactly those
+     * columns is malformed.
+     */
+    orderTupleValues(tuple, keyCols, filterInfo) {
+        const byCol = new Map();
+        tuple.entries.forEach((e, i) => byCol.set(e.constraint.iColumn, tuple.values[i]));
+        if (byCol.size !== keyCols.length) {
+            this.multiSeekMalformed(filterInfo, `seek tuple covers ${byCol.size} columns, expected ${keyCols.length}`);
+        }
+        return keyCols.map(colIdx => {
+            if (!byCol.has(colIdx))
+                this.multiSeekMalformed(filterInfo, `seek tuple missing column ${colIdx}`);
+            return byCol.get(colIdx);
+        });
+    }
+    /**
+     * Serve a multi-seek (`plan=5`) FilterInfo: one point window per distinct
+     * IN-list tuple, scanned in ascending encoded-key order.
+     *
+     * Window order is not cosmetic. Encoded-byte order IS index-key order (per-column
+     * DESC inversion is baked into the bytes), and the isolation overlay merges an
+     * index scan with its pending rows by (indexKey, PK) — an out-of-order underlying
+     * stream misplaces overlay rows in the output. Two overlap hazards are folded
+     * away before scanning:
+     *   - Tuples whose K-encoded prefix byte-matches (duplicate bound parameters, or
+     *     case variants under a NOCASE table key collation) share ONE window, each
+     *     kept as a residual alternative — see {@link MultiSeekWindowContext} for why
+     *     a single tuple's residual would drop rows when the comparison collation is
+     *     finer than K.
+     *   - A window with no finite upper bound (all-0xff prefix — see
+     *     buildIndexPrefixBounds) contains every later-sorting window outright (any
+     *     key ≥ an all-0xff prefix necessarily starts with it), so those windows fold
+     *     into it instead of re-scanning an overlapping range out of order.
+     *
+     * Emission is lazy per window — `… in (…) limit 1` stops after the first yielded
+     * row without materializing the remaining windows. Each window goes through
+     * {@link scanIndex} → {@link iterateEffective}, so read-your-own-writes and the
+     * stale-entry / deleted-row defenses hold per seek key.
+     */
+    async *scanMultiSeek(spec, filterInfo) {
+        const { tuples, seekWidth } = this.decodeMultiSeekTuples(spec, filterInfo);
+        if (spec.indexName === '_primary_') {
+            yield* this.scanMultiSeekPrimary(tuples, seekWidth, filterInfo);
+            return;
+        }
+        const index = this.resolveIndexFromIdxStr(filterInfo.idxStr);
+        if (!index)
+            this.multiSeekMalformed(filterInfo, `no index named '${spec.indexName}'`);
+        const indexCols = index.columns.map(c => c.index);
+        const indexDirections = index.columns.map(c => !!c.desc);
+        if (seekWidth > indexCols.length) {
+            this.multiSeekMalformed(filterInfo, `seekWidth ${seekWidth} exceeds ${index.name}'s ${indexCols.length} columns`);
+        }
+        const seekCols = indexCols.slice(0, seekWidth);
+        // The K-encoded byte windows below carry no residual able to resurrect a
+        // skipped row, so a seek column whose byte equality under-fetches the type's
+        // equality (TIMESPAN, JSON — see pkHasSemanticOrderingMember) cannot be
+        // multi-seeked. StoreModule.tryIndexAccessPlan declines such plans; one
+        // arriving anyway is malformed.
+        if (seekCols.some(colIdx => hasSemanticOrdering(this.tableSchema.columns[colIdx]?.logicalType))) {
+            this.multiSeekMalformed(filterInfo, 'semantic-ordering seek column');
+        }
+        // One window per distinct K-encoded tuple prefix; K-equal tuples merge into
+        // one window, each kept as a residual alternative.
+        const windows = new Map();
+        for (const tuple of tuples) {
+            const ordered = this.orderTupleValues(tuple, seekCols, filterInfo);
+            const bounds = buildIndexPrefixBounds(ordered, this.encodeOptions, indexDirections.slice(0, seekWidth));
+            const hex = bytesToHex(bounds.gte);
+            const info = { ...filterInfo, constraints: tuple.entries };
+            const existing = windows.get(hex);
+            if (existing)
+                existing.infos.push(info);
+            else
+                windows.set(hex, { bounds, infos: [info] });
+        }
+        if (windows.size === 0)
+            return; // every tuple had a NULL component — nothing matches
+        const sorted = [...windows.values()].sort((a, b) => compareBytes(a.bounds.gte, b.bounds.gte));
+        const disjoint = [];
+        for (const w of sorted) {
+            const last = disjoint[disjoint.length - 1];
+            if (last && last.bounds.lt === undefined)
+                last.infos.push(...w.infos);
+            else
+                disjoint.push(w);
+        }
+        const indexStore = await this.ensureIndexStore(index.name);
+        // Identical for every window (resolveFilterCollations dedups by column), so
+        // resolve once and thread it through.
+        const collations = this.resolveFilterCollations(filterInfo, this.indexColumnCollations(index));
+        const seen = new Set();
+        for (const w of disjoint) {
+            yield* this.scanIndex(indexStore, { index, type: 'point', bounds: w.bounds }, w.infos[0], { seen, collations, extraTuples: w.infos.slice(1) });
+        }
+    }
+    /**
+     * Multi-seek over the PRIMARY key: each tuple is a full PK, resolved by a point
+     * read in ascending encoded-data-key order (the table's native emission order).
+     *
+     * NOT reachable from this module's own plans today: `StoreModule.computeBestAccessPlan`
+     * claims IN-list filters only for secondary indexes (see its EQ_OPS vs EQ_OR_IN_OPS
+     * split and tickets/backlog/feat-store-pk-in-list-multiseek). The branch exists so
+     * a `_primary_` multi-seek arriving from a future plan gets a correct answer rather
+     * than the scan arm's silent zero rows, and it is what PK-IN enablement will build on.
+     */
+    async *scanMultiSeekPrimary(tuples, seekWidth, filterInfo) {
+        const pkColumns = this.tableSchema.primaryKeyDefinition.map(pk => pk.index);
+        if (pkColumns.length === 0) {
+            this.multiSeekMalformed(filterInfo, 'primary-key multi-seek on a table with no primary key');
+        }
+        if (seekWidth !== pkColumns.length) {
+            this.multiSeekMalformed(filterInfo, `seekWidth ${seekWidth} does not cover the ${pkColumns.length}-column primary key`);
+        }
+        // Mirrors analyzePKAccess's conservative decline of the point arm for such PKs
+        // (see pkHasSemanticOrderingMember); with the residual gone there is no scan to
+        // degrade to, so fail loudly rather than risk an under-fetch.
+        if (this.pkHasSemanticOrderingMember()) {
+            this.multiSeekMalformed(filterInfo, 'semantic-ordering primary-key member');
+        }
+        // Dedup by encoded data key (collapses K-equal tuples), keeping every merged
+        // tuple's residual as an alternative — same rationale as the index branch.
+        const points = new Map();
+        for (const tuple of tuples) {
+            const ordered = this.orderTupleValues(tuple, pkColumns, filterInfo);
+            const key = this.encodeDataKey(ordered);
+            const hex = bytesToHex(key);
+            const info = { ...filterInfo, constraints: tuple.entries };
+            const existing = points.get(hex);
+            if (existing)
+                existing.infos.push(info);
+            else
+                points.set(hex, { key, infos: [info] });
+        }
+        const collations = this.resolveFilterCollations(filterInfo);
+        for (const p of [...points.values()].sort((a, b) => compareBytes(a.key, b.key))) {
+            const row = await this.readEffectiveRowByKey(p.key);
+            if (row && p.infos.some(fi => this.matchesFilters(row, fi, collations))) {
                 yield row;
             }
         }
@@ -1225,7 +1605,16 @@ export class StoreTable extends VirtualTable {
             const rowValue = row[constraint.iColumn];
             const filterValue = filterInfo.args[argvIndex - 1];
             const collation = collations.get(constraint.iColumn) ?? BINARY_COLLATION;
-            if (!this.compareValues(rowValue, constraint.op, filterValue, collation)) {
+            // A semantic-ordering column (TIMESPAN, JSON) must filter under the type's
+            // compare — the same order the engine's operators and Sort use — or a pushed
+            // `d > 'PT90M'` would text-compare and drop rows the predicate admits. The
+            // comparator is built per row only on this rare column kind; if a profile
+            // ever shows it, resolve it once per scan alongside the collations.
+            const logicalType = this.tableSchema.columns[constraint.iColumn]?.logicalType;
+            const compare = hasSemanticOrdering(logicalType)
+                ? createTypedComparator(logicalType, collation)
+                : undefined;
+            if (!this.compareValues(rowValue, constraint.op, filterValue, collation, compare)) {
                 return false;
             }
         }
@@ -1296,11 +1685,11 @@ export class StoreTable extends VirtualTable {
      * NULL on either side fails every operator except EQ-with-both-NULL (the
      * internal point-lookup convention; the planner never pushes `= NULL`).
      */
-    compareValues(a, op, b, collationFunc) {
+    compareValues(a, op, b, collationFunc, semanticCompare) {
         if (a === null || b === null) {
             return op === IndexConstraintOp.EQ ? a === b : false;
         }
-        const cmp = compareSqlValuesFast(a, b, collationFunc);
+        const cmp = semanticCompare ? semanticCompare(a, b) : compareSqlValuesFast(a, b, collationFunc);
         switch (op) {
             case IndexConstraintOp.EQ: return cmp === 0;
             case IndexConstraintOp.NE: return cmp !== 0;
@@ -1324,7 +1713,7 @@ export class StoreTable extends VirtualTable {
                     throw new QuereusError('INSERT requires values', StatusCode.MISUSE);
                 const coerced = args.preCoerced ? values : this.coerceRow(values);
                 const pk = this.extractPK(coerced);
-                const key = buildDataKey(pk, this.encodeOptions, this.pkDirections, this.pkKeyCollations);
+                const key = this.encodeDataKey(pk);
                 // Check for existing row (for conflict handling).
                 // Resolve PK-conflict action: statement OR > per-constraint default > ABORT.
                 const pkEffective = args.onConflict ?? resolvePkDefaultConflict(schema) ?? ConflictResolution.ABORT;
@@ -1442,8 +1831,8 @@ export class StoreTable extends VirtualTable {
                 const coerced = args.preCoerced ? values : this.coerceRow(values);
                 const oldPk = this.extractPK(oldKeyValues);
                 const newPk = this.extractPK(coerced);
-                const oldKey = buildDataKey(oldPk, this.encodeOptions, this.pkDirections, this.pkKeyCollations);
-                const newKey = buildDataKey(newPk, this.encodeOptions, this.pkDirections, this.pkKeyCollations);
+                const oldKey = this.encodeDataKey(oldPk);
+                const newKey = this.encodeDataKey(newPk);
                 // Get old row for index updates. Read the effective
                 // (pending-over-committed) image UNCONDITIONALLY — including the trusted
                 // flush path — so an old image written earlier in the same transaction is
@@ -1558,7 +1947,7 @@ export class StoreTable extends VirtualTable {
                 if (!oldKeyValues)
                     throw new QuereusError('DELETE requires oldKeyValues', StatusCode.MISUSE);
                 const pk = this.extractPK(oldKeyValues);
-                const key = buildDataKey(pk, this.encodeOptions, this.pkDirections, this.pkKeyCollations);
+                const key = this.encodeDataKey(pk);
                 // Get old row for index cleanup. Read the effective
                 // (pending-over-committed) image so a row inserted earlier in the same
                 // transaction is seen: this fixes index cleanup, the `-1` stats delta
@@ -1614,6 +2003,9 @@ export class StoreTable extends VirtualTable {
             const indexStore = await this.ensureIndexStore(index.name);
             const indexCols = index.columns.map(c => c.index);
             const indexDirections = index.columns.map(c => !!c.desc);
+            // Canonicalize semantic-ordering index members ('PT1H'/'PT60M' → one key) so a
+            // UNIQUE enforcement seek and delete-then-insert maintenance address one entry.
+            const indexTransforms = resolveIndexKeyTransforms(index, this.tableSchema.columns);
             // Partial index: only rows the predicate unambiguously accepts are
             // indexed (mirrors buildIndexEntries' build-time filtering). Guarding both
             // halves keeps a row that transitions across the predicate scope on UPDATE
@@ -1624,7 +2016,7 @@ export class StoreTable extends VirtualTable {
             // Remove old index entry (only if the old row was within scope).
             if (oldRow && (!predicate || predicate.evaluate(oldRow) === true)) {
                 const oldIndexValues = indexCols.map(i => oldRow[i]);
-                const oldIndexKey = buildIndexKey(oldIndexValues, oldPk, this.encodeOptions, indexDirections, this.pkDirections, this.pkKeyCollations);
+                const oldIndexKey = buildIndexKey(oldIndexValues, oldPk, this.encodeOptions, indexDirections, this.pkDirections, this.pkKeyCollations, indexTransforms, this.pkKeyTransforms);
                 if (inTransaction && this.coordinator) {
                     this.coordinator.delete(oldIndexKey, indexStore);
                 }
@@ -1635,7 +2027,7 @@ export class StoreTable extends VirtualTable {
             // Add new index entry (only if the new row is within scope).
             if (newRow && (!predicate || predicate.evaluate(newRow) === true)) {
                 const newIndexValues = indexCols.map(i => newRow[i]);
-                const newIndexKey = buildIndexKey(newIndexValues, newPk, this.encodeOptions, indexDirections, this.pkDirections, this.pkKeyCollations);
+                const newIndexKey = buildIndexKey(newIndexValues, newPk, this.encodeOptions, indexDirections, this.pkDirections, this.pkKeyCollations, indexTransforms, this.pkKeyTransforms);
                 // Index value = the row's encoded DATA key. The index-entry key can
                 // locate a row's byte window, but its PK suffix is not losslessly
                 // recoverable to SqlValues (a NOCASE/RTRIM PK column encodes lossily)
@@ -1684,16 +2076,36 @@ export class StoreTable extends VirtualTable {
         }
         return compiled;
     }
-    /** Check if two PK arrays are equal. */
+    /**
+     * Check if two PK arrays name the same row. A semantic-ordering member compares
+     * through its type's `compare` (see {@link resolvePkSemanticEquality}) so
+     * differently-spelled equal values ('PT1H' / 'PT60M') answer "same row",
+     * agreeing with the physical key identity {@link encodeDataKey} produces; every
+     * other member keeps the original strict `!==`.
+     */
     keysEqual(a, b) {
         if (a.length !== b.length)
             return false;
         for (let i = 0; i < a.length; i++) {
-            if (a[i] !== b[i])
+            const semantic = this.pkSemanticEquality[i];
+            if (semantic ? semantic(a[i], b[i]) !== 0 : a[i] !== b[i])
                 return false;
         }
         return true;
     }
+    /**
+     * Per-constrained-column comparison functions for one UNIQUE constraint: the
+     * type's `compare` for a semantic-ordering column (so 'PT1H' conflicts with
+     * 'PT60M', matching the memory backend's typed BTree), else the enforcement
+     * collation the caller resolved (`resolveUniqueEnforcementCollations`) through
+     * `compareSqlValuesFast` — the exact comparison every finder used before.
+     *
+     * Thin wrapper over the engine's `uniqueEnforcementComparators`, which memory
+     * and the isolation overlay share so the three backends cannot drift.
+     */
+    uniqueColumnComparators(uc, collations) {
+        return uniqueEnforcementComparators(this.tableSchema.columns, uc.columns, collations);
+    }
     /**
      * Returns true if any column covered by a UNIQUE constraint differs between
      * oldRow and newRow, or — for partial UNIQUE — any column referenced by the
@@ -1927,7 +2339,10 @@ export class StoreTable extends VirtualTable {
         // unregistered name and cannot be inlined, so a per-candidate call would be
         // pure overhead.
         const collations = resolveUniqueEnforcementCollations(this.tableSchema, uc, this.collationResolver);
-        const bounds = buildIndexPrefixBounds(uc.columns.map(c => newRow[c]), this.encodeOptions, index.columns.map(c => !!c.desc));
+        const compares = this.uniqueColumnComparators(uc, collations);
+        // Same per-column transforms `updateSecondaryIndexes` wrote the entries under, so
+        // the probe for 'PT60M' lands on the window holding the 'PT1H' entry.
+        const bounds = buildIndexPrefixBounds(uc.columns.map(c => newRow[c]), this.encodeOptions, index.columns.map(c => !!c.desc), resolveIndexKeyTransforms(index, this.tableSchema.columns));
         for await (const entry of this.iterateEffective(indexStore, bounds)) {
             // A legacy index store (written before index values carried the data key)
             // holds EMPTY values. `scanIndex` may skip such an entry — a read that
@@ -1944,7 +2359,7 @@ export class StoreTable extends VirtualTable {
             const pk = this.extractPK(candidate);
             if (selfPks.some(skip => this.keysEqual(pk, skip)))
                 continue;
-            if (uc.columns.some((c, i) => compareSqlValuesFast(newRow[c], candidate[c], collations[i]) !== 0))
+            if (uc.columns.some((c, i) => compares[i](newRow[c], candidate[c]) !== 0))
                 continue;
             if (predicate && predicate.evaluate(candidate) !== true)
                 continue;
@@ -1971,6 +2386,7 @@ export class StoreTable extends VirtualTable {
         // COLLATE for an index-derived UNIQUE, else the declared column collation.
         // Resolved once here, not per candidate row.
         const collations = resolveUniqueEnforcementCollations(this.tableSchema, uc, this.collationResolver);
+        const compares = this.uniqueColumnComparators(uc, collations);
         const matches = (candidate) => {
             const pk = this.extractPK(candidate);
             for (const skip of selfPks) {
@@ -1979,7 +2395,7 @@ export class StoreTable extends VirtualTable {
             }
             for (let i = 0; i < constrainedCols.length; i++) {
                 const idx = constrainedCols[i];
-                if (compareSqlValuesFast(newRow[idx], candidate[idx], collations[i]) !== 0)
+                if (compares[i](newRow[idx], candidate[idx]) !== 0)
                     return null;
             }
             // Partial UNIQUE: candidate must also be in the predicate's scope to conflict.
@@ -2024,6 +2440,7 @@ export class StoreTable extends VirtualTable {
         const newSourcePk = this.extractPK(newRow);
         // Resolved once, above the candidate loop.
         const collations = resolveUniqueEnforcementCollations(this.tableSchema, uc, this.collationResolver);
+        const compares = this.uniqueColumnComparators(uc, collations);
         const candidates = await this.db._lookupCoveringConflicts(mv, uc, newRow, newSourcePk);
         for (const cand of candidates) {
             const liveRow = await this.readLiveRowByPk(cand.pk);
@@ -2041,7 +2458,7 @@ export class StoreTable extends VirtualTable {
             // index over a BINARY column) is declined upstream by the collation gate in
             // findRowTimeCoveringStructure, so only BINARY-floor or equal-collation MVs
             // reach here — the superset this re-validation can soundly filter.
-            if (uc.columns.some((c, i) => compareSqlValuesFast(newRow[c], liveRow[c], collations[i]) !== 0))
+            if (uc.columns.some((c, i) => compares[i](newRow[c], liveRow[c]) !== 0))
                 continue;
             if (predicate && predicate.evaluate(liveRow) !== true)
                 continue;
@@ -2065,7 +2482,7 @@ export class StoreTable extends VirtualTable {
     // the table's own read/write paths.
     /** Encode `pkValues` (in PK-definition order) exactly as the data store keys rows. */
     encodeDataKey(pkValues) {
-        return buildDataKey(pkValues, this.encodeOptions, this.pkDirections, this.pkKeyCollations);
+        return buildDataKey(pkValues, this.encodeOptions, this.pkDirections, this.pkKeyCollations, this.pkKeyTransforms);
     }
     /**
      * Byte bounds covering every data key whose leading PK columns equal
@@ -2074,7 +2491,7 @@ export class StoreTable extends VirtualTable {
      * exact slice. An empty prefix yields full-scan bounds.
      */
     encodePkPrefixBounds(prefixValues) {
-        return buildPkPrefixBounds(prefixValues, this.encodeOptions, this.pkDirections.slice(0, prefixValues.length), this.pkKeyCollations.slice(0, prefixValues.length));
+        return buildPkPrefixBounds(prefixValues, this.encodeOptions, this.pkDirections.slice(0, prefixValues.length), this.pkKeyCollations.slice(0, prefixValues.length), this.pkKeyTransforms.slice(0, prefixValues.length));
     }
     /**
      * Effective (pending-over-committed) point read by encoded data key: a pending
@@ -2284,7 +2701,7 @@ export class StoreTable extends VirtualTable {
      */
     async deleteRowAt(inTransaction, pk, oldRow) {
         const store = await this.ensureStore();
-        const key = buildDataKey(pk, this.encodeOptions, this.pkDirections, this.pkKeyCollations);
+        const key = this.encodeDataKey(pk);
         if (inTransaction && this.coordinator) {
             this.coordinator.delete(key, store);
         }