Speed, determinism, and the boundaries of trust

Ripwire’s value depends on repeated use: an agent should be able to ask for context during a task without waiting for a heavyweight service, and a changed answer should reflect a changed repository rather than a changed thread schedule. This chapter examines the engineering contracts behind that promise—data layout, fixed numerical reductions, cache identity, parser safeguards, integration boundaries, and evaluation discipline. The practical judgment is to separate speed from correctness, warm reuse from stale reuse, and measured coverage from unknown coverage.

A fast answer is not automatically a reliable answer. A cache can make an obsolete index arrive quickly. A parallel parser can produce plausible symbols in a different order on every run. A benchmark can report a strong average while hiding the one task class that matters most. Ripwire treats these as separate failure modes and gives each a different defense.

Fast because the work is shaped

The expensive part of a repository map is usually not writing the final XML. It is walking and parsing source files, running tree-sitter queries, and assembling enough facts for later resolution. Ripwire shapes that work before optimizing it. The crawl collects paths first, the parser work can run with one parser per worker, and the model merge restores a canonical order. The graph then uses compact arrays instead of an object graph with pointers and per-node allocations.

That data shape matters to the ranker. The graph stores symbols as nodes and keeps the incoming edges of each target in compressed sparse row form. PageRank can therefore gather the contribution of callers into each target with sequential access through a compact structure. Weighted out-degree and edge values live in parallel arrays. The representation is less convenient than a general graph library, but it matches the operation the tool repeats most often and keeps the ranking kernel predictable.

The power-iteration loop allocates its scratch vectors before it starts. It uses double-precision rank values, computes dangling mass through fixed-size blocks, and folds each global reduction in canonical order. A published profile on one machine and corpus reported about 8.74 billion retired instructions for the cold tree-sitter parse and about 52.3 million for a warm cache load—roughly 167 times fewer instructions for that dominant phase. That is a useful explanation of why caching matters, but it is not a universal latency guarantee: the profile is one machine, one repository, and one build configuration.

The same profile explains a second architectural choice. Parsing and query execution are compute-dense, while graph construction and ranking stream through memory-heavy structures. The project’s structure-of-arrays and CSR choices are intended to keep those graph phases efficient without changing their observable answer. Optional optimization builds can reduce cold time further, but the stated contract is that they produce byte-identical output. Faster computation is valuable only because it preserves the same evidence.

Determinism is therefore stronger than “the result usually looks stable.” Ripwire sorts candidate paths before assigning symbol identifiers.