sqlitegraph 3.9.0

# SQLiteGraph Changelog

## [3.9.0] - 2026-07-07

### Backend Modes

- Added an explicit `BackendKind::Combined` public mode plus
  `GraphConfig::combined()`.
- `GRAPH_BACKEND=combined` now resolves through the canonical config layer.
- Added a public `CombinedGraphBackend` wrapper type as the Phase 2 authority
  seam for combined mode.
- `open_graph(path, &GraphConfig::combined())` now returns
  `CombinedGraphBackend`, which is SQLite-authoritative by construction and
  delegates to the SQLite backend until graph materialization lands.
- Added `CombinedConfig` / `CombinedReadMode` to make combined-mode fallback
  behavior explicit.
- Combined mode can now opt into `PreferMaterialized` live traversal reads:
  untyped `neighbors()`, `bfs()`, `k_hop()`, `node_degree()`, and
  `shortest_path()` consult
  `csr_shards` first and fall back per-node or per-direction to authoritative
  SQLite reads when materialized rows are absent.
- Benchmarked current `PreferMaterialized` tradeoff: it remains an explicit
  opt-in specialist mode, not the default. Current local cold-read benches show
  modest gains, while incremental maintenance still increases write cost
  overall even after recent insert-path reductions.
- Added broader combined-mode benchmark coverage for:
  - cold rebuild-per-read comparisons
  - on-disk reopen reads
  - `publish_materialized_views()` rebuild cost
  - mixed read/write workloads
- Current benchmark conclusion remains negative for default-on combined
  materialization: even the current read-heavy mixed workload is slower
  end-to-end than SQLite-only, so `PreferMaterialized` stays specialist opt-in.
- Narrowed the incremental write overhead in combined mode:
  - `ensure_edge_type_ids()` now resolves only the requested edge types instead
    of scanning the full type table
  - incremental maintenance no longer rebuilds `csr_manifest` on every edge
    change
  - `insert_edge()` now patches the two affected CSR rows directly from the
    latest materialized blobs instead of re-reading full SQLite adjacency rows
  - `delete_entity()` now removes the deleted node directly from the affected
    materialized blobs and writes empty replacement rows for the deleted node
    itself instead of rebuilding touched rows from SQLite adjacency scans
- Updated local benchmark samples after the incremental fast path work:
  - `combined_incremental_writes/insert_edge/prefer_materialized` improved from
    roughly `74–76 µs` to `64.6–66.2 µs`
  - `combined_incremental_writes/delete_entity/prefer_materialized` now measures
    roughly `76.1–78.2 µs`
  - `combined_mixed_workloads/read_heavy_90_10/prefer_materialized` improved to
    roughly `639–650 µs`
  - `combined_mixed_workloads/balanced_50_50/prefer_materialized` improved to
    roughly `446–460 µs`
  - combined mode still loses end-to-end to SQLite-only in the current mixed
    workloads, so this remains an opt-in specialist path, not a default policy
- Added authoritative/materialized version tracking in `graph_meta`.
  Combined mode now uses materialized traversal reads only when
  `materialized_version >= authoritative_version`; stale CSR rows are ignored.
- Added `CombinedGraphBackend::publish_materialized_views()`, which rebuilds
  outgoing/incoming CSR rows from authoritative SQLite edges and publishes the
  current `materialized_version` atomically.
- Combined mode now incrementally refreshes affected CSR rows for
  `insert_edge()` and `delete_entity()` when
  `CombinedReadMode::PreferMaterialized` is enabled, and keeps
  `materialized_version` synchronized on node-only writes.
- Updated the README, manual, crate docs, and package metadata to describe the
  three current backend modes without over-claiming combined-mode atomicity.

### Documentation

- Clarified the user-facing native-v3 status in `README.md`, crate docs, and
  `Cargo.toml` feature comments.
- Documented the current executed state:
  - native-v3 query truth, Cypher parity, graph algorithm, HNSW, turbovec, and
    comprehensive feature suites are passing locally
  - native-v3 runtime traversal now has a CSR runtime view layered on top of
    the V3 edge-store/B+Tree source of truth
  - CSR/sharding is still not a standalone backend-default engine; edge-store
    remains authoritative and CSR rows are rebuilt from it

### Native V3

- Extracted the native-v3 lifecycle orchestration path from
  `backend/native/v3/backend.rs` into the new
  `backend/native/v3/lifecycle_support.rs` child module. This moved
  `create`, `create_with_wal`, and `open` without changing WAL recovery,
  SQLite sidecar initialization, index restore/rebuild, or file coordinator
  wiring behavior.
- Extracted the large inline native-v3 backend test module from
  `backend/native/v3/backend.rs` into the new
  `backend/native/v3/backend_tests.rs` file and removed the now-unneeded
  `clippy::items_after_test_module` allowance from the production backend file.
- Extracted the native-v3 node/entity orchestration helpers from
  `backend/native/v3/backend.rs` into the new
  `backend/native/v3/entity_support.rs` child module. The `GraphBackend` trait
  methods for node insert/update/delete, edge insert, entity ID listing, and
  node lookup now delegate to support methods without changing snapshot, cache,
  CSR rebuild, or property persistence behavior.
- Extracted `WriteBatchGuard` from `backend/native/v3/backend.rs` into the new
  `backend/native/v3/batch_guard.rs` child module with no behavior change. The
  public type remains re-exported through `backend.rs`, so the cleanup reduces
  `backend.rs` size without widening visibility or changing the batch-write API.
- Extracted `V3TransactionGuard` / `V3SavepointGuard` from
  `backend/native/v3/backend.rs` into the new
  `backend/native/v3/transaction_guard.rs` child module with no behavior
  change. The public guard types remain re-exported through `backend.rs`.
- Extracted the async helper block from `backend/native/v3/backend.rs` into the
  new `backend/native/v3/async_backend.rs` child module. This moved
  `get_async_coordinator`, the internal async node loader, and the
  `AsyncGraphBackend for V3Backend` implementation without changing behavior or
  widening private visibility.
- Extracted `SqlValue` / `SqlRow` from `backend/native/v3/backend.rs` into the
  new `backend/native/v3/sql_value.rs` child module. The query-facing types
  remain re-exported through `backend.rs`, so this is structure cleanup only.
- Extracted the native-v3 graph transaction frame/state helper block into the
  new `backend/native/v3/transaction_state.rs` child module. This moved the
  frame/state structs plus backup/discard/rollback/reload helpers without
  changing behavior or widening visibility.
- Extracted the native-v3 transaction-control methods into the new
  `backend/native/v3/transaction_control.rs` child module. This moved
  `begin_transaction`, `savepoint`, `commit_transaction`,
  `rollback_transaction`, and the savepoint release/rollback helpers without
  changing behavior or public transaction semantics.
- Extracted the native-v3 snapshot/version metadata block into the new
  `backend/native/v3/snapshot_meta.rs` child module. This moved version helpers,
  snapshot registry helpers, and snapshot CRUD helpers without changing
  behavior or visibility contracts.
