Refactor: Unify Node Inventory Logic between topology.py and nodes.py

[DarinShapiro]

Problem

\get_mesh_state\ and \list_all_nodes\ should remain separate external MCP tools, but they currently rebuild overlapping node facts in two different places:

• \pipeline/topology.py::build_topology()\ builds graph-oriented node rows plus links and partition summaries.
• \pipeline/nodes.py::list_nodes_enriched()\ builds inventory-oriented node rows for tables and operator inspection.

The overlap is not just conceptual. Both paths independently derive or project many of the same node-level facts:

• identity: \eui64, \riendly_name\
• placement: \�rea_name, \partition_id\
• mesh role:
  ole,
  outing_role\
• parent relationship: \parent_eui64\
• freshness/lifecycle: \last_seen, \status, \last_referenced_at\
• partition leadership context: leader discovery by
  outing_role == leader\
• phantom filtering behavior

At the same time, each tool adds different higher-level projections:

• \get_mesh_state: graph links, partition summaries, split flag, weak/error/asymmetric link tagging, graph diagnostics
• \list_all_nodes: \display_name, \device_kind, HA metadata, availability fields, router peer summaries,
  ext_hop_to_otbr, SED-specific mesh-alive fields, optional \signal_strength\

This means the public tools are correctly distinct, but the internal node snapshot logic is not centralized.

Why This Should Not Collapse Into One Public Tool

Do not merge \get_mesh_state\ and \list_all_nodes\ into one MCP tool.

They serve different consumers and payload shapes:

• \get_mesh_state\ is graph-first and should stay optimized for topology reasoning / rendering.
• \list_all_nodes\ is inventory-first and should stay optimized for table views, filtering, and operator inspection.

The refactor goal is shared internal data assembly, not API consolidation.

Current Code Anchors

• \�ddons/thread-observability/app/src/thread_observability/pipeline/topology.py\
• \�ddons/thread-observability/app/src/thread_observability/pipeline/nodes.py\

Relevant current behavior:

• \�uild_topology()\ directly queries node fields, derives \parent_eui64, computes per-node \stale, and then builds partition summaries and links.
• \list_nodes_enriched()\ starts from \store.list_nodes(), derives parent/leader/peer/OTBR-hop context, and projects a richer inventory row.

Proposed Refactor

Introduce one shared internal node snapshot builder that produces a canonical base row per visible node. Then project that base row into:

1. a graph-facing node shape for \get_mesh_state\
2. an inventory-facing row shape for \list_all_nodes\

Proposed Internal Shape

Create an internal helper or dataclass, e.g. \CanonicalNodeSnapshot, containing only the common base facts needed by both projections.

Suggested fields:

• \eui64\
• \riendly_name\
• \�rea_name\
• 
  ole\
• 
  outing_role\
• \partition_id\
• \leader_router_id\
• 
  outer_id\
• \�endor_id\
• \product_id\
• \serial_number\
• \manufacturer\
• \model\
• \device_id\
• \irst_seen\
• \last_seen\
• \status\
• \status_changed_at\
• \last_referenced_at\
• \�vailable\
• \�vailability_source\
• \�vailability_checked_at\
• \parent_eui64\
• \last_rssi\
• \last_lqi\
• \is_phantom\
• \suppressed_duplicate_euis\

Notes:

• Keep this internal shape free of graph-only artifacts like \links, \split, or edge tags.
• Keep it free of inventory-only projections like \display_name, \device_kind,
  outer_peers, or
  ext_hop_to_otbr\ unless those are computed in a second projection step.
• \stale\ in topology should likely remain a topology projection derived from \last_seen\ + \reshness_minutes, not a stored base field.

Implementation Outline

1. Extract a shared helper in \pipeline/\ for collecting canonical node rows from storage.
2. Move duplicate identity / partition / lifecycle / parent assembly into that helper.
3. Make \�uild_topology()\ consume the shared canonical rows and then add:
   • topology-specific \stale\
   • partition summaries
   • links
   • graph annotations / diagnostics
4. Make \list_nodes_enriched()\ consume the same canonical rows and then add:
   • \display_name\
   • \device_kind\
   • partition leader name
   • router peer counts / peer names
   • \parent_name\
   • 
     ext_hop_to_otbr\
   • SED-specific fields
   • optional \signal_strength\
5. Preserve existing response schemas for both tools.

Non-Goals

• No MCP tool rename.
• No contract merge between \get_mesh_state\ and \list_all_nodes.
• No dashboard behavior changes required as part of this refactor.
• No broad topology/diagnostics redesign.

Acceptance Criteria

