How VelociDB's async API and parallel query execution work - the tokio spawn_blocking model in src/async_api.rs and the rayon thresholds in the executor. Use when modifying async_api.rs, adding async methods, tuning parallelism, or debugging blocked runtimes, stalled futures, or async test hangs.
VelociDB Change Data Capture - the in-memory change log in src/cdc.rs and its executor hooks. Use when modifying cdc.rs, adding CDC hooks to new write paths, changing ChangeEvent fields, or debugging missing/duplicate/out-of-order change events.
How to run and write VelociDB tests - test suite layout, commands, and patterns for unit, integration, crash-recovery, property-based, and async tests. Use when adding features, fixing bugs, writing new tests, or deciding which suites must pass before a change is done.
VelociDB vector search implementation - F32_BLOB(n)/VECTOR(n) columns, vector32 literals, distance functions, and exact parallel KNN. Use when modifying src/vector.rs, adding distance metrics, extending vector SQL syntax, or debugging dimension-mismatch, KNN-ordering, or vector-parsing issues.
VelociDB code conventions - error handling, module boundaries, the experimental-modules policy, locking style, and documentation expectations. Use when writing or reviewing any VelociDB code, deciding where new code lives, or cleaning up warnings.
Debugging VelociDB - REPL-based reproduction, tracing, inspecting db/WAL files, and a map of common failure modes to their causes. Use when investigating bugs, corruption errors, deadlocks/hangs, wrong query results, or data that disappears after reopen.
Extending VelociDB's regex-based SQL parser in src/parser.rs - statement dispatch, quote/paren-aware splitting helpers, value parsing, and known fragility. Use when adding SQL syntax, new statements or operators, changing WHERE/ORDER BY/VALUES parsing, or debugging "Invalid ... syntax" / mis-split errors.
On-disk formats for VelociDB - page layout, WAL record format, B-tree node layout, row serialization type tags, and the schema page encoding. Use when modifying src/storage.rs, src/wal.rs, src/btree.rs row (de)serialization, adding a new Value variant or DataType, or debugging corruption / "Invalid type tag" / schema-truncation errors.