How to read this article #
Items are grouped by direction and marked with stable roadmap identifiers (R-*). For each: what → what benefit it brings → at what cost. The priorities are honest: first close the "documentation promises — code does not deliver" gaps, then scale, then add capabilities.
Direction 1 — evidence and security (R-SEC, R-EVID) #
| Item | What it brings | Cost |
|---|
R-SEC-1 Panel token only from console/env (close GET /api/token) | Local processes can no longer silently change corpus settings | small: delete the endpoint, token — startup print |
R-SEC-4 Drop shell=True in the Joern launch | Remove the last shell vector (currently — manual quoting) | medium: subprocess args + Windows-path regression |
| R-EVID-1 CI gate for metrics M5/M6 on every PR | "100% code-fact verifiability" stops being a manual run — becomes a branch property | medium: GitHub Actions + a fixed mini-corpus |
| R-EVID-2 Publish bench artifacts of every release | External reproducibility of measurements (today — two published runs) | small |
| Item | What it brings | Cost |
|---|
| R-PERF-1 Parallel AST walk (make the documented "8 cores/16 threads" a fact) | Large-corpus indexing several times faster; closes the main documentation↔code divergence | high: workers, identifier determinism (content hashes are already deterministic — traversal order does not affect them) |
| R-PERF-3 Query embedding cache | search from ~1 s to tens of ms on repeated queries; agents ask similar questions constantly | small: LRU by sha1(normalized_query)+model |
| R-PERF-4 Incremental CPG divisibility | Rebuild Joern only for changed files | very high: Joern has no incrementality — we would have to keep our own delta graphs |
R-PKG-1 pip install ragraf[gpu] extras | The GPU path becomes a one-command install instead of hand-assembling torch | small |
Direction 3 — analytics (R-CPG) #
| Item | What it brings | Cost |
|---|
R-CPG-2 Product taint operations over cfg_edge/dfg_edge ("source→sink") | RAGRAF turns from a navigator into an audit tool: the path of user input to SQL/echo without running code. A direct answer to the VulnGym problem space | high: operations, precision limits (LCIP reference: F1 ~55% — publish honestly), derived-edge calibration |
| R-CPG-3 CPG for Python/JS (not only php2cpg) | The interprocedural layer beyond PHP | medium: Joern supports it; the contract must be re-verified per language |
R-CORE-5 Cross-layer data_flow (code↔schema↔routes in one slice) | The answer "what happens to this table if this route changes" in one call | high |
Direction 4 — product and scale (R-CORE, R-PKG) #
| Item | What it brings | Cost |
|---|
| R-CORE-7 Multi-corpus (several projects in one panel/one MCP server) | One agent works with an N-service monorepo; the panel becomes a dispatcher | medium |
| R-CORE-8 File watcher (live-guard between requests) | The drift ledger fills without a triggering request; stale_warnings fresher | medium: watchdog + debounce; battery is the cost of idle |
| R-I18N-2 English documentation as primary (RU as translation) | A lower entry barrier for external contributors | small: the translation already exists (docs/en) |
| R-PKG-2 PyPI publication | pip install ragraf instead of a clone; release versioning | medium: build, tests on 3.13, naming policy |
Direction 5 — the agent evidence base (R-T) #
| Item | What it brings | Cost |
|---|
| R-T-1 Live A/B protocol: one task, two agents (with/without the index), automatic counting of calls, reads, tokens | "14 vs 28/43" turns from a single pilot into a repeatable stand on any customer corpus — the main adoption argument | medium: the protocol scaffolding partially exists in bench/ |
| R-T-2 Agent "health profiles" from telemetry (share of symbol/search vs grep, stale-ignoring) | The panel starts evaluating not only the index but the agent's discipline; the regimen improves from data | small on top of the ready usage_call |
| R-VIS-1 Graph visualization (read-only web view of a revision) | Debugging impact/slice by eye; product demonstration | medium: DOT export is already trivial; interactivity — d3/cytoscape |
What all of this adds up to (if everything ships) #
The "RAGRAF v0.4" scenario: an agent in an N-service monorepo asks "what breaks if this column changes" and receives a single code→schema→routes slice with taint paths of user input, on a 50k-vertex graph in <1 s (GPU CSR), against a revision fresher than a minute (file watcher) — and all of it reproducible on the customer's A/B stand with artifacts published in CI. That is no longer "search over code" but a verifiable knowledge system about a system.
What is deliberately NOT on the roadmap #
- A graph query language (P4 — measured, not debatable).
- A cloud version — the product is local on philosophical grounds (secrets never leave the machine; telemetry is local).
- Autonomous patching — RAGRAF answers, the agent edits; mixing the roles breaks responsibility attribution.
- Own embedding models — the multilingual MiniLM covers the task at 240 MB; training our own model does not pay off on foreseeable corpora.
Prioritization source: the repository's ROADMAP.md (40+ items, v0.1→v0.4 sequencing) and the defect register (43 findings: 4 CRIT / 11 HIGH / 19 MED / 9 LOW).