@quereus/store 4.5.0 → 4.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (104) hide show
  1. package/README.md +30 -4
  2. package/dist/src/common/encoding.d.ts +4 -3
  3. package/dist/src/common/encoding.d.ts.map +1 -1
  4. package/dist/src/common/encoding.js +17 -13
  5. package/dist/src/common/encoding.js.map +1 -1
  6. package/dist/src/common/events.d.ts +5 -1
  7. package/dist/src/common/events.d.ts.map +1 -1
  8. package/dist/src/common/events.js.map +1 -1
  9. package/dist/src/common/implicit-unique-index.d.ts +80 -0
  10. package/dist/src/common/implicit-unique-index.d.ts.map +1 -0
  11. package/dist/src/common/implicit-unique-index.js +148 -0
  12. package/dist/src/common/implicit-unique-index.js.map +1 -0
  13. package/dist/src/common/index.d.ts +7 -3
  14. package/dist/src/common/index.d.ts.map +1 -1
  15. package/dist/src/common/index.js +5 -2
  16. package/dist/src/common/index.js.map +1 -1
  17. package/dist/src/common/json-key.d.ts +2 -2
  18. package/dist/src/common/json-key.js +2 -2
  19. package/dist/src/common/key-builder.d.ts +33 -14
  20. package/dist/src/common/key-builder.d.ts.map +1 -1
  21. package/dist/src/common/key-builder.js +24 -17
  22. package/dist/src/common/key-builder.js.map +1 -1
  23. package/dist/src/common/kv-store.d.ts +10 -0
  24. package/dist/src/common/kv-store.d.ts.map +1 -1
  25. package/dist/src/common/pk-key-resolution.d.ts +275 -0
  26. package/dist/src/common/pk-key-resolution.d.ts.map +1 -0
  27. package/dist/src/common/pk-key-resolution.js +389 -0
  28. package/dist/src/common/pk-key-resolution.js.map +1 -0
  29. package/dist/src/common/store-module-access-plan.d.ts +32 -0
  30. package/dist/src/common/store-module-access-plan.d.ts.map +1 -0
  31. package/dist/src/common/store-module-access-plan.js +424 -0
  32. package/dist/src/common/store-module-access-plan.js.map +1 -0
  33. package/dist/src/common/store-module-alter-column.d.ts +23 -0
  34. package/dist/src/common/store-module-alter-column.d.ts.map +1 -0
  35. package/dist/src/common/store-module-alter-column.js +393 -0
  36. package/dist/src/common/store-module-alter-column.js.map +1 -0
  37. package/dist/src/common/store-module-alter.d.ts +55 -0
  38. package/dist/src/common/store-module-alter.d.ts.map +1 -0
  39. package/dist/src/common/store-module-alter.js +519 -0
  40. package/dist/src/common/store-module-alter.js.map +1 -0
  41. package/dist/src/common/store-module-base.d.ts +268 -0
  42. package/dist/src/common/store-module-base.d.ts.map +1 -0
  43. package/dist/src/common/store-module-base.js +362 -0
  44. package/dist/src/common/store-module-base.js.map +1 -0
  45. package/dist/src/common/store-module-catalog.d.ts +269 -0
  46. package/dist/src/common/store-module-catalog.d.ts.map +1 -0
  47. package/dist/src/common/store-module-catalog.js +462 -0
  48. package/dist/src/common/store-module-catalog.js.map +1 -0
  49. package/dist/src/common/store-module-index-build.d.ts +88 -0
  50. package/dist/src/common/store-module-index-build.d.ts.map +1 -0
  51. package/dist/src/common/store-module-index-build.js +280 -0
  52. package/dist/src/common/store-module-index-build.js.map +1 -0
  53. package/dist/src/common/store-module-index.d.ts +116 -0
  54. package/dist/src/common/store-module-index.d.ts.map +1 -0
  55. package/dist/src/common/store-module-index.js +373 -0
  56. package/dist/src/common/store-module-index.js.map +1 -0
  57. package/dist/src/common/store-module-rename.d.ts +49 -0
  58. package/dist/src/common/store-module-rename.d.ts.map +1 -0
  59. package/dist/src/common/store-module-rename.js +244 -0
  60. package/dist/src/common/store-module-rename.js.map +1 -0
  61. package/dist/src/common/store-module-schema-rewrite.d.ts +57 -0
  62. package/dist/src/common/store-module-schema-rewrite.d.ts.map +1 -0
  63. package/dist/src/common/store-module-schema-rewrite.js +140 -0
  64. package/dist/src/common/store-module-schema-rewrite.js.map +1 -0
  65. package/dist/src/common/store-module-schema-sync.d.ts +232 -0
  66. package/dist/src/common/store-module-schema-sync.d.ts.map +1 -0
  67. package/dist/src/common/store-module-schema-sync.js +529 -0
  68. package/dist/src/common/store-module-schema-sync.js.map +1 -0
  69. package/dist/src/common/store-module.d.ts +43 -909
  70. package/dist/src/common/store-module.d.ts.map +1 -1
  71. package/dist/src/common/store-module.js +184 -3276
  72. package/dist/src/common/store-module.js.map +1 -1
  73. package/dist/src/common/store-table-base.d.ts +523 -0
  74. package/dist/src/common/store-table-base.d.ts.map +1 -0
  75. package/dist/src/common/store-table-base.js +878 -0
  76. package/dist/src/common/store-table-base.js.map +1 -0
  77. package/dist/src/common/store-table-constraints.d.ts +237 -0
  78. package/dist/src/common/store-table-constraints.d.ts.map +1 -0
  79. package/dist/src/common/store-table-constraints.js +624 -0
  80. package/dist/src/common/store-table-constraints.js.map +1 -0
  81. package/dist/src/common/store-table-scan.d.ts +415 -0
  82. package/dist/src/common/store-table-scan.d.ts.map +1 -0
  83. package/dist/src/common/store-table-scan.js +821 -0
  84. package/dist/src/common/store-table-scan.js.map +1 -0
  85. package/dist/src/common/store-table.d.ts +71 -1144
  86. package/dist/src/common/store-table.d.ts.map +1 -1
  87. package/dist/src/common/store-table.js +166 -2383
  88. package/dist/src/common/store-table.js.map +1 -1
  89. package/dist/src/testing/index.d.ts +12 -0
  90. package/dist/src/testing/index.d.ts.map +1 -0
  91. package/dist/src/testing/index.js +12 -0
  92. package/dist/src/testing/index.js.map +1 -0
  93. package/dist/src/testing/kv-assert.d.ts +19 -0
  94. package/dist/src/testing/kv-assert.d.ts.map +1 -0
  95. package/dist/src/testing/kv-assert.js +25 -0
  96. package/dist/src/testing/kv-assert.js.map +1 -0
  97. package/dist/src/testing/kv-conformance.d.ts.map +1 -1
  98. package/dist/src/testing/kv-conformance.js +1 -15
  99. package/dist/src/testing/kv-conformance.js.map +1 -1
  100. package/dist/src/testing/kv-provider-conformance.d.ts +54 -0
  101. package/dist/src/testing/kv-provider-conformance.d.ts.map +1 -0
  102. package/dist/src/testing/kv-provider-conformance.js +183 -0
  103. package/dist/src/testing/kv-provider-conformance.js.map +1 -0
  104. package/package.json +8 -8
