In `@nexum_core/benches/db_comparison.rs`:
- Around line 77-88: The benchmarks label a "Cold" vs "Cached" run but
setup_nexum() constructs an Executor without enabling the semantic cache, so the
"Cached" path (the extra warmup execute on nexum_executor with select_stmt) has
no effect; either enable the cache by calling with_cache(...) on the Executor
returned by setup_nexum() (so that nexum_executor.with_cache(...) /
setup_nexum() config includes the caching layer) before running the
"NexumDB_Point_Lookup_Cached" benchmark, or remove/rename the cached benchmark
and its warmup execute to avoid the misleading distinction between
NexumDB_Point_Lookup_Cold and NexumDB_Point_Lookup_Cached.
- Around line 39-46: The NexumDB benchmark reuses a parsed INSERT with a fixed
id, making it incomparable to SQLite; update the bench closure in
group.bench_function("NexumDB_Single_Insert", using setup_nexum and
executor.execute, to generate a unique id each iteration (e.g., incrementing
counter or UUID) and build/parse the INSERT inside b.iter so each iteration
inserts a distinct id; ensure you stop cloning a single Parser::parse(statement)
and instead parse/prepare the per-iteration SQL (or at minimum substitute the
generated id into a pre-parsed template) before calling executor.execute to
match SQLite's behavior.
- Around line 70-74: The benchmark currently calls sqlite_conn.prepare(...)
inside group.bench_function's closure, causing prepare() to be measured; move
the prepare call out of the iteration so the prepared statement is created once
(e.g., before invoking b.iter) and then inside the iteration only call
stmt.query_row(...) (the prepared statement variable `stmt` returned by
sqlite_conn.prepare and the use of `query_row`) so the benchmark measures only
query execution latency.
- Around line 16-27: The TempDir created in setup_nexum is being dropped at
function exit causing the storage directory to be deleted while
StorageEngine/Executor remain live; change the signature of setup_nexum to
return both the Executor and the TempDir (e.g., -> (Executor, TempDir)), keep
the db_path variable in scope by returning it alongside the Executor, and update
any callers to accept the tuple so TempDir stays alive for the duration of the
benchmark; reference the setup_nexum function, the db_path TempDir,
StorageEngine::new and Executor::new when making this change.
- Around line 9-14: The setup_sqlite function creates a NamedTempFile that is
dropped at return, causing the returned Connection to point to a deleted file
(problematic on Windows); modify setup_sqlite to keep the temp file alive by
returning the NamedTempFile alongside the rusqlite::Connection (or alternatively
create a tempdir and build the DB path inside it), update call sites to
accept/destructure the tuple (e.g., let (conn, _db_file) = setup_sqlite()) so
the NamedTempFile remains in scope while Connection is used.
- Around line 60-68: The NexumDB insert loop uses a constant INSERT with id=1,
so the SELECT WHERE id = 500 matches nothing; change the insert logic to insert
unique, incrementing ids that mirror SQLite (e.g., use the loop index) so ids
span the same range as row_count. Concretely, replace the constant
insert_sql/insert_stmt usage with an INSERT that injects the current loop index
(or prepare a parameterized statement and bind i) inside the for 0..row_count
loop where nexum_executor.execute(...) is called, keeping the
Parser::parse/execute flow (or use a prepared statement) so nexum_executor,
insert_stmt, Parser::parse, and row_count align with SQLite's 0..row_count id
sequence.

In `@nexum_core/benches/README.md`:
- Around line 29-32: The README's claim that PyO3 bridge and semantic caching
contribute to the ~1.8ms latency is incorrect because the benchmark executor is
created without .with_cache(), so those layers are never invoked; update the
README text (the paragraph discussing "PyO3 Bridge" and "Semantic Caching") to
remove or reword claims about PyO3/semantic-caching overhead and instead state
that the current benchmark measures SQL parsing + sled scan only, and add a note
that accurate measurement of PyO3/semantic-caching requires creating the
executor with .with_cache() and re-running the benchmarks.
- Around line 10-14: The benchmark SELECT numbers are invalid because
db_comparison.rs inserts NexumDB rows all with id=1 then queries WHERE id = 500
(zero matches) and labels Cold/Cached without enabling a cache; fix
db_comparison.rs by generating unique IDs for inserted rows (e.g., use the loop
index or a proper primary key) and make the SELECT query target an existing id
(or benchmark point selects by key present in the dataset), remove or correctly
implement the caching scenario (enable the cache before the Cached run or drop
the Cached/Cold distinction), then re-run the benchmarks and update the README
table in nexum_core/benches/README.md with the corrected timings.
- Around line 6-48: The Markdown has lint issues: ensure every heading (e.g.,
"## Performance & Benchmarks (Feb 2026)", "### Comparative Performance Results",
"### Analysis", "### Architectural Insights", "#### 1. Write Throughput: The
LSM-Tree Advantage", "#### 2. Read Latency & AI Overhead", and "##
Architecture") is surrounded by a blank line above and below, add a blank line
before and after the table starting with "| Operation | SQLite | NexumDB | Delta
|" and after the table block, and remove the trailing space on the line in the
"Read Latency & AI Overhead" paragraph; reflow nearby lines so code/inline
elements (like `criterion`, `sled`, `Statement`, `PyO3`) remain properly fenced
and the image link ("![Benchmark
Visualization](./nexum_core/benches/bench_results.png)") is also separated by
blank lines.
- Line 17: The image reference in the README uses an incorrect nested path;
update the markdown image tag on the line showing "![Benchmark
Visualization](./nexum_core/benches/bench_results.png)" to point to the local
file name (e.g., "![Benchmark Visualization](./bench_results.png)") so the link
resolves correctly from the README in nexum_core/benches; change only the path
in that image tag.
- Around line 5-6: Remove the orphaned heading "## Benchmark Categories" that is
immediately followed by "## Performance & Benchmarks (Feb 2026)" in the README;
either delete the "## Benchmark Categories" line or merge its intent into "##
Performance & Benchmarks (Feb 2026)" and ensure a blank line before the
remaining heading to satisfy markdownlint MD022. Locate the headings by their
exact text ("## Benchmark Categories" and "## Performance & Benchmarks (Feb
2026)"), remove or replace the former, and add a single blank line above the
retained heading.

In `@nexum_core/benches/storage_bench.rs`:
- Around line 1-10: Remove the unnecessary blank lines in the imports and before
the function declaration in this file: collapse the extra blank line after "use
std::time::Duration;", remove the blank line(s) between the criterion use block
and "use nexum_core::StorageEngine;", and eliminate the blank line(s)
immediately before the "fn storage_write_throughput(c: &mut Criterion) {"
declaration so imports and the function are grouped consistently.

In `@nexum_core/benches/visualize.py`:
- Line 23: The line containing ax.set_yscale('log') in visualize.py has a
trailing whitespace; remove the extra space after the closing parenthesis so the
call is exactly ax.set_yscale('log') to clean up the trailing whitespace.
- Around line 4-7: The benchmark visualization currently uses hard-coded arrays
(labels, sqlite_times, nexum_times) in nexum_core/benches/visualize.py which
will become stale; update visualize.py to load benchmark data dynamically by
either parsing Criterion's JSON output (e.g.,
target/criterion/**/new/estimates.json) to populate labels and times or by
accepting those values as CLI arguments, and replace the static lists with the
parsed/CLI-provided values so functions that generate the chart use the dynamic
data sources instead of the hard-coded variables.
- Around line 1-27: The script runs plotting code at import time; wrap the body
into a typed main function and add an entrypoint guard: create def main() ->
None that declares typed variables (e.g., labels: list[str], sqlite_times:
list[float], nexum_times: list[float], x: np.ndarray, width: float, fig:
plt.Figure, ax: plt.Axes) and moves the plotting and
plt.savefig('bench_results.png') into it, then add if __name__ == "__main__":
main() to prevent side effects on import and satisfy PEP 8/type-hint
requirements.