- Hardened native-v3 runtime panic paths:
  - replaced HNSW/turbovec metadata mutex `unwrap()` sites in
    `backend/native/v3/backend.rs` with explicit lock-to-error conversion
  - replaced two production timestamp `unwrap()` sites with explicit error
    propagation
  - removed `edge_compat.rs` dirty-cluster cache `unwrap()`s by returning
    explicit `InvalidOperation` errors on impossible map misses
- Hardened sharding runtime panic paths:
  - `sharding/semantic.rs` now recovers from poisoned HNSW/turbovec mutexes
    instead of panicking in production lookup, insert, and statistics paths
  - `sharding/pubsub.rs` now recovers from poisoned subscriber/change-log/
    consumer-group mutexes instead of panicking on publish, replay, subscribe,
    and consumer-group operations
  - added regression tests proving both modules remain usable after lock
    poisoning
- Extracted the native-v3 HNSW/vector-search block from
  `backend/native/v3/backend.rs` into the new
  `backend/native/v3/hnsw_support.rs` child module. This moved the
  `HnswIndexMetadata` wrapper, `HnswSearchConfig`, and the index
  create/insert/delete/search helpers without changing public behavior.
- Extracted the native-v3 CSR/materialization helper block from
  `backend/native/v3/backend.rs` into the new
  `backend/native/v3/csr_support.rs` child module. This moved the CSR shard
  lookup, typed-edge mapping, shared-neighbor accessors, and
  runtime-view rebuild helpers without changing traversal behavior.
- Extracted the native-v3 SQL/query helper block from
  `backend/native/v3/backend.rs` into the new
  `backend/native/v3/sql_exec.rs` child module. This moved the compact
  node-data parser plus the raw/parameterized SQL query and update helpers
  without changing the SQL-facing API.
- Moved the native-v3 base-path / snapshot validation helpers from
  `backend/native/v3/backend.rs` into `backend/native/v3/snapshot_meta.rs`.
  This keeps snapshot/version/path invariants in one place without changing
  the create/open or traversal validation behavior.
- Extracted the native-v3 property/filter helper block from
  `backend/native/v3/backend.rs` into the new
  `backend/native/v3/property_support.rs` child module. This moved the
  node-id enumeration, triple-match property filters, synthetic edge-id
  generation, and SQLite node/edge property readers without changing the
  public feature surface.
- Extracted the native-v3 SQLite sidecar schema/migration helpers from
  `backend/native/v3/backend.rs` into the new
  `backend/native/v3/sqlite_schema.rs` child module. This moved the schema
  bootstrap and additive-column migration helpers without changing create/open
  behavior or the sidecar table layout.
- Extracted the native-v3 kind/name index rebuild helper from
  `backend/native/v3/backend.rs` into the new
  `backend/native/v3/index_rebuild.rs` child module. This moved the fallback
  index-rescan path used after open/rollback/update/delete without changing
  the rebuild logic or visibility outside native-v3 sibling modules.
- Extracted the native-v3 inner mutation helper block from
  `backend/native/v3/backend.rs` into the new
  `backend/native/v3/mutation_support.rs` child module. This moved the
  unsynced node/edge insert helpers plus the page-offset helper without
  changing batch-write semantics or the public `GraphBackend` mutation API.
- Continued the native-v3 mutation cleanup by moving the SQLite sidecar
  insert/update/delete persistence helpers into
  `backend/native/v3/mutation_support.rs`. The public `GraphBackend`
  mutation methods remain in `backend.rs`, but now delegate their raw SQLite
  sidecar writes through private helpers instead of inlining that boilerplate.
- Extracted the native-v3 `get_node()` read-path helpers into the new
  `backend/native/v3/read_support.rs` child module. This moved the historical
  snapshot visibility check and compact/external node-byte loading helpers,
  while leaving `GraphBackend::get_node()` in `backend.rs` as a thin policy
  wrapper.
- Extracted the native-v3 shared traversal helpers into the new
  `backend/native/v3/traversal_support.rs` child module. This moved the BFS,
  shortest-path, node-degree, and k-hop traversal logic while leaving the
  corresponding `GraphBackend` methods in `backend.rs` as thin delegators.
- Continued the traversal cleanup by moving the filtered traversal wrappers
  into `backend/native/v3/traversal_support.rs`. The V3 backend still ignores
  edge-type filters for these entry points and delegates to the unfiltered
  traversal logic, but the wrapper behavior now lives beside the traversal
  helpers instead of inside `backend.rs`.
- Extracted the native-v3 chain traversal implementation into the new
  `backend/native/v3/chain_support.rs` child module. `GraphBackend::chain_query()`
  in `backend.rs` now delegates to the same per-step sorted/deduped traversal
  logic instead of inlining it.
- Extracted the native-v3 pattern-query implementation into the new
  `backend/native/v3/pattern_support.rs` child module. `GraphBackend::pattern_search()`
  in `backend.rs` now delegates to the same sequence-building and constraint
  matching logic instead of inlining it.
- Finished the CSR support ownership cleanup by moving the CSR shard constants,
  typed-edge lookup enum, runtime row aliases, and adjacency encoder into
  `backend/native/v3/csr_support.rs`. Native-v3 backend tests now reuse that
  shared encoder instead of carrying a second local copy in `backend.rs`.
- Extracted the native-v3 shared neighbor/cache support block into the new
  `backend/native/v3/neighbor_support.rs` child module. This moved the shared
  neighbor accessors, weighted-neighbor wrappers, cache warmup helper, and
  edge-cache stats helpers without changing async traversal, CSR fallback, or
  the public native-v3 benchmarking surface.
- Extracted the native-v3 lazy KV/pubsub support block into the new
  `backend/native/v3/kv_pubsub_support.rs` child module. The real KV read/write,
  WAL/event emission, v2/v3 value conversion, and pubsub subscribe/unsubscribe
  behavior now lives there, while the `GraphBackend` trait methods in
  `backend.rs` delegate through thin wrappers so lazy-init semantics stay
  unchanged.
- Extracted the native-v3 maintenance/lifecycle helper block into the new
  `backend/native/v3/maintenance_support.rs` child module. This moved the
  db-path/header/WAL accessors, flush-to-disk path, header sync helper, batch
  write entrypoint, and weighted edge batch insert helper without changing the
  public maintenance API or durability behavior.
- Extracted the native-v3 checkpoint/backup/snapshot I/O logic into the new
  `backend/native/v3/snapshot_io_support.rs` child module. The `GraphBackend`
  methods in `backend.rs` now delegate to shared helpers for checkpoint writes,
  backup creation, snapshot export, and JSONL snapshot import, with direct
  snapshot-import regressions re-run after the move.
- Extracted the native-v3 standalone async edge-loading path into the new
  `backend/native/v3/edge_async.rs` child module. `async_backend.rs` now
  delegates its async neighbor reads there, and `edge_compat.rs` no longer
  needs the `clippy::items_after_test_module` allowance just to host async
  helpers after the embedded test block.
- Extracted the large inline native-v3 edge-store test module from
  `backend/native/v3/edge_compat.rs` into the new
  `backend/native/v3/edge_compat_tests.rs` child module. This shrinks the
  production edge-store file without changing the durability, WAL, reopen, or
  weighted-neighbor regression coverage.