• There is one shared internal node snapshot assembly path used by both \�uild_topology()\ and \list_nodes_enriched().
• \get_mesh_state\ response shape remains unchanged.
• \list_all_nodes\ response shape remains unchanged.
• Existing phantom filtering behavior remains intact.
• Parent resolution remains consistent across both tools.
• Partition leader derivation is not duplicated in both modules.
• Existing tests covering topology and node inventory continue to pass.
• Add focused tests for the shared helper covering:
  • phantom filtering
  • duplicate hardware collapse passthrough
  • parent derivation
  • partition/leader consistency across both projections

[DarinShapiro]

Concrete implementation plan based on current code structure:

Proposed extraction target

Introduce a shared internal helper in pipeline/nodes.py or a new sibling module such as pipeline/node_snapshot.py.

Suggested internal entry point:

`python

def build_canonical_node_snapshots(
store: SQLiteStore,
*,
include_phantoms: bool,
freshness_cutoff: str | None = None,
) -> list[dict[str, Any]]:
...
`

If a typed shape is preferred, use an internal dataclass / TypedDict, but keep the external tool payloads unchanged.

What this helper should own

This helper should centralize the base node-row assembly that is currently split across build_topology() and list_nodes_enriched():

• source node rows from storage
• collapse_duplicate_hardware_rows(...)
• phantom filtering
• parent resolution
  • prefer live neighbor_table is_child=1 relationships when available
  • otherwise fall back to latest attach / parent_change event-derived parent
• canonical identity / lifecycle / partition fields
• leader lookup inputs needed by both projections
• passthrough of duplicate-hardware suppression metadata

The canonical rows should include at least:

• eui64
• friendly_name
• area_name
• role
• routing_role
• partition_id
• leader_router_id
• router_id
• vendor_id
• product_id
• serial_number
• manufacturer
• model
• device_id
• first_seen
• last_seen
• status
• status_changed_at
• last_referenced_at
• available
• availability_source
• availability_checked_at
• parent_eui64
• last_rssi
• last_lqi
• is_phantom
• suppressed_duplicate_euis

What should stay outside the helper

These remain projection-specific and should not be baked into the canonical base rows.

build_topology() only

• stale derived from freshness_minutes
• nodes graph projection
• links
• edge classification and tags
• partitions summary
• split
• graph diagnostics

list_nodes_enriched() only

• display_name
• device_kind
• partition_leader_name
• router_peer_count
• router_peers
• parent_name
• next_hop_to_otbr
• SED-specific mesh state
• optional signal_strength

Recommended extraction order

1. Extract parent resolution first.

   • Today topology computes parent_of inline from links and event fallback.
   • Nodes uses _build_parent_map(s).
   • Unify these before anything else so both tools stop disagreeing on parent semantics.

2. Extract canonical node row assembly.

   • Replace the direct SQL-to-dict assembly in build_topology().
   • Replace the direct s.list_nodes() + collapse + per-row base field access in list_nodes_enriched().

3. Extract shared leader-by-partition derivation.

   • Both code paths currently re-scan nodes for routing_role == leader.

4. Leave link processing in topology.py.

   • This is graph-specific and should not move into the shared node helper.

5. Leave router peer / OTBR hop / SED enrichment in nodes.py.

   • These are inventory/operator projections, not canonical node facts.

Minimal first refactor slice

The smallest safe first PR for this issue is:

• add shared helper for canonical node rows
• update list_nodes_enriched() to consume it
• update build_topology() to consume it
• do not touch link-building logic yet
• do not change MCP tool schemas

Suggested tests to add

Add focused tests around the shared helper rather than only end-to-end tool tests.

Recommended coverage:

1. phantom filtering parity

   • helper returns/excludes phantom rows based on include_phantoms

2. duplicate hardware collapse parity

   • suppressed duplicate EUI list survives into both projections

3. parent derivation precedence

   • neighbor-table child relationship wins over stale event fallback

4. partition leader consistency

   • the same leader is surfaced to both topology and node inventory projections

5. topology/list parity on shared fields

   • for the same fixture, shared fields such as eui64, friendly_name, partition_id, parent_eui64, status, last_seen agree across both projections

Guardrails

• Do not merge the public tools.
• Do not add graph-only data to list_all_nodes.
• Do not add inventory-only/operator-only fields to get_mesh_state.
• Preserve current MCP contract shapes.
• Preserve current duplicate-hardware behavior.

This should be implemented as an internal deduplication/refactor issue, not a product-surface redesign.

[DarinShapiro]

Closing as duplicate of #87.

[DarinShapiro]

Reopening as the canonical detailed tracker for node inventory unification.