docs/META_CONTRACT.md

Producer metadata contract

Every peer registers with POST /send {"type": "setPeerStatus", "roles": [...], "meta": {...}}. Central stores meta verbatim and forwards it unchanged to every owner-scoped surface: the SSE list / peerStatusChanged / sessionStateChanged frames, GET /api/robot-status and GET /api/debug/peers. Daemons may add fields at any time without a central change; clients must tolerate unknown keys.

This page lists the few keys central reads. Anything not listed is opaque to the server.

Keys interpreted by central

Key	Sent by	Server-side use
name	producer, consumer	Producer: robotName in /api/robot-status. Consumer: reported as activeApp while it holds a session. Display only.
hardware_id	producer (daemons >= v1.7.2)	Stable per-robot identity: a new registration with the same hardware_id under the same HF user evicts the older producer (last-writer-wins). Its presence also marks the daemon as heartbeat-capable, which opts it into the stale-producer sweep.
install_id	producer (reserved)	Same dedup semantics as hardware_id, checked independently. Not emitted by any shipped daemon yet.
kind	producer	Robot family, used only for the public per-kind counters (/health producers_by_kind, status page). See below.
robot_type	producer	Alias for kind, consulted only when kind is absent or empty.

Keys such as transport, release or api_version are passed through untouched and never interpreted.

kind

• Missing means Reachy Mini. Reachy Mini daemons send no kind at all (their meta is {name, transport, hardware_id}), so when neither kind nor robot_type holds a non-blank string the producer classifies as reachy_mini. A kind that is absent, null, blank or not a string falls through to robot_type.
• Known values: reachy_mini, microduck. Matching is case-insensitive and ignores every character outside a-z0-9, so Micro-Duck, micro duck, microduck, Reachy Mini, reachy-mini and reachymini all resolve to their canonical kind. A raw value longer than 64 characters is classified as other without any normalisation.
• meta must be a JSON object. A setPeerStatus whose meta is not an object is rejected with HTTP 400 and leaves the previously registered meta untouched.
• Anything else counts as other on the public counters. kind is untrusted input (any authenticated HF user can send any meta), so the public surfaces only ever expose the fixed key set {reachy_mini, microduck, other} - an unknown value can bump the other counter and nothing more. The status page labels for those keys are server-side constants; no meta string is ever rendered there.
• The raw value is still forwarded verbatim to the owner's own listeners and /api/* endpoints. Classification is a read-only view for the public counters; it never rewrites meta.

Adding a robot family is a one-line change to KNOWN_ROBOT_KINDS (and a label in ROBOT_KIND_LABELS) in app.py; the tests in test_robot_kind.py and test_routes.py pin the behaviour above.

Public counters (GET /health)

{
  "status": "healthy",
  "peers": 3,
  "producers": 2,
  "sessions": 1,
  "producers_by_kind": {"reachy_mini": 1, "microduck": 1, "other": 0},
  "started_at": "2026-09-16T08:00:00Z",
  "uptime_seconds": 12345
}

peers, producers and producers_by_kind count connected peers only. started_at / uptime_seconds are wall-clock and exist so an operator can tell a fresh redeploy (all counters reset) from a quiet fleet. Both / and /health are served with Cache-Control: no-store.