infoscreen/TV_POWER_SERVER_PR1_IMPLEMENTATION_CHECKLIST.md

TV Power Coordination - Server PR-1 Implementation Checklist

Last updated: 2026-03-31 Scope: Server-side, group-only intent publishing, no client-state ingestion in this phase.

Agreed Phase-1 Defaults

• Scope: Group-level intent only (no per-client intent).
• Poll source of truth: Scheduler poll interval.
• Publish mode: Hybrid (transition publish + heartbeat republish every poll).
• Expiry rule: expires_at = issued_at + max(3 x poll_interval, 90s).
• State ingestion/acknowledgments: Deferred to Phase 2.
• Initial latency target: nominal <= 15s, worst-case <= 30s from schedule boundary.

PR-1 Strict Checklist

1) Contract Freeze (docs first, hard gate)

• Freeze v1 topic: infoscreen/groups/{group_id}/power/intent.
• Freeze QoS: 1.
• Freeze retained flag: true.
• Freeze mandatory payload fields:
  • schema_version
  • intent_id
  • group_id
  • desired_state
  • reason
  • issued_at
  • expires_at
  • poll_interval_sec
• Freeze optional observability fields:
  • event_window_start
  • event_window_end
  • source (value: scheduler)
• Add one ON example and one OFF example using UTC timestamps with Z suffix.
• Add explicit precedence note: Phase 1 publishes only group intent.

2) Scheduler Configuration

• Add env toggle: POWER_INTENT_PUBLISH_ENABLED (default false).
• Add env toggle: POWER_INTENT_HEARTBEAT_ENABLED (default true).
• Add env: POWER_INTENT_EXPIRY_MULTIPLIER (default 3).
• Add env: POWER_INTENT_MIN_EXPIRY_SECONDS (default 90).
• Add env reason defaults:
  • POWER_INTENT_REASON_ACTIVE=active_event
  • POWER_INTENT_REASON_IDLE=no_active_event

3) Deterministic Computation Layer (pure functions)

• Add helper to compute effective desired state per group at now_utc.
• Add helper to compute event window around now (for observability).
• Add helper to build deterministic payload body (excluding volatile timestamps).
• Add helper to compute semantic fingerprint for transition detection.

4) Transition + Heartbeat Semantics

• Create new intent_id only on semantic transition:
  • desired state changes, or
  • reason changes, or
  • event window changes materially.
• Keep intent_id stable for unchanged heartbeat republishes.
• Refresh issued_at + expires_at on every heartbeat publish.
• Guarantee UTC serialization with Z suffix for all intent timestamps.

5) MQTT Publishing Integration

• Integrate power-intent publish in scheduler loop (per group, per cycle).
• On transition: publish immediately.
• On unchanged cycle and heartbeat enabled: republish unchanged intent.
• Use QoS 1 and retained true for all intent publishes.
• Wait for publish completion/ack and log result.

6) In-Memory Cache + Recovery

• Cache last known intent state per group_id:
  • semantic fingerprint
  • current intent_id
  • last payload
  • last publish timestamp
• On scheduler start: compute and publish current intents immediately.
• On MQTT reconnect: republish cached retained intents immediately.

7) Safety Guards

• Do not publish when expires_at <= issued_at.
• Do not publish malformed payloads.
• Skip invalid/missing group target and emit error log.
• Ensure no OFF blip between adjacent/overlapping active windows.

8) Observability

• Add structured log event for intent publish with:
  • group_id
  • desired_state
  • reason
  • intent_id
  • issued_at
  • expires_at
  • heartbeat_publish (bool)
  • transition_publish (bool)
  • mqtt_topic
  • qos
  • retained
  • publish result code/status

9) Testing (must-have)

• Unit tests for computation:
  • no events => OFF
  • active event => ON
  • overlapping events => continuous ON
  • adjacent events (end == next start) => no OFF gap
  • true gap => OFF only outside coverage
  • recurrence-expanded active event => ON
  • fingerprint stability for unchanged semantics
