propose: neighbors dot-key traversal for DECLARES.* composed keys

[HumanBean17]

What

Adds propose/NEIGHBORS-DOT-KEY-TRAVERSAL-PROPOSE.md — design proposal for making neighbors accept the DECLARES.* composed dot-keys that edge_summary already surfaces.

Why now

Addresses #162. Current agent workflow requires 15+ describe calls to discover which methods in a class declare clients/producers/routes. The dot-key approach collapses that to a single neighbors call after describe.

Highlights

• neighbors accepts DECLARES.DECLARES_CLIENT, DECLARES.DECLARES_PRODUCER, DECLARES.EXPOSES as edge_types
• Single 2-hop Cypher per dot-key (no N+1); query shape already exists in member_edge_rollup_for
• edge_type echoes the dot-key; via_id in attrs identifies the intermediate method
• No re-index, no ontology bump, no graph schema change
• OVERRIDDEN_BY.* family deferred to #165

Tests

Docs-only; baseline unchanged.

Out of scope

• Implementation (single follow-up PR)
• OVERRIDDEN_BY.* dot-keys (#165)
• NodeRef schema changes (superseded by this approach)

Made with Cursor

[HumanBean17]

Critical review

Verdict: Approve the propose direction, with amendments before the implementation PR.

The design is sound, grounded in existing code, and a better fit than #162’s NodeRef.capabilities approach. CI is green (docs-only). Main gaps: scope completeness, locking open decisions, and explicitly documenting a deliberate reversal of an earlier invariant.

---

What’s strong

1. Correct pivot from #162 — Reusing edge_summary dot-keys and making them traversable is coherent: “what describe counts, neighbors can walk,” without widening every NodeRef.
2. Technically accurate Cypher — The 2-hop shape matches member_edge_rollup_for in kuzu_queries.py (same DECLARES → member → terminal rel pattern; only RETURN changes from count(e) to rows).
3. No re-index / no ontology bump — Correct: read-only query paths over existing edges.
4. Edge result model — Echoing the dot-key in edge_type, origin_id = class, via_id in attrs, terminal other = Client/Producer/Route avoids implying a fake 1-hop edge from the type.
5. Scoped deferral of OVERRIDDEN_BY.* — Matches describe-time dispatch computation; linking to #165 is right.
6. Test plan — Named tests, mixed flat/composed, inbound rejection, regression guard — good handoff for implementation.

---

Critical issues (address in propose or implementation scope)

1. Reverses a landed design decision — say so explicitly

propose/completed/DESCRIBE-MEMBER-EDGE-ROLLUP-PROPOSE.md and PR-89 intentionally rejected dot-keys in neighbors via EdgeType (decision #11: “read-only by construction”). Today that’s enforced in mcp_v2.py comments and tests like test_neighbors_rejects_overridden_by_and_dot_keys.

Add a short “Decision reversal” section: which prior decision is superseded, why (DECLARES.* is a stored 2-hop walk; OVERRIDDEN_BY.* stays describe-only), and that MCP-FILTER-FRAME UC18-style guidance becomes obsolete for the three DECLARES.* keys only.

2. Implementation scope is incomplete for agent-facing behavior

Scope lists mcp_v2.py, README.md, EDGE-NAVIGATION.md but not:

File	Why it matters
docs/AGENT-GUIDE.md	Still says composed keys are not valid in neighbors and documents the 2-hop manual walk
mcp_hints.py	TPL_DESCRIBE_TYPE_CLIENTS_VIA_MEMBERS / TPL_DESCRIBE_TYPE_ROUTES_VIA_MEMBERS still prescribe DECLARES → per-member hops
server.py	describe / neighbors tool description= strings are part of the MCP contract

If hints and AGENT-GUIDE stay on the old recipe after implementation, agents will keep doing 15+ hops despite the new API.

Recommendation: Add docs/AGENT-GUIDE.md, mcp_hints.py, and server.py to scope; add a hint test update.

3. Open Questions should be closed in the propose

Four items are marked [TBD] but each already has a Recommended answer. Lock decisions #1–#3 now so the implementation PR isn’t a second design review. #4 (NodeFilter on terminal node): one-line “locked: yes, same as flat neighbors.”

4. #162 is only partially solved — workflow claim is slightly overstated

Dot-keys help when the agent has a type id and wants clients/producers/routes in one call (with via_id to map back to methods). They do not add signals on method rows returned from neighbors(..., ['DECLARES']).

The “17+ → 3 calls” story assumes describe(class_id) first. Agents that reach the class via find / search without describe won’t see counts unless they know to call the dot-key without prompting.

Recommendation: Add a paragraph: solves class-level bulk enumeration and via_id back-links; does not replace per-method capabilities on NodeRef for method-list filtering.

5. Origin kind constraint is unspecified

member_edge_rollup_for only runs for type symbols. If an agent passes a method id with DECLARES.DECLARES_CLIENT, the query likely returns empty with no explanation.

Recommendation: Spec that v1 dot-keys require a type Symbol origin; return a clear validation error for method/route/client/producer origins.

6. Align with edge-row counting semantics

AGENT-GUIDE documents that composed counts are edge rows, not distinct methods. The propose should require:

• Unfiltered len(neighbors(..., dot-key)) aligns with edge_summary[dot-key].out for the same origin
• Duplicate other.id with different via_id is expected
• Note limit / offset interaction (empty page + non-zero edge_summary possible)

7. Cypher RETURN should match flat neighbors attrs

Sample Cypher only returns confidence and strategy. Flat neighbors_v2 also projects match, mechanism, annotation, etc. Implementation should reuse the same column set on terminal rel e or document omissions (brownfield client edges often need strategy for hints).

---

Smaller notes

• Branch name vs file name mismatch is cosmetic.
• EDGE-NAVIGATION.md type_subject lines should add the one-call dot-key alternative (in scope — good).
• On implement: split tests — accept DECLARES.*, still reject OVERRIDDEN_BY / OVERRIDDEN_BY.*.
• Sync DECLARES.DECLARES_PRODUCER in hints/docs wherever client/route are mentioned.

---

Merge recommendation

Aspect	Recommendation
PR #166 (propose doc)	Merge after amendments above (or fast follow-up on same branch).
Implementation PR	Proceed once scope includes hints + agent guide; treat as deliberate API contract change.