feat(query): say why a result set is empty instead of returning a bare 0

[tirth8205]

A zero from the graph is currently indistinguishable from an absence in the code. query_graph_tool(pattern="callers_of", target="X") returns result_count: 0 whether X has no callers, X is not indexed, the graph is stale, or the language cannot express that relationship statically. Agents read the zero as proof and act on it. Issues #314, #850, #851 and #819 all describe this failure, and #851 states it directly: a zero with no uncertainty marker is the dangerous direction.

Change

Adds one optional response key, confidence, a short string present only when the result list is empty. First match wins:

1. Not indexed - target not indexed: no node matching 'X', so this 0 is not evidence that none exist
2. Stale by commit - graph built at an older commit than HEAD
3. Stale by mtime - the file changed after the last build (a matching commit says nothing about uncommitted edits, so both are checked)
4. Known language gap - e.g. php container-resolved and constructor-injected calls are not statically traced, so callers can be missing (#850, #851)
5. Confirmed absence - 'X' is indexed and the graph is current, so this 0 is a real absence, degrading to graph currency unverified when currency could not be established rather than over-claiming

The gap table lives as data in the new uncertainty.py, keyed by language and by query pattern, so a container-resolution note appears on callers_of and tests_for but not on file_summary. Wired into query_graph, get_impact_radius and semantic_search_nodes. No tool signature changes.

Token cost, measured

response	today	with marker	delta
query_graph empty, standard	392 ch	522 ch	+130 ch (~33 tok)
query_graph empty, minimal	381 ch	511 ch	+130 ch (~33 tok)
unindexed target, minimal	220 ch	325 ch	+105 ch (~27 tok)
semantic_search zero hits	159 ch	272 ch	+113 ch (~29 tok)
any response with results			+0 bytes, key absent

Worst case is 156 characters. The alternative behaviour, an agent that distrusts the zero and greps the repository, costs orders of magnitude more, so this is a net saving. A test asserts the exact absence of the key on non-empty responses so the budget cannot regress.

Accuracy of the gap table

Every claimed gap was verified against the parser with live parse runs rather than assumed:

• Go: struct and interface embedding still emit no INHERITS edges on main (verified: type Impl struct { Base } yields only CONTAINS). Issue [Bug]: Go struct and interface embeddings never emit INHERITS edges #834 is open and its fix fix(go): model and resolve embedded type relationships #835 is still in review, so the note is worded to hold either way, on structural typing.
• JS/TS: callbacks are captured as REFERENCES, not CALLS, so references_to is excluded from the call-pattern set and the note says exactly that.
• Python: web-framework route registration is not modelled at all (Endpoint and HANDLES are Java Spring only), so the note covers decorator-based registration generally.
• Kotlin imports, dotted-stem JS/TS imports (fix(parser): resolve dotted-stem relative imports in JS/TS and Dart #845) and Python keyword-argument callbacks (fix(parser): track keyword argument callback references #855) are genuinely fixed and are deliberately not listed.

Tests

50 new tests in tests/test_uncertainty.py: unknown target versus real absence, per-language and per-pattern firing, stale detection by commit and by mtime, silent degradation on failure, length cap under hostile unicode and control characters, and the key-absence budget guard.

Full suite 2759 passed, 5 skipped, 2 xpassed. ruff and mypy clean.

Relates to #314, #850, #851, #819.

[github-actions]

code-review-graph review

Overall risk: 0.75 (HIGH) — 52 changed function(s)/class(es), 0 affected flow(s), 15 test gap(s)

Risk-scored changes

Risk	Level	Symbol	Location	Tested
0.75	high	code_review_graph/tools/query.py::query_graph	code_review_graph/tools/query.py:249	yes
0.65	medium	code_review_graph/uncertainty.py::_clip	code_review_graph/uncertainty.py:175	no
0.65	medium	code_review_graph/uncertainty.py::_clean	code_review_graph/uncertainty.py:182	no
0.65	medium	code_review_graph/uncertainty.py::_fragment	code_review_graph/uncertainty.py:194	no
0.65	medium	code_review_graph/uncertainty.py::_bounded	code_review_graph/uncertainty.py:199	no
0.65	medium	code_review_graph/uncertainty.py::_interpolated	code_review_graph/uncertainty.py:204	no
0.65	medium	code_review_graph/uncertainty.py::_interpolated_target	code_review_graph/uncertainty.py:228	no
0.65	medium	code_review_graph/uncertainty.py::not_indexed_note	code_review_graph/uncertainty.py:239	yes
0.65	medium	code_review_graph/uncertainty.py::_staleness	code_review_graph/uncertainty.py:279	no
0.60	medium	code_review_graph/uncertainty.py::gap_note	code_review_graph/uncertainty.py:159	yes

Test gaps

• code_review_graph/uncertainty.py::LanguageGap (code_review_graph/uncertainty.py:58)
• code_review_graph/uncertainty.py::_clip (code_review_graph/uncertainty.py:175)
• code_review_graph/uncertainty.py::_clean (code_review_graph/uncertainty.py:182)
• code_review_graph/uncertainty.py::_fragment (code_review_graph/uncertainty.py:194)
• code_review_graph/uncertainty.py::_bounded (code_review_graph/uncertainty.py:199)
• ...and 10 more without direct tests

Token savings: this graph-backed report used ~31,427 fewer tokens (~81%) than reading every changed file in full (estimated, chars/4 approximation).

---

Powered by code-review-graph — local-first analysis; no code leaves the CI runner.