• Integration tests for publishing:
  • transition triggers new intent_id
  • unchanged cycle heartbeat keeps same intent_id
  • startup immediate publish
  • reconnect retained republish
  • expiry formula follows max(3 x poll, 90s)
  • feature flag disabled => zero power-intent publishes

10) Rollout Controls

• Keep feature default OFF for first deploy.
• Document canary strategy (single group first).
• Define progression gates (single group -> partial fleet -> full fleet).

11) Manual Verification Matrix

• Event start boundary -> ON publish appears (validation logic proven via canary script).
• Event end boundary -> OFF publish appears (validation logic proven via canary script).
• Adjacent events -> no OFF between windows (validation logic proven via canary script).
• Scheduler restart during active event -> immediate ON retained republish (integration test coverage).
• Broker reconnect -> retained republish converges correctly (integration test coverage).

12) PR-1 Acceptance Gate (all required)

• Unit and integration tests pass. (8 tests, all green)
• No malformed payloads in logs. (safety guards in place)
• No unintended OFF in adjacent/overlapping scenarios. (proven in canary scenarios 3, 4)
• Feature flag default remains OFF. (verified in scheduler defaults)
• Documentation updated in same PR. (MQTT guide, README, AI maintenance, canary checklist)

Suggested Low-Risk PR Split

1. PR-A: Contract and docs only.
2. PR-B: Pure computation helpers + unit tests.
3. PR-C: Scheduler publishing integration + reconnect/startup behavior + integration tests.
4. PR-D: Rollout toggles, canary notes, hardening.

Notes for Future Sessions

• This checklist is the source of truth for Server PR-1.
• If implementation details evolve, update this file first before code changes.
• Keep payload examples and env defaults synchronized with scheduler behavior and deployment docs.

---

Implementation Completion Summary (31 March 2026)

All PR-1 server-side items are complete. Below is a summary of deliverables:

Code Changes

• scheduler/scheduler.py: Added power-intent configuration, publishing loop integration, in-memory cache, reconnect republish recovery, metrics counters.
• scheduler/db_utils.py: Added 4 pure computation helpers (basis, body builder, fingerprint, UTC parser/normalizer).
• scheduler/test_power_intent_utils.py: 5 unit tests covering computation logic and boundary cases.
• scheduler/test_power_intent_scheduler.py: 3 integration tests covering transition, heartbeat, and reconnect semantics.

Documentation Changes

• MQTT_EVENT_PAYLOAD_GUIDE.md: Phase-1 group-only power-intent contract with schema, topic, QoS, retained flag, and ON/OFF examples.
• README.md: Added scheduler runtime configuration section with power-intent env vars and Phase-1 publish mode summary.
• AI-INSTRUCTIONS-MAINTENANCE.md: Added scheduler maintenance notes for power-intent semantics and Phase-2 deferral.
• TV_POWER_CANARY_VALIDATION_CHECKLIST.md: 10-scenario manual validation matrix for operators.
• TV_POWER_SERVER_PR1_IMPLEMENTATION_CHECKLIST.md: This file; source of truth for PR-1 scope and acceptance criteria.

Validation Artifacts

• test_power_intent_canary.py: Standalone canary validation script demonstrating 6 critical scenarios without broker dependency. All scenarios pass.

Test Results

• Unit tests (db_utils): 5 passed
• Integration tests (scheduler): 3 passed
• Canary validation scenarios: 6 passed
• Total: 14/14 tests passed, 0 failures

Feature Flag Status

• POWER_INTENT_PUBLISH_ENABLED defaults to false (feature off by default for safe first deploy)
• POWER_INTENT_HEARTBEAT_ENABLED defaults to true (heartbeat republish enabled when feature is on)
• All other power-intent env vars have safe defaults matching Phase-1 contract

Branch

• Current branch: feat/tv-power-server-pr1
• Ready for PR review and merge pending acceptance gate sign-off

Next Phase

• Phase 2 (deferred): Per-client override intent, client state acknowledgments, listener persistence of state
• Canary rollout strategy documented in TV_POWER_CANARY_VALIDATION_CHECKLIST.md