feat(hints): v4 success-path neighbors road signs (N1a–N7)

[HumanBean17]

Summary

Implements PR-HINTS-V4-A (plans/PLAN-HINTS-V4.md § PR-A) per propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md (locked).

• Adds v4 non-empty neighbors success-path catalog N1a–N7 in mcp_hints.py: neighbors_success_hints() + N2–N7 templates; N1a/N1b alias TPL_DESCRIBE_TYPE_*_VIA_MEMBERS verbatim with {id} = echoed origin_id.
• Gates: success, non-empty results, offset == 0, exactly one requested_edge_types entry, homogeneous other endpoints, 120-char cap per rendered string.
• Dot-key filter split: _filter_neighbors_dotkey_hints applies to empty structural pairs only; success-path N1a/N1b may emit DECLARES.DECLARES_CLIENT / DECLARES.EXPOSES.
• Lossy N1a/N1b: both fire whenever type Symbol + homogeneous method/constructor DECLARES out page holds — no edge_summary gate (same as propose Open Q1).
• No re-index, no ontology bump, no mcp_v2.py changes.

Test plan

• .venv/bin/ruff check .
• .venv/bin/python -m pytest tests/test_mcp_hints.py -v -k "hints_neighbors or hints_all_v4 or hv20 or v2_declares_success"
• .venv/bin/python -m pytest tests -v (with .venv/bin on PATH for CLI entry point)
• Required round-trip: test_hints_neighbors_v2_declares_success_emits_dot_key_clients
• HV20 narrowed to empty payloads; test_hints_neighbors_success_may_emit_declares_dot_keys added

Made with Cursor

[HumanBean17]

Review summary

Verdict: Approve — matches locked PR-A / propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md; the risky wiring is correct.

What looks good

• Dot-key filter split is the critical detail: _filter_neighbors_dotkey_hints applies only to empty_pairs; success-path N1a/N1b correctly bypass it.
• Contract fidelity: gates (success, non-empty results, offset == 0, single requested_edge_types, homogeneous other, flat type subject_record for N1a/N1b) match the propose; N1a/N1b reuse describe templates verbatim.
• Tests: per-template N2–N7 coverage, mixed-endpoint silence, offset suppression, cap vs fuzzy, HV20 scope split + complement test, and the required neighbors_v2 round-trip on kuzu_graph (guards the flat-row vs NodeRecord footgun).
• Scope: hints-only; no ontology / graph / mcp_v2 churn — appropriate.

Accepted tradeoffs (documented in propose)

• Lossy N1a/N1b: both fire whenever homogeneous method/constructor targets hold — intentional (Open Q1).
• N4 may often dead-end after EXPOSES → handlers — ship anyway per Open Q2.

Minor nits (non-blocking)

1. Char cap asymmetry: _append_neighbors_success_hint drops N1a/N1b when rendered length > 120 (long origin_id), while describe has no equivalent cap on the same templates. Rare in practice; worth knowing if traces show silent neighbors hints on huge FQCNs.
2. Missing negative tests (optional follow-up): len(requested_edge_types) > 1 → silence; DECLARES from method (non-type) origin → no N1a/N1b.
3. MCP_HINTS_FIELD_DESCRIPTION: still only documents empty structural dot-key prohibition; success-path type-origin dot-keys are propose-intentional but invisible in the schema string alone.

No blockers from my side — nice work on the filter split and the round-trip test.