Why the symbol graph never blocks your work

The advisory guarantee, and what it means when the index is missing or wrong.

Written By Dustin

Last updated About 3 hours ago

TOVIO treats the semantic layer as a lens over version control, never as part of it. The guarantee is explicit: the symbol graph is never on a core critical path. Committing, merging, landing, syncing and materialising do not depend on it, do not wait for it, and do not fail because of it.

Why the guarantee exists

Parsers are the least reliable component in a version-control system. They break on syntax they have not seen, they change behaviour when a grammar is upgraded, and they are slow on large files. Making correctness depend on one would mean a parser bug could stop you committing.

So the layer is built to be droppable. Every indexing path swallows its own errors and a commit is never blocked by one.

What that looks like in practice

Situation	What happens
The file's language has no backend	Not indexed; everything about it degrades to a text diff.
A file fails to parse	That file is skipped. The rest of the index is unaffected, and so is the commit.
A cached shard was built by an older indexer	Treated as a cache miss and re-extracted. Not corruption.
A symbol object is malformed	Rejected — it is re-hashed on read like any object — and that path falls back to a text diff.
The file is policy-protected and you are not a recipient	Its symbols are simply absent from your view. No error, and no hint that they exist.
You are on a partial clone missing symbol attachments	Queries find nothing rather than failing. `tovio fetch --complete` restores a definitive answer.
A source file is very large or very deeply nested	Skipped before parsing, above a fixed size cap. It parses fine; it is simply not indexed, so its symbols never appear.
The binary has no semantic layer at all	The `semantic` commands are absent. Everything else is unchanged — except a land onto a lane that requires the check, which is refused.

The single exception

A protected lane that opts into a required semantic check. That is the one surface where a semantic finding refuses an operation, and it exists only because someone deliberately switched it on for that lane. Absent that opt-in, no finding from this layer can stop anything.

What this means for you

Read semantic output as advice with real evidence behind it, not as a verdict. An empty impact report is not a clearance. A clean interface diff is not a guarantee. A missing index is not a broken repository.

And the corollary: because it is advisory, it is safe to run constantly. There is no cost to checking a diff before you land, and no risk that the check itself becomes the thing that breaks.

The trade this buys

Determinism. The same bytes and the same pinned backend always produce a byte-identical index, on every machine — a grammar upgrade that would change extracted facts has to change the recorded fingerprint, which makes it a deliberate, visible format change rather than silent drift. That property is only affordable because nothing critical depends on the result.