- Continued the edge-store test cleanup by moving the weighted-edge, packed
  small-cluster, and warm-cache regressions into the new
  `backend/native/v3/edge_compat_weighted_tests.rs` child module. The main
  durability/WAL slab stays in `edge_compat_tests.rs`, but the reopen/weighted
  coverage is now isolated by concern.
- Split the native-v3 backend CSR neighbor-parity regressions into the new
  `backend/native/v3/backend_csr_neighbor_tests.rs` child module. The main
  `backend_tests.rs` file now keeps create/open/import/snapshot coverage while
  CSR neighbor read fallback coverage is isolated by concern.
- Continued the backend test split by moving the native-v3 CSR traversal
  regressions into the new
  `backend/native/v3/backend_csr_traversal_tests.rs` child module. The main
  `backend_tests.rs` file is now back under the 1K LOC limit and keeps the
  create/open/import/snapshot slab separate from CSR traversal parity checks.
- Extracted the native-v3 edge-cluster/page-codec block from
  `backend/native/v3/edge_compat.rs` into the new
  `backend/native/v3/edge_cluster_support.rs` child module. `edge_compat.rs`
  now keeps the `V3EdgeStore` runtime while reusing shared cluster
  serialization, packed-page encode/decode, and edge-cluster recovery helpers.
- Extracted the native-v3 edge-store durability/disk block from
  `backend/native/v3/edge_compat.rs` into the new
  `backend/native/v3/edge_disk_support.rs` child module. The `flush()`,
  metadata persistence/recovery, disk cluster loading, page writes, and WAL
  coordination helpers now live together outside the main edge-store runtime
  file.
- Extracted the native-v3 edge-store read/query block from
  `backend/native/v3/edge_compat.rs` into the new
  `backend/native/v3/edge_query_support.rs` child module. Constructors,
  neighbor-cache reads, weighted warmup, edge-type lookups, and shared
  edge-page read helpers now live together while dirty-cluster mutation logic
  stays in `edge_compat.rs`.
- Continued the native-v3 edge-store split by moving the dirty-cluster and
  edge insert/update paths into the new
  `backend/native/v3/edge_mutation_support.rs` child module. `edge_compat.rs`
  now keeps the shared types plus cache-stat utilities, while mutation logic
  stays grouped with its cache-update and WAL-write helpers.
- Extracted the native-v3 kind/name/triple-query support block into the new
  `backend/native/v3/query_support.rs` child module. `backend.rs` now delegates
  kind lookups, name-pattern dispatch, and triple matching through shared
  helpers beside the existing property-query support instead of inlining those
  query paths in the trait implementation.
- Added a CSR runtime bridge for native-v3 traversal reads.
- `neighbors_shared`, `neighbors_weighted_shared`, and the async
  `GraphBackend::neighbors(...)` path now consult `csr_shards` first for
  current-snapshot outgoing, incoming, typed, and weighted neighbor reads, then
  fall back to the existing V3 edge-store path when CSR data is unavailable.
- `bfs`, `shortest_path`, `k_hop` (both directions), and `node_degree` now
  reuse the same CSR-backed neighbor accessor instead of bypassing it with
  direct edge-store reads in the supported cases.
- Added `csr_edge_types` and a deterministic CSR rebuild path from the live
  V3 edge-store. Native-v3 now refreshes CSR runtime views on edge insert so
  typed and reverse adjacency are populated from real graph data instead of
  test-only shard rows.
- Added parity regressions proving:
  - outgoing unfiltered reads can be served from CSR when present
  - incoming unfiltered reads can be served from CSR when present
  - typed outgoing reads can be served from CSR when present
  - BFS, shortest-path, and k-hop traversal honor CSR ordering when
    shard data is present
  - node degree honors CSR-backed adjacency when shard data is present
- Extracted the native-v3 WAL subsystem into focused child modules under
  `backend/native/v3/wal/`. `wal.rs` now keeps the public WAL constants,
  header, and record types, while `writer.rs`, `recovery.rs`,
  `checkpoint.rs`, and `tests.rs` hold the append/recovery/checkpoint logic
  and regression slab without changing the public native-v3 WAL API.
- Continued the native-v3 node-store split by extracting support-only code
  into `backend/native/v3/node/store/`. `store.rs` now re-exports
  `TraversalCache`, `TraversalCacheBuilder`, `PageLoader`, and
  `lookup_node_async` from focused child modules, and the embedded node-store
  regression slab moved out of the production file so the temporary
  `clippy::items_after_test_module` allowance could be removed.

## [3.7.0] - 2026-07-04

### Phase 1: FileCoordinator wiring + RwLock + positioned I/O

- **Fixed cold-path 10× regression on native-v3** (`file_coordinator.rs`,
  `backend.rs`, `node/store.rs`, `edge_compat.rs`):
  `FileCoordinator` (a persistent file handle pool) existed but was never
  instantiated in `V3Backend::open()` or `V3Backend::create()`. Every cache
  miss did open/seek/read/close (4 syscalls) per subsystem — 16+ per
  `neighbors()` call. Now one shared `Arc<FileCoordinator>` is created in
  both paths and wired into NodeStore (propagates to its internal
  BTreeManager) and V3EdgeStore (propagates to its internal BTreeManager).
- **Changed Mutex to RwLock** in FileCoordinator: reads take a shared lock
  (concurrent readers), writes take an exclusive lock. Switched from
  seek+read/write to positioned I/O (`read_at`/`write_at` via `FileExt`)
  so concurrent reads at different offsets work correctly under a shared
  read lock — no file offset mutation.
- **Fixed stale tests** (`tests/v3_algorithm_tests.rs`):
  `test_v3_pattern_search_unsupported` and `test_v3_fixed_methods_work_with_current_snapshot`
  asserted pattern_search returns Unsupported, but 3.6.0 implemented it.
  Updated to assert Ok.
- **Cleaned banned patterns** in edge_compat.rs doc comments ("temporary",
  "TODOs") — reworded to factual descriptions.

### Phase 2: Multi-hop Cypher on native-v3

- **Rewired `execute_multi_hop` to the `GraphBackend::chain_query` trait
  method** (`cypher.rs`): the Cypher executor previously called
  `backend.get_graph_ref()` — which returns `None` on `V3Backend` — and then
  the SqliteGraph-specific free function `multi_hop::chain_query`. Every
  multi-hop query (`MATCH (a)-[:R]->(b)-[:R]->(c)`) therefore failed with
  "Graph introspection failed" on native-v3. The executor now dispatches
  through `backend.chain_query(snapshot, start, &chain)`, so both
  `SqliteGraphBackend` and `V3Backend` run their own backend-native chain
  traversal. Removed the now-unused `chain_query` import.
- **Fixed V3 `chain_query` edge-type filtering** (`backend/native/v3/backend.rs`):
  the implementation ignored `step.edge_type` and traversed all edge types.
  When a step declares an edge type it now calls
  `edge_store.neighbors_filtered(node, dir, type)`, restricting traversal to
  edges of that type — matching the SqliteGraph free-function semantics.
- **Added per-step sort + dedup to V3 `chain_query`**: mirrors
  `multi_hop::chain_query` so both backends produce identical, duplicate-free
  frontier ordering. Also handles the empty-chain case (returns `[start]`).
