@quereus/store 4.5.0 → 4.7.0

package/dist/src/common/store-table-scan.d.ts

@@ -0,0 +1,452 @@
+/**
+ * The read path of the KVStore-backed virtual table: turning a pushed predicate
+ * into a byte window over the data store or a secondary index, iterating that
+ * window, and re-checking every pushed constraint under the column's real
+ * collation.
+ *
+ * Second layer of the store-table chain:
+ *   StoreTableBase -> StoreTableScan -> StoreTableConstraints -> StoreTable
+ */
+import { IndexConstraintOp, type IdxStrSpec, type CollationFunction, type CompareFn, type LogicalType, type TableIndexSchema, type Row, type FilterInfo, type SqlValue } from '@quereus/quereus';
+import type { IterateOptions, KVStore } from './kv-store.js';
+import type { KeyValueTransform } from './encoding.js';
+import { StoreTableBase } from './store-table-base.js';
+/**
+ * Read-path layer of the generic KVStore-backed virtual table.
+ *
+ * Every arm below reads the EFFECTIVE row state (see
+ * {@link StoreTableBase.iterateEffective}), so a byte window narrowed here still
+ * honors read-your-own-writes.
+ */
+export declare abstract class StoreTableScan extends StoreTableBase {
+    /**
+     * Query the table with optional filters.
+     *
+     * All three access arms read the EFFECTIVE row state: the committed store
+     * merged with this table's coordinator's pending ops when a transaction is
+     * active (read-your-own-writes — see {@link iterateEffective} /
+     * {@link readLiveRowByPk}). Merged emission stays in encoded-PK-key order,
+     * preserving the module's `providesOrdering` / `monotonicOn` advertisements.
+     */
+    query(filterInfo: FilterInfo): AsyncIterable<Row>;
+    /**
+     * True when a byte window over the LEADING PK column reproduces the comparator's order
+     * — the precondition {@link buildPKRangeBounds} needs, and the exact condition
+     * `computeBestAccessPlan` (store-module-access-plan.ts) uses before claiming the range filters handled.
+     * When false, the range arm degrades to a full scan + `matchesFilters` residual.
+     */
+    protected leadingPkRangeIsOrderSafe(): boolean;
+    /**
+     * True when some PK member's logical type carries semantic ordering (TIMESPAN,
+     * JSON) — the gate {@link scanMultiSeekPrimary} declines on.
+     *
+     * A primary-key multi-seek merges N byte windows with the residual Filter already
+     * dropped, and has no degradation available: a window that under-fetches loses rows
+     * outright, and falling back to the scan arm would AND N mutually-exclusive
+     * equalities to zero rows. So it fails loudly instead. Re-opening it is backlog
+     * `feat-store-semantic-key-multiseek`.
+     *
+     * NOT a gate on the single-value point arm any more: both types' key transforms (see
+     * {@link storeSemanticKeyTransform}) make byte equality exactly the type's equality
+     * ('PT1H' and 'PT60M' land on one key), so {@link analyzePKAccess} admits a point
+     * window per PROBE ({@link semanticProbeIsKeyFaithful}) rather than declining per
+     * schema. A single point window CAN degrade to the scan arm; N merged ones cannot.
+     */
+    protected pkHasSemanticOrderingMember(): boolean;
+    /** Analyze filter info to determine PK access pattern. */
+    protected analyzePKAccess(filterInfo: FilterInfo): PKAccessPattern;
+    /**
+     * Convert a leading-PK-column range access into one seek + early-terminate
+     * iterate window.
+     *
+     * Each LT/LE/GT/GE constraint's bound value is encoded under the SAME
+     * per-column DESC direction and key collation as the data keys (via
+     * {@link encodePkPrefixBounds}), giving the byte region `[lo, hi)` whose
+     * leading column equals that value (`lo = encode([x])`,
+     * `hi = incrementLastByte(lo)`). The op maps that region's endpoints onto a
+     * `gte`/`lt` window; because a DESC column bit-inverts its bytes (larger value
+     * ⇒ smaller bytes), the lower/upper assignment swaps with direction:
+     *
+     *   | op | ASC      | DESC     |
+     *   |----|----------|----------|
+     *   | GE | gte = lo | lt  = hi |
+     *   | GT | gte = hi | lt  = lo |
+     *   | LE | lt  = hi | gte = lo |
+     *   | LT | lt  = lo | gte = hi |
+     *
+     * Across constraints (BETWEEN ⇒ one lower + one upper; a redundant same-side
+     * pair ⇒ the tighter wins) we keep the MAX lower candidate for `gte` and the
+     * MIN upper candidate for `lt`. A candidate that resolves to `undefined` (an
+     * `hi` whose increment overflowed all-0xff) leaves that side unbounded — a safe
+     * SUPERSET, since {@link matchesFilters} stays the authoritative collation-aware
+     * row filter. A NULL/missing bound value is likewise skipped (the planner never
+     * pushes `= NULL`, and a range op against NULL rejects every row in matchesFilters).
+     * A bound over a semantic-ordering leading column whose VALUE has no faithful byte
+     * position ({@link semanticProbeIsKeyFaithful} — a numeric or unparseable TIMESPAN
+     * probe, a blob/bigint JSON probe) is skipped the same way: dropping a RANGE bound
+     * only WIDENS the window (worst case to the pre-existing full scan), and the plan
+     * claimed the range handled from the schema alone, so the predicate the engine's
+     * dropped Filter carried is reproduced by {@link matchesFilters} under the type's
+     * own compare. The EQUALITY arms cannot widen this way and degrade differently —
+     * see {@link semanticProbeIsKeyFaithful}'s per-arm table.
+     *
+     * NOTE: a range window over a text PK column is sound only when the column's key
+     * normalizer is ORDER-preserving with respect to its comparator — i.e. the comparator
+     * orders two strings the way memcmp orders their normalized bytes. That is NOT implied
+     * by `db.registerCollation`'s normalizer contract, which promises only an equality
+     * partition, and a built-in NAME may be re-registered with a comparator + normalizer
+     * pair that preserves equality while inverting order. This method is therefore only
+     * ever reached under {@link leadingPkRangeIsOrderSafe} — enforced by
+     * {@link analyzePKAccess} here and mirrored by `computeBestAccessPlan` (store-module-access-plan.ts)
+     * before it claims the range filters handled. A collation without the
+     * `orderPreserving` assertion costs the seek, never a row.
+     */
+    protected buildPKRangeBounds(access: PKAccessPattern): IterateOptions;
+    /**
+     * Scan a leading-PK-column range, seeking to the window start and
+     * early-terminating at its end.
+     *
+     * {@link buildPKRangeBounds} converts the LT/LE/GT/GE constraints into one
+     * encoded-byte `gte`/`lt` window under the same per-column DESC directions and
+     * key collations the data keys use, so the iterate visits a SUPERSET of the
+     * qualifying rows (a collation widening or the bound-byte increment can
+     * over-fetch, never under-fetch). {@link matchesFilters} stays the authoritative
+     * collation-aware row filter. {@link iterateEffective} restricts the pending
+     * merge to the same `bounds`, so read-your-own-writes holds on the narrowed window.
+     */
+    protected scanPKRange(store: KVStore, access: PKAccessPattern, filterInfo: FilterInfo): AsyncIterable<Row>;
+    /**
+     * Resolve the secondary index chosen by the planner from `filterInfo.idxStr`.
+     *
+     * The planner emits `idx=<name>(<n>);plan=…` when its access plan set both an
+     * `indexName` and `seekColumnIndexes` (see `getBestAccessPlan` and
+     * rule-select-access-path.ts). Decoding goes through the engine's shared
+     * `decodeIdxStr`, so the store, the in-memory vtab, and the isolation overlay all
+     * read one format. Returns null for the PK/scan sentinels (`_primary_`, `fullscan`,
+     * `empty`), an idxStr that names no index, or a name absent from `schema.indexes` —
+     * every one of which routes back to a PK/full-scan arm.
+     */
+    protected resolveIndexFromIdxStr(idxStr: string | null): TableIndexSchema | null;
+    /**
+     * Analyze filter info to determine a secondary-index access pattern, mirroring
+     * {@link analyzePKAccess} but over the index chosen in `idxStr`.
+     *
+     * A contiguous leading-prefix EQ on the index columns yields a `point` window
+     * (the prefix covers every entry sharing those leading values — an index seek
+     * is a PREFIX scan, not a single row, since the index need not be unique and
+     * the PK suffix varies); otherwise a range (LT/LE/GT/GE) on the LEADING index
+     * column yields a `range` window. Returns null when neither applies or when the
+     * index is unresolved. {@link matchesFilters} stays the authoritative row filter,
+     * so the window need only be a SUPERSET.
+     *
+     * Index-column bytes are encoded under each column's own key collation
+     * ({@link indexKeyCollations}); {@link matchesFilters} re-checks a fetched row under the
+     * index column's `COLLATE` else the table column's declared collation. The EQ/prefix
+     * window is EXACTLY the qualifying set when those two agree, which
+     * {@link indexPrefixSeekIsCollationExact} decides; the RANGE window additionally equates
+     * memcmp of the key bytes with the residual's comparison ORDER, which
+     * {@link indexRangeIsOrderSafe} decides. `tryIndexAccessPlan`
+     * (store-module-access-plan.ts) consults the SAME two predicates before claiming the
+     * filters handled, so the two decisions cannot disagree. Either failing returns null and
+     * the caller full-scans, where the residual is authoritative.
+     */
+    protected analyzeIndexAccess(filterInfo: FilterInfo): IndexAccessPattern | null;
+    /**
+     * Lazy cache behind {@link indexKeyCollations}: one resolved array per index-schema
+     * object, invalidated when the column array it was resolved against is replaced (an
+     * ALTER can retype a column without minting new index objects, so the index identity
+     * alone is not a safe key).
+     */
+    private readonly indexKeyCollationsCache;
+    /**
+     * Per-column KEY collation for `index`'s own columns, memoized — see
+     * {@link resolveIndexKeyCollations}. The one resolution every scan-side encode site
+     * ({@link analyzeIndexAccess}, {@link buildIndexRangeBounds}, {@link scanMultiSeek})
+     * threads into `buildIndexPrefixBounds`, so a scan window can never address
+     * different bytes than the maintenance writes.
+     */
+    protected indexKeyCollations(index: TableIndexSchema): (string | undefined)[];
+    /**
+     * Lazy cache behind {@link indexKeyTransforms} — the transform twin of
+     * {@link indexKeyCollationsCache}, with the same columns-identity invalidation rule
+     * (an ALTER can retype a column without minting new index objects).
+     */
+    private readonly indexKeyTransformsCache;
+    /**
+     * Per-column key VALUE TRANSFORM for `index`'s own columns, memoized — see
+     * {@link resolveIndexKeyTransforms}. Threaded, like {@link indexKeyCollations},
+     * into every scan-side `buildIndexPrefixBounds` call ({@link analyzeIndexAccess},
+     * {@link buildIndexRangeBounds}, {@link scanMultiSeek}) so a scan window addresses
+     * the same TRANSFORMED bytes `buildIndexKey` wrote for a semantic-ordering column.
+     * The point/multi-seek callers only ever see `undefined` entries today (their arms
+     * still decline semantic-ordering prefixes), but threading all three uniformly is
+     * the point — an arm re-opened later cannot silently address raw-value bytes.
+     */
+    protected indexKeyTransforms(index: TableIndexSchema): (KeyValueTransform | undefined)[];
+    /**
+     * Per-column comparators stating the store's actual index-key BYTE order for
+     * `indexName` — the `VirtualTable.getIndexComparator` isolation hook, mirroring
+     * `MemoryTable.getIndexComparator`. The isolation layer merges the overlay's pending
+     * rows against this table's index scan by `(indexKey, PK)` sort key and prefers these
+     * over its descriptor-derived fallback, so each column's comparator must reproduce
+     * the order {@link scanIndex} emits in:
+     *   - the column's KEY collation ({@link indexKeyCollations}: index COLLATE, else the
+     *     table column's declared collation, else BINARY) for text;
+     *   - the logical type's `compare` for a semantic-ordering column (its key bytes
+     *     encode through an order-preserving transform — see `storeSemanticKeyTransform`);
+     *   - negated for a DESC column (its key bytes are bit-inverted).
+     * Resolved against the MATERIALIZED schema so a hidden `_uc_*` name resolves too.
+     *
+     * NOTE: for a text column this states the COMPARATOR's order, which is the byte order
+     * only while the collation's key normalizer preserves order (`_isCollationOrderPreserving`
+     * — asserted by the built-ins, opt-in for a custom one; see keyOrderMatchesCollation).
+     * Under an equality-only custom collation the emitted byte order and this comparator can
+     * disagree, misplacing an overlay row within an index-key-equal group. Same exposure the
+     * isolation layer's descriptor fallback carried before this method existed, so nothing
+     * regressed; if a custom equality-only collation on an INDEX column ever ships, gate this
+     * on the assertion (returning undefined declines to the fallback, which is no better —
+     * the real fix is to make the store emit in comparator order or the merge tolerate it).
+     */
+    getIndexComparator(indexName: string): CompareFn[] | undefined;
+    /**
+     * True when a byte window over the LEADING column of `index` reproduces the order the
+     * residual comparison uses. Delegates to {@link indexLeadingRangeIsOrderSafe} — the SAME
+     * call the range arm of `tryIndexAccessPlan` (store-module-access-plan.ts) makes before
+     * it marks the range filters handled, so the "build a window" and "mark handled"
+     * decisions cannot disagree. The memoized {@link indexKeyCollations} is passed as the
+     * key side, so the predicate judges the bytes this scan actually addresses.
+     */
+    protected indexRangeIsOrderSafe(index: TableIndexSchema): boolean;
+    /**
+     * Convert leading-index-column LT/LE/GT/GE constraints into one encoded-byte
+     * `gte`/`lt` window — the secondary-index analogue of {@link buildPKRangeBounds}.
+     *
+     * Each bound value is encoded under the leading index column's own key `collation`
+     * ({@link indexKeyCollations}) and DESC `dir` — exactly as {@link buildIndexKey}
+     * encodes that column — via {@link buildIndexPrefixBounds}, giving the byte region
+     * `[lo, hi)` whose leading column equals that value. The op maps that region's
+     * endpoints onto `gte`/`lt`, with the same DESC lower/upper SWAP as the PK path:
+     *
+     *   | op | ASC      | DESC     |
+     *   |----|----------|----------|
+     *   | GE | gte = lo | lt  = hi |
+     *   | GT | gte = hi | lt  = lo |
+     *   | LE | lt  = hi | gte = lo |
+     *   | LT | lt  = lo | gte = hi |
+     *
+     * Across constraints keep the MAX lower and MIN upper. An `undefined` upper (an
+     * `hi` whose increment overflowed all-0xff) leaves that side unbounded — a safe
+     * SUPERSET. A NULL/missing bound value is skipped (the planner never pushes
+     * `= NULL`, and a range op against NULL rejects every row in matchesFilters).
+     * A bound over a semantic-ordering leading column (`logicalType`) whose VALUE has
+     * no faithful byte position ({@link semanticProbeIsKeyFaithful}) is skipped the
+     * same way — a dropped RANGE bound only widens the window, and matchesFilters
+     * reproduces the predicate under the type's compare; see the widen-vs-decline
+     * note on {@link buildPKRangeBounds}. `transform` is the leading column's key
+     * value transform ({@link indexKeyTransforms}), so a surviving bound addresses
+     * the same transformed bytes the index store holds.
+     */
+    protected buildIndexRangeBounds(constraints: Array<{
+        op: IndexConstraintOp;
+        value?: SqlValue;
+    }>, dir: boolean, collation: string | undefined, logicalType: LogicalType | undefined, transform: KeyValueTransform | undefined): IterateOptions;
+    /**
+     * Scan a secondary index over `access.bounds`, resolving each index entry to its
+     * base row and re-filtering.
+     *
+     * {@link iterateEffective} yields the committed index entries merged with this
+     * transaction's pending index puts/deletes (read-your-own-writes over the
+     * index), in index-key byte order — the order the isolation overlay merge relies
+     * on (`isolated-table.ts` § buildSortKey). We resolve each entry to its row via
+     * its stored data-key value WITHOUT reordering, so index-key order is preserved.
+     *
+     * Defense in depth mirroring the memory layer's live-recheck: a resolved-null
+     * row (the entry's row was deleted — a pending index delete would normally
+     * suppress the entry, but a committed entry can lag) is skipped, and every
+     * resolved row is re-checked by {@link matchesFilters} (the byte window is only
+     * a superset, and a stale entry whose indexed column no longer matches is
+     * dropped).
+     */
+    protected scanIndex(indexStore: KVStore, access: IndexAccessPattern, filterInfo: FilterInfo, multi?: MultiSeekWindowContext): AsyncIterable<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.
+     */
+    private multiSeekMalformed;
+    /**
+     * 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.
+     */
+    private decodeMultiSeekTuples;
+    /**
+     * 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.
+     */
+    private orderTupleValues;
+    /**
+     * 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 encoded prefix byte-matches (duplicate bound parameters, or
+     *     case variants under a NOCASE key collation C) share ONE window, each kept
+     *     as a residual alternative — see {@link MultiSeekWindowContext}.
+     *   - 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.
+     */
+    protected scanMultiSeek(spec: IdxStrSpec, filterInfo: FilterInfo): AsyncIterable<Row>;
+    /**
+     * 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: `computeBestAccessPlan` (store-module-access-plan.ts)
+     * 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.
+     */
+    protected scanMultiSeekPrimary(tuples: MultiSeekTuple[], seekWidth: number, filterInfo: FilterInfo): AsyncIterable<Row>;
+    /**
+     * Check if a row matches the filter constraints.
+     *
+     * `collations` maps a constrained column index to the comparison function that
+     * column must be re-checked under; every caller builds it once per scan with
+     * {@link resolveFilterCollations}, whose doc comment explains how the name is
+     * chosen. A column absent from the map compares BINARY — the same result
+     * {@link resolveFilterCollations} produces for an undeclared collation, and the
+     * only reachable absence, since both walk the constraint list under identical
+     * skip conditions.
+     */
+    protected matchesFilters(row: Row, filterInfo: FilterInfo, collations: ReadonlyMap<number, CollationFunction>): boolean;
+    /**
+     * Resolve, ONCE per scan, the comparison collation function for every pushed
+     * constraint column, keyed by column index.
+     *
+     * The name for a column is its DECLARED collation (absent ⇒ BINARY) — the same
+     * resolution the access path's collation-cover analysis uses
+     * (indexColumnCollationLookup / primaryKeyCollationLookup) when it decides a
+     * pushed constraint is fully covered, and the same source `StoreTableConstraints`'
+     * UNIQUE checks compare under. On a collation MATCH the planner drops the residual
+     * Filter, so {@link matchesFilters} alone must reproduce the predicate.
+     *
+     * `indexCollationNames` (from {@link indexColumnCollations}) overrides the
+     * declared name for the secondary-index scan arm: the planner's MATCH there is
+     * against the INDEX column's collation, which an explicit `COLLATE` on the index
+     * can make differ from the table column's.
+     *
+     * Names resolve against {@link collationResolver}, so an unregistered collation
+     * raises `no such collation sequence` at scan setup rather than byte-ordering
+     * every row.
+     *
+     * NOTE: rebuilt on every `query()` / `scanPKRange()` / `scanIndex()` call — one
+     * registry lookup per distinct constrained column, dwarfed by the scan's I/O. If a
+     * point-lookup-heavy profile ever shows it, memoize on the `FilterInfo`.
+     */
+    protected resolveFilterCollations(filterInfo: FilterInfo, indexCollationNames?: ReadonlyMap<number, string | undefined>): ReadonlyMap<number, CollationFunction>;
+    /**
+     * Effective per-column comparison collation for a secondary index's columns:
+     * the index column's own `COLLATE` when present, else the underlying table
+     * column's declared collation. Mirrors the resolution `StoreModule`'s
+     * index-maintenance UNIQUE dedup uses (`indexCol.collation ?? tableColumn`), so
+     * a re-checked index-scan row compares under the same collation the planner used
+     * to justify dropping (or keeping) the residual Filter.
+     */
+    protected indexColumnCollations(index: TableIndexSchema): Map<number, string | undefined>;
+    /**
+     * Compare two values according to an operator, under `collationFunc` (already
+     * resolved by {@link resolveFilterCollations} against this database's collation
+     * registry). So the LT/LE/GT/GE range bounds honour a NOCASE/RTRIM/custom column
+     * collation rather than a raw BINARY JS comparison — the capability
+     * `StoreModule.getBestAccessPlan` advertises via `honorsCollatedRangeBounds`.
+     * NULL on either side fails every operator except EQ-with-both-NULL (the
+     * internal point-lookup convention; the planner never pushes `= NULL`).
+     */
+    protected compareValues(a: SqlValue, op: IndexConstraintOp, b: SqlValue, collationFunc: CollationFunction, semanticCompare?: (a: SqlValue, b: SqlValue) => number): boolean;
+}
+/** PK access pattern analysis result. */
+interface PKAccessPattern {
+    type: 'point' | 'range' | 'scan';
+    values?: SqlValue[];
+    columnIndex?: number;
+    constraints?: Array<{
+        columnIndex: number;
+        op: IndexConstraintOp;
+        value?: SqlValue;
+    }>;
+}
+/**
+ * Secondary-index access pattern analysis result: the chosen index plus the
+ * encoded byte window {@link StoreTableScan.scanIndex} iterates. `point` is a
+ * leading-prefix EQ window, `range` a leading-column LT/LE/GT/GE window; both
+ * resolve to a `bounds` scan (an index seek is always a prefix scan, never a
+ * single entry).
+ */
+interface IndexAccessPattern {
+    index: TableIndexSchema;
+    type: 'point' | 'range';
+    bounds: IterateOptions;
+}
+/** One pushed-constraint entry, as {@link FilterInfo.constraints} carries it. */
+type ConstraintEntry = FilterInfo['constraints'][number];
+/**
+ * One multi-seek tuple: its W constraint entries and their bound values, in
+ * constraint order (see {@link StoreTableScan.decodeMultiSeekTuples}).
+ */
+interface MultiSeekTuple {
+    entries: ConstraintEntry[];
+    values: SqlValue[];
+}
+/**
+ * Per-window context a multi-seek passes to {@link StoreTableScan.scanIndex} (absent for
+ * ordinary single-window scans).
+ *
+ * `seen` — data-key hexes already YIELDED by an earlier window. Checked before the
+ * data-store read (a cross-window duplicate costs no extra `get`), added only on a
+ * yield: adding at visit time would let a stale index entry (row re-keyed since
+ * indexing) that FAILS its residual poison the set and suppress the row's live entry
+ * in a later window.
+ * NOTE: holds one hex string per row the multi-seek yields, for the whole seek — the
+ * only unbounded allocation on this path. Windows are byte-disjoint, so the only real
+ * duplicate source is a stale index entry; if a large-result `IN` ever shows up as a
+ * memory problem, the set can be scoped per window (or dropped for a consistent store).
+ *
+ * `collations` — the constraint collation map, resolved once per multi-seek (it is
+ * identical for every window).
+ *
+ * `extraTuples` — additional seek tuples whose encoded window byte-equals this
+ * window's (duplicate bound parameters, or case-variant values under a NOCASE key
+ * collation). A row is yielded when it matches the primary FilterInfo OR any of
+ * these. Index bytes now encode under the same collation C the residual compares
+ * under (`indexKeyCollations`), so byte-equal tuples are C-equal and each merged
+ * tuple's residual admits the same rows — the OR is redundancy, kept because it is
+ * what makes the fold safe by construction rather than by that argument, and it is
+ * what a custom equality-only normalizer (byte-equal ⇏ comparator-equal order but
+ * equal partition) still relies on.
+ */
+interface MultiSeekWindowContext {
+    seen: Set<string>;
+    collations: ReadonlyMap<number, CollationFunction>;
+    extraTuples: readonly FilterInfo[];
+}
+export {};
+//# sourceMappingURL=store-table-scan.d.ts.map

package/dist/src/common/store-table-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-table-scan.d.ts","sourceRoot":"","sources":["../../../src/common/store-table-scan.ts"],"names":[],"mappings":"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"}