API: define network_health and placement_candidates contracts for UI and AI reasoning

[DarinShapiro]

Parent epic: #121

Problem

Even with a strong scoring model, the product still needs a stable API contract so the frontend and AI can consume the same health facts without re-deriving them. The contract must support both visualization and recommendation workflows.

Goal

Define the response shape for deterministic network-health and recommendation endpoints or payload sections, including enough detail for:

• summary cards and health bands
• topology visualization overlays
• ranked weak links and bottlenecks
• AI explanation and remediation suggestions
• future what-if placement simulation

Proposed API surfaces

At minimum, specify contracts for:
1.
etwork_health
2. placement_candidates

If the design prefers embedding these in an existing endpoint instead of adding new endpoints, the issue should still define the payload schemas as explicit contracts.

etwork_health must support

Summary

• overall score
• health band
• confidence score
• computed_at / as_of timestamps
• data freshness summary

Component scores

• redundancy score
• path-diversity score
• link-quality score
• bottleneck score
• partition-risk score
• end-device health summary

Node-level details

For each relevant node, include fields such as:

• node identifier and friendly name
• role / node type
• router strong-neighbor count
• usable-neighbor count
• alternate-path count
• parent quality for end devices
• bottleneck / articulation indicators
• health band and reason codes

Edge-level details

For each important edge, include fields such as:

• source and target ids
• normalized edge quality score
• classification band
• contributing metrics
• freshness
• whether the edge is a bridge or near-critical connector

Ranked findings

• weakest links
• most fragile routers
• articulation points
• clusters with poor interconnect quality
• nodes affected by stale or low-confidence observations

placement_candidates must support

For each candidate placement or recommendation, include:

• candidate id
• location descriptor or abstract placement label
• recommendation type, e.g. mains-powered Thread router
• why this type is recommended
• estimated score delta
• estimated redundancy/path-diversity improvement
• nodes or regions helped
• bottlenecks reduced
• assumptions and confidence

The contract should make it possible for the AI to say things like: a mains-powered Thread outlet or plug near location X would likely create an alternate path for devices A, B, and C and reduce dependence on router Y.

Cross-cutting contract rules

• Separate deterministic computed facts from human-readable explanation text.
• Include machine-readable reason codes and structured evidence references.
• Include explicit unknown/stale states rather than silently omitting data.
• Preserve stable field names suitable for frontend and prompt consumption.
• Keep transformation/business logic in the backend; the UI should only render.

Example payloads required

• one healthy mesh response
• one degraded mesh response with bottleneck and weak bridge findings
• one placement-candidate response with at least two ranked recommendations

Acceptance criteria

• The issue body or linked design doc defines explicit JSON payload shapes.
• The contract supports both frontend rendering and AI reasoning without additional client-side computation.
• Unknown, stale, and low-confidence states are represented explicitly.
• Placement recommendations contain enough structure to justify why a router class and placement zone were suggested.
• The contract is compatible with replay fixtures and future floorplan-aware extensions.

Out of scope

• Full spatial inference implementation
• UI component design details
• The final recommendation model for exact physical coordinates

[DarinShapiro]

Draft API contract is now in-repo at documentation/12-network-health-api-contract.md, paired with the scoring spec in documentation/11-network-health-scoring-spec.md so payload design stays aligned with deterministic formulas and reason codes.