@dikolab/kbdb 0.3.0 → 0.3.1

package/docs/goals/concurrency.md

@@ -0,0 +1,259 @@
+# Concurrent Write Safety
+
+*One writer at a time, unlimited concurrent readers --
+formalizing the locking model, multi-daemon prevention,
+crash recovery, and stress-test methodology.*
+
+## Goal
+
+The worker daemon serializes all write operations
+through a single-writer lock. Multiple concurrent
+readers proceed without any lock. This document
+formalizes the locking model, multi-daemon prevention,
+atomic write guarantees, crash recovery, and
+stress-test methodology.
+
+This goal addresses gap #3 from the issue
+[2026-06-23 Opus 4.8 Second Brain Review](../issues/2026-06-23-opus-48-second-brain-review.md):
+the single-writer lock in the worker daemon must be
+validated under concurrent load before concurrent
+multi-agent use can be trusted.
+
+## Single-Writer Lock
+
+The daemon acquires an exclusive file lock on
+`kbdb-{ctx}.lock` in the OS temporary directory during
+write operations. The lock file uses the same context
+ID as the PID file and IPC socket (see
+[Worker Daemon](worker-daemon.md) for context ID
+derivation).
+
+- **Read operations** -- search, recall, retrieve,
+  content, dbStatus, and listByType -- proceed without
+  acquiring the lock. Concurrent read requests from
+  multiple worker client connections are fully parallel.
+- **Write operations** -- addSection, updateSection,
+  removeSection, groupSections, removeGrouping,
+  initDirectory, gc, rebuildIndexes, and export --
+  acquire the exclusive lock before calling the
+  corresponding WASM export. If another write is
+  already in progress, the new write queues behind the
+  lock and waits.
+- The lock is held only for the duration of a single
+  write operation. It is released immediately after
+  the operation completes. It is never held across
+  multiple operations or across client connections.
+- The locking model is implemented in TypeScript inside
+  the worker daemon (`src/shared/worker-daemon/`), not
+  inside any WASM module.
+
+This model is equivalent to SQLite's default locking:
+readers never block, and writers take turns one at a
+time.
+
+### Write Operations Subject to the Lock
+
+| IPC Method               | WASM Export                |
+|--------------------------|----------------------------|
+| `addSection`             | `worker_add_section`       |
+| `updateSection`          | `worker_update_section`    |
+| `removeSection`          | `worker_remove_section`    |
+| `groupSections`          | `worker_group_sections`    |
+| `removeGrouping`         | `worker_remove_grouping`   |
+| `initDirectory`          | `worker_init_directory`    |
+| `gc`                     | `worker_garbage_collect`   |
+| `rebuildIndexes`         | `worker_rebuild_indexes`   |
+| `export`                 | `db_export`                |
+
+## Multi-Daemon Prevention
+
+Each database context gets exactly one daemon process
+at a time, enforced by a PID file keyed to the context
+ID.
+
+- The PID file is named `kbdb-{ctx}.pid` and lives in
+  the OS temporary directory. Its presence means a
+  daemon for that context is either running or died
+  without cleaning up.
+- Before spawning a new daemon, the worker client reads
+  the PID file (if present) and checks whether the
+  recorded process is alive.
+  - **PID file absent** -- no running daemon; spawn a
+    new one.
+  - **PID file present, process alive** -- connect to
+    the existing daemon; do not spawn.
+  - **PID file present, process dead** -- stale PID
+    file from a prior crash; remove the file and spawn
+    a new daemon.
+- The daemon writes its PID file only after all startup
+  preconditions pass and the WASM module is loaded
+  successfully. See [Worker Daemon](worker-daemon.md)
+  for the full startup sequence.
+- On graceful shutdown, the daemon removes its PID
+  file before exiting.
+
+This protocol ensures that the same database directory
+is never served by two concurrent daemon processes.
+
+## Atomic Write Guarantees
+
+All file writes in the database use the atomic
+write pattern: content is written to a temporary file
+first, then the temporary file is renamed to the final
+path. Rename is an atomic operation on all supported
+filesystems (POSIX and Windows NTFS).
+
+- **Section files** (`sections/{prefix}/{kbid}.sec`)
+  are written to `sections/{prefix}/{kbid}.sec.tmp`
+  then renamed.
+- **Document manifests** (`documents/{docid}.toml`)
+  are written to `documents/{docid}.toml.tmp` then
+  renamed.
+- **Index files** (`indexes/terms.idx`, etc.) are
+  rebuilt to temporary paths then renamed into place.
+- **Catalog** (`catalog.toml`) is written last,
+  after all data files are in place. A crash
+  before the catalog rename leaves the catalog
+  consistent with the previous complete state.
+
+If the daemon crashes mid-write, the temporary file
+is orphaned but the original file is intact. On next
+daemon startup, orphaned temporary files (matching
+`*.tmp`) in the database directory are cleaned up.
+
+The atomic write pattern is specified in
+[Database](database.md) under Storage Design.
+
+## Crash Recovery
+
+The table below describes every identified failure
+scenario, the resulting disk state, and the recovery
+action.
+
+| Scenario | State After Crash | Recovery |
+|---|---|---|
+| Crash during section write | `*.sec.tmp` orphaned, original `.sec` intact | Startup cleans `*.tmp` files |
+| Crash during index rebuild | Partial `*.idx.tmp`, originals intact | Startup cleans `*.tmp`; next `rebuildIndexes` overwrites |
+| Crash during GC | Some unreferenced sections deleted, others not | Re-run `gc`; idempotent |
+| Crash during catalog write | `catalog.toml.tmp` orphaned, original intact | Startup cleans `*.tmp` |
+| PID file not removed | Stale `kbdb-{ctx}.pid` on disk | Worker client detects dead process, removes PID, spawns new daemon |
+| Lock file not released | `kbdb-{ctx}.lock` orphaned | Daemon startup acquires the exclusive lock fresh; OS releases orphaned file locks when the process that held them exits |
+| WASM crash inside write | Partial in-memory state, temp file may exist | Daemon exits; startup cleans `*.tmp`; next operation starts clean |
+
+All recovery actions are automatic. No manual
+intervention is required for any scenario in this
+table.
+
+## Stress Test Specification
+
+The following test harness validates concurrent write
+safety. It must pass on both Deno and Node.js runtimes
+before a release can claim concurrent safety.
+
+### Setup
+
+1. Create a fresh, empty database directory.
+2. Prepare N unique documents (N in the range 10--50).
+   Each document must have distinct content to avoid
+   content-address collisions that would make section
+   count verification meaningless.
+
+### Execution
+
+3. Launch N concurrent `kbdb learn` invocations, all
+   targeting the same database directory. Each
+   invocation learns one of the N unique documents.
+4. Use a process pool or parallel shell to launch all
+   N invocations simultaneously -- not sequentially.
+5. Wait for all N invocations to complete. Record any
+   non-zero exit codes as failures.
+
+### Verification
+
+6. Run `kbdb check` against the database.
+   The response must have `ok: true`. Any errors in the
+   response are test failures.
+7. Query the section count. The count must equal the
+   expected number of sections derived from the N
+   documents (no duplicates from race conditions, no
+   losses from interleaved writes).
+8. Verify that no section has a checksum mismatch.
+   A mismatch indicates a torn write -- the atomic
+   rename pattern failed or was bypassed.
+
+### Pass Criteria
+
+| Check | Expected Result |
+|---|---|
+| All `kbdb learn` exit codes | `0` |
+| `kbdb check` response | `ok: true`, zero errors |
+| Section count | Exactly the expected count |
+| Checksum mismatches | Zero |
+
+### Runtime Matrix
+
+Run the full harness on both runtimes:
+
+| Runtime | Command prefix |
+|---|---|
+| Node.js >= 20 | `node dist/kbdb.mjs` |
+| Deno | `deno run --allow-all src/cli.ts` |
+
+Both must pass. A failure on one runtime but not the
+other indicates a runtime-specific locking bug.
+
+## Edge Cases
+
+### Two CLI Invocations Through the Same Daemon
+
+When two `kbdb` CLI processes connect to the same
+daemon (same database directory), their write requests
+share the single-writer lock automatically. No user
+action is required. The second write waits for the
+first to complete.
+
+### MCP Server Connections
+
+An MCP server connection routes all requests through
+a worker client to the daemon, the same as a CLI
+invocation. Multiple MCP client connections routed to
+the same daemon share the write lock:
+
+- Concurrent read requests from multiple MCP clients
+  are served in parallel.
+- Concurrent write requests from multiple MCP clients
+  are serialized through the lock one at a time.
+
+There is no per-connection or per-client lock; the
+lock is global to the daemon process.
+
+### Direct File Access
+
+Accessing or modifying `.kbdb` files directly -- via
+text editor, shell commands, or any process other than
+the daemon -- is not supported. Direct writes bypass
+the single-writer lock and the atomic write pattern,
+and may corrupt the database. All mutations must go
+through the daemon's IPC API.
+
+## Design Constraints
+
+- **Per-daemon locking, not per-file** -- The lock
+  covers all writes to a database context, not writes
+  to individual files. This means writes to unrelated
+  sections still serialize behind the same lock. The
+  simplicity of a single lock outweighs the throughput
+  cost at current scale. If per-section parallelism
+  becomes necessary, this constraint is the place to
+  revisit.
+- **Single-machine only** -- The locking model
+  relies on OS-level file locks and process identity
+  on a single machine. It provides no guarantees across
+  network filesystems or multiple machines. Cross-machine
+  scenarios require an external sync mechanism (see
+  [Sync](sync.md) when available).
+- **Lock implemented in TypeScript** -- The write lock
+  is managed by the TypeScript worker daemon layer, not
+  by any WASM module. WASM modules have no knowledge of
+  concurrent callers; they process one call at a time
+  through the host.

