Skip to content

NodeRef lacks per-method edge-presence signals for method-list filtering #167

@HumanBean17

Description

@HumanBean17

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions