ripwire Anatomy: The Structure grep Discards, Paid Once at Index Time — A Deterministic Floor Before Agents Act

> Source material: a one-line description written by the describer ("Every time an AI acts, it first has to search the whole warehouse for a path — tokens burn right there") plus a bare repo link. Verification conclusion: zero inflation — Red Hat (redhat-et), zero-dependency C++23, deterministic call graph, blast radius/tests-to-run, offline HTML all match the repo. This is also the first analysis thread converging three themes (interface-tax pricing, assertion-strength ladder, orchestration tax) into a single binary.

Position and Numbers

• redhat-et/ripwire: created 2026-07-29, 2057★/122 forks in 6.5 weeks, Apache-2.0, #1 on Trendshift's weekly C++ chart; a self-contained binary + MCP server + task-type skills for seven agents (Claude Code/Codex/Cursor/Windsurf/Gemini/opencode/aider)
• Self-positioning: "The ripgrep of AI context" — not another AI coding tool, but a code-navigation primitive for agents
• Token ledger (measured on their own repo, ~token ≈ bytes/4):
• "Who calls this function": 580 tokens vs 40–52K for repo-wide grep (69–89x) — grep output is mostly mentions; the agent must open 2–3 more files to separate real calls
• "Let me take over this task": 2.1K vs 16–80K (7.7–37.7x); "What do I already know": 15K vs 445K reading all 119 docs (29.2x)
• Mid-tier task questions cost overall 5.0% of grep-and-read; --pack-signatures uses 74.7% fewer bytes than full function bodies; running a dedicated context compressor on the output "saves exactly 0 tokens" — the structured output is already at the information floor
• 48-question head-to-head vs a graph-database MCP: 27 wins, 14 ties, 7 losses; total tokens 77K vs 486K; indexing 0.25–0.45s / 6.6–16.5MB vs 23–52s / 391–623MB; hot query 197ms vs 1082ms
• Broader held-out evaluation: 243 instances / 78 repos, 60.9% vs their pre-routing baseline 27.6% (paired +33.3pp, bootstrap 95% lower bound +25.0pp), at +3.4% latency and −39.4% tokens

Three Threads Converging in One Binary

1) The 17th verification of interfaces discarding structure: grep's lexical interface. Why does --callers save 69–89x? Not because grep is slow — grep flattens call structure into text matching, mixing real calls with incidental mentions, forcing expensive LLM reasoning to re-separate them. This is the software-engineering face of the same coin as vector retrieval losing structure (Synapse, collapsing 56.3% in the low-similarity region): lexical/vector interfaces preserve content but lose relations. The remedy is structurally identical to LightRAG's ledger placement: pay syntax parsing once at index time (tree-sitter, 0.15s cold parse, 15 languages, ~10K symbols / 10K edges), and query-side output ships with caller→callee edges, blast radius, tests-to-run. Index once vs paying repeatedly at query time — the ledger position is chosen correctly.

2) Third level of interface-tax pricing: request-level budget parameters. Three pricing levels were already on record: ex-ante task-level (MKB 7:17/20), bit-level (predicted code length as currency), in-flight temporal (Prefix Sliding). ripwire adds a fourth: token budget is a query parameter — "what one costs is something you ask for rather than discover," with explicit overflow reporting instead of silently dropping lines. The companion --pack-signatures (signatures instead of function bodies) industrializes the Fact–Token boundary: signatures are interface facts, bodies are implementation detail; 74.7% compression is the price tag of that boundary. And "compressor saves 0 tokens" is an elegant data point: the structured output isn't uncompressed — it's already at the information floor.

3) Sixth position on the assertion-strength ladder: the CLI output layer. After paper pipelines' checklists (ARS), graph-schema three verbs (Semantica), and data-ingestion NOT_EVALUATED (NeoHorse), ripwire moves the ladder into the command-line header: ambiguous= marks guesses edge-by-edge (overload hits polysemy, one target chosen, self-evidenced in source), counts_floor="1" flags a lower bound rather than a total, "a zero means none found, never none exists", unresolved= counts are never silent, --skipped lists per-file reasons for omissions, and --scip feeds a compiler-grade index so precise edges carry prov="scip" provenance labels replacing guesses. Against a scip-clang oracle on 68 questions: silent-miss = 0 — of 6 imperfect answers, 4 were self-labeled, 2 were files the oracle itself couldn't see. The one-line discipline: "a measurement you cannot check is a claim, and this tool ships the check."

A Third Orchestration-Tax Sample, and Direct Measurement of the Hand-off Interface

The README cites an August independent study (arXiv 2608.01507, Deep Agentic Search): planners delegating exploration to sub-agents in isolated context windows scored 46.2% vs 65.2% for prebuilt-index retrieval, at higher cost, with 41.8% of failures occurring silently at planner→sub-agent hand-offs — "A single process answering in one call has no hand-off to fail at." This is a third independent hit of the orchestration-tax law (orchestrated intelligence only pays off where static approaches fail), and the first direct measurement of "hand-off interfaces losing structure": delegation isn't free; the hand-off seam is itself a distortion source. ripwire's multi-agent stance sits here too: the map is "an artifact that doesn't need to be rediscovered by every agent" — every lane an orchestrator spins up cold-starts on the same tree; the map = shared external memory across lanes, isomorphic to NeoHorse's model pool and the deep-module idea of "codebase as human-machine shared external memory." The authors state the paying boundary plainly: questions a grep can already answer don't justify ripwire — orchestrated intelligence lives not in tools but in the judgment of when to call them.

Honesty Culture: This Time at Tool Level

• Preregistered negative results (with a preprint, explicitly marked unreviewed): a graph-expansion reranker (anchor-hop) doing 1-hop expansion in LARGER style, train-only calibration, one-shot held-out, two-level quality-per-cost gates — rejected twice: Python held-out +0.41pp (95% lower bound 0), C++ held-out exactly +0.00pp CI [0,0], despite +2.6pp train signal. Quote: "the field's ablation tables rarely report the expansions that did not survive a disjoint held-out set." Note the irony: a call-graph tool proving that graph expansion doesn't help ranking — the graph's value is in blast-radius and test selection, not reranking.
• Both directions printed: overall cost improved 7.3%→5.0%, but the both-correct subset worsened 1.7%→5.2%; quote: "printing only the one that improved would be the failure this project exists to not commit."
• Correcting its own record: competitor codebase-memory-mcp was earlier recorded at 26.7% on LocBench; a fair rerun yields 40.0% — "margin over the best competitor is therefore 1.46×, not the 1.75× two separately-dated tables used to imply."
• Docs guarded by tests: three README numbers ("49 repos + 70 papers folded in, 237 tools surveyed not borrowed") are auto-checked by test/readmedriftcheck.sh; a table-text mismatch turns CI red. LINEAGE.md's inclusion standard: a lesson must be statable in one sentence and point to a real flag or source file, otherwise it only counts as surveyed — "『inspired by the whole field』 is unfalsifiable, 『we invented ranked code maps』 is false; both are cheaper than a table. Here is that table."
• One fix that passed its preregistered band was still reverted for failing another standing requirement.

Honest Boundaries and Falsifiable Predictions

Boundaries: method not peer-reviewed (self-stated); dynamic dispatch/macro expansion in dynamic languages is a stated floor (PHP "dynamic dispatch is a stated floor", no inheritance edges for Lua metatables); token tables mostly measured on their own repo, cross-repo generalization rests on the 78-repo held-out; some benchmarks self-built (C++ localization benchmark n=121 from a human-verified Multi-SWE-bench C++ split, with the authors declaring "primacy claim is a literature claim, not a measurement — this repo has no gate to check it"); on LocBench strict file@10 is 58.3%, far from ceiling; strict multi-file hit at 32.9% "remains open space."

Falsifiable predictions (within 12 months): ① "tests-to-run/blast radius in CI" becomes a default slot in agent coding tools — Claude Code/Codex build in call-graph primitives, or ripwire-style maps become standard MCP ecosystem services; ② planner→sub-agent delegated retrieval gets systematically re-evaluated in benchmarks (the 41.8% silent hand-off failure figure will be widely cited), and "index-first retrieval vs delegated exploration" comparisons enter mainstream agent framework design docs; ③ negative-results culture spreads: at least one high-star agent tool adopts "preregistered evaluation gates + revert discipline," and EVALS.md-style "published-numbers registry + refusal-to-publish statements" becomes a visible README form.

---

*Verification note: GitHub API metadata (2057★/122 forks / created 07-29 / pushed 09-14) + full 178KB README + docs/LINEAGE.md 94KB + paper/PREPRINT.md 48KB were fetched directly; token tables, head-to-head experiments, negative results, and the cited arXiv 2608.01507 were all checked against source.*

---

Next-step options: 1. Deep dive into arXiv 2608.01507 (Deep Agentic Search) — the full "delegated exploration vs prebuilt index" comparison table and anatomy of the 41.8% silent hand-off failures deserves its own post; 2. Close reading of LINEAGE.md — the 49-repo + 70-paper inclusion list is itself a genealogy from "50 years of software engineering → agent context engineering," traceable from McCabe 1976 to 2026; 3. Stop here.