Epic: reliability before features — durability, AOT, query correctness and oracle coverage #288

Discussion: #287 · v6.0.0 migration guide, changelog, docs, samples and release engineering: #296

Goal

Every promise in README.md and AOT_LIMITATIONS.md is true and backed by a test, before new features land. The issues below were found by the oracle suites and the AOT smoke test. Most already have a fix PR. The last groups extend the oracles to every documented library section, so the next promise is checked before it is broken.

Done when

• The P0 issues below are closed.
• The oracle suites (test: oracle tests for the LINQ provider and the typed collection store #250 → test(oracles): model-based test of BTreeIndex with page accounting #259 → test(oracles): crash consistency of the WAL and page store by fault injection #263 → test(oracles): differential and model-based tests of DynamicCollection #272 → test(aot): Native AOT smoke test, a consumer under JIT and AOT with the publish log as oracle #277 → test: encrypted mode for the store model and WAL crash oracles #294) are merged, and the ones agreed on run in CI.
• README states what each WAL sync mode guarantees, and "zero allocation" is reworded to match the benchmarks.
• BENCHMARKS.md is re-run after fix(wal): sync the WAL to disk before a commit is acknowledged #280 with the sync mode of every engine stated.
• The README has a stability matrix (stable / experimental) in which a section is stable only when its oracle is merged and its registry is empty, and AOT_LIMITATIONS.md matches the smoke test.

P0 — Durability and data integrity

• WAL commits are never flushed to disk: a power loss drops acknowledged commits and can leave documents pointing at freed pages #260 WAL commits are never flushed to disk; a power loss drops acknowledged commits → PR fix(wal): sync the WAL to disk before a commit is acknowledged #280
• Encrypted database: a page allocated by a transaction that never commits cannot be decrypted afterwards (rollback, backup during an open transaction, close with an uncommitted transaction) #274 Encrypted database: a page allocated by a transaction that never commits cannot be decrypted → PR fix(storage): write a new page of an encrypted file at allocation so an uncommitted page decrypts #279
• A crash between the two page writes of PageFile.FreePage/AllocatePage leaves a Free page off the free list #262 A crash between the two page writes of FreePage/AllocatePage leaves a Free page off the free list
• Multi-process WAL: a permanently unreadable record inside the published range stalls replay, checkpoints and truncation #220 Multi-process WAL: a permanently unreadable record stalls replay, checkpoints and truncation
• Two concurrent transactions both commit, and one of them is silently lost: no write-write conflict detection #304 Two concurrent transactions both commit and one is silently lost: no write-write conflict detection → PR fix(storage): detect write-write conflicts at commit (#304) #310
• A checkpoint drops a page image committed while it drains the WAL index: the commit is lost and an id can return another document #311 A checkpoint drops a page image committed while it drains the WAL index → PR fix(storage): drain only the flushed WAL image, atomically, after a checkpoint (#311) #313
• Collection-per-file mode: creating a collection can route another collection's page to the main file (lock-free read of a Dictionary) #312 Collection-per-file mode: creating a collection can route another collection's page to the main file → PR fix(storage): make the collection slot map safe for lock-free readers (#312) #314
• A commit that waits for another commit's disk sync fails with TimeoutException after 500 ms: LockTimeout.Default is tuned for an unsynced WAL #303 LockTimeout.Default (500 ms) is tuned for an unsynced WAL → PR fix(storage): raise LockTimeout.Default to 5 s so writers queued behind slow commits do not time out (#303) #321, lands together with fix(wal): sync the WAL to disk before a commit is acknowledged #280

P0 — Native AOT (the mobile and Unity story depends on it)

• Typed collections cannot write under Native AOT: the generated mapper registers its BSON keys by reflection that trimming removes #273 Typed collections cannot write under Native AOT → PR fix(generator): emit the mapper's BSON keys so typed writes work under Native AOT #278
• Native AOT publish of a consumer reports trim/AOT warnings inside BLite.Core: #pragma warning disable IL2026/IL3050/IL2070 hides reflection from BLite's build but not from ILC #275 #pragma warning disable IL2026/IL3050/IL2070 hides reflection that ILC reports at consumer publish
• BLite.Caching uses reflection-based System.Text.Json: warns under AOT and throws in any trimmed or AOT app #276 BLite.Caching uses reflection-based System.Text.Json and throws when trimmed
• Native AOT smoke test → PR test(aot): Native AOT smoke test, a consumer under JIT and AOT with the publish log as oracle #277

P0 — Browser (Blazor WASM)

Found by the browser harness (PR #295). The Blazor WASM niche of #287 stays experimental in the stability matrix until these close.

• BLite.Wasm: a committed write is lost on a page reload unless a checkpoint ran, and CheckpointAsync does not reliably prevent it #289 A committed write is lost on a page reload unless a checkpoint ran, and CheckpointAsync does not reliably prevent it
• BLite.Wasm: synchronous waits block or kill the browser runtime (HasIndex open, sync LINQ/BLQL ToList, Dispose, IsAvailable) #290 Synchronous waits block or kill the browser runtime (HasIndex open, sync LINQ and BLQL ToList, Dispose, IsAvailable)
• BLite.Wasm: two tabs on one database lose a committed write (IndexedDB) or cannot open it (OPFS) #291 Two tabs on one database lose a committed write (IndexedDB) or cannot open it (OPFS)
• BLite.Wasm: a 50 MB database cannot be reopened (out of memory reading the WAL); CheckpointAsync returns at once while a background checkpoint runs #292 A 50 MB database cannot be reopened; CheckpointAsync returns at once while a background checkpoint runs
• BLite.Wasm: package lacks its JS files and offers no typed-context factory #293 The package lacks its JS files and offers no typed-context factory

P1 — Index-served queries return what LINQ returns

Typed collections and B-tree:

• Typed collections: == null and OrderBy(nullable).Take(n) served from an index return no null-keyed documents (indexes skip null keys, planner reads the null bucket) #247 == null and OrderBy(nullable).Take(n) from an index return no null-keyed documents → PR fix(index): don't plan null lookups or nullable orderings from typed indexes (#247) #253
• x.Prop != constant does not match documents whose property is null (BsonExpressionEvaluator.Compare has no branch for a stored Null) #248 x.Prop != constant misses null properties → PR fix(linq): x.Prop != constant matches documents whose property is null or absent (#248) #251
• Indexed double equality misses -0.0: IndexKey(double) gives the two zeros different keys #249 Indexed double equality misses -0.0 → PR fix(index): -0.0 and +0.0 share one index key (#249) #252
• BTreeIndex.Equal/In/GreaterThan/LessThan/Between/StartsWith miss duplicate keys and fail past the last key #255 BTreeIndex Equal/In/GreaterThan/LessThan/Between/StartsWith miss duplicate keys and fail past the last key
• Equal keys come back from a B-Tree in reverse insertion order on a forward scan #256 Equal keys come back in reverse insertion order on a forward scan → PR fix(index): keep equal B-tree keys in insertion order on a forward scan #281
• A NaN with the sign bit clear sorts above +Infinity in an index on a double #257 A positive NaN sorts above +Infinity → PR fix(index): give every NaN one index key, below -Infinity #282 (stacked on fix(index): -0.0 and +0.0 share one index key (#249) #252)
• OrderByDescending served by an index returns tied keys in reverse insertion order, unlike LINQ and the non-indexed path #210 OrderByDescending from an index returns ties in reverse insertion order → PR fix(index): return equal keys in id order when a descending scan serves a query (#210) #244
• Typed secondary index keys are not prefix-free: values containing bytes 0x00–0x03 are mis-bounded #212 Typed secondary index keys are not prefix-free (bytes 0x00–0x03)

DynamicCollection and BLQL:

• DynamicCollection: range filters and sorts on an indexed double field return wrong results (keys are little-endian BitConverter bytes) #254 Range filters and sorts on an indexed double return wrong results
• BLQL filters and sorts cannot reach a nested field, though a dynamic index can be built on one #264 BLQL cannot reach a nested field
• BLQL orders and compares ObjectIds by their little-endian bytes, not as ObjectId.CompareTo #265 BLQL orders ObjectIds by little-endian bytes
• BLQL First and FirstOrDefault ignore Sort and Skip #266 BLQL First/FirstOrDefault ignore Sort and Skip → PR fix(blql): First and FirstOrDefault honour Sort and Skip #284
• BLQL range operators match fields of another BSON type: null under $lt, strings under $gt #267 BLQL range operators match other BSON types
• BLQL compares two Int64 values through double #268 BLQL compares Int64 through double → PR fix(blql): compare two integers exactly instead of through double #285
• A dynamic index misses keys for a numeric bound of another BSON type and keys no Decimal128 or Boolean value #269 Dynamic index misses keys for a numeric bound of another type; no Decimal128/Boolean keys
• QueryIndexAsync rejects a DateTime bound #270 QueryIndexAsync rejects a DateTime bound → PR fix(index): accept DateTime and DateTimeOffset bounds in QueryIndexAsync #286
• A failed unique CreateIndexAsync leaves the half-filled index registered #271 A failed unique CreateIndexAsync leaves the half-filled index registered → PR fix(index): a failed unique CreateIndexAsync on a DynamicCollection leaves no index behind #283

P1 — API correctness found in the v6 review (#296)

• BsonValue equality is wrong for negative Int64 and pre-1970 dates: FromInt64(-1) != FromInt64(-1), and FromInt64(0) == FromInt64(long.MinValue) #306 BsonValue equality is wrong for negative Int64 and pre-1970 dates → PR fix(bson): compare Int64 and date BsonValues by their stored bits (#306) #315
• BLiteSession.Rollback() does not await the rollback: it returns while the transaction is still active, and failures go unobserved #307 BLiteSession.Rollback() does not await the rollback → PR fix(session): await the rollback in BLiteSession; add RollbackAsync (#307) #316
• A DocumentDbContext whose class name does not end in "Context" gets no generated code and no diagnostic; its collections stay null #300 A DocumentDbContext whose name does not end in "Context" gets no generated code → PR fix(generator): discover a DocumentDbContext whatever its class name (#300) #317
• GdprMode.Strict warns that deleted documents are not zeroed, but every delete zero-fills them #299 GdprMode.Strict warns that deleted documents are not zeroed → PR fix(gdpr): Strict mode no longer claims deleted documents are not zeroed (#299) #318
• The schema-less API cannot read a typed collection that holds a document larger than one page: FindAllAsync and BLiteMigration throw "Skipping type 69" #301 The schema-less API cannot read a typed document stored in overflow pages → PR fix(core): the schema-less API reads documents a typed collection stored in overflow pages (#301) #319
• An engine and a session hold separate DynamicCollection instances: an index created through one misses the other's writes, and a session commit can erase the index definition #305 An engine and a session hold separate DynamicCollection instances

P2 — Multi-process mode (experimental until these close)

• Multi-process WAL: PrepareTransactionAsync and the direct commit paths bypass the commit and cross-process writer locks #188 PrepareTransactionAsync and direct commit paths bypass the commit and writer locks → PR fix(storage): keep prepared transactions' WAL records until they commit or roll back (#188) #246
• Multi-process follow-ups after #221 (open lock): index fill under the lock, dictionary reload for readers, stale free-list head, ... #226 Open-lock follow-ups after fix(storage): serialise multi-process create/open and remap grown files (#216) #221 → PR fix(storage): multi-process open-lock follow-ups (#226) #245

P2 — Space reclamation

• A crash leaks pages freed or allocated outside the WAL (queued frees, index roots on first open) #261 A crash leaks pages freed or allocated outside the WAL
• B-Tree pages allocated by a rolled-back split are never reclaimed #237 B-tree pages from a rolled-back split are never reclaimed
• Every reopen strands the unwritten rest of the last page growth block #258 Every reopen strands the rest of the last page growth block
• DynamicCollection secondary index keys are not unique: deleting entries of a heavily duplicated value is quadratic #234 Deleting heavily duplicated dynamic index keys is quadratic

Oracle coverage by library section

One oracle for every library section the documentation makes a promise about, each with a seed that proves it catches a real defect and a candidate registry that links what it finds to issues (method: docs/ORACLE_TESTS.md, in #250). A section counts as stable in the README's stability matrix once its oracle is merged and its registry is empty.

Written, in review:

• LINQ on typed collections: differential, 331 query shapes vs LINQ-to-Objects → PR test: oracle tests for the LINQ provider and the typed collection store #250 (found Typed collections: == null and OrderBy(nullable).Take(n) served from an index return no null-keyed documents (indexes skip null keys, planner reads the null bucket) #247–Indexed double equality misses -0.0: IndexKey(double) gives the two zeros different keys #249)
• Transactions and CRUD, single- and multi-process: model-based vs an in-memory model → PR test: oracle tests for the LINQ provider and the typed collection store #250
• B-tree indexes and page accounting: model-based vs a sorted dictionary → PR test(oracles): model-based test of BTreeIndex with page accounting #259 (found BTreeIndex.Equal/In/GreaterThan/LessThan/Between/StartsWith miss duplicate keys and fail past the last key #255–Every reopen strands the unwritten rest of the last page growth block #258)
• WAL and crash recovery: fault injection, three crash modes, ~1,900 crash states → PR test(oracles): crash consistency of the WAL and page store by fault injection #263 (found WAL commits are never flushed to disk: a power loss drops acknowledged commits and can leave documents pointing at freed pages #260–A crash between the two page writes of PageFile.FreePage/AllocatePage leaves a Free page off the free list #262)
• DynamicCollection and BLQL: differential and model-based vs LINQ-to-Objects and the typed collection → PR test(oracles): differential and model-based tests of DynamicCollection #272 (found BLQL filters and sorts cannot reach a nested field, though a dynamic index can be built on one #264–A failed unique CreateIndexAsync leaves the half-filled index registered #271)
• Native AOT and trimming: twin build vs the JIT build and the publish log → PR test(aot): Native AOT smoke test, a consumer under JIT and AOT with the publish log as oracle #277 (found Typed collections cannot write under Native AOT: the generated mapper registers its BSON keys by reflection that trimming removes #273–BLite.Caching uses reflection-based System.Text.Json: warns under AOT and throws in any trimmed or AOT app #276)
• Blazor WASM storage backends (OPFS, IndexedDB): browser harness, reload as the crash, two tabs as two processes → PR test: browser harness for BLite.Wasm (OPFS, IndexedDB, in-memory; trimmed and AOT) #295 (found BLite.Wasm: a committed write is lost on a page reload unless a checkpoint ran, and CheckpointAsync does not reliably prevent it #289–BLite.Wasm: package lacks its JS files and offers no typed-context factory #293)
• Encryption at rest: the store model and crash oracles on an encrypted database vs unencrypted → PR test: encrypted mode for the store model and WAL crash oracles #294 (new crash shapes of Encrypted database: a page allocated by a transaction that never commits cannot be decrypted afterwards (rollback, backup during an open transaction, close with an uncommitted transaction) #274)

Next:

• BSON and source-generated mappers: round trip of every supported type and edge value (identity)
• Composite and nested indexes: more rows in the LINQ differential vs the same rows unindexed
• Vector search (HNSW): recall vs exact brute-force k-NN
• Geospatial (R-tree): differential vs a linear scan with the same predicate
• TimeSeries and retention policies: model-based, the model applies the retention rule
• CDC / Watch: model-based, events equal the committed operations in commit order, nothing from rolled-back transactions
• Key-value store, TTL, BLite.Caching: model-based vs a dictionary with expiry
• Backup, VACUUM, single ↔ multi-file migration: same contents before and after (Backup and Vacuum are already store-model steps; migration is new)
• GDPR: secure erase leaves no bytes of the erased document in the file; subject export equals the model filtered by subject; masked CDC events carry no [PersonalData] field

Not covered by any oracle, stays with review: targets other than net10.0 (netstandard2.1, Unity IL2CPP, MAUI), real multi-process races, crashes in multi-process mode and inside Backup, torn page writes, performance, API design.

Docs (after the fixes above land)

The wider v6 docs work (migration guide, docs in the repository, compiled samples) is tracked in #296; the items below are the ones these fixes need.

• README: stability matrix, reworded "zero allocation", a "When not to use BLite" section
• BENCHMARKS.md: re-run after fix(wal): sync the WAL to disk before a commit is acknowledged #280; BLite Full vs SQLite WAL + synchronous=FULL, BLite Normal vs SQLite WAL + NORMAL
• AOT_LIMITATIONS.md: match what the test(aot): Native AOT smoke test, a consumer under JIT and AOT with the publish log as oracle #277 smoke test shows
• TESTING.md: what each oracle suite checks, how to run it, and the seeded defects it catches