Class EmbedDb

Create a lazy embedding-index handle after validating all runtime options.

Acquire an additional shared semantic-family lifetime in the already pinned scopes. A prepared in-memory HNSW context owns this after its short-lived SQLite snapshot handle closes.

Audit one content kind without mutating the index.

A declared file is complete only when its actual rows have the declared count and occupy the contiguous chunk-index range 0..n_chunks - 1. Embedding-only paths and quarantine markers are also mismatches. Both sides are filtered by kind, so independent markdown and PDF syncs cannot contaminate one another's result.

Validate numerical health of every stored vector for one content kind.

Evidence-grade embeddings must be finite, non-zero, and approximately L2-normalized. The wider tolerance accounts for optional int8 storage quantization while still rejecting zero/NaN/Infinity and arbitrary-scale payloads that would invalidate cosine-as-dot-product search.

Capture the cheap physical-generation identity from one SQLite snapshot.

Unlike a full HNSW receipt this reads only the immutable instance UUID and mutation epoch, so request-time callers can verify graph authority before and after awaited filesystem validation without hashing every vector.

Capture HNSW build vectors and their receipt from one SQLite snapshot.

Capture the complete trusted authority needed to load a native HNSW graph. Row metadata and DB-canonical decoded vectors come from the same synchronous SQLite snapshot as the persistence receipt.

Capture one transactionally consistent, fully admitted HNSW receipt.

Every configuration cell, quarantine marker, source receipt, row field, and raw vector BLOB is read inside one synchronous better-sqlite3 transaction. A malformed non-quarantined row refuses the complete HNSW snapshot instead of silently creating a partial-recall graph.

Remove the embed db + WAL/SHM/rollback-journal sidecars, HNSW persistence sidecars, and the process-restart watcher interlock (<embed-db>.watcher-activation.guard). The guard contains no vault content, but clear-embeddings is the explicit recovery operation after a failed startup and therefore owns its removal. Idempotent.

v3.9.0-rc.34 (deep-audit P-2) — the HNSW sidecars were previously NOT removed by clear-embeddings, so a --use-hnsw user's vault content persisted on disk after "clearing" — and the historical format-2 .hnsw.meta.json carried text_preview (raw chunk text), so this was a right-to-erasure / data-cleanup gap, not just stale-index hygiene. Current compact pointers omit previews, but native vector generations remain sensitive and the same erasure authority still owns the whole family.

Close the SQLite handle synchronously and begin releasing its shared persistence lifetime. Release failures are retained for an awaited retry through closeAndRelease; no rejection escapes unobserved.

Close SQLite and await exact shared-lifetime release. A failed release remains retryable: a later invocation reuses the same core handle rather than silently acquiring or forgetting a second marker.

Return the receipt portion of captureHnswReceiptSnapshot.

Compute the legacy string-only HNSW staleness signature.

Validate multiple source receipts atomically in one synchronous SQLite read snapshot. Output indices correspond exactly to input indices.

Delete one source only while a derived HNSW graph still owns the expected physical generation.

Hash the exact kind-scoped source declarations and embedding payload.

Rows, quarantine markers, and durable source revisions are streamed in deterministic order so strict before/after evidence detects same-shape in-place mutations without loading the vector corpus into memory.

v2.13.0 — return every (vector, row) pair for HNSW build. Caller is responsible for assigning sequential integer labels (we use embeddings.id since it's already a stable AUTOINCREMENT PK).

Memory footprint: ~1.5 KB per row (384-dim Float32 + path string + preview). For 50K chunks: ~75 MB peak during build. Caller should release the array after building HNSW (we intentionally don't stream — HNSW build is 30s on 50K chunks anyway, the 75 MB is insignificant compared to the ONNX runtime + FTS5 working set). Rows are source-state-bound and non-quarantined, but this legacy bootstrap shape carries no receipt; public HNSW egress must hydrate labels through getSearchRowsByIds.

Return the exact pinned semantic-family scopes while this database is open. HNSW publishers must use these scopes instead of re-resolving a pathname.

Return quarantined source paths in deterministic order.

Hydrate HNSW labels from current, receipt-bound database rows. Missing, orphaned, kind-mismatched, and quarantined labels are omitted. Scores are deliberately absent because callers obtain them from the HNSW query that produced the labels.

Read the source-state table — caller compares mtimes to decide what to re-embed. v2.8.0: optional kind filter — when set, only rows of that kind are returned. Lets the markdown-sync and PDF-sync paths run independently without one's "missing files" being deleted by the other.

Confirm that a persisted hit still names the exact current source generation. This check is synchronous so callers can run it immediately after their final awaited live-vault stat, leaving no await-sized race.

Open the SQLite database, verify ownership on the live handle, bootstrap only an admitted schema, then enable WAL and best-effort tighten file permissions. Refusal preserves logical schema and cell/BLOB values. SQLite itself may still take locks, recover/checkpoint an existing journal, or touch physical container/sidecar bytes while opening and closing; this API does not claim byte-identical DB/WAL/SHM or directory state. Before dependency loading and again immediately before native open, the main, WAL, SHM, and rollback- journal leaves must be wholly absent or every present leaf must be a singly linked regular file; orphan sidecars refuse. Idempotent after success.

Persistently quarantine one source after an uncertain embedding attempt. Physical rows remain available for a later successful replacement, but every retrieval API excludes them immediately.

Quarantine one source only while a derived HNSW graph still owns the expected physical generation.

The comparison and the marker insert run under one BEGIN IMMEDIATE transaction. A drift result performs no DML, allowing the watcher to process-quarantine its stale graph before writing the marker DB-only.

Brute-force cosine top-K over current, non-quarantined database rows. Vectors are L2-normalized at insert time so cosine equals dot product. This legacy-compatible surface intentionally omits internal source receipts; persisted-content egress callers use searchWithReceipts. Acceptable up to roughly 50K chunks; larger corpora use HNSW.

Brute-force cosine top-K with the exact persisted source receipt selected alongside every preview. Callers must validate the receipt after their final awaited live-source check before exposing persisted bytes.

Total embedded chunks — used by stats / UI.

Replace all embeddings for a single note. Caller computes vectors. v2.8.0: optional kind parameter ("md" | "pdf"); defaults to "md" so existing callers (markdown indexing path) need no changes.

Replace one source generation and return the exact decoded vectors stored by the same SQLite transaction.

Replace one source only if an in-memory HNSW graph still names the exact current database generation.

The comparison and every mutation run under one BEGIN IMMEDIATE transaction. A drift result performs no DML, allowing the watcher to quarantine its stale graph before retrying through the authoritative database-only path.