package/docs/goals/hybrid-search.md

@@ -0,0 +1,436 @@
+# Hybrid Search -- Lexical + Vector Retrieval
+
+*Optional vector retrieval path alongside BM25F, fused
+with RRF for best-of-both ranking.*
+
+## Goal
+
+The current retrieval mode is lexical search: BM25F with
+stemming and synonym expansion. It works well for
+structured documentation where terminology is consistent
+-- the agent searches "authentication" and the indexed
+content uses the same word.
+
+Lexical search has a ceiling, however. It misses
+associative recall when terminology diverges between the
+time content was stored and the time it is retrieved.
+Example: an agent stores "we chose Postgres because of
+JSONB" and later searches "database rationale" -- lexical
+search misses it because none of the indexed tokens
+(`postgres`, `chose`, `jsonb`) overlap with the query
+tokens (`database`, `rationale`). Vector search finds
+it because the embedding of the query is geometrically
+close to the embedding of the stored sentence.
+
+This gap is identified as the critical lexical-only
+ceiling in
+[Opus 4.8 Second Brain Review](../issues/2026-06-23-opus-48-second-brain-review.md)
+(gap #1). Hybrid search closes it by adding an optional
+vector retrieval path alongside the existing lexical
+path, fusing both ranked lists using Reciprocal Rank
+Fusion (RRF) for a final result set that benefits from
+both modes.
+
+## Architecture
+
+Two retrieval paths run in parallel. The vector path
+runs entirely in TypeScript. No WASM code is added or
+modified.
+
+```
+Query → ┌─ Lexical path (WASM) ─→ BM25F ranked list ─┐
+        │                                              ├─→ RRF Fusion → Final results
+        └─ Vector path (TS)   ─→ Cosine ranked list ──┘
+```
+
+The WASM boundary is untouched. `query-parser.wasm`
+remains a pure-computation lexical module. `kb-worker.wasm`
+continues to orchestrate lexical retrieval via
+`fs-database.wasm` exactly as today. No new WASM crate,
+no new WASM export, and no new host import is needed for
+the vector path.
+
+The TypeScript daemon layer adds the vector path as an
+independent retrieval step that runs after the lexical
+path completes (or concurrently if the runtime allows).
+The fused list is assembled in TypeScript before the
+response is returned to the worker client.
+
+## EmbeddingProvider Interface
+
+### Why TypeScript, Not WASM
+
+Three reasons embeddings are computed in TypeScript
+rather than in WASM:
+
+1. `wasm32-unknown-unknown` has no network I/O. Calling
+   an embedding API from WASM is impossible without a
+   host bridge that would defeat the purpose of running
+   in WASM.
+2. Embedding models are too large for WASM. A typical
+   all-MiniLM-L6-v2 model is ~90 MB. Loading that inside
+   the WASM sandbox on every daemon startup is
+   impractical.
+3. TypeScript allows pluggable backends. An interface-based
+   design lets the daemon swap providers (local ONNX,
+   remote API) without changing any WASM code.
+
+### Interface Specification
+
+```typescript
+interface EmbeddingProvider {
+   embed(texts: string[]): Promise<Float32Array[]>;
+   dimensions(): number;
+   modelName(): string;
+}
+```
+
+| Member       | Description                                  |
+|--------------|----------------------------------------------|
+| `embed`      | Compute embeddings for a batch of input texts. Returns one `Float32Array` per input, each of length `dimensions()`. |
+| `dimensions` | Fixed embedding dimensionality for this provider. All vectors stored under the same model must have this length. |
+| `modelName`  | Stable identifier for the model. Used for stale-detection when the configured model changes. |
+
+### Implementations
+
+Three concrete implementations are specified.
+
+**`NullEmbeddingProvider`** -- no-op, returns empty
+arrays. The default when no `[embedding]` section is
+present in `worker.toml`. Requesting `vector` or
+`hybrid` search mode with this provider returns a
+structured error rather than silently returning empty
+results. Satisfies POLA: the absence of configuration
+does not silently degrade results.
+
+**`OnnxEmbeddingProvider`** -- local offline inference
+using ONNX Runtime. Default model: `all-MiniLM-L6-v2`
+(384 dimensions). The model file is downloaded on first
+use and cached in the OS user-data directory. Works on
+both Deno and Node.js >= 20. No network dependency
+after the initial model download. Suitable for
+air-gapped or cost-sensitive deployments.
+
+**`ApiEmbeddingProvider`** -- calls an external HTTP
+embedding API. Compatible with OpenAI, Anthropic, and
+any endpoint that accepts a `POST /embeddings` request
+with a JSON body `{ "input": string[] }` and returns
+`{ "data": [{ "embedding": number[] }] }`. Configured
+via `worker.toml`. The API key is read from an
+environment variable named by `api_key_env`.
+
+## Vector Storage
+
+### New Index Files
+
+Two new files are added to `indexes/` alongside the
+existing index files. They follow the same rebuild
+semantics as `terms.idx`, `positions.idx`, and
+`corpus.dat`: derived data, rebuildable from section
+content, excluded from version control.
+
+**`vectors.idx`** -- binary, fixed-width records.
+
+Header layout:
+
+| Bytes | Field          | Type   | Description                   |
+|-------|----------------|--------|-------------------------------|
+| 0-3   | magic          | u8[4]  | `b"KBVX"` -- format sentinel  |
+| 4     | version        | u8     | Format version, currently `1` |
+| 5-6   | dimensions     | u16    | Vector length per record       |
+| 7-10  | record_count   | u32    | Total number of records        |
+
+Each record immediately follows the header:
+
+| Bytes          | Field          | Type           | Description       |
+|----------------|----------------|----------------|-------------------|
+| 0-15           | kbid_hash      | u8[16]         | First 16 bytes of the section kbid, used as a compact lookup key |
+| 16 onwards     | embedding      | f32[dimensions]| Raw embedding vector |
+
+Record size = `16 + dimensions * 4` bytes. All records
+are the same size, enabling O(1) offset computation by
+record index and binary search by kbid hash.
+
+**`vectors-meta.toml`** -- human-readable metadata.
+
+```toml
+[vectors]
+model_name  = "all-MiniLM-L6-v2"
+dimensions  = 384
+version     = 1
+last_built  = "2026-06-23T10:00:00Z"
+section_count = 2847
+```
+
+| Field           | Description                               |
+|-----------------|-------------------------------------------|
+| `model_name`    | Model name from `EmbeddingProvider.modelName()`. Used for stale detection. |
+| `dimensions`    | Must match the `dimensions` header in `vectors.idx`. |
+| `version`       | `vectors.idx` format version.             |
+| `last_built`    | ISO 8601 timestamp of the last rebuild.   |
+| `section_count` | Number of sections embedded.              |
+
+### Updated Directory Layout
+
+```
+.kbdb/
+└── indexes/
+    ├── meta.toml
+    ├── terms.idx
+    ├── positions.idx
+    ├── corpus.dat
+    ├── references.idx
+    ├── vectors.idx          # new -- binary embedding store
+    └── vectors-meta.toml   # new -- embedding metadata
+```
+
+## Embedding Lifecycle
+
+### Learn Time
+
+When a section is added via `kbdb learn`, the lexical
+indexing pipeline runs first (unchanged). After lexical
+indexing completes, the daemon asynchronously computes
+an embedding for the section using the configured
+`EmbeddingProvider`.
+
+The embedding input is the concatenation of the
+section's title and body content:
+
+```
+{title}\n{content}
+```
+
+The title is prepended because it carries strong
+semantic weight (it receives a 2.0x BM25F field weight
+for the same reason). Concatenating both fields gives
+the embedding model the same semantic signal that BM25F
+heading-weight gives to lexical scoring.
+
+Sections with no body content (binary sections where
+content is base64) embed only the title and
+description. Sections with neither title nor body
+content are not embedded.
+
+Embedding is best-effort at learn time: if the provider
+fails for a section, the section is still stored
+lexically. A warning is emitted in the learn response
+(`vector_embedding_failed: true`).
+
+### Rebuild
+
+`kbdb rebuild` regenerates all vector embeddings from
+section content alongside the existing lexical index
+rebuild. Sections are embedded in batches of up to 64
+to respect provider rate limits. The `vectors.idx` and
+`vectors-meta.toml` files are written atomically after
+all embeddings are computed.
+
+### Stale Detection
+
+When the daemon starts, it reads `vectors-meta.toml`
+and compares `model_name` to the currently configured
+provider's `modelName()`. If they differ, the vector
+index is marked stale. Stale vector indexes are not
+used for retrieval. Search falls back to lexical-only
+with a warning field in the response:
+`vector_index_stale: true`.
+
+The agent or operator must run `kbdb rebuild` to
+regenerate vectors with the new model before hybrid or
+vector search resumes.
+
+## Score Fusion
+
+### Reciprocal Rank Fusion (RRF)
+
+RRF combines the lexical ranked list and the vector
+ranked list into a single fused list without requiring
+score normalization. BM25F scores and cosine similarity
+scores live on different scales and cannot be directly
+added -- RRF sidesteps this by working on ranks rather
+than scores.
+
+Formula:
+
+```
+score(d) = 1/(k + rank_lexical(d)) + 1/(k + rank_vector(d))
+```
+
+Where:
+
+- `k = 60` (standard default, configurable via
+  `worker.toml` as `rrf_k`)
+- `rank_lexical(d)` is the 1-based rank of document `d`
+  in the BM25F result list, or infinity if `d` does not
+  appear in the lexical results
+- `rank_vector(d)` is the 1-based rank of document `d`
+  in the cosine similarity result list, or infinity if
+  `d` does not appear in the vector results
+- A rank of infinity contributes 0 to the sum (since
+  `1/(k + ∞) = 0`)
+
+Documents appearing in only one result set receive full
+contribution from that set and zero from the other.
+Documents appearing in both receive a higher combined
+score than either path could produce alone, naturally
+surfacing cross-path agreement.
+
+The final result list is sorted by RRF score descending.
+
+### Why RRF
+
+- Parameter-light: `k = 60` is the well-established
+  default from the original RRF paper (Cormack et al.,
+  2009). It rarely needs tuning.
+- No normalization: BM25F scores and cosine similarity
+  are not comparable in magnitude. RRF requires only
+  rank order, not the scores themselves.
+- Robust: adding a low-quality second path cannot hurt
+  the top results badly because RRF dampens rank
+  contributions as `k` is approached.
+
+## Search Mode Parameter
+
+A new `search_mode` parameter controls which retrieval
+paths are active for a given search request.
+
+| Value      | Retrieval behaviour                         | Embedding provider required |
+|------------|---------------------------------------------|-----------------------------|
+| `lexical`  | Lexical path only. Current behaviour. Default. | No                        |
+| `vector`   | Vector path only. Cosine similarity ranking.   | Yes                       |
+| `hybrid`   | Both paths, RRF fusion.                        | Yes                        |
+
+The default is `lexical`. Existing integrations that do
+not supply `search_mode` are unchanged. This is a
+strict backward-compatibility guarantee.
+
+Requesting `vector` or `hybrid` when no embedding
+provider is configured (i.e. `NullEmbeddingProvider` is
+active) returns a structured error:
+
+```json
+{
+  "error": "Vector search requires a configured embedding provider",
+  "code": "EMBEDDING_PROVIDER_NOT_CONFIGURED"
+}
+```
+
+## CLI and MCP Surface
+
+### CLI
+
+The `search` subcommand gains an optional `--mode` flag:
+
+```
+kbdb search "database rationale"
+kbdb search --mode hybrid "database rationale"
+kbdb search --mode vector "database rationale"
+```
+
+Omitting `--mode` defaults to `lexical`. The flag is
+not shown in the short help unless an embedding provider
+is configured.
+
+### MCP
+
+The `search` MCP tool gains an optional `mode` parameter
+(string enum: `"lexical" | "vector" | "hybrid"`). The
+parameter is documented as optional in the tool schema
+with a default of `"lexical"`.
+
+### Response Envelope
+
+`PagedSearchResult` gains two new fields:
+
+| Field              | Type   | Description                     |
+|--------------------|--------|---------------------------------|
+| `search_mode`      | string | The mode that was requested: `"lexical"`, `"vector"`, or `"hybrid"` |
+| `retrieval_method` | string | The mode that was actually used: `"lexical"`, `"vector"`, or `"hybrid"`. Differs from `search_mode` when a fallback occurred (e.g. stale vector index forced `"lexical"`). |
+
+Both fields are always present in the response,
+including when `search_mode` was not supplied (in which
+case both fields are `"lexical"`).
+
+## Configuration
+
+`worker.toml` gains an `[embedding]` section:
+
+```toml
+[embedding]
+provider    = "onnx"           # "onnx" | "api" | "none"
+model       = "all-MiniLM-L6-v2"
+dimensions  = 384
+rrf_k       = 60               # RRF parameter k
+
+# API provider only:
+api_url     = ""
+api_key_env = "KBDB_API_KEY"
+```
+
+| Key           | Default              | Description                  |
+|---------------|----------------------|------------------------------|
+| `provider`    | `"none"`             | Which `EmbeddingProvider` implementation to use |
+| `model`       | `"all-MiniLM-L6-v2"` | Model name, passed to the provider |
+| `dimensions`  | `384`                | Embedding vector length      |
+| `rrf_k`       | `60`                 | RRF constant `k`             |
+| `api_url`     | `""`                 | Base URL for API provider    |
+| `api_key_env` | `"KBDB_API_KEY"`     | Environment variable holding the API key |
+
+When `[embedding]` is absent from `worker.toml`,
+`provider` defaults to `"none"` and `NullEmbeddingProvider`
+is used.
+
+## Fallback Behaviour
+
+Three fallback conditions are defined. Each is surfaced
+in the search response with a specific warning field
+rather than silently degrading.
+
+**No embedding provider configured.**
+`search_mode` defaults to `lexical`. Requesting `hybrid`
+or `vector` returns a structured error with code
+`EMBEDDING_PROVIDER_NOT_CONFIGURED`. No silent fallback
+occurs -- the caller receives an actionable error
+message.
+
+**Stale vector index (model mismatch).**
+When `vectors-meta.toml` model name does not match the
+configured provider's `modelName()`, the daemon marks
+the vector index stale. Any search request that would
+use the vector path falls back to `lexical`. The
+response includes `retrieval_method: "lexical"` and
+`vector_index_stale: true`. The correct remediation is
+`kbdb rebuild`.
+
+**Embedding failure during learn.**
+If the embedding provider returns an error for a section
+during learn, the section is stored lexically without an
+embedding. The learn response includes
+`vector_embedding_failed: true`. The section will
+appear in lexical results but not in vector or hybrid
+results until a rebuild is run.
+
+## Provider Tradeoffs
+
+| Aspect        | ONNX (local)              | API (cloud)                  |
+|---------------|---------------------------|------------------------------|
+| Latency       | ~10 ms/embed              | ~100 ms/embed                |
+| Offline       | Yes                       | No                           |
+| Cost          | Free                      | Per-token                    |
+| Quality       | Good (384 dimensions)     | Excellent (1536+ dimensions) |
+| Setup         | Model download on first use | API key required            |
+| Dual runtime  | Deno + Node.js >= 20      | Deno + Node.js >= 20         |
+
+Both providers implement the same `EmbeddingProvider`
+interface. The daemon interacts only with the interface.
+
+## Design Constraints
+
+| Constraint            | Details                                        |
+|-----------------------|------------------------------------------------|
+| WASM purity           | `query-parser.wasm` remains pure lexical computation with no I/O. No new WASM crate or export is added. |
+| Backward compatibility | Default `search_mode` is `lexical`. Callers that do not supply the parameter receive identical behaviour to today. |
+| File-based storage    | `vectors.idx` and `vectors-meta.toml` follow the same derived-and-rebuildable pattern as all other index files. |
+| Dual runtime          | `EmbeddingProvider` and all embedding logic must work on Deno and Node.js >= 20. No Node-specific or Deno-specific APIs in the implementation. |
+| No new WASM deps      | All new dependencies are TypeScript-side only. The WASM modules (`fs-database.wasm`, `query-parser.wasm`, `kb-worker.wasm`) are not recompiled for this feature. |