feat(neighbors): navigate OVERRIDDEN_BY.* composed edge types in one call

[HumanBean17]

Summary

• neighbors accepts four override-axis composed dot-keys (OVERRIDDEN_BY, OVERRIDDEN_BY.DECLARES_CLIENT, OVERRIDDEN_BY.DECLARES_PRODUCER, OVERRIDDEN_BY.EXPOSES) on non-static method Symbol origins with direction="out".
• Traversal uses stored [:OVERRIDES] for the dispatch hop (not signature Cypher in the read path); composed results echo the dot-key as edge_type and include via_id in attrs (except base OVERRIDDEN_BY).
• Axis-specific fail-fast gates reject mixed DECLARES.* + OVERRIDDEN_BY.* on one origin; hints/docs/README aligned with describe-time rollups.

Implements PR-OVERRIDDEN-BY-1 from plans/PLAN-OVERRIDDEN-BY-DOT-KEY-TRAVERSAL.md / propose #165.

Test plan

• .venv/bin/ruff check .
• PATH="$(pwd)/.venv/bin:$PATH" .venv/bin/python -m pytest tests -q — 686 passed, 13 skipped
• Focused: pytest tests/test_mcp_v2_compose.py tests/test_mcp_hints.py -k "overridden_by or parity_blocking or mixed_composed"
• Merge-blocking parity: test_neighbors_overridden_by_rollup_traversal_parity_blocking (all four keys; bank-chat + smoke fixture)

Manual evidence

ChatAssignmentPort.requestAssignment on bank-chat fixture:

KUZU=/tmp/ob-dotkey-evidence/code_graph.kuzu
rm -rf /tmp/ob-dotkey-evidence
.venv/bin/python build_ast_graph.py \
  --source-root tests/bank-chat-system \
  --kuzu-path "$KUZU" --verbose
# describe(mid) → OVERRIDDEN_BY / OVERRIDDEN_BY.DECLARES_CLIENT out counts
# neighbors_v2(mid, direction='out', edge_types=['OVERRIDDEN_BY.DECLARES_CLIENT']) → len(results) matches

OVERRIDDEN_BY: edge_summary out=1 neighbors len=1 match=True
OVERRIDDEN_BY.DECLARES_CLIENT: edge_summary out=1 neighbors len=1 match=True

No ontology bump / re-index (read-path only).

Made with Cursor

[HumanBean17]

Critical review

Verdict: Solid, plan-aligned implementation. Approve with comments — the main concern is describe/traversal using different dispatch logic, not test or doc gaps in this PR.

What works well

• Contract symmetry (#162 / #165): Four OVERRIDDEN_BY* keys are valid edge_types; results echo the dot-key; composed rows carry via_id; base OVERRIDDEN_BY has empty attrs; mixed DECLARES.* + OVERRIDDEN_BY.* fail fast with axis-specific messages.
• Read-path design: override_axis_traversal_for mirrors member_edge_traversal_for (untyped [e] + label(e) filter), uses stored [:OVERRIDES] for dispatch, and exports OVERRIDE_AXIS_COMPOSED_EDGE_TYPES for partition logic.
• Tests: Base hop parity (out/OVERRIDDEN_BY ≡ in/OVERRIDES), merge-blocking edge_summary ↔ neighbors counts, origin gates, hint single-call templates.
• Docs/MCP: README, AGENT-GUIDE, EDGE-NAVIGATION, server.py descriptions aligned; stored vs virtual direction documented.

High — describe counts vs traversal use different dispatch logic

Path	Dispatch hop
describe → override_axis_rollup_for	IMPLEMENTS|EXTENDS + signature
neighbors → override_axis_traversal_for	stored [:OVERRIDES]

Parity tests prove equality on fixtures only. On a partial/stale index, describe can advertise out > 0 while neighbors returns fewer rows — agents following edge_summary/hints would see a silent contract break.

Follow-up (not necessarily blocking this PR): align rollup dispatch to stored [:OVERRIDES], add a regression when stored/signature diverge, or document that parity assumes a complete ontology-13+ index.

Medium

1. Parity parametrization gap: test_neighbors_overridden_by_rollup_traversal_parity_blocking does not run OVERRIDDEN_BY.DECLARES_CLIENT on override_axis_graph (only bank-chat + smoke for other keys). Plan called for smoke on all four.
2. Gate error UX: Static methods (and constructors) get the same message as wrong node kind (require a method Symbol origin). Consider “non-static method” / constructor-specific wording.
3. ComposedEdgeType literals still duplicated vs kuzu_queries registry (#172 follow-up).

Low / nits

• Move propose/plan to completed on merge.
• Default limit=25 can truncate large composed result sets (pre-existing for DECLARES.*); optional doc note.

Pre-merge checklist (optional)

• Ticket or doc the rollup vs traversal dual-path risk
• Add smoke to parity param for OVERRIDDEN_BY.DECLARES_CLIENT if fixture has non-zero rollup
• Sharpen static/constructor rejection messages

No re-index / ontology bump concerns for this read-path change.