Summary
Follow-up from #162.
The dot-key traversal proposal (NEIGHBORS-DOT-KEY-TRAVERSAL-PROPOSE.md, PR #166) solves the class-level bulk enumeration case: from a type Symbol, neighbors(class_id, 'out', ['DECLARES.DECLARES_CLIENT']) retrieves terminal Client nodes in one call, with via_id linking back to the declaring method.
It does not solve the method-list filtering case. When an agent receives a list of method NodeRefs (from neighbors(..., ['DECLARES']), find(kind="symbol"), or resolve), it still has no signal on each NodeRef about whether that method declares clients, producers, or routes — short of calling describe on each one.
When this matters
- Agent arrives at a class via
find or neighbors (not search), and calls neighbors(class_id, 'out', ['DECLARES']) to list methods before describe-ing the class
- Agent wants to filter a batch of method refs without making N
describe calls
- Agent is doing method-to-method tracing and needs to know which peer methods in a class are "interesting" for cross-service communication
Relationship to #162
#162's Option A proposed adding capabilities (already stored on each Symbol node) to NodeRef. This was deferred in favor of the dot-key approach. If method-list filtering proves to be a practical pain point, capabilities on NodeRef remains the most lightweight option:
class NodeRef(BaseModel):
...
capabilities: list[str] | None = None # e.g. ["HTTP_CLIENT", "MESSAGE_PRODUCER"]
Zero extra queries — capabilities is already stored on each Symbol row. For neighbors, the row already contains capabilities via _load_node_record. For find and resolve, one column is added to the Cypher projection.
Dependencies
None — independent of the dot-key traversal implementation. Can be evaluated once dot-key support is live to see if the remaining gap is a real pain point.
Summary
Follow-up from #162.
The dot-key traversal proposal (
NEIGHBORS-DOT-KEY-TRAVERSAL-PROPOSE.md, PR #166) solves the class-level bulk enumeration case: from a type Symbol,neighbors(class_id, 'out', ['DECLARES.DECLARES_CLIENT'])retrieves terminal Client nodes in one call, withvia_idlinking back to the declaring method.It does not solve the method-list filtering case. When an agent receives a list of method
NodeRefs (fromneighbors(..., ['DECLARES']),find(kind="symbol"), orresolve), it still has no signal on eachNodeRefabout whether that method declares clients, producers, or routes — short of callingdescribeon each one.When this matters
findorneighbors(notsearch), and callsneighbors(class_id, 'out', ['DECLARES'])to list methods beforedescribe-ing the classdescribecallsRelationship to #162
#162's Option A proposed adding
capabilities(already stored on eachSymbolnode) toNodeRef. This was deferred in favor of the dot-key approach. If method-list filtering proves to be a practical pain point,capabilitiesonNodeRefremains the most lightweight option:Zero extra queries —
capabilitiesis already stored on each Symbol row. Forneighbors, the row already contains capabilities via_load_node_record. Forfindandresolve, one column is added to the Cypher projection.Dependencies
None — independent of the dot-key traversal implementation. Can be evaluated once dot-key support is live to see if the remaining gap is a real pain point.