Trust Boundaries

Know the invariants that keep KuraDB read-only to its consumers and consistent internally.

Trust boundaries and invariants

Read surfaces

• The HTTP API registers GET routes only; no mutation endpoint may bypass ingestion.
• MCP exposes exactly two read-only tools, list_rag and search_rag; no tool writes to SQLite or the caches.
• The HTTP listener binds to 127.0.0.1, and /mcp is mounted only when remote is enabled at startup.
• API responses expose source, chunk, and content, but not internal IDs, scores, hit counts, or totals.

Write path

• Content writes flow through watcher → parser → databaseHandler.Upsert → SQLite; no layer outside internal/database writes file_data.
• The daemon is the only writer. kura mcp opens the same databases but registers no query-cache write hook and starts no watcher or embedder.
• Images and other skipped binary formats do not enter the text embedding pipeline.

Data invariants

• Keyword and semantic reads exclude rows where dismiss = TRUE.
• Embeddings must match the process-wide openai.Dim() (512 dimensions). Query-cache rows of any other size are skipped when global.db is preloaded; chunk vectors are not length-checked at load, and vectors whose length differs from the query are skipped during search.
• Newly registered databases become available only after a restart.