plan: neighbors DECLARES.* dot-key traversal

[HumanBean17]

Summary

Planning only in this PR — adds execution plan and Cursor handoff for issue #162. No runtime or test code changes.

• plans/PLAN-NEIGHBORS-DOT-KEY-TRAVERSAL.md
• plans/CURSOR-PROMPTS-NEIGHBORS-DOT-KEY-TRAVERSAL.md

Implementation follows on branch feat/neighbors-dot-key-traversal (single PR): make neighbors accept DECLARES.DECLARES_CLIENT, DECLARES.DECLARES_PRODUCER, and DECLARES.EXPOSES as 2-hop traversals from type Symbols; no ontology bump or re-index.

Test plan

• Docs/planning only — no code changes
• Reviewer: confirm plan matches propose/NEIGHBORS-DOT-KEY-TRAVERSAL-PROPOSE.md

[HumanBean17]

Review — plan PR (approve with nits)

Verdict: Approve this planning PR after fixing the PR description. The plan and Cursor prompt are strong, faithful to propose/NEIGHBORS-DOT-KEY-TRAVERSAL-PROPOSE.md, and appropriately scoped as a single implementation PR. CI is fine for docs-only.

---

Must-fix (PR metadata)

1. PR description contradicts itself

• Summary describes the implementation PR (“make neighbors accept …”).
• Test plan says “Docs/planning only — no code changes” (checked).

For this PR, the test plan is correct. Suggest clarifying the summary, e.g. “Planning only in this PR; implementation follows on feat/neighbors-dot-key-traversal.”

2. Manual evidence snippet is broken

CURSOR-PROMPTS-NEIGHBORS-DOT-KEY-TRAVERSAL.md imports BANK_KUZU_PATH from tests.conftest, which does not exist (conftest exposes kuzu_graph / kuzu_db_path). Fix before the feat PR copy-pastes it.

---

Gaps to tighten before / during implementation PR

Missing test file in handoff

The plan only mentions splitting test_neighbors_rejects_overridden_by_and_dot_keys in test_mcp_v2_compose.py, but tests/test_mcp_v2.py also has test_neighbors_rejects_composed_edge_summary_key — add @tests/test_mcp_v2.py to the Cursor attach list and plan §8.

Shared rel map

Plan says “mirror member_edge_rollup_for” but doesn’t require a single shared constant/tuple for both rollup and traversal. Recommend extracting one map used by both methods to prevent drift (parity test helps, but DRY is cheaper).

requested_edge_types echo

Plan says echo the full request including dot-keys; today neighbors_v2 uses list(labels) (flat only). Worth an explicit step in the refactor list so it isn’t dropped.

Minor: merge order (flat vs composed) before offset/limit is unspecified — fine if tests only check membership; one sentence in the plan would avoid review bikeshedding.

---

Strengths (keep as-is)

• Clear partial reversal of HINTS-ROAD-SIGNS plan: Tier 1B (B2b + B6) plan + per-PR Cursor prompts #11 for three TPL_DESCRIBE_TYPE_*_VIA_MEMBERS only, while preserving _filter_neighbors_dotkey_hints / HV20.
• Count parity test + shared rel map mitigation targets the highest-risk bug.
• v1 guardrails (type origin, out only, OVERRIDDEN_BY* still rejected at validation, via_id in attrs, dot-key in Edge.edge_type) match current describe semantics.
• Shorter hint templates should stay within the ≤120-char parametrized test more easily than the current two-hop then strings.

---

Bottom line: Merge the plan after fixing the PR body and manual-evidence snippet; optional plan tweaks (test_mcp_v2.py, shared rel map) will make the feat PR smoother.