Skip to content

fix(explore): render the symbol you asked for, and charge what you spend - #223

Merged
sunerpy merged 1 commit into
mainfrom
feat/tier5-explore-budget
Aug 20, 2026
Merged

sunerpy merged 1 commit into
mainfrom
feat/tier5-explore-budget

Conversation

@sunerpy

@sunerpy sunerpy commented Aug 20, 2026

Copy link
Copy Markdown
Owner

Tier 5 of the post-v1.5.0 upstream sync — upstream's CG-24…CG-38 selection/budget epic, minus CG-27 which upstream measured and rejected (delivered characters 7,539 → 397, inner closures 7/11 → 0/11).

A named symbol could vanish entirely

Asking for a symbol by name returned 615 bytes, 0 source sections, 0 definition lines — while query found it immediately. Two independent escapes produce that, and they need separate fixes because they take different branches:

escape line gate char gate what happens
A pass pass whole-file returns a complete section, then it is rejected whole — the windowing code never runs
B pass fail falls through to clustering, first cluster accepted unconditionally, then rejected for being oversize

Escape A is the subtle one: whole_file_max_chars = 3 × max_chars_per_file is not derived from max_output_chars, so whole-file eligibility says nothing about affordability. It needs the target file not to rank first — at the cap an 11,375-byte file renders to 12,160 against a 12,780 budget, affordable as the first file by only 201 bytes, and any earlier admitted file erases that margin.

Measured:

fixture before after
escape B (merge) 632 B / 0 sections 5,152 B / 1 section, lines 1..51 + 598..620
escape A 10,616 B / 1 section, target absent 10,729 B / 2 sections, target rendered

A later cluster that did not fit was skipped whole

So a file could contribute its header and nothing else — 848 B with processPayroll(function) in the header and no body. Later clusters now shrink to the remaining room: 4,138 B with both bodies.

The bound applies to the finished section, not the cluster bodies: the admission test compares section.len(), so a ceiling on bodies leaves the frame (header + lang + fences, measured 168 B) unpaid and the windowed section is discarded anyway. Hence .saturating_sub(section_frame) sits outside the min.

Ambient declarations could take the top slot

A .d.ts that nothing depends on outranked implementations on a flow query. Now damped, combined with the generated-file signal by min so a file that is both is penalised once, not twice — verified arithmetically: generated-only and generated+ambient both weigh 3, so their order falls to the path tie-break, and non-ambient files stay order-isomorphic to today's ranking.

Order became upload.ts, env.d.ts, chunker.ts with section sizes 228 / 966 / 138 byte-identical — a pure reorder. That is why the acceptance criteria assert rank, not share: item 14 cannot move a share, and an earlier share < 0.50 assertion was not just unreachable but actively wrong — a lazy "drop .d.ts from file_order" fix scores 0% and would have passed it, while len(names) == 3 and size == BASE catch it.

The budget was wrong in both directions at once

Every section was charged a flat 200 characters instead of its real cost, while the epilogue was appended after the loop and charged nothing. Fixing either alone makes overflow more likely, so both land together with the epilogue's frame reserved up front and its pointer block sized elastically:

fixture before after
f15c 24,720 B, over budget by 720 23,889 B — the plan's ledger closing value, to the byte
f15b 13,442 B / 2 sections / cut fired 20,869 B / 3 sections / no cut
f15 23,264 B / 6 sections byte-identical

The hard-ceiling cut consequently becomes unreachable — hard_ceiling = min(max_output_chars × 1.5, 25000) exceeds the budget at every tier (19,500>13,000; 25,000>18,000; 25,000>24,000) — so the truncation note no longer deletes the very text saying what was omitted.

One existing test had to be rerouted, and it took three attempts

ext_explore_banner_ignores_marker_collision_from_retained_source asserted "the hard-ceiling cut must run", a premise this change removes by construction. Its real invariant — a spoofed #### path marker in retained source must not cause a dropped file to be cited — is intact and now pinned through admission-drop instead.

