Skip to content

fix(sections): stop get_section's retry from reusing the full graph's search index (#5385) - #5386

Open
Deepjyoti-Sarmah wants to merge 6 commits into
Graphify-Labs:v8from
Deepjyoti-Sarmah:fix/5385-section-subgraph-index
Open

Deepjyoti-Sarmah wants to merge 6 commits into
Graphify-Labs:v8from
Deepjyoti-Sarmah:fix/5385-section-subgraph-index

Conversation

@Deepjyoti-Sarmah

@Deepjyoti-Sarmah Deepjyoti-Sarmah commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

What does this PR do?

Fixes #5385. get_section raises KeyError: 'Key deploy_sh not found' when the
query is ambiguous or resolves to a non-section node.

resolve_section_query resolves in two passes:

_resolve_single_node(G, query)            full graph
  hit is a section?  -> return it
  else retry on G.subgraph(section nodes)  <- crashes here

A networkx subgraph view is not a new graph. It shares the parent's graph
dict, and that is where serve.py caches its search state. The retry therefore
reads the full graph's trigram index. Its ids include deploy_sh, which is not
in the view, and _find_node_tiers does G.nodes[nid] on it.

  sections = G.subgraph([...])
+ sections.graph = {k: v for k, v in G.graph.items()
+                   if not k.startswith("_") or k in _SECTION_VIEW_GRAPH_KEYS}
  sec_nid, _ = _resolve_single_node(sections, query)

The view keeps every public key, plus the private keys a lookup reads. That is
_SECTION_VIEW_GRAPH_KEYS = {"_logical_directed"}. Every other _-prefixed key
is dropped. That covers the four search caches serve.py keeps today
(_trigram_index, _idf_cache, _traversal_view, _path_search_graphs) and
any cache added later.

serve.py also stores _learning_overlay and _built_at_commit. Neither
_resolve_single_node nor its callees read them, so dropping them from this
temporary view doesn't change a lookup.

It is not only the warm case

The issue says the index has to be warm, which the MCP server does at load
(serve.py:167). It does not have to be. The first pass,
_resolve_single_node(G, query), builds the full graph's index itself. So any
query that falls through to the retry crashes, on a cold graph too. The test
parametrizes both.

The sharing is also unsafe in the other direction, though this function does not
reach it today: a view searched before its parent would write a sections-only
index into the shared dict, and the full graph's later searches would miss code
nodes. test_retry_does_not_replace_full_graph_index checks that the full
graph's index still covers every node after a retry.

Why not .copy()

The issue suggests G.subgraph(...).copy(). That alone does not fix it: networkx
copies G.graph into the new graph, caches included. I checked:

>>> G.graph["_trigram_index"] = "x"
>>> "_trigram_index" in G.subgraph([1]).copy().graph
True

It would also copy every section node and edge on each fallback query. A fresh
dict on the view costs one small dict comprehension.

The other suggestion, filtering candidates with nid in G in
_trigram_candidates, would stop the crash. But the view would still share
every other cache with the parent. Fixing the shared dict covers all of them.

Five commits

70ad5b9b  refactor(sections): name the search caches serve.py keeps on G.graph (#5385)
14265ba3  fix(sections): give the section retry view its own graph caches (#5385)
0d7b5440  test(sections): pin the section retry against shared graph caches (#5385)
065464a7  test(sections): pin isolated retry view caches (#5385)
563b5db8  fix(sections): allowlist view graph metadata (#5385)

The last two answer the review. 065464a7 proves the retry runs on an
isolated view, and 563b5db8 turns the explicit cache list into an allowlist,
so a cache added to G.graph later is not shared by default. Each part
reverts alone: reverting 563b5db8 goes back to the explicit list, and the
unknown-cache test fails again.

Type of change

  • Bug fix
  • New feature
  • Documentation
  • Tests or CI
  • Refactor
  • Security fix

Verification & Invariants

The invariant: a search on a graph view uses an index built from that view's
nodes, and never changes the parent graph's caches.

  • Read the CONTRIBUTING.md guide.
  • Reproduced the issue and identified the invariant.
  • Made the smallest fix necessary.
  • Added a regression test (if bug fix) or isolated boundary test.
  • Kept the PR description synchronized with the final implementation.
  • Documented any limitations / unsupported cases explicitly.

Merge Danger

Door: two-way. Nothing persisted changes: no schema, cache-key or file-format
change. Only the in-memory view used for the retry is touched.

Blast radius: small.

  • Queries that resolve to a section on the first pass return before the change
    and are unaffected.
  • The retry no longer reads or writes the full graph's caches.
  • The view's own caches are dropped with the view after the call, so each retry
    builds a sections-only index. That costs work proportional to the number of
    section nodes, on the fallback path only. On a synthetic graph of 2,186 nodes
    (the largest checked-in example graph plus 300 section nodes), the median of
    9 fresh builds was about 10 ms for the sections view against about 120 ms
    for the full graph. That is too small to justify a cache keyed on the parent,
    with its own invalidation and lifetime, so I left it out.

Limitations

  • The allowlist is explicit in the other direction: a private key that a lookup
    starts reading later has to be added to _SECTION_VIEW_GRAPH_KEYS. Missing it
    can only make the view miss metadata. It can't make it reuse a full-graph cache.
  • Other G.subgraph(...) uses (cluster.py) do not call the serve.py search
    helpers, so they are not affected. I did not change them.

How was this tested?

tests/test_section_subgraph_index.py is new and has 6 tests, built on the issue's
synthetic graph:

  • test_non_section_query_does_not_raise[False] and [True]: the issue's query,
    cold and warm, gives the same answer as a fresh graph.
  • test_retry_does_not_replace_full_graph_index: after a retry, the full graph's
    index still covers every node, and filler 7 still resolves.
  • test_heading_still_resolves_with_warm_index: a valid heading still resolves on
    the first pass.
  • test_retry_uses_isolated_section_view: a spy on _resolve_single_node checks
    that the retry runs on exactly the section nodes, with its own .graph that
    keeps _logical_directed. It also checks that, with the full index warm, the
    view never holds the full graph's _trigram_index.
  • test_retry_drops_unknown_future_cache: a key the code doesn't know,
    _some_new_cache, is not visible on the view.

The first three fail on v8 with the issue's KeyError, and so do the two new
ones. All six pass here. On 0d7b5440, before the allowlist,
test_retry_drops_unknown_future_cache fails. The issue's repro now prints the
normal message:

Ambiguous: 'deploy' matches 2 nodes in deploy.sh.

All with PYTHONPATH set to the worktree:

.venv/bin/python -m pytest -q tests/test_section_subgraph_index.py
    v8 (3671f311)  -> 5 failed, 1 passed
    this branch    -> 6 passed
.venv/bin/python -m pytest -q tests
    v8 (3671f311)  -> 11833 passed, 122 skipped, 1 xfailed
    this branch    -> 11839 passed, 122 skipped, 1 xfailed
.venv/bin/python -m ruff check graphify/sections.py tests/test_section_subgraph_index.py
    -> All checks passed

Not tested: Windows. Nothing here builds paths.

Graphify-specific checklist

  • I updated generated skill artifacts (uv run python -m tools.skillgen --bless) when changing their source fragments. (N/A: no skill fragments touched.)
  • I confirmed that AST/structural extraction remains deterministic (no ambient state dependencies like ENV variables). (Extraction is untouched.)
  • I reviewed changes for security implications (no unsafe interpolation into shell/Python).
  • I confirmed no API keys or local-only graph data are included.
  • (If applicable) I disclosed AI authorship in my commit messages. (No trailer in the commit messages.)

@github-actions

Copy link
Copy Markdown

Thanks for the pull request, @Deepjyoti-Sarmah. A maintainer will review it soon.

Want to talk it through while it is in review? Come join us on our Discord server. For longer-form discussion there is also GitHub Discussions.

A couple of things that speed up review: make sure the test suite passes on Python 3.11 and 3.13, and that the change keeps extraction deterministic.

@github-actions github-actions Bot added the contributor Pull request from a returning community contributor label Nov 21, 2026

@graphify-labs graphify-labs Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Graphify review View in Graphify

Review before merging · Merge confidence 4/5

1 bug · 1 possible issue to check · High impact

The section resolver retries failed lookups against a graph view containing only Markdown section nodes.

P2  Non-string graph metadata keys can crash section lookup · sections.py:196

1 possible issue we couldn't confirm

They don't change the score.

Code graph · 379 functions depend on this change
  • 4 of 614 test files are affected by this change.
  • Gate, test list and every flagged function: in the Graphify check.

Reviewed 8c7af1d · 3 earlier findings not re-checked · Full report in the Graphify check

…hify-Labs#5385)

G.subgraph() shares G.graph, so the get_section retry reused the full
graph's trigram index, whose ids include nodes outside the view, and
_find_node_tiers raised KeyError. The view now gets its own graph dict
without the derived search caches.
@Deepjyoti-Sarmah
Deepjyoti-Sarmah force-pushed the fix/5385-section-subgraph-index branch from d487198 to 0d7b544 Compare November 21, 2026 23:32
Comment thread graphify/sections.py
Comment on lines +193 to +196
# caches (ids of nodes not in the view) or store its own over the full
# graph's. Keep public graph metadata and the logical direction flag, but
# discard other private state so future caches cannot leak into this view.
sections.graph = {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2  Non-string graph metadata keys can crash section lookup

A section lookup that needs the retry can raise AttributeError when the graph has a non-string metadata key.

Check that graph metadata keys are strings before calling startswith in resolve_section_query in graphify/sections.py.

Evidence · checked against the code

Expected: The resolver returns its normal section match or not-found result.
Actually: The retry’s metadata filter calls startswith on the non-string key and raises AttributeError.

  • Independent source review: The CLI caller loads a graph before calling the resolver, and the MCP caller uses its graph; these paths do not establish that all callers supply JSON-loaded graphs. The inspected tests cover retry behavior and cache isolation but do not test non-string graph metadata keys.
  • The inspected CLI and MCP call sites use graphs loaded from JSON, whose metadata keys are strings; the issue applies to callers that supply a NetworkX graph with a non-string metadata key.
  • Also reported as: Section lookup can raise an exception when the graph's metadata has a non-text key
Prompt to fix with AI
In graphify/sections.py, resolve_section_query (lines 193-196):
Problem: Non-string graph metadata keys can crash section lookup
Expected: The resolver returns its normal section match or not-found result.
Actually: The retry’s metadata filter calls `startswith` on the non-string key and raises `AttributeError`.
Fix it at the cause, and add a test that fails without the fix.

Graphify · Checked against the code · View in Graphify

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

contributor Pull request from a returning community contributor

Projects

None yet

Development

Successfully merging this pull request may close these issues.

get_section: KeyError when query falls through to section-subgraph retry (subgraph view reuses full-graph trigram index)

1 participant