In `@nexum_core/Cargo.toml`:
- Line 26: Update the rusqlite dependency in Cargo.toml from "0.31.0" to the
latest "0.38.0" (replace the rusqlite = "0.31.0" line with rusqlite = "0.38.0"),
then run cargo update -p rusqlite and cargo build/test to surface any breaking
changes; if the build fails, inspect and update usages of rusqlite APIs (e.g.,
Connection, params!, named_params!, Transaction methods) to match the 0.38.0
API.

In `@nexum_core/src/executor/mod.rs`:
- Line 830: Replace the non-descriptive inline comment "// second test" with a
meaningful description (or remove it) near the related test in
nexum_core::executor::mod.rs; for example, replace it with a concise phrase like
"// Verify that DROP TABLE physically removes row data from storage" so the test
intent is clear, or delete the comment if it adds no value.
- Line 815: Update the comment on the test in mod.rs to follow idiomatic Rust
comment style by adding a leading space and capitalizing the first word; change
the existing `//added a test that checks if dropping a non-existent table
without IF EXISTS fails correctly.` to `// Added a test that checks if dropping
a non-existent table without IF EXISTS fails correctly.` — locate and edit the
inline comment near the test (around the test that verifies dropping a
non-existent table) in nexum_core::executor::mod.rs.