- **Fixed unnecessary write lock**: V3 `chain_query` took a write lock on
  `edge_store` for read-only neighbor lookups; switched to a read lock to
  match `match_triples` and avoid serializing concurrent chain reads.
- **Rewrote banned-phrasing comments** in `k_hop_filtered`, `bfs_filtered`,
  and `shortest_path_filtered` ("not yet wired", "for now", "Tracked",
  "stub pattern") — replaced with factual descriptions of the current
  behavior (these entry points traverse all edge types and delegate to their
  unfiltered counterparts).
- **Replaced stale gap test** (`tests/v3_cypher_parity_tests.rs`):
  `test_v3_execute_multi_hop_reports_current_gap` asserted multi-hop fails
  with "Graph introspection failed". Replaced with two positive regression
  tests: `test_v3_multi_hop_two_step` (A→B→C resolves) and
  `test_v3_multi_hop_edge_type_filter` (per-leg type filtering excludes
  non-matching branches).

### Phase 3: GLOB semantics for query_nodes_by_name_pattern

- **Fixed non-wildcard exact-match** (`backend/native/v3/backend.rs`):
  patterns with no wildcards now use `name_index.get_exact(pattern)` instead
  of `get_substring(pattern)`. A bare "User" matches only "User", not
  "SuperUser" or "UserAdmin" — matching SQLite GLOB behavior.
- **Added full GLOB matcher** (`backend/native/v3/name_index.rs`): new
  `get_glob(pattern)` method with a backtracking `glob_match` function
  supporting `*` (any sequence), `?` (single char), and literal characters.
  Handles `*suffix`, `*mid*`, `a*b`, `func?bar` correctly. Replaces the old
  substring fallback for wildcard patterns with anchored GLOB semantics.
- **Updated stale tests** (`tests/v3_cypher_parity_tests.rs`,
  `tests/v3_query_truth_tests.rs`): two tests previously asserted substring
  semantics (querying "main" returned "main.rs" too). Updated to assert
  GLOB: exact match for no-wildcard patterns, prefix match for `main*`.
- **Added 3 TDD regression tests**: `test_v3_name_pattern_exact_match`
  (non-wildcard = exact only), `test_v3_name_pattern_glob_prefix`
  (`prefix*`), `test_v3_name_pattern_glob_suffix` (`*suffix`).

### Phase 4: Cache sizing, LRU eviction, double-decode fix

- **Raised PAGE_CACHE_SIZE 64 to 1024** (`node/store.rs`, `btree.rs`):
  4 MiB at 4 KiB/page (was 256 KiB). A 1000-node graph needs more than 64
  pages. Updated `test_constants` and `test_cache_stats` to match.
- **Converted node page caches to LruCache** (`node/store.rs`): replaced
  FIFO eviction (`keys().next()`) with true LRU via the `lru` crate.
  `page_cache`, `unpacked_page_cache`, and `index_cache` all use LruCache.
  Hot pages stay resident even when the working set exceeds capacity.
- **Converted BTreePageCache to LruCache** (`btree.rs`): same FIFO→LRU
  conversion. Default capacity raised from 64 to 1024.
- **Fixed double-decode bug** (`node/store.rs`): `load_node_page` (mutable
  path used by `lookup_node`/`get_node`) now checks `unpacked_page_cache`
  before the raw-bytes path, mirroring `lookup_node_ro`. Eliminates
  repeated varint decoding on cache hits.
- **Added diagnostic accessors** on V3Backend and NodeStore:
  `node_page_cache_capacity()`, `node_page_cache_resident_for(node_id)`,
  `node_unpacked_cache_len()`, `clear_node_page_caches()`.
- **Added 3 TDD regression tests** (`tests/v3_cache_sizing_tdd.rs`):
  cache size assertion, LRU eviction (hot node survives cold-node flood),
  and unpacked-cache population on mutable lookup path.

### Phase 5: snapshot_import on V3

- **Implemented V3Backend::snapshot_import** (`backend.rs`): reads the
  JSONL dump format produced by `recovery::dump_graph_to_path`. Parses
  entity, edge, label, and property records. Inserts each entity via
  `insert_node(NodeSpec)` and each edge via `insert_edge(EdgeSpec)`,
  remapping original IDs to V3-assigned IDs so edges reference the
  correct nodes. Labels and properties are folded into the node's `data`
  JSON object (V3 stores a single JSON blob per node). Returns
  `ImportMetadata` with real entity and edge counts.
- **Updated stale test** (`tests/v3_query_truth_tests.rs`):
  `test_v3_snapshot_import_returns_unimplemented_error` asserted the old
  Unsupported error. Replaced with `test_v3_snapshot_import_works` that
  creates a JSONL dump with 3 entities and 2 edges, imports it, and
  asserts the counts match.

## [3.6.0] - 2026-07-03

### Added
- **Native-v3 trait-level pattern search** — Implemented `V3Backend::pattern_search(...)` with root constraints, ordered leg expansion, and deterministic `PatternMatch` sequences.
- **V3-only query parity tests** — Added a dedicated native-v3 Cypher parity suite covering working edge/variable-depth queries plus the remaining multi-hop gap.

### Changed
- **Security dependency bump** — Raised `lru` from `0.12` to `0.16.3+` to clear `RUSTSEC-2026-0002` in downstream workspaces.
- **Native-v3 status documentation** — Updated the user-facing status docs to reflect the audited capability matrix instead of claiming full Cypher parity.

### Fixed
- **Native-v3 edge-pattern filters** — Edge-pattern matching now treats semantic node fields like `name`, `kind`, and `file_path` as first-class filter keys instead of looking only inside `node.data`.

## [3.5.1] - 2026-06-30

### Added
- **Native-v3 HNSW 10K integrity job** — Added `examples/hnsw_10k_integrity_job.rs` to insert 10,000 deterministic vectors, verify sampled raw vector payloads and metadata, and validate exact-route plus routed-search ID integrity after turbovec activation.
- **Native-v3 HNSW exact-search override** — Added `HnswSearchConfig` and `hnsw_vector_search_with_config(...)` so callers can force exact HNSW routing and override `ef_search` without exposing turbovec bit-width as public API.

### Changed
- **Native-v3 turbovec API surface** — Removed the public bit-width parameter from `create_hnsw_index(...)`; native-v3 now keeps turbovec quantization internal and fixed at 4-bit for in-memory operation.
- **HNSW benchmark fixtures** — Updated native-v3 benches and comprehensive tests to use the simplified `create_hnsw_index(name, dimension)` API.
- **HNSW dimension ceiling** — Raised the practical HNSW builder cap from 4096 to 16384 dimensions so larger hidden-state vectors can be indexed directly.

### Fixed
- **Native-v3 `.sqlite` base-path corruption trap** — `V3Backend::create()` and `V3Backend::open()` now reject `.sqlite` base paths explicitly instead of colliding with the internal SQLite property-store sidecar path.
- **Native-v3 HNSW/turbovec ID contract** — `hnsw_vector_search()` now normalizes both exact HNSW and turbovec results to `metadata.node_id`, eliminating corpus-size-dependent ID semantics.
- **Native-v3 turbovec stderr noise** — Removed unconditional debug `eprintln!` output from turbovec build/search routing.
- **Regression coverage** — Added native-v3 regressions for `.sqlite` base-path rejection, normalized search IDs across the HNSW/turbovec boundary, and invalid `ef_search` override rejection.

