chore(firmware): mark TODOs for the dev-only 60s polling cap

Three cross-referenced markers — config.h, operation.h, and FW-10 in the
test file — calling out that the FETCH_INTERVAL_MS cap is intentionally
holding the polling rate at 1 minute for dev iteration. Once the firmware
is stable and we want the device to honor the app's per-frame
rotationIntervalMinutes / wakeHour settings, the cap in operation.h
becomes a sanity-clamp (e.g., 30 s ≤ sleep ≤ 25 h) and the no-header
fallback splits into its own constant.

Behavior unchanged — comments only.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/config.h

@@ -123,6 +123,18 @@
 #define AP_IP             "192.168.4.1"
 #define WIFI_TIMEOUT_MS   30000
 #ifndef FETCH_INTERVAL_MS
-#define FETCH_INTERVAL_MS 60000   // 1 min deep sleep between polls
+// TODO(post-dev): drop the 60s cap. Today this value is used in
+// operation.h as BOTH the no-header fallback AND the upper bound that
+// clamps the server-provided X-Interval-Ms. While we're iterating on the
+// firmware we want the frame to poll every minute so changes land fast,
+// but in production we want to honor whatever the app sends (e.g.,
+// rotationIntervalMinutes=60 → 1 hour, or wakeHour set → ~24 h sleep).
+// When the firmware stabilizes, split this into two constants:
+//   - FETCH_INTERVAL_MS_FALLBACK (used when no X-Interval-Ms header)
+//   - SLEEP_CLAMP_MIN_MS / SLEEP_CLAMP_MAX_MS (sanity bounds, not the
+//     primary schedule)
+// and let server values flow through. See operation.h:138 for the cap
+// site, and tests FW-09/FW-10 for the assertions that will need updating.
+#define FETCH_INTERVAL_MS 60000   // 1 min deep sleep between polls (DEV value)
 #endif
 #define IMAGE_PATH        "/img.bin"

src/operation.h

@@ -131,6 +131,15 @@ void normal_operation_impl(const String& mac, HTTP& http, const String& url, Pre
     http.collectHeaders(collectHeaders, 3);
     int code = http.GET();
 
+    // TODO(post-dev): trust the server's X-Interval-Ms instead of capping
+    // it at FETCH_INTERVAL_MS. The cap is here so the dev unit polls
+    // every minute regardless of what the app's rotationIntervalMinutes /
+    // wakeHour settings say — fast iteration. Once the firmware is stable
+    // and we want real battery life on V2, the line below should become
+    // simply `sleepMs = v;` plus a sanity clamp (e.g. min 30 s, max 25 h).
+    // Tests FW-09 and FW-10 in test_normal_operation/test_main.cpp lock
+    // the current behavior — update them when removing the cap. See the
+    // matching note in config.h on FETCH_INTERVAL_MS.
     uint64_t sleepMs = FETCH_INTERVAL_MS;
     String intervalHdr = http.header("X-Interval-Ms");
     if (intervalHdr.length() > 0) {

test/test_normal_operation/test_main.cpp

@@ -271,7 +271,12 @@ void test_fw09_server_interval_honored() {
     TEST_ASSERT_EQUAL_UINT64(30000ULL * 1000ULL, g_sleep_us);
 }
 
-// FW-10: server interval > FETCH_INTERVAL_MS → capped at ceiling
+// FW-10: server interval > FETCH_INTERVAL_MS → capped at ceiling.
+// TODO(post-dev): when the cap in operation.h is removed (so the device
+// honors the app's rotationIntervalMinutes / wakeHour settings), this
+// test should flip to assert sleepMs == 999999999 (or whatever the
+// server-side max is, e.g. 25 h clamp). See operation.h:~140 and the
+// matching TODO in config.h on FETCH_INTERVAL_MS.
 void test_fw10_server_interval_capped() {
     g_http_response_headers["X-Interval-Ms"] = "999999999";
     g_http_response_headers["X-Image-Id"] = "1";