@@ -0,0 +1,415 @@
1
+ /**
2
+ * The read path of the KVStore-backed virtual table: turning a pushed predicate
3
+ * into a byte window over the data store or a secondary index, iterating that
4
+ * window, and re-checking every pushed constraint under the column's real
5
+ * collation.
6
+ *
7
+ * Second layer of the store-table chain:
8
+ * StoreTableBase -> StoreTableScan -> StoreTableConstraints -> StoreTable
9
+ */
10
+ import { IndexConstraintOp, type IdxStrSpec, type CollationFunction, type CompareFn, type TableIndexSchema, type Row, type FilterInfo, type SqlValue } from '@quereus/quereus';
11
+ import type { IterateOptions, KVStore } from './kv-store.js';
12
+ import { StoreTableBase } from './store-table-base.js';
13
+ /**
14
+ * Read-path layer of the generic KVStore-backed virtual table.
15
+ *
16
+ * Every arm below reads the EFFECTIVE row state (see
17
+ * {@link StoreTableBase.iterateEffective}), so a byte window narrowed here still
18
+ * honors read-your-own-writes.
19
+ */
20
+ export declare abstract class StoreTableScan extends StoreTableBase {
21
+ /**
22
+ * Query the table with optional filters.
23
+ *
24
+ * All three access arms read the EFFECTIVE row state: the committed store
25
+ * merged with this table's coordinator's pending ops when a transaction is
26
+ * active (read-your-own-writes — see {@link iterateEffective} /
27
+ * {@link readLiveRowByPk}). Merged emission stays in encoded-PK-key order,
28
+ * preserving the module's `providesOrdering` / `monotonicOn` advertisements.
29
+ */
30
+ query(filterInfo: FilterInfo): AsyncIterable<Row>;
31
+ /**
32
+ * True when a byte window over the LEADING PK column reproduces the comparator's order
33
+ * — the precondition {@link buildPKRangeBounds} needs, and the exact condition
34
+ * `computeBestAccessPlan` (store-module-access-plan.ts) uses before claiming the range filters handled.
35
+ * When false, the range arm degrades to a full scan + `matchesFilters` residual.
36
+ */
37
+ protected leadingPkRangeIsOrderSafe(): boolean;
38
+ /**
39
+ * True when some PK member's logical type carries semantic ordering (TIMESPAN,
40
+ * JSON). Such PKs decline the point arm and full-scan, where
41
+ * {@link matchesFilters} applies the type's compare. Historically required —
42
+ * byte-key equality was a strict subset of the type's equality ('PT1H' ≡
43
+ * 'PT60M' elapsed-time-equal, byte-distinct) and a point window under-fetched
44
+ * with no residual able to resurrect a skipped row. Both types' key transforms
45
+ * (see {@link storeSemanticKeyTransform}) now make byte equality the type's
46
+ * equality, so the decline is conservative; re-opening is tracked in backlog
47
+ * `feat-reopen-timespan-store-seeks`. (Range windows and ordering
48
+ * advertisements are already declined by {@link keyOrderMatchesCollation}.)
49
+ */
50
+ protected pkHasSemanticOrderingMember(): boolean;
51
+ /** Analyze filter info to determine PK access pattern. */
52
+ protected analyzePKAccess(filterInfo: FilterInfo): PKAccessPattern;
53
+ /**
54
+ * Convert a leading-PK-column range access into one seek + early-terminate
55
+ * iterate window.
56
+ *
57
+ * Each LT/LE/GT/GE constraint's bound value is encoded under the SAME
58
+ * per-column DESC direction and key collation as the data keys (via
59
+ * {@link encodePkPrefixBounds}), giving the byte region `[lo, hi)` whose
60
+ * leading column equals that value (`lo = encode([x])`,
61
+ * `hi = incrementLastByte(lo)`). The op maps that region's endpoints onto a
62
+ * `gte`/`lt` window; because a DESC column bit-inverts its bytes (larger value
63
+ * ⇒ smaller bytes), the lower/upper assignment swaps with direction:
64
+ *
65
+ * | op | ASC | DESC |
66
+ * |----|----------|----------|
67
+ * | GE | gte = lo | lt = hi |
68
+ * | GT | gte = hi | lt = lo |
69
+ * | LE | lt = hi | gte = lo |
70
+ * | LT | lt = lo | gte = hi |
71
+ *
72
+ * Across constraints (BETWEEN ⇒ one lower + one upper; a redundant same-side
73
+ * pair ⇒ the tighter wins) we keep the MAX lower candidate for `gte` and the
74
+ * MIN upper candidate for `lt`. A candidate that resolves to `undefined` (an
75
+ * `hi` whose increment overflowed all-0xff) leaves that side unbounded — a safe
76
+ * SUPERSET, since {@link matchesFilters} stays the authoritative collation-aware
77
+ * row filter. A NULL/missing bound value is likewise skipped (the planner never
78
+ * pushes `= NULL`, and a range op against NULL rejects every row in matchesFilters).
79
+ *
80
+ * NOTE: a range window over a text PK column is sound only when the column's key
81
+ * normalizer is ORDER-preserving with respect to its comparator — i.e. the comparator
82
+ * orders two strings the way memcmp orders their normalized bytes. That is NOT implied
83
+ * by `db.registerCollation`'s normalizer contract, which promises only an equality
84
+ * partition, and a built-in NAME may be re-registered with a comparator + normalizer
85
+ * pair that preserves equality while inverting order. This method is therefore only
86
+ * ever reached under {@link leadingPkRangeIsOrderSafe} — enforced by
87
+ * {@link analyzePKAccess} here and mirrored by `computeBestAccessPlan` (store-module-access-plan.ts)
88
+ * before it claims the range filters handled. A collation without the
89
+ * `orderPreserving` assertion costs the seek, never a row.
90
+ */
91
+ protected buildPKRangeBounds(access: PKAccessPattern): IterateOptions;
92
+ /**
93
+ * Scan a leading-PK-column range, seeking to the window start and
94
+ * early-terminating at its end.
95
+ *
96
+ * {@link buildPKRangeBounds} converts the LT/LE/GT/GE constraints into one
97
+ * encoded-byte `gte`/`lt` window under the same per-column DESC directions and
98
+ * key collations the data keys use, so the iterate visits a SUPERSET of the
99
+ * qualifying rows (a collation widening or the bound-byte increment can
100
+ * over-fetch, never under-fetch). {@link matchesFilters} stays the authoritative
101
+ * collation-aware row filter. {@link iterateEffective} restricts the pending
102
+ * merge to the same `bounds`, so read-your-own-writes holds on the narrowed window.
103
+ */
104
+ protected scanPKRange(store: KVStore, access: PKAccessPattern, filterInfo: FilterInfo): AsyncIterable<Row>;
105
+ /**
106
+ * Resolve the secondary index chosen by the planner from `filterInfo.idxStr`.
107
+ *
108
+ * The planner emits `idx=<name>(<n>);plan=…` when its access plan set both an
109
+ * `indexName` and `seekColumnIndexes` (see `getBestAccessPlan` and
110
+ * rule-select-access-path.ts). Decoding goes through the engine's shared
111
+ * `decodeIdxStr`, so the store, the in-memory vtab, and the isolation overlay all
112
+ * read one format. Returns null for the PK/scan sentinels (`_primary_`, `fullscan`,
113
+ * `empty`), an idxStr that names no index, or a name absent from `schema.indexes` —
114
+ * every one of which routes back to a PK/full-scan arm.
115
+ */
116
+ protected resolveIndexFromIdxStr(idxStr: string | null): TableIndexSchema | null;
117
+ /**
118
+ * Analyze filter info to determine a secondary-index access pattern, mirroring
119
+ * {@link analyzePKAccess} but over the index chosen in `idxStr`.
120
+ *
121
+ * A contiguous leading-prefix EQ on the index columns yields a `point` window
122
+ * (the prefix covers every entry sharing those leading values — an index seek
123
+ * is a PREFIX scan, not a single row, since the index need not be unique and
124
+ * the PK suffix varies); otherwise a range (LT/LE/GT/GE) on the LEADING index
125
+ * column yields a `range` window. Returns null when neither applies or when the
126
+ * index is unresolved. {@link matchesFilters} stays the authoritative row filter,
127
+ * so the window need only be a SUPERSET.
128
+ *
129
+ * Index-column bytes are encoded under each column's own key collation
130
+ * ({@link indexKeyCollations}); {@link matchesFilters} re-checks a fetched row under the
131
+ * index column's `COLLATE` else the table column's declared collation. The EQ/prefix
132
+ * window is EXACTLY the qualifying set when those two agree, which
133
+ * {@link indexPrefixSeekIsCollationExact} decides; the RANGE window additionally equates
134
+ * memcmp of the key bytes with the residual's comparison ORDER, which
135
+ * {@link indexRangeIsOrderSafe} decides. `tryIndexAccessPlan`
136
+ * (store-module-access-plan.ts) consults the SAME two predicates before claiming the
137
+ * filters handled, so the two decisions cannot disagree. Either failing returns null and
138
+ * the caller full-scans, where the residual is authoritative.
139
+ */
140
+ protected analyzeIndexAccess(filterInfo: FilterInfo): IndexAccessPattern | null;
141
+ /**
142
+ * Lazy cache behind {@link indexKeyCollations}: one resolved array per index-schema
143
+ * object, invalidated when the column array it was resolved against is replaced (an
144
+ * ALTER can retype a column without minting new index objects, so the index identity
145
+ * alone is not a safe key).
146
+ */
147
+ private readonly indexKeyCollationsCache;
148
+ /**
149
+ * Per-column KEY collation for `index`'s own columns, memoized — see
150
+ * {@link resolveIndexKeyCollations}. The one resolution every scan-side encode site
151
+ * ({@link analyzeIndexAccess}, {@link buildIndexRangeBounds}, {@link scanMultiSeek})
152
+ * threads into `buildIndexPrefixBounds`, so a scan window can never address
153
+ * different bytes than the maintenance writes.
154
+ */
155
+ protected indexKeyCollations(index: TableIndexSchema): (string | undefined)[];
156
+ /**
157
+ * Per-column comparators stating the store's actual index-key BYTE order for
158
+ * `indexName` — the `VirtualTable.getIndexComparator` isolation hook, mirroring
159
+ * `MemoryTable.getIndexComparator`. The isolation layer merges the overlay's pending
160
+ * rows against this table's index scan by `(indexKey, PK)` sort key and prefers these
161
+ * over its descriptor-derived fallback, so each column's comparator must reproduce
162
+ * the order {@link scanIndex} emits in:
163
+ * - the column's KEY collation ({@link indexKeyCollations}: index COLLATE, else the
164
+ * table column's declared collation, else BINARY) for text;
165
+ * - the logical type's `compare` for a semantic-ordering column (its key bytes
166
+ * encode through an order-preserving transform — see `storeSemanticKeyTransform`);
167
+ * - negated for a DESC column (its key bytes are bit-inverted).
168
+ * Resolved against the MATERIALIZED schema so a hidden `_uc_*` name resolves too.
169
+ *
170
+ * NOTE: for a text column this states the COMPARATOR's order, which is the byte order
171
+ * only while the collation's key normalizer preserves order (`_isCollationOrderPreserving`
172
+ * — asserted by the built-ins, opt-in for a custom one; see keyOrderMatchesCollation).
173
+ * Under an equality-only custom collation the emitted byte order and this comparator can
174
+ * disagree, misplacing an overlay row within an index-key-equal group. Same exposure the
175
+ * isolation layer's descriptor fallback carried before this method existed, so nothing
176
+ * regressed; if a custom equality-only collation on an INDEX column ever ships, gate this
177
+ * on the assertion (returning undefined declines to the fallback, which is no better —
178
+ * the real fix is to make the store emit in comparator order or the merge tolerate it).
179
+ */
180
+ getIndexComparator(indexName: string): CompareFn[] | undefined;
181
+ /**
182
+ * True when a byte window over the LEADING column of `index` reproduces the order the
183
+ * residual comparison uses. Delegates to {@link indexLeadingRangeIsOrderSafe} — the SAME
184
+ * call the range arm of `tryIndexAccessPlan` (store-module-access-plan.ts) makes before
185
+ * it marks the range filters handled, so the "build a window" and "mark handled"
186
+ * decisions cannot disagree. The memoized {@link indexKeyCollations} is passed as the
187
+ * key side, so the predicate judges the bytes this scan actually addresses.
188
+ */
189
+ protected indexRangeIsOrderSafe(index: TableIndexSchema): boolean;
190
+ /**
191
+ * Convert leading-index-column LT/LE/GT/GE constraints into one encoded-byte
192
+ * `gte`/`lt` window — the secondary-index analogue of {@link buildPKRangeBounds}.
193
+ *
194
+ * Each bound value is encoded under the leading index column's own key `collation`
195
+ * ({@link indexKeyCollations}) and DESC `dir` — exactly as {@link buildIndexKey}
196
+ * encodes that column — via {@link buildIndexPrefixBounds}, giving the byte region
197
+ * `[lo, hi)` whose leading column equals that value. The op maps that region's
198
+ * endpoints onto `gte`/`lt`, with the same DESC lower/upper SWAP as the PK path:
199
+ *
200
+ * | op | ASC | DESC |
201
+ * |----|----------|----------|
202
+ * | GE | gte = lo | lt = hi |
203
+ * | GT | gte = hi | lt = lo |
204
+ * | LE | lt = hi | gte = lo |
205
+ * | LT | lt = lo | gte = hi |
206
+ *
207
+ * Across constraints keep the MAX lower and MIN upper. An `undefined` upper (an
208
+ * `hi` whose increment overflowed all-0xff) leaves that side unbounded — a safe
209
+ * SUPERSET. A NULL/missing bound value is skipped (the planner never pushes
210
+ * `= NULL`, and a range op against NULL rejects every row in matchesFilters).
211
+ */
212
+ protected buildIndexRangeBounds(constraints: Array<{
213
+ op: IndexConstraintOp;
214
+ value?: SqlValue;
215
+ }>, dir: boolean, collation: string | undefined): IterateOptions;
216
+ /**
217
+ * Scan a secondary index over `access.bounds`, resolving each index entry to its
218
+ * base row and re-filtering.
219
+ *
220
+ * {@link iterateEffective} yields the committed index entries merged with this
221
+ * transaction's pending index puts/deletes (read-your-own-writes over the
222
+ * index), in index-key byte order — the order the isolation overlay merge relies
223
+ * on (`isolated-table.ts` § buildSortKey). We resolve each entry to its row via
224
+ * its stored data-key value WITHOUT reordering, so index-key order is preserved.
225
+ *
226
+ * Defense in depth mirroring the memory layer's live-recheck: a resolved-null
227
+ * row (the entry's row was deleted — a pending index delete would normally
228
+ * suppress the entry, but a committed entry can lag) is skipped, and every
229
+ * resolved row is re-checked by {@link matchesFilters} (the byte window is only
230
+ * a superset, and a stale entry whose indexed column no longer matches is
231
+ * dropped).
232
+ */
233
+ protected scanIndex(indexStore: KVStore, access: IndexAccessPattern, filterInfo: FilterInfo, multi?: MultiSeekWindowContext): AsyncIterable<Row>;
234
+ /**
235
+ * Fail loudly on a multi-seek FilterInfo this table cannot serve. The plan already
236
+ * dropped the residual Filter, and {@link matchesFilters} ANDs every pushed
237
+ * constraint — so falling through to the scan arm would AND N mutually-exclusive
238
+ * equalities and return zero rows: a silent wrong answer, not a slow one.
239
+ */
240
+ private multiSeekMalformed;
241
+ /**
242
+ * Decode a multi-seek FilterInfo into its N seek tuples of width W. Tuple i pairs
243
+ * `args[i*W … i*W+W-1]` with the same slice of `constraints` (argvIndex runs
244
+ * 1…N*W in order — see rule-select-access-path's multiSeek emission). A tuple with
245
+ * a NULL/undefined component is dropped: IN is set membership and a NULL component
246
+ * matches nothing. The planner pre-reduces literal lists, but a parameter-bound /
247
+ * mixed-binding list reaches here unreduced, so this skip is the only line of
248
+ * defense for those.
249
+ */
250
+ private decodeMultiSeekTuples;
251
+ /**
252
+ * Order one tuple's values to match `keyCols` (the leading index columns, or the
253
+ * PK definition) using each constraint entry's column. The plan's seek columns and
254
+ * the constraint list must agree; a tuple that does not cover exactly those
255
+ * columns is malformed.
256
+ */
257
+ private orderTupleValues;
258
+ /**
259
+ * Serve a multi-seek (`plan=5`) FilterInfo: one point window per distinct
260
+ * IN-list tuple, scanned in ascending encoded-key order.
261
+ *
262
+ * Window order is not cosmetic. Encoded-byte order IS index-key order (per-column
263
+ * DESC inversion is baked into the bytes), and the isolation overlay merges an
264
+ * index scan with its pending rows by (indexKey, PK) — an out-of-order underlying
265
+ * stream misplaces overlay rows in the output. Two overlap hazards are folded
266
+ * away before scanning:
267
+ * - Tuples whose encoded prefix byte-matches (duplicate bound parameters, or
268
+ * case variants under a NOCASE key collation C) share ONE window, each kept
269
+ * as a residual alternative — see {@link MultiSeekWindowContext}.
270
+ * - A window with no finite upper bound (all-0xff prefix — see
271
+ * buildIndexPrefixBounds) contains every later-sorting window outright (any
272
+ * key ≥ an all-0xff prefix necessarily starts with it), so those windows fold
273
+ * into it instead of re-scanning an overlapping range out of order.
274
+ *
275
+ * Emission is lazy per window — `… in (…) limit 1` stops after the first yielded
276
+ * row without materializing the remaining windows. Each window goes through
277
+ * {@link scanIndex} → {@link iterateEffective}, so read-your-own-writes and the
278
+ * stale-entry / deleted-row defenses hold per seek key.
279
+ */
280
+ protected scanMultiSeek(spec: IdxStrSpec, filterInfo: FilterInfo): AsyncIterable<Row>;
281
+ /**
282
+ * Multi-seek over the PRIMARY key: each tuple is a full PK, resolved by a point
283
+ * read in ascending encoded-data-key order (the table's native emission order).
284
+ *
285
+ * NOT reachable from this module's own plans today: `computeBestAccessPlan` (store-module-access-plan.ts)
286
+ * claims IN-list filters only for secondary indexes (see its EQ_OPS vs EQ_OR_IN_OPS
287
+ * split and tickets/backlog/feat-store-pk-in-list-multiseek). The branch exists so
288
+ * a `_primary_` multi-seek arriving from a future plan gets a correct answer rather
289
+ * than the scan arm's silent zero rows, and it is what PK-IN enablement will build on.
290
+ */
291
+ protected scanMultiSeekPrimary(tuples: MultiSeekTuple[], seekWidth: number, filterInfo: FilterInfo): AsyncIterable<Row>;
292
+ /**
293
+ * Check if a row matches the filter constraints.
294
+ *
295
+ * `collations` maps a constrained column index to the comparison function that
296
+ * column must be re-checked under; every caller builds it once per scan with
297
+ * {@link resolveFilterCollations}, whose doc comment explains how the name is
298
+ * chosen. A column absent from the map compares BINARY — the same result
299
+ * {@link resolveFilterCollations} produces for an undeclared collation, and the
300
+ * only reachable absence, since both walk the constraint list under identical
301
+ * skip conditions.
302
+ */
303
+ protected matchesFilters(row: Row, filterInfo: FilterInfo, collations: ReadonlyMap<number, CollationFunction>): boolean;
304
+ /**
305
+ * Resolve, ONCE per scan, the comparison collation function for every pushed
306
+ * constraint column, keyed by column index.
307
+ *
308
+ * The name for a column is its DECLARED collation (absent ⇒ BINARY) — the same
309
+ * resolution the access path's collation-cover analysis uses
310
+ * (indexColumnCollationLookup / primaryKeyCollationLookup) when it decides a
311
+ * pushed constraint is fully covered, and the same source `StoreTableConstraints`'
312
+ * UNIQUE checks compare under. On a collation MATCH the planner drops the residual
313
+ * Filter, so {@link matchesFilters} alone must reproduce the predicate.
314
+ *
315
+ * `indexCollationNames` (from {@link indexColumnCollations}) overrides the
316
+ * declared name for the secondary-index scan arm: the planner's MATCH there is
317
+ * against the INDEX column's collation, which an explicit `COLLATE` on the index
318
+ * can make differ from the table column's.
319
+ *
320
+ * Names resolve against {@link collationResolver}, so an unregistered collation
321
+ * raises `no such collation sequence` at scan setup rather than byte-ordering
322
+ * every row.
323
+ *
324
+ * NOTE: rebuilt on every `query()` / `scanPKRange()` / `scanIndex()` call — one
325
+ * registry lookup per distinct constrained column, dwarfed by the scan's I/O. If a
326
+ * point-lookup-heavy profile ever shows it, memoize on the `FilterInfo`.
327
+ */
328
+ protected resolveFilterCollations(filterInfo: FilterInfo, indexCollationNames?: ReadonlyMap<number, string | undefined>): ReadonlyMap<number, CollationFunction>;
329
+ /**
330
+ * Effective per-column comparison collation for a secondary index's columns:
331
+ * the index column's own `COLLATE` when present, else the underlying table
332
+ * column's declared collation. Mirrors the resolution `StoreModule`'s
333
+ * index-maintenance UNIQUE dedup uses (`indexCol.collation ?? tableColumn`), so
334
+ * a re-checked index-scan row compares under the same collation the planner used
335
+ * to justify dropping (or keeping) the residual Filter.
336
+ */
337
+ protected indexColumnCollations(index: TableIndexSchema): Map<number, string | undefined>;
338
+ /**
339
+ * Compare two values according to an operator, under `collationFunc` (already
340
+ * resolved by {@link resolveFilterCollations} against this database's collation
341
+ * registry). So the LT/LE/GT/GE range bounds honour a NOCASE/RTRIM/custom column
342
+ * collation rather than a raw BINARY JS comparison — the capability
343
+ * `StoreModule.getBestAccessPlan` advertises via `honorsCollatedRangeBounds`.
344
+ * NULL on either side fails every operator except EQ-with-both-NULL (the
345
+ * internal point-lookup convention; the planner never pushes `= NULL`).
346
+ */
347
+ protected compareValues(a: SqlValue, op: IndexConstraintOp, b: SqlValue, collationFunc: CollationFunction, semanticCompare?: (a: SqlValue, b: SqlValue) => number): boolean;
348
+ }
349
+ /** PK access pattern analysis result. */
350
+ interface PKAccessPattern {
351
+ type: 'point' | 'range' | 'scan';
352
+ values?: SqlValue[];
353
+ columnIndex?: number;
354
+ constraints?: Array<{
355
+ columnIndex: number;
356
+ op: IndexConstraintOp;
357
+ value?: SqlValue;
358
+ }>;
359
+ }
360
+ /**
361
+ * Secondary-index access pattern analysis result: the chosen index plus the
362
+ * encoded byte window {@link StoreTableScan.scanIndex} iterates. `point` is a
363
+ * leading-prefix EQ window, `range` a leading-column LT/LE/GT/GE window; both
364
+ * resolve to a `bounds` scan (an index seek is always a prefix scan, never a
365
+ * single entry).
366
+ */
367
+ interface IndexAccessPattern {
368
+ index: TableIndexSchema;
369
+ type: 'point' | 'range';
370
+ bounds: IterateOptions;
371
+ }
372
+ /** One pushed-constraint entry, as {@link FilterInfo.constraints} carries it. */
373
+ type ConstraintEntry = FilterInfo['constraints'][number];
374
+ /**
375
+ * One multi-seek tuple: its W constraint entries and their bound values, in
376
+ * constraint order (see {@link StoreTableScan.decodeMultiSeekTuples}).
377
+ */
378
+ interface MultiSeekTuple {
379
+ entries: ConstraintEntry[];
380
+ values: SqlValue[];
381
+ }
382
+ /**
383
+ * Per-window context a multi-seek passes to {@link StoreTableScan.scanIndex} (absent for
384
+ * ordinary single-window scans).
385
+ *
386
+ * `seen` — data-key hexes already YIELDED by an earlier window. Checked before the
387
+ * data-store read (a cross-window duplicate costs no extra `get`), added only on a
388
+ * yield: adding at visit time would let a stale index entry (row re-keyed since
389
+ * indexing) that FAILS its residual poison the set and suppress the row's live entry
390
+ * in a later window.
391
+ * NOTE: holds one hex string per row the multi-seek yields, for the whole seek — the
392
+ * only unbounded allocation on this path. Windows are byte-disjoint, so the only real
393
+ * duplicate source is a stale index entry; if a large-result `IN` ever shows up as a
394
+ * memory problem, the set can be scoped per window (or dropped for a consistent store).
395
+ *
396
+ * `collations` — the constraint collation map, resolved once per multi-seek (it is
397
+ * identical for every window).
398
+ *
399
+ * `extraTuples` — additional seek tuples whose encoded window byte-equals this
400
+ * window's (duplicate bound parameters, or case-variant values under a NOCASE key
401
+ * collation). A row is yielded when it matches the primary FilterInfo OR any of
402
+ * these. Index bytes now encode under the same collation C the residual compares
403
+ * under (`indexKeyCollations`), so byte-equal tuples are C-equal and each merged
404
+ * tuple's residual admits the same rows — the OR is redundancy, kept because it is
405
+ * what makes the fold safe by construction rather than by that argument, and it is
406
+ * what a custom equality-only normalizer (byte-equal ⇏ comparator-equal order but
407
+ * equal partition) still relies on.
408
+ */
409
+ interface MultiSeekWindowContext {
410
+ seen: Set<string>;
411
+ collations: ReadonlyMap<number, CollationFunction>;
412
+ extraTuples: readonly FilterInfo[];
413
+ }
414
+ export {};
415
+ //# sourceMappingURL=store-table-scan.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"store-table-scan.d.ts","sourceRoot":"","sources":["../../../src/common/store-table-scan.ts"],"names":[],"mappings":"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"}