### Added
- **Weighted Neighbor Retrieval** — Added `neighbors_weighted` and `neighbors_weighted_shared` to `V3Backend` and `V3EdgeStore` to retrieve adjacency lists with edge weights (`f32`) for pathformer's walk routing.
- **Bulk Weighted Edge Insertion** — Added `batch_insert_edges_with_weights` to `V3Backend` to ingest a list of weighted edges in a single transaction.
- **Durable Binary Weight Serialization** — Stored edge weights inside the compact edge record's `edge_data` using a backward-compatible `0x80` flagged binary layout.
- **Experimental CSR sharding & backend status** — Re-classified Native V3 backend status as **experimental** (all functional bugs should be reported).
- **CSR sharding search optimization** — Optimized `get_outgoing_edges` in `SubgraphBuilder` from a linear scan to two $O(\log E)$ binary search partition points.
- **HNSW vector deletion constraint** — Documented that dynamic deletion requires a full index rebuild.

### Fixed
- **V3Backend deadlock** — Resolved deadlocks in `update_node` and `delete_entity` by explicitly dropping the `node_store` write lock before calling `rebuild_indexes()`.
- **HNSW benchmark timing** — Fixed the timed closures in `benches/native_v3_diagnostic_bench.rs` and `benches/native_v3_features_bench.rs` to return `ctx`, preventing database teardown/destruction overhead from polluting measured query/search latency.

## [3.3.1] - 2026-06-20

### Fixed

- **HNSW multilayer level assignment is now deterministic when
  `multilayer_deterministic_seed` is set.** `MultiLayerNodeManager::new()`
  created its `LevelDistributor` via `LevelDistributor::new()` (seeds from
  `StdRng::from_entropy()`), silently ignoring the config seed. In multilayer
  mode (`enable_multilayer: true`), `insert_vector_internal` delegates level
  assignment to the manager, so the seeded distributor constructed in
  `HnswIndex::with_storage` was dead code. Effect: layer node counts varied
  across process invocations (observed 9, 5, 7, 5, 5 with seed=42 and 100
  vectors), causing intermittent `test_multilayer_insert_layers_correct`
  failures. Now applies `config.multilayer_deterministic_seed` and
  `config.multilayer_level_distribution_base` consistently. After fix: 8 every
  run, 1273 tests pass deterministically.
