Dashboard telemetry contract

This is the implementation reference for optimization dashboards. User-facing status belongs in the run hub, not in this schema.

An optimizer writes dashboard/live.json (preferred) or live.json in its run directory. Writes must use atomic replacement so browser polling cannot observe partial JSON. Schema version 2 is nested; the publisher also accepts older flat fields for historical runs.

{
  "schema_version": 2,
  "status": "running",
  "updated_at": "2026-08-15T12:00:00+00:00",
  "iteration": 4,
  "stage": "pole_validation",
  "metrics": {
    "q": 516.0,
    "mode_volume": 0.82,
    "q_over_v": 629.27,
    "wavelength_nm": 1551.4
  },
  "coupling": {
    "total_guided_fraction": 0.956,
    "forward_fraction": 0.478,
    "backward_fraction": 0.478,
    "radiation_fraction": 0.044,
    "target_total": 0.95,
    "target_per_direction": 0.475,
    "symmetry_reduced": true,
    "symmetry_factor": 2,
    "feedthrough_mode_certified": true,
    "measurement": "vector TE0 overlap on uniform-lead planes"
  },
  "optimizer": {
    "trust_step": 0.5,
    "trust_step_units": "nm RMS boundary motion",
    "decision": "accepted",
    "decision_reason": "Q improved and all gates passed",
    "degrees_of_freedom": 12480,
    "step_wall_time_seconds": 418.2,
    "wall_time_seconds": 3821.9
  },
  "artifacts": [
    {
      "label": "incumbent geometry",
      "href": "artifacts/incumbent.png",
      "kind": "geometry"
    }
  ]
}

Semantic requirements

• status must reflect the campaign state, including terminal or blocked conditions. A stale dashboard cache must not override runtime_status.json or state.json.
• Q values must identify their solver in adjacent metadata when more than one solver is present.
• total_guided_fraction means both feedthrough directions divided by total emitted power. Never put a one-sided result in that field.
• A half-domain run may report one direction only when it also sets symmetry_reduced: true and the correct symmetry_factor.
• Raw PML-exit absorption is not a certified feedthrough-mode measurement.
• Robustness corners must be physical re-solves, not first-order predictions.
• Relative artifact links must remain inside the run's dashboard/ tree so the persistent mirror can publish them.

Required visual panels for optimizations

1. objective versus accepted and attempted iteration;
2. initial and current geometry at matched axes with material legend;
3. representative tracked field with frequency, component, slice, normalization, and color scale;
4. decision history with rejected-step reasons;
5. physical-solver checkpoints, clearly separated from surrogate values.

Historical diagnostics that do not use the current geometry map or acceptance policy must be labeled and collapsed, or moved to the dashboard of the run that generated them.

Publisher

python tools/publish_hub.py refreshes the catalog and dashboard mirrors. tools/publish_online.sh builds the docs, stages the hub below the public /cavitygrad/hub/ mount, and verifies the deployed files. The user service cavitygrad-online-publisher.service performs this guarded cycle every minute.