propose: JSON-shaped hint ids for MCP copy safety (#195)

[HumanBean17]

What

Adds propose/HINTS-MCP-JSON-IDS-PROPOSE.md for #195 (fix combo 1 + 2 + 6).

Why now

Battle testing showed agents copy Python-style neighbors(['<id>'],…) from road-sign hints into MCP ids, producing Unknown id prefix for \['']`. README/AGENT-GUIDE examples also teach misleading sym:` FQN ids while the graph stores 40-char hex symbol ids.

Highlights

• Lock JSON-shaped hint emissions ({"ids":"<id>",…}) across mcp_hints.py and EDGE_SCHEMA.typical_traversals
• AGENT-GUIDE + README + server.py ids description: hints are advisory; never "['…']" strings
• Document live id shapes (hex symbols; r:/c:/p: terminals); drop misleading sym: examples
• No ontology bump, no re-index, no runtime coercion (options 3–5 deferred)

Tests

Docs-only; baseline unchanged.

Out of scope

Implementation deferred to a follow-up PR per the propose sequencing section.

Closes #195 when implementation lands; this PR only adds the design propose.

Made with Cursor

[HumanBean17]

Critical review (propose-only PR)

Solid direction: root cause matches #195, combo 1+2+6 is the right default, and scoping out coercion / ontology bump is correct. The coordination callout with DESCRIBE-HINTS-STRUCTURAL-PROPOSE.md is valuable.

Before merging this propose (and definitely before the implementation PR), I'd tighten a few gaps that will otherwise bite the implementer.

---

1. 120-char cap is not theoretical — several locked templates will overflow

The propose defers shortening to "Open Questions" / implementation, but you can quantify this now with a realistic 40-char symbol id:

Template (label prefix)	Current (approx)	JSON canonical (approx)
routes via members:	102	122
clients in overriders:	118	138

So at least the OVERRIDDEN_BY.* override-axis strings need an explicit per-template plan (shorter label, drop label, abbreviate keys, or first-hop-only) in this propose, not left as TBD. Otherwise the implementation PR will either fail existing char-cap tests or silently weaken the road-sign contract.

Also flag templates that are already near/over cap today with optional params (TPL_NEIGHBORS_CALLS_* with edge_filter=…, structural row H with include_unresolved=True in DESCRIBE-HINTS-STRUCTURAL-PROPOSE.md) — JSON + boolean keys makes this worse.

---

2. "Entire hint surface" is only half-specified

§1 locks a neighbors JSON object shape, but the inventory still leaves copy-risk on other tools:

• TPL_FIND_EMPTY_RESOLVE — resolve(identifier, hint_kind='{kind}') (Python kwargs / single quotes)
• TPL_RESOLVE_NONE_TRY_FIND_* — filter={{path_prefix: '…'}} (Python dict + format escaping)
• TPL_RESOLVE_NONE_TRY_SEARCH — search(query='…')
• TPL_SEARCH_WEAK — find(role=…)

These are the same class of failure for agents that paste into MCP JSON (especially filter / edge_filter, which the guide already warns about for stringified JSON). Either:

• extend the canonical contract to find / resolve / search JSON fragments (even if shorter prose for empty-find), or
• narrow the scope statement to neighbors-shaped emissions + ontology typical_traversals, and explicitly defer the resolve/find/search templates.

Right now §1 says "entire" but §2 only details neighbors + docs.

---

3. Batch / fake id hints need a locked decision, not only a recommendation

TPL_NEIGHBORS_SUCCESS_HTTP_TARGETS / _ASYNC_TARGETS / _CALLERS / _HANDLER still emit client_ids, handler_ids, etc. — that's the primary copy-paste footgun for multi-row results. Open Question 1's recommended prose is good; please promote it to a normative rule in §1 (and add one example emission) so implementation doesn't re-litigate.

---

4. Cross-propose / in-flight plan sequencing

Good that you block merging structural hints on the old shape. Two more coordination notes for the implementation PR author:

• Update DESCRIBE-HINTS-STRUCTURAL-PROPOSE.md tier table (rows A–H still show neighbors(['{id}'],…)) in the same PR that lands JSON hints — your sequencing §4 says this; worth making it a checklist item under Scope.
• plans/PLAN-OVERRIDDEN-BY-DOT-KEY-TRAVERSAL.md also rewrites several of the same TPL_DESCRIBE_METHOD_* strings — call out merge order vs that plan so two branches don't fight over Appendix A locks.

---

5. Small inaccuracies / nits

• Inventory lists tests/test_java_ontology.py "(if present)" — there is no such file; drop or point at tests/test_mcp_hints.py only.
• DESCRIBE-HINTS-STRUCTURAL tier table still says "≤120 chars with realistic sym:… id" — implementation should use hex ids per §6; align that prose when you amend the structural propose.
• Consider a lightweight plans/PLAN-HINTS-MCP-JSON-IDS.md + CURSOR-PROMPTS-… for the ~23 neighbors( templates + ontology traversals + EDGE-NAVIGATION regen — repo handoff norm for this size of change.

---

Verdict

Approve the problem diagnosis and combo 1+2+6. I'd merge this propose after folding in (1) char-cap math with explicit template fallout, (2) resolve/find/search hint contract or narrowed scope, and (3) locked batch-id wording.

Implementation PR should not close #195 until templates + tests + README/AGENT-GUIDE/server descriptions land (PR body already says that — good).