Invariants - cruisinme30/spelunk GitHub Wiki

These rules always hold. Each keeps a whole class of bugs out, so a change that breaks one needs an ADR first.

Rule	What it means	Bug it prevents
One parser	Only daemon/internal/query parses query text. search/start re-parses rather than trusting an AST	Two sides disagreeing on what a query means
The webview is a pure view	No files, Git or daemon. Fix-its, completions and toggles are text edits + query.changed	Logic hiding in the UI that tests can't reach
ref is opaque	Hosts and webviews pass refs back unchanged	Clients depending on daemon internals
One writer	Only the indexer writes the index directory, and of the daemons with a repo open, only the one holding its lock writes it; engines read published snapshots, and the spelunk command and agents never write	Searches over half-written indexes, and windows overwriting each other's saves
One write path	Only Replace all changes the user's files: the host applies the daemon's replace/plan as one WorkspaceEdit, after checking each planned line still reads as the daemon read it. The daemon never writes them	An edit landing on a line that moved, or half a replace
Engines own results	The RPC layer forwards ResultItems unchanged	Results changed in transit
Protocol changes start in the schema	Additive changes keep the version; breaking ones bump it	Type drift between Go and TypeScript

---

Next: Cross-Cutting Concerns: cancellation, offsets, limits and budgets.