2d01ba314c* 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
155 lines
5.6 KiB
Markdown
155 lines
5.6 KiB
Markdown
# YAMS-facing vector library surface map — 2026-06-02
|
|
|
|
Purpose: identify the subset of `third_party/simeon` and `third_party/sqlite-vec-cpp` that the **YAMS vector path** actually depends on, so cleanup can focus on interface alignment instead of preserving every library API.
|
|
|
|
## Scope
|
|
|
|
This map is intentionally limited to the vector-path audit:
|
|
|
|
- `include/yams/vector/*`
|
|
- `src/vector/*`
|
|
- `src/embedding_simeon/*`
|
|
- vector-specific tests/benchmarks
|
|
|
|
Note: `simeon` has broader use in YAMS search (`src/search/simeon_lexical_backend.cpp`, `include/yams/search/simeon_lexical_backend.h`, `src/topology/topology_input_extractor.cpp`, `src/daemon/components/post_ingest_enrichment.cpp`). Those are real consumers, but they are outside the narrow vector-interface alignment work.
|
|
|
|
## 1. simeon usage from the YAMS vector path
|
|
|
|
### Direct headers used
|
|
|
|
- `simeon/simeon.hpp`
|
|
- from `src/embedding_simeon/simeon_embedding_backend.cpp`
|
|
- `simeon/pq.hpp`
|
|
- from `src/vector/sqlite_vec_backend.cpp`
|
|
- from `src/vector/simeon_pq_persistence.h`
|
|
|
|
### Actual symbols used by YAMS vector code
|
|
|
|
#### Embedding backend glue (`src/embedding_simeon/simeon_embedding_backend.cpp`)
|
|
Used surface:
|
|
- `simeon::NGramMode`
|
|
- `simeon::ProjectionMode`
|
|
- `simeon::EncoderConfig`
|
|
- `simeon::Encoder`
|
|
- `simeon::active_simd_tier()`
|
|
- `simeon::simd_tier_name()`
|
|
|
|
Observed pattern:
|
|
- YAMS uses simeon here as a configurable in-process text encoder.
|
|
- YAMS does **not** use the broader retrieval, BM25, concept-mining, or fragment-geometry surface in this vector adapter.
|
|
|
|
#### PQ-backed vector search (`src/vector/sqlite_vec_backend.cpp`, `src/vector/simeon_pq_persistence.h`)
|
|
Used surface:
|
|
- `simeon::PQConfig`
|
|
- `simeon::ProductQuantizer`
|
|
- `simeon::PQQuery`
|
|
- `ProductQuantizer::m()`
|
|
- `ProductQuantizer::k()`
|
|
- `ProductQuantizer::dim()`
|
|
- `ProductQuantizer::is_trained()`
|
|
- `ProductQuantizer::codebooks()`
|
|
- `ProductQuantizer::import_codebooks(...)`
|
|
- `ProductQuantizer::train(...)`
|
|
- `ProductQuantizer::encode_batch(...)`
|
|
- `PQQuery::inner_product(...)`
|
|
|
|
Observed pattern:
|
|
- YAMS only needs the **PQ/ADC compression and scoring surface** here.
|
|
- This suggests a stable YAMS-facing sub-surface could be defined around:
|
|
- encoder
|
|
- PQ train/import/export/encode
|
|
- PQ query scoring
|
|
- Everything else in simeon is extra from the vector audit point of view.
|
|
|
|
### Trimming implication for simeon
|
|
|
|
For vector-path cleanup, YAMS could conceptually depend on a much narrower subset:
|
|
- `encoder` module
|
|
- `pq` module
|
|
- SIMD tier reporting
|
|
|
|
That means future cleanup should avoid coupling YAMS vector code to unrelated simeon research/retrieval APIs.
|
|
|
|
## 2. sqlite-vec-cpp usage from the YAMS vector path
|
|
|
|
### Direct headers used
|
|
|
|
- `sqlite-vec-cpp/sqlite/registration.hpp`
|
|
- `sqlite-vec-cpp/distances/l2.hpp`
|
|
- `sqlite-vec-cpp/distances/cosine.hpp`
|
|
- `sqlite-vec-cpp/distances/inner_product.hpp`
|
|
- `sqlite-vec-cpp/index/hnsw_persistence.hpp` (migration compatibility only)
|
|
|
|
### Actual symbols used by YAMS vector code
|
|
|
|
#### sqlite function/module registration (`src/vector/sqlite_vec_backend.cpp`)
|
|
Used surface:
|
|
- `sqlite_vec_cpp::sqlite::register_all_functions(db_)`
|
|
|
|
Observed pattern:
|
|
- YAMS currently registers the **entire sqlite-vec-cpp SQL surface**.
|
|
- But for the vector backend, the real need is narrower:
|
|
- `vec0` virtual table module
|
|
- required distance/vector helper functions used by YAMS SQL paths and migration/tests
|
|
|
|
This is the clearest opportunity for surface reduction.
|
|
|
|
#### Distance kernels (`src/vector/sqlite_vec_backend.cpp`)
|
|
Used surface:
|
|
- `sqlite_vec_cpp::distances::l2_distance(...)`
|
|
- `sqlite_vec_cpp::distances::cosine_distance(...)`
|
|
- `sqlite_vec_cpp::distances::inner_product(...)`
|
|
|
|
Observed pattern:
|
|
- YAMS uses the distance kernels as plain C++ helpers, independent of the wider SQL API.
|
|
|
|
#### HNSW persistence compatibility (`src/vector/vector_schema_migration.cpp`)
|
|
Used surface:
|
|
- `sqlite_vec_cpp::index::create_hnsw_shadow_tables(...)`
|
|
|
|
Observed pattern:
|
|
- This is legacy migration residue, not an active data-plane dependency.
|
|
- It should be treated as compatibility code, and likely removed or isolated once HNSW migration support is cleaned up.
|
|
|
|
### Trimming implication for sqlite-vec-cpp
|
|
|
|
For the YAMS vector path, the practical dependency is:
|
|
- vec0 module registration
|
|
- a few distance kernels
|
|
- temporary migration compatibility shim
|
|
|
|
YAMS does **not** need to preserve the full sqlite-vec-cpp public interface in order to improve its own vector architecture.
|
|
|
|
## 3. Alignment recommendations
|
|
|
|
### Best near-term alignment target
|
|
|
|
Define and document a **YAMS-supported library subset**:
|
|
|
|
#### simeon subset for vectors
|
|
- Encoder config + encoder runtime
|
|
- PQ train/import/export/encode/query
|
|
- SIMD tier reporting
|
|
|
|
#### sqlite-vec-cpp subset for vectors
|
|
- vec0 registration
|
|
- exact distance helpers used in backend code/tests
|
|
- migration-only compatibility helper(s), ideally isolated
|
|
|
|
### Concrete cleanup directions
|
|
|
|
1. Add a YAMS-local wrapper around sqlite-vec registration
|
|
- replace direct `register_all_functions()` dependency with a narrower wrapper
|
|
2. Isolate migration-only HNSW compatibility from the steady-state vector path
|
|
3. Keep YAMS vector code from reaching into non-vector simeon features
|
|
4. Split “owned library cleanup” from “YAMS integration contract” in future tasks
|
|
|
|
## 4. What this means for the audit
|
|
|
|
The vector audit should optimize for:
|
|
- stable YAMS-facing configuration defaults
|
|
- clean YAMS adapter contracts
|
|
- strong tests around the subset YAMS actually uses
|
|
- perf validation on YAMS-used paths
|
|
|
|
It should **not** require preserving or re-auditing every unused public API in either owned third-party library.
|