Trevon 2d01ba314c

Assertion hardening, metadata correctness, & daemon lifecycle fixes (#41 )

* fix(core): add assertions and harden daemon lifecycle

* fix(daemon): tighten shutdown lifecycle invariants

* fix(test): add PressureLimitedPoller capability-sleep shutdown test

* refactor(vector): harden backend contracts

Split the vector backend surface into narrower contracts and
move entity read paths to Result<> so callers can distinguish
backend errors from empty results.

Also fixes the TurboQuant lazy-init race, makes VectorDatabase
error state thread-safe, wires eager index preparation, and
adds regression plus memory-scaling benchmark coverage.

* fix(vector): address audit findings plus hardening

Fix the five confirmed bugs: coroutine lifetime hazard in
embedding_generator (await_with_timeout outliving captured state),
VectorSystemManager init retry latch poisoning, incremental HNSW
persistence race, vec0 registry key collisions, and simeon PMI
output_dim/config() drift.

Add invariant hardening: PostIngestQueue stage validation +
numChunks assertion, VectorSystemManager success postcondition,
VectorDatabase TurboQuant non-null assertions on all quantize/
dequantize paths, and sqlite_vec_backend Simeon PQ range and
divisibility preconditions.

Also adds regression coverage for init-retry and lock-busy paths
and a locked node snapshot helper for safe incremental HNSW
persistence.

* fix(test): add PressureLimitedPoller wake-timer shutdown tests

* chore(vector): resolve clang-tidy hygiene across queue, vdb, and sqlite-vec

Replace unprotected std::getenv calls with locked getenvCopy helpers,
add debug-level logging to previously-silent catch blocks in
PostIngestQueue, VectorDatabase, and SqliteVecBackend, wrap
PostIngestQueue timer-detach allocations in try-catch, and fix
unsigned-widening / optional-deref / unused-include hygiene.

Verified with LSP diagnostics and rebuilds of catch2_vector_submodule
and catch2_daemon_component_submodule.

* fix(daemon): harden PressureLimitedPoller inFlightCounter null check

* fix(daemon): harden PostIngestQueue wait_until deadline checks

* fix(daemon): clean up recovery sentinels regardless of salvage count

Previously the .recovered-* sentinel and .corrupt-* file cleanup
was gated on documentsSalvaged > 0, leaving quarantine
artifacts to accumulate on repeated crash/recovery cycles where
the corrupt DB had 0 salvageable docs.

Move cleanup outside the salvage-count guard so stale
quarantine artifacts are always removed after examination.

* feat(vec0): restore persisted ANN index on daemon restart

After vec0 rebuild, probe for vectors_<dim>_hnsw_meta shadow tables
and load a previously-persisted HNSW index.  When found, the ANN
index is set directly on the vec0 table, skipping the O(n log n)
rebuild that was previously paid on every daemon restart.

Removes the stub restoreVec0AnnIndexIfPresentUnlocked() in favor
of inline restoration in rebuildVec0DimUnlocked(), which has
the vec0 table already created and ready for ann_index assignment.

* fix: enable DCHECK by default and assert metadata counter consistency

* fix(services): assert document deletion ordering content-before-metadata

* fix(test): add fork-based assertion validation tests

* fix(test): expand assertion tests for POSTCONDITION, DCHECK, UNREACHABLE

* fix(ci): enable -Denable-dcheck=true in all test CI lanes

* fix(test): address assertion review findings

* refactor(daemon): isolate poller config assertion checks

* refactor(services): reduce deletion and poller complexity

* style(ci): normalize test workflow spacing

* refactor(services): extract list query helpers

* refactor(services): extract list hydration helpers

* refactor(daemon): extract metrics snapshot helpers

* refactor(daemon): extract metrics counter snapshot

* refactor(daemon): extract metrics resource snapshot

* feat(graph): add daemon-backed explore

Wire graph explore through daemon IPC, keep CLI rendering stable,
and fall back locally when daemon transport or protocol skew fails.

Also add graph context service/tests, improve graph follow-up hints,
and keep release builds working with the current JSON library.

* fix(services): prevent prune delete metadata orphans

* fix(cli): honor data-dir in graph explore

- bypass daemon explore when the CLI pins a data dir so\n  temp fixtures do not resolve against a long-lived global DB\n- guard snippet truncation and ratio math to remove Fold-\n  reported underflow and div-by-zero paths\n- clamp zero-based symbol lines before rendering graph\n  context

* fix(daemon): make lifecycle stop completion safe

* fix(daemon): gate db-open startup against shutdown

* fix(metadata): serialize FTS indexed counter updates

* test(daemon): simulate vector lock contention cross-process

* test(daemon): isolate post-ingest identity batch

* style(daemon): normalize test include order

* refactor(graph): split cli graph helpers

Keep graph command paths smaller and easier to evolve.

Lock graph explore/topology contracts into focused presenter,
dispatcher, and support tests so follow-up refactors keep the
current IPC and hot-path behavior intact.

* fix(config): harden expand_tilde and fix Windows XDG state path doubling

- expand_tilde: handle bare ~ and ~/ explicitly to avoid std::out_of_range
  on substr(2) for single-char input
- getXDGStateHome: on Windows, go up two levels from %LOCALAPPDATA%\yams\state
  to %LOCALAPPDATA% so callers' xdg/yams append doesn't double the yams segment

* fix(static-analysis): add logging to empty catch blocks and fix nosemgrep syntax

* fix(static-analysis): strip trailing text from nosemgrep comments

* fix(doctor): add logging to daemon_check empty catch blocks

* fix(db_repair): add logging to empty catch blocks

* fix(chunking): add precondition checks for rabin polynomial and windowSize

* fix(safety): add null precondition checks for Fold proved null-deref sites

* fix(daemon): widen init-failure dispatch, add null/dbz preconditions

InitializationFailedEvent races with shutdown — async init
fails after teardown begins. Widen canDispatch to accept
Ready/ShuttingDown. Add static_assert on SnapshotRing N>0.
Add YAMS_PRECONDITION null guards on hex/stages/data/bytes.

* ci(ubsan): use restricted build targets to avoid runner timeout

* fix(daemon): detach wake timers on Windows stop path to prevent SIGSEGV

* fix(config): cast parseTomlU32 to size_t for batch fields

* fix(ci): use static helper for Windows timer leak, restrict ubsan tests

2026-06-04 12:53:42 -04:00

3.6 KiB

Raw Permalink Blame History

Vector hotspot profiling — 2026-06-02

Platform: Apple Silicon (macOS) Tools: sample (CLI profiler), xctrace record (Time Profiler) Build: build/debug (asan + coverage)

Hotspots

1. vec0 first-query ANN index build (CRITICAL)

Benchmark: vector_backend_engine_compare --corpus=500 --dim=128 Tool: sample (8s, 1ms interval)

Call stack:

main
  runEngine (vec0_l2 path)
    SqliteVecBackend::searchSimilar          [104bf4900]
      Impl::searchSimilar                    [104bf520c]
        vec0SearchUnlocked                   [104de44a4]
          sqlite3_step → sqlite3VdbeExec
            vec0Filter
              vec0_run_ann_query
                vec0_ensure_ann_index        ← 99.2% of samples
                  HNSWIndex::insert_single_threaded
                    connect_neighbors_unlocked
                      prune_connections_unlocked
                        comparable_distance_nodes
                          compute_comparable_distance
                            l2_squared_distance (NEON SIMD)  ← inner loop

Observations:

4,087 out of 4,121 CPU samples (99.2%) in HNSW index construction
The SIMD l2_squared_distance_float_neon kernel is the inner hot loop (~1,953 samples)
All sample time is spent building the index; no queries are executed during the profile window
vec0 search latency is hidden behind index-build wall time

Recommendation: In production, prepareSearchIndex() or buildIndex() must be called before any query hits the vec0 backend. This cost is already handled in the existing API — the benchmark was profiling a cold-first-query scenario.

2. Simeon encoder projection comparison

Benchmark: simeon_microbench 50 512 Tool: sample (4s)

Projection	Sketch→Output	us/doc	docs/sec	vs default
AchlioptasSparse	4096→384	6,237	160	1.00× (current default)
AchlioptasSparse	4096→256	3,544	282	1.76×
VerySparse	4096→384	360	2,776	17.33×
VerySparse	4096→256	483	2,068	12.9×
DenseGaussian	4096→384	5,100	196	1.22×
DenseGaussian	4096→256	4,321	231	1.44×

Observations:

VerySparse is ~17× faster than AchlioptasSparse at 4096→384
DenseGaussian is marginally faster than AchlioptasSparse at 4096→384
FWHT (YAMS default via ConfigResolver) is not in the currently built microbench binary — needs rebuild for direct comparison

Recommendation: Rebuild simeon_microbench with FWHT rows to compare directly against VerySparse. The FJLT literature (Ailon-Chazelle 2009, Fandina et al. 2023) suggests FWHT should be comparable or faster than VerySparse for wide sketches. Verify before changing defaults.

3. Simeon encoder CPU profile (asan build)

The asan build doesn't resolve symbols well — most frames appear as offset+address. The measurable throughput from JSONL output (above) is more informative than the sample callgraph for this build.

Commands used

# vec0 search profiling
build/debug/tests/benchmarks/vector_backend_engine_compare --corpus=500 --queries=30 --dim=128 --k=10 &
sample $PID 8 -file /tmp/vector-search-sample.txt

# simeon encoder profiling
third_party/simeon/build-asan/benchmarks/simeon_microbench 50 512 &
sample $PID 4 -file /tmp/simeon-encoder-sample.txt

Next steps

Build release variant of benchmarks for accurate CPU profiles
Add FWHT rows to simeon microbench for direct comparison
Profile daemon startup + repair path (requires daemon harness)
Profile with xctrace record --template "Time Profiler" on release builds for Instruments-compatible traces

3.6 KiB Raw Permalink Blame History Unescape Escape