Two replacement assertions were inert before one discriminated, and I initially mis-measured this myself: my revert kept the 6-symbol pointer cap, and with the cap in place every pointer line fits regardless, so nothing could discriminate. The minimal failing set is {cap, elastic block} — matching the plan's own "the cap bounds a line, elasticity bounds the block, both are needed". Verified independently:

revert {cap, elastic}      -> FAILS on "the cut must NOT run"
same, assertion 3 disabled -> FAILS on "the epilogue must survive"   (independent)
nothing reverted           -> passes

The docstring records the sensitivity table and names where the real-cost charge and the reserve are pinned, so nobody mistakes this test for budget coverage.

Verification

  • make ci green: 133 suites / 3,426 passed / 0 failed (baseline 133 / 3,408).
  • reference/ completely clean including untracked — no extraction-golden and no MCP-fixture movement. CURRENT_EXTRACTION_VERSION stays 9; this is a query-time surface.
  • Erlang's 2 legitimate recursive calls self-edges intact; no #[ignore], no deleted assertion, no dependency change.
  • explore_tiny_tier_budget_drops_whole_methods_not_mid_method output diffed against the pre-change binary: byte-identical.
  • Edits confined to crates/codegraph-mcp/src/engine.rs and crates/codegraph-mcp/tests/golden_mcp.rs.

The plan cleared eight review rounds and seventeen blockers; two of those rounds corrected me rather than the plan.

Four selection and budget defects, all reachable from one code path.

A named symbol could vanish. Asking for a symbol by name gave back 615 bytes,
no source sections at all, and no sign anything was missing — while `query`
found it immediately. Two independent escapes produced that: a file whose whole
section is unaffordable was rejected entire, before any windowing existed to
narrow it, and a file that fell through to clustering had its first cluster
accepted unconditionally and then thrown away for being oversize. Named symbols
now carry a protected focus, a whole-file section that cannot be afforded is
windowed around it rather than dropped, and a first cluster is bounded instead
of trusted.

A later cluster that did not fit was skipped whole, so a file could contribute
its header and nothing else. Later clusters now shrink to what the remaining
room allows, and the bound is applied to the finished section rather than to the
cluster bodies alone — the admission test compares the section, so a ceiling on
the bodies leaves the frame unpaid and the windowed section is discarded anyway.

An ambient declaration file that nothing depends on could take the top slot on a
flow query, pushing implementations down the page. Such files are now damped,
combined with the generated-file signal by taking the stronger of the two, so a
file that is both is penalised once rather than twice. Files whose type the query
names are exempt.

The budget was wrong in both directions at once: every section was charged a flat
200 characters instead of its real cost, while the epilogue was appended after the
loop and charged nothing. Fixing either alone makes overflow more likely, so both
land together, with the epilogue's frame reserved up front and its pointer block
sized to the room that is actually left. The hard-ceiling cut consequently becomes
unreachable — it sits above the budget at every tier — which is why the truncation
note no longer eats the very text that says what was omitted.

CG-27 is deliberately not ported: upstream measured it dropping delivered
characters from 7,539 to 397 and rejected it.
@codecov

codecov Bot commented Aug 20, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 98.32905% with 13 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
crates/codegraph-mcp/src/engine.rs 98.32% 13 Missing ⚠️

Impacted file tree graph

@@            Coverage Diff             @@
##             main     #223      +/-   ##
==========================================
+ Coverage   95.31%   95.35%   +0.03%     
==========================================
  Files         141      141              
  Lines       78022    78711     +689     
==========================================
+ Hits        74364    75051     +687     
- Misses       3658     3660       +2     
Files with missing lines Coverage Δ
crates/codegraph-mcp/src/engine.rs 97.91% <98.32%> (+0.21%) ⬆️

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@sunerpy
sunerpy merged commit 31326cb into main Aug 20, 2026
7 checks passed
@sunerpy
sunerpy deleted the feat/tier5-explore-budget branch August 20, 2026 22:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant