infoscreen/TV_POWER_HANDOFF_SERVER.md

Server Handoff: TV Power Coordination

Purpose

Implement server-side MQTT power intent publishing so clients can keep TVs on across adjacent events and power off safely after schedules end.

Source of Truth

• Shared full plan: TV_POWER_COORDINATION_TASKLIST.md

Scope (Server Team)

• Scheduler-to-intent mapping
• MQTT publishing semantics (retain, QoS, expiry)
• Conflict handling (group vs client)
• Observability for intent lifecycle

MQTT Contract (Server Responsibilities)

Topics

• Primary (per-client): infoscreen/{client_id}/power/intent
• Optional (group-level): infoscreen/groups/{group_id}/power/intent

Delivery Semantics

• QoS: 1
• retained: true
• Always publish UTC timestamps (ISO 8601 with Z)

Intent Payload (v1)

{
  "schema_version": "1.0",
  "intent_id": "uuid-or-monotonic-id",
  "issued_at": "2026-03-31T12:00:00Z",
  "expires_at": "2026-03-31T12:10:00Z",
  "target": {
    "client_id": "optional-if-group-topic",
    "group_id": "optional"
  },
  "power": {
    "desired_state": "on",
    "reason": "event_window_active",
    "grace_seconds": 30
  },
  "event_window": {
    "start": "2026-03-31T12:00:00Z",
    "end": "2026-03-31T13:00:00Z"
  }
}

Required Behavior

Adjacent/Overlapping Events

• Never publish an intermediate off intent when windows are contiguous/overlapping.
• Maintain continuous desired_state=on coverage across adjacent windows.

Reconnect/Restart

• On scheduler restart, republish effective retained intent.
• On event edits/cancellations, replace retained intent with a fresh intent_id.

Conflict Policy

• If both group and client intent exist: per-client overrides group.

Expiry Safety

• expires_at must be set for every intent.
• Server should avoid publishing already-expired intents.

Implementation Tasks

1. Add scheduler mapping layer that computes effective desired_state per client timeline.
2. Add intent publisher with retained QoS1 delivery.
3. Generate unique intent_id for each semantic transition.
4. Emit issued_at/expires_at and event_window consistently in UTC.
5. Add group-vs-client precedence logic.
6. Add logs/metrics for publish success, retained payload age, and transition count.
7. Add integration tests for adjacent events and reconnect replay.

Acceptance Criteria

1. Adjacent events do not create OFF gap intents.
2. Fresh client receives retained intent after reconnect and gets correct desired state.
3. Intent payloads are schema-valid, UTC-formatted, and include expiry.
4. Publish logs and metrics allow intent timeline reconstruction.

Operational Notes

• Keep intent publishing idempotent and deterministic.
• Preserve backward compatibility while clients run in hybrid mode.