In `@nexum_core/src/storage/mod.rs`:
- Around line 1-5: The engine module is currently made public but its only
exported item is already re-exported as StorageEngine; change the module
declaration from `pub mod engine;` to `mod engine;` to keep the internal module
private while retaining the public API via `pub use engine::StorageEngine;`, and
ensure no other code refers to `storage::engine::` directly (update any such
references to use `StorageEngine` through the re-export).

In `@nexum_core/benches/db_comparison.rs`:
- Around line 56-64: The SQLite benchmark discards the query_row result (let _)
which can be optimized away; wrap the retrieved value in criterion::black_box
inside the group.bench_function closure to prevent dead-code elimination (i.e.,
pass the result of stmt.query_row(... ) into black_box). Ensure
criterion::black_box is in scope (import if necessary) and update the closure
around stmt.query_row in the "SQLite_Point_Lookup" benchmark to use black_box
instead of ignoring the value.
- Around line 88-89: Add full CRUD benchmarks and register them: implement new
benchmark functions named bench_inserts, bench_updates, and bench_deletes
(matching the existing bench_selects pattern) that perform the same operations
against NexumDB and SQLite (use the INSERT statements already in the file for
setup as a guide), measure throughput with Criterion, and ensure each test
cleans up or isolates data between runs; then update the criterion_group!
invocation to criterion_group!(benches, bench_selects, bench_inserts,
bench_updates, bench_deletes) so all four benchmarks are run and comparable to
the README results.

In `@nexum_core/benches/visualize.py`:
- Around line 1-6: Remove the unused sys import from the top-level imports:
delete the reference to sys in the import block alongside json, argparse, Path,
typing, and matplotlib so the file no longer imports an unused module (ensure
only the remaining imports json, argparse, Path, Dict/List/Optional typing, and
matplotlib.pyplot as plt remain).
- Around line 17-30: The find_benchmark_data function currently uses
base_path.rglob("estimates.json") which can return both base/estimates.json and
new/estimates.json and leads to non-deterministic overwrites; update the loop to
only accept the latest run by filtering json_path to ensure it is the
"new/estimates.json" file (e.g., check json_path.name == "estimates.json" and
json_path.parent.name == "new" or match the suffix "/new/estimates.json") before
calling parse_criterion_json and assigning results[target] = val so only
latest-run values are collected.