# MQTT Payload Migration Checklist (One Page)

Use this checklist to migrate from legacy flat dashboard payload to grouped v2 payload.

## A. Client Implementation

- [ ] Create branch for migration work.
- [ ] Capture one baseline message from MQTT (legacy format).
- [ ] Implement one canonical payload builder function.
- [ ] Emit grouped blocks in this order: `message`, `content`, `runtime`, `metadata`.
- [ ] Add `metadata.schema_version = "2.0"`.
- [ ] Add `metadata.producer = "simclient"`.
- [ ] Add `metadata.published_at` in UTC ISO format.
- [ ] Map capture type to `metadata.capture.type` (`periodic`, `event_start`, `event_stop`).
- [ ] Map screenshot freshness to `metadata.capture.age_s`.
- [ ] Keep screenshot object unchanged in semantics (`filename`, `data`, `timestamp`, `size`).
- [ ] Keep trigger behavior unchanged (periodic and triggered sends still work).
- [ ] Add publish log fields: schema version, capture type, age.
- [ ] Validate all 3 paths end-to-end:
  - [ ] periodic
  - [ ] event_start
  - [ ] event_stop

## B. Server Migration

- [ ] Add grouped v2 parser (`message/content/runtime/metadata`).
- [ ] Add temporary legacy fallback parser.
- [ ] Normalize both parsers into one internal server model.
- [ ] Mark required fields:
  - [ ] `message.client_id`
  - [ ] `message.status`
  - [ ] `metadata.schema_version`
  - [ ] `metadata.capture.type`
- [ ] Keep optional fields tolerated (`runtime.process_health`, `content.screenshot`).
- [ ] Update dashboard consumers to use normalized model (not raw legacy keys).
- [ ] Add migration counters:
  - [ ] v2 parse success
  - [ ] legacy fallback usage
  - [ ] parse failures
- [ ] Test compatibility matrix:
  - [ ] new client -> new server
  - [ ] legacy client -> new server
- [ ] Run short soak in dev.

## C. Cutover and Cleanup

- [ ] Set v2 as primary parser path on server.
- [ ] Confirm fallback usage is near zero for agreed window.
- [ ] Remove legacy parser/fallback.
- [ ] Remove client-side temporary compatibility fields (if used).
- [ ] Keep one canonical schema sample in repo.
- [ ] Close migration ticket with final validation evidence.

## Quick Go/No-Go Gate

Go only if all are true:

- [ ] No parse failures in dev soak
- [ ] All 3 capture types visible in dashboard
- [ ] Screenshot payload integrity unchanged
- [ ] Metadata group present and complete