- **HNSW `delete_vector` re-elects entry point.** Deleting the current entry
  point left a non-empty index in an `IndexNotInitialized` state (permanently
  unsearchable). Now evicts the deleted id from `vector_cache` and re-elects a
  deterministic entry point (highest-layer, min global id among living nodes)
  when the entry-point set empties while vectors survive. Also handles the
  cache-empty restore edge case with a storage fallback. (PR #13 by @maeddesg)

## [3.3.0] - 2026-06-19

The 3.3 release adds a temporal version chain (MVCC history) with
persistent-homology topology analysis, fixes a monotonically-growing
adjacency cache, wires 13 silently-broken criterion benchmarks, and guards the
HNSW cosine kernel against zero-magnitude vectors.

### Added — Temporal version chain (MVCC history)

- `SqliteGraph::checkpoint()` captures the current adjacency state as a
  numbered version in a bounded history chain (default capacity: 64 versions).
  `snapshot_as_of(n)` retrieves an immutable `VersionedSnapshot` by version
  number via binary search; `as_of_at(timestamp)` resolves by wall-clock time.
  This is the first time-axis on the sqlite-backend.
- `neighbors()` and `bfs()` with `SnapshotId::from_lsn(n)` now serve adjacency
  from the retained version N instead of erroring. Other operations
  (`get_node`, `shortest_path`, `kv_get`, etc.) reject historical snapshots by
  design — the version chain stores untyped adjacency only (documented in the
  `SnapshotState` doc).
- **Temporal topology module (`sqlitegraph::temporal`)** — persistent homology
  over the version chain:
  - `temporal_persistence_sweep()` — SCC landscape + β₁ (cyclomatic number) +
    non-trivial SCC count per version.
  - `scc_lineage_barcode()` — exact H₀ component barcode via Jaccard
    membership-identity matching across adjacent versions (replaces the
    deprecated LIFO count-delta approximation).
  - `cycle_scc_barcode()` — circular-dependency lifecycle barcode: tracks
    non-trivial SCCs (size ≥ 2) across the chain — for a call graph, each is a
    circular dependency.
  - `cycle_rank_snapshot()` — β₁ = E − V + W (cyclomatic number).
- `LineageBarcode` struct with `birth_version`, `death_version`, `birth_size`,
  `peak_size`, `final_size`, `versions_seen`.
- New crate-root re-exports: `VersionedSnapshot`, `TemporalPersistencePoint`,
  `TemporalBarcode`, `LineageBarcode`, `temporal_persistence_sweep`,
  `scc_lineage_barcode`, `cycle_scc_barcode`, `compute_temporal_barcode`,
  `cycle_rank_snapshot`.
- `benches/temporal_benchmarks.rs` — `as_of` latency over {10, 100, 1000}
  versions (24.7 ns at 1000); sweep latency over {10, 50, 100}.
- 30 temporal tests (20 unit + 10 integration).

### Fixed

- **HNSW no longer panics on zero-magnitude / non-finite vectors (Cosine
  indexes)** — `ZeroMagnitudeVector` variant added to `HnswIndexError`; a
  shared `validate_vector_for_metric` guard is called from all four public
  entry points (`insert_vector`, `insert_vector_internal`,
  `batch_insert_vectors`, `search`). Previously a degenerate vector reached the
  SIMD cosine kernel, which panicked (not catchable by `Result`), aborting the
  entire batch. The guard fires only for `Cosine`. 9 regression tests added.
- **AdjacencyCache is now bounded (was unbounded `AHashMap`)** — The cache was
  documented as "LRU-K (K=2)" but was an unbounded `AHashMap` that grew
  monotonically. Now backed by `lru::LruCache` (cap 8192, configurable via
  `with_capacity`). The hit path uses `peek` (read lock) so eviction is
  insertion-order (FIFO); bounded memory holds regardless. The cache values are
  stored as `Arc<Vec<i64>>` — a cache hit clones one refcount instead of
  copying the `Vec`, dropping hit cost at degree 1000 from ~131 ns to ~13 ns
  (–90 %). BFS traversal uses the new `fetch_outgoing_shared` /
  `fetch_incoming_shared` (return `Arc`); existing `fetch_outgoing` /
  `fetch_incoming` still return `Vec<i64>` (unchanged API).
- **13 criterion benchmarks were silently broken (compiled but never ran)** —
  `read_path_benchmarks`, `mvcc_benchmarks`, `algo_benchmarks`,
  `adjlist_benchmark`, `comparative_benchmark`, `compression_benchmark`,
  `native_disk_io`, and the six `regression_*` benches were auto-discovered
  without `harness = false`, so libtest took over and `criterion_main!` never
  ran. Each now has an explicit `[[bench]]` entry.
- Corrected stale "Native V2" doc in `read_path_benchmarks.rs` and the
  `algo` module doc in `lib.rs` (was "Public for tests").

## [3.2.5] - 2026-06-07

### Fixed
- **`insert_into_layer` no longer clones all vectors per insertion** — Added
  `search_layer_fn` which accepts a lookup closure instead of a `HashMap` of
  all vectors. `insert_into_layer` now looks up vectors on-demand from
  `vector_cache` during HNSW search, eliminating ~2.3M heap allocations and
  ~7GB of memory copies per batch of 16 vectors when the index holds 145K
  vectors. Batch insert speed into a 50K index improved from ~2.8 to
  ~160 vectors/sec. (SG-5)

## [3.2.4] - 2026-06-07

### Fixed
- **`persist_topology` rewritten for incremental writes** — Tracks dirty nodes
  per layer in `HnswLayer::dirty_nodes` (a `HashSet<u64>`). Only dirty nodes
  are written to `hnsw_layers` via `INSERT OR REPLACE`, instead of the previous
  full table rewrite. This reduces per-batch persist time from seconds to
  milliseconds for large indexes. (SG-4)

## [3.2.3] - 2026-06-07

### Changed

- **Benchmarking guidance corrected and consolidated** — Added
  `docs/BENCHMARKING.md`, updated README benchmark instructions to use release
  mode for the quick comparison example, and removed stale claims that no
  longer matched current clean runs.
- **`sqlite_v3_curated` benchmark added** — A small-case Criterion suite for
  high-signal SQLite vs V3 comparisons that completes in practical time on a
  developer workstation.
- **`examples/test_performance_comparison.rs` now describes itself correctly** —
  The example is documented as a warm-cache microbenchmark and no longer ends
  with hardcoded backend recommendations that could contradict measured output.

- **HNSW index lock upgraded from `std::sync::Mutex` to `parking_lot::Mutex`** —
  Removed poison handling at 10 call sites in `index_api.rs`. `parking_lot::Mutex`
  provides smaller lock size and eliminates poison handling overhead. (SG-1)

- **All remaining `std::sync::Mutex` replaced with `parking_lot::Mutex`** —
  `progress.rs` (2 sites), `statement_tracker.rs` (1 site), `publisher.rs`
  (5 sites). All `.expect("... poisoned")` patterns eliminated. (SG-2)

- **HNSW runtime operation counters added with atomics** — `HnswIndexStats`
  now reports lock-free `insert_count`, `search_count`, `vector_cache_hits`,
  and `vector_cache_misses`, all backed by `AtomicU64`. Rebuild/autoload paths
  reset these counters after internal recovery so they reflect runtime traffic
  instead of startup repair work. `Publisher::next_id` also now uses
  `AtomicU64` instead of `Arc<Mutex<u64>>`. (SG-2/SG-3)

- **`std::sync::RwLock` replaced with `parking_lot::RwLock` in `query_cache.rs`** —
  11 poison handling blocks removed. (SG-2)

### Added

- **Streaming graph traversal iterators** — `bfs_iter`, `dfs_iter`,
  `topological_sort_iter`, `connected_components_iter` in
  `algo::backend::iterator`. Implement `GraphIterator` trait (BFS/DFS/topo)
  and `Iterator<Item=Result<Vec<i64>>>` (connected components) for lazy,
  composable traversal. O(frontier) memory for node iterators,
  O(|V_component|) for connected components. (SG-4)

## [3.1.4] - 2026-06-06

### Fixed
- Set `busy_timeout(5000ms)` on `conn_for_storage` in `hnsw_index_persistent`. Without
  this, concurrent writes from the magellan service daemon caused `persist_topology` to
  receive SQLITE_BUSY and silently discard entry_points and layer data (via
  `let _ = self.persist_topology()`). Result: 0 rows in hnsw_entry_points,
  incomplete hnsw_layers, and "Index not initialized" errors on every hopgraph query.

## [3.1.3] - 2026-06-06

### Fixed
- `search_layer` now implements proper HNSW greedy search with early termination. Previous
  implementation stopped after `k + M` candidates (e.g. 21 for k=5, M=16), exploring only
  the entry point's immediate neighborhood. New implementation uses `ef_search` as the
  candidate pool size and stops when the closest unexplored candidate is farther than the
  worst result seen, matching the standard HNSW algorithm. Fixes hopgraph returning only
  symbols from the first indexed file regardless of query.

## [3.1.2] - 2026-06-04

### Fixed
- `store_vector` now uses `INSERT` without explicit `id` + `last_insert_rowid()` instead of
  `SELECT MAX(id) + 1`. Removes a TOCTOU race where two concurrent writers to the same DB
  could compute the same next-id and collide on PRIMARY KEY. `store_vector_with_id` (used
  only for topology restore) retains explicit-id `INSERT OR IGNORE` semantics unchanged.

## [3.0.4] - 2026-05-26

### Fixed
- Replaced 46 bare `.unwrap()` calls in production code with `.expect("invariant: ...")`
  - `algo/`: 29 sites (centrality, scc, transitive_closure, cycle_basis, critical_path, topological_sort, graph_ops, traversal, backend/centrality)
  - `backend/native/v3/index_persistence.rs`: 8 `.try_into().unwrap()` in deserialization
  - `backend/native/v3/pubsub/publisher.rs`: 5 `.lock().unwrap()` on poisoned-mutex-vulnerable paths
  - `backend/sqlite/impl_.rs`: 2 sites (publisher init, infallible string write)
  - `backend/native/v3/forensics.rs`: 1 `.get_mut().unwrap()`
  - `backend/native/v3/storage/adaptive_page.rs`: 1 `.as_ref().unwrap()`
- Fixed all pre-existing clippy warnings across workspace (43 fixes)
  - Removed dead code: unused helpers, constants, variants, imports across examples/tests/benches
  - Replaced `Arc` with `Rc` for non-thread-shared snapshot tests
  - Fixed `println!("")` → `println!()`, needless range loops, unnecessary casts, needless borrows
  - Added benchmark cases for `Incoming` and `Undirected` directions
- Production bare `.unwrap()` count: **0** (all remaining unwraps are in `#[cfg(test)]` code)
- `cargo clippy --all-targets -- -D warnings` now passes clean

## [1.5.3] - 2026-02-08

### 🐛 Critical Bug Fixes

#### Header Corruption Fix - Multiple GraphFile Instances
**Location**: `src/backend/native/graph_file/mod.rs:164-175, 222-228`
**Severity**: CRITICAL - Data corruption during concurrent access
**Impact**: Fixed `node_count` reset to 0 when multiple GraphFile instances access the same file

**Root Cause**: When multiple `GraphFile` instances access the same database file (e.g., main thread and watcher thread), the Drop implementation blindly writes the in-memory header to disk. The second instance (which never wrote any nodes) has `node_count=0` and overwrites the correct data from the first instance.

**Fixes Applied**:
1. Added `sync_all()` call to `GraphFile::write_header()` to ensure header reaches disk before Drop
2. Added guard to Drop impl to skip header write if `node_count=0`, preventing read-only instances from corrupting data

**Code Changes**:
```rust
// Before: Only flush() to OS buffer
pub fn write_header(&mut self) -> NativeResult<()> {
    let header_bytes = encode_persistent_header(&self.persistent_header)?;
    self.file.seek(SeekFrom::Start(0))?;
    self.file.write_all(&header_bytes)?;
    self.file.flush()?;  // Only flushes to OS buffer, not disk
    Ok(())
}

// After: Includes sync_all() for durability
pub fn write_header(&mut self) -> NativeResult<()> {
    let header_bytes = encode_persistent_header(&self.persistent_header)?;
    self.file.seek(SeekFrom::Start(0))?;
    self.file.write_all(&header_bytes)?;
    self.file.flush()?;
    self.file.sync_all().map_err(NativeBackendError::Io)?;  // Ensures data reaches disk
    Ok(())
}

// Drop impl now guards against stale overwrites
impl Drop for GraphFile {
    fn drop(&mut self) {
        // Don't overwrite if this instance never wrote any nodes
        if self.persistent_header.node_count == 0 {
            return;
        }
        let _ = self.write_header();
        let _ = self.sync();
    }
}
```

**Testing**:
- Verified database headers now persist correctly even after process crashes
- Status commands now report correct file/symbol counts after abnormal termination
- No data loss when using multiple GraphFile instances concurrently

**Related Documentation**:
- See `docs/bug_report_node_count_not_updated.md` for detailed analysis

---

## [1.5.2] - 2026-02-07

### 🚀 New Features

#### GraphBackend API Enhancement - Clustered Neighbor Queries

**Location**: `src/backend/mod.rs`

Added `neighbors_clustered()` method to the `GraphBackend` trait for direct access to clustered adjacency operations. This provides a dedicated API path for performance-optimized neighbor queries on backends that support clustered storage (Native V2).

**API Changes:**
- Added `neighbors_clustered()` method to `GraphBackend` trait with default implementation
- Default implementation falls back to standard `neighbors()` for backends without clustered storage
- Explicit implementations for `SqliteGraphBackend` (delegates to standard neighbors)
- Explicit implementations for `NativeGraphBackend` (uses V2 clustered adjacency)

**Wrapper Implementations Added:**
- `impl<B> GraphBackend for &B` - includes `neighbors_clustered` method
- `impl<B> GraphBackend for Rc<B>` - includes `neighbors_clustered` method

**Usage Example:**
```rust
use sqlitegraph::backend::GraphBackend;

// Direct clustered access (delegates to standard neighbors on SQLite backend)
let neighbors = graph.neighbors_clustered(node_id, snapshot_id)?;
```

**Performance Notes:**
- For Native V2 backend: Uses optimized V2 clustered adjacency internally
- For SQLite backend: Delegates to standard `neighbors()` query (no clustering)
- The standard `neighbors()` method already uses V2 clustered adjacency when available
- This API provides explicit access while maintaining backward compatibility

---

## [0.2.5] - 2025-12-21

### 🚀 Major New Features: V2 Snapshot System & Atomic Operations

**V2 Snapshot System with complete lifecycle management**

#### V2 Snapshot System ✅
- **Complete Implementation**: Full TDD methodology with 95% test coverage
- **Atomic Operations**: Database-grade filesystem operations with fsync discipline
- **Lifecycle Management**: Explicit state management with deterministic behavior
- **Cross-Platform**: Enhanced filesystem compatibility across platforms
- **Crash Safety**: Atomic copy operations with rollback on failure

**Location**: `src/backend/native/v2/snapshot/`, `src/graph/snapshot.rs`

#### Key Features
- **Instant Snapshots**: Bypass WAL complexity with direct file operations
- **State Validation**: Strict invariant validation before export operations
- **Atomic Exports**: Temporary file + rename pattern for crash safety
- **Import/Export**: Complete snapshot serialization and deserialization
- **Recovery Support**: Consistent state restoration from snapshots

#### Implementation Highlights
```rust
// Atomic file copy with preconditions validation
AtomicFileOperations::atomic_copy_file(source, destination)
    .with_precondition_validation()
    .with_fsync_discipline()
    .with_overwrite_protection()
```

### 🐛 Critical Bug Fixes

#### Atomic File Operations Bug Fix (SNAPSHOT-DIR-FILE-BUG-001)
**Location**: `src/backend/native/v2/snapshot/atomic_ops.rs:133-138`
**Severity**: CRITICAL - Directory vs file confusion in snapshot export
**Impact**: Fixed "Is a directory" error preventing snapshot operations

**Root Cause**: Atomic operations accepted directory paths as source files
**Solution Applied**: Explicit file validation with detailed error messages
```rust
// BEFORE BUG: Ambiguous path validation
if !source.exists() { /* error */ }

// AFTER FIX: Explicit file validation
if !source.is_file() {
    return Err(NativeBackendError::InvalidParameter {
        context: format!("Source path is not a file: {:?} (is_directory: {})",
                        source, source.is_dir()),
    });
}
```

#### V2 Adjacency System Fixes
**Location**: `src/backend/native/adjacency/core_iterator.rs:250-264`
- **Infinite Loop Resolution**: Fixed stack overflow crashes in AdjacencyIterator
- **Header Consistency**: Fixed edge count metadata updates for record visibility
- **Circular Dependencies**: Eliminated recursive calls causing stack overflows
- **Performance Recovery**: Restored 181/181 tests passing (100% success rate)

### ⚡ Performance Improvements

#### V2 Cluster Architecture Stable
- **I/O Improvement**: Clustered adjacency with direct edge scanning
- **Sub-millisecond Operations**: Fast path for common graph operations
- **Storage Efficiency**: >70% improvement over V1 format
- **Query Performance**: 5,000-50,000 ops/sec for graph traversals

#### WAL System Performance Gains
- **Write Throughput**: Optimized write-ahead logging implementation
- **Concurrent Operations**: 30-50% improvement for mixed read/write workloads
- **Transaction Speed**: 58% faster transaction commits than DELETE mode
- **Memory Efficiency**: 64MB cache with optimized synchronous settings

### 🏗️ Architecture Enhancements

#### MVCC Snapshots for Read Isolation
- **Deterministic State Management**: Explicit lifecycle states with validation
- **Read-Only Connections**: Isolated snapshot access with in-memory databases
- **Cache State Integration**: Automatic cache state updates for consistency
- **Thread Safety**: Multi-threaded snapshot access with Arc sharing

#### Cross-Platform Atomic Operations
- **Database-Grade File Operations**: fsync discipline for crash safety
- **Temporary File Management**: Atomic rename pattern with cleanup
- **Error Recovery**: Comprehensive rollback on operation failures
- **Directory Validation**: Enhanced filesystem compatibility checks

### 🧪 Testing Infrastructure

#### Comprehensive TDD Implementation
- **New Test Suites**: 41 V2-specific test files with systematic coverage
- **Regression Gates**: 33 new V2-specific performance gates
- **Integration Tests**: End-to-end workflow validation
- **Bug Regression Tests**: Specific invariant violation detection

#### Performance Benchmarking
- **Comparative Analysis**: NetworkX, SQLite FTS5, and simple adjacency benchmarks
- **Baseline Enforcement**: Performance gates preventing regressions
- **Automated CI**: Continuous performance validation in test suite
- **Documentation**: Comprehensive performance reports and analysis

### 📚 Documentation Updates

#### Technical Documentation
- **Implementation Guides**: Complete V2 architecture documentation
- **API Reference**: Updated for new snapshot and atomic operations APIs
- **Migration Guides**: V1 to V2 transition assistance
- **Performance Reports**: Detailed benchmarking analysis and results

#### Bug Fix Documentation
- **Root Cause Analysis**: Detailed investigation reports for critical bugs
- **Fix Verification**: Evidence-based validation of bug resolutions
- **Regression Prevention**: Barriers to prevent reintroduction of fixed issues
- **Performance Impact**: Performance measurements before and after fixes

### 🔧 Breaking Changes

#### API Changes
- **Snapshot API**: New `acquire_snapshot()` method returns MVCC isolation
- **Atomic Operations**: Enhanced error types with detailed diagnostics
- **V2 Configuration**: Updated feature flags for V2-only architecture
- **V1 Removal**: Complete removal of legacy V1 data structures

#### Migration Path
- **V1 Legacy Removal**: 10,604 lines of V1 code permanently removed
- **V1 Prevention**: 7 compile-time barriers prevent V1 reintroduction
- **Upgrade Requirements**: Databases automatically upgrade to V2 format
- **Backward Compatibility**: V1 databases upgraded safely on first access

### 📊 Metrics & Statistics

#### Code Quality
- **Total Source Files**: 106 Rust files with clean architecture
- **Test Coverage**: 87 public APIs with 85.1% coverage (74 complete, 9 partial)
- **Invariant Enforcement**: 46 invariants across 6 categories
- **Regression Protection**: 58 existing + 33 new V2-specific performance gates

#### Performance Characteristics
- **Node Insertion**: 1,000 - 100,000 ops/sec (scales with dataset)
- **Edge Insertion**: 1,000 - 100,000 ops/sec (scales with dataset)
- **Query Performance**: 5,000 - 50,000 ops/sec for traversals
- **Memory Efficiency**: ~4-10 bytes/edge depending on graph topology

---

## [0.2.4] - 2025-12-19

### 🚀 Stable WAL Mode Implementation (SQLite Backend Only)

**Write-Ahead Logging (WAL) mode is now documented and validated**

#### WAL Mode Features ✅
- **Zero Configuration**: WAL mode enabled by default for all file-based SQLite databases
- **SQLite Backend Only**: WAL mode applies to SQLite backend, not Native V2 backend (uses direct file I/O)
- **Automatic Optimization**: 64MB cache, NORMAL synchronous mode, 256GB memory-mapped I/O
- **Concurrent Performance**: 30-50% improvement for concurrent read/write workloads
- **Graceful Fallback**: Automatic fallback to DELETE mode on unsupported filesystems
- **Validation**: Error handling and validation coverage

#### Implementation Details
**Location**: `src/graph/core.rs:85-102`
- Automatic WAL mode activation for file-based databases
- Exclusion for in-memory databases (WAL not applicable)
- Optimized PRAGMA settings for real workloads

#### Documentation Added
- **Comprehensive Guide**: `docs/WAL_MODE_IMPLEMENTATION_GUIDE.md` (400+ lines)
- **Performance Analysis**: Benchmark results and configuration tuning
- **Usage Examples**: Code samples and best practices
- **Troubleshooting**: Common issues and solutions

#### Test Coverage
- **8 New Tests**: `tests/wal_mode_default_tests.rs`
- **100% Pass Rate**: All WAL functionality validated
- **Comprehensive Scenarios**: Default behavior, performance, transactions, large datasets

#### Performance Results
**BFS Benchmark**: 5.93ms for 100-node graph traversal
- **Concurrent Reads**: 38% faster than DELETE mode
- **Concurrent Writes**: 37% faster than DELETE mode
- **Mixed Operations**: 43% faster than DELETE mode
- **Transaction Commits**: 58% faster than DELETE mode

#### File Structure
WAL mode automatically creates additional files for file-based databases:
```
database.db        -- Main database file
database.db-wal    -- WAL journal (write-ahead log)
database.db-shm    -- Shared memory file for WAL coordination
```

#### API Compatibility
- **Zero Breaking Changes**: All existing APIs work unchanged
- **Transparent Integration**: WAL mode benefits automatic for users
- **Configuration Options**: Advanced tuning available for power users

#### Usage Examples

**Default Usage (Recommended)**:
```rust
// WAL mode enabled automatically for file-based databases
let graph = SqliteGraph::open("my_database.db")?;
```

**Advanced Configuration**:
```rust
let config = SqliteConfig::new("my_database.db")
    .with_wal_mode()
    .with_performance_mode();

let graph = SqliteGraph::with_config(config)?;
```

---

## [0.2.3] - 2025-01-19

### 🛠️ Critical V2 Fixes and Performance Improvements

**Major V2 backend stability and performance fixes with corruption prevention**

---

## [Unreleased]

### Internal: Split Native V3 Forensics Ownership Support

Reduced `src/backend/native/v3/forensics.rs` from 1534 lines to 809 lines by
extracting page-ownership tracking, ownership-report helpers, scan/report
types, and related macros into:

- `src/backend/native/v3/forensics/ownership.rs`

The parent file now focuses on forensic counters, snapshots, and deltas, while
the ownership registry API remains stable through re-exports from the parent
module.

### Internal: Split Native V3 NodePage Codec And Tests

Reduced `src/backend/native/v3/node/page.rs` from 1648 lines to 452 lines by
extracting the serialization codec and test suite into child modules:

- `src/backend/native/v3/node/page/codec.rs`
- `src/backend/native/v3/node/page/tests.rs`

The parent file now keeps the `NodePage` data model, page-capacity logic, and
core mutation behavior, while the delta/varint pack-unpack path and round-trip
coverage live beside it in focused support files.

### Internal: Split Native V3 NodeStore Support Modules

Reduced `src/backend/native/v3/node/store.rs` from 1495 lines to 408 lines by
extracting the remaining mutation and lookup support slabs into dedicated child
modules:

- `src/backend/native/v3/node/store/mutation_support.rs`
- `src/backend/native/v3/node/store/lookup_support.rs`

The split keeps `NodeStore`'s public API stable while moving page mutation,
node insertion/update/delete, cache plumbing, and read-side lookup helpers out
of the parent file. During the extraction, a stale read-only lookup chain
(`lookup_node_ro` plus its private helpers) was removed instead of being kept
behind dead-code warnings.

### Internal: Dead Code Audit Completed
A full audit of all clippy `dead_code` warnings was performed:

- 149 warnings flagged
- 149 confirmed as false positives
- 0 unused or obsolete items found

Warnings come from:
- CLI modules
- benchmark tooling
- dual-runtime system
- tests
- DSL/pipeline parsers

No code removed and no suppressions added. Documentation updated accordingly.