nx_iot_scene_sync.nx

nx_iot_scene_sync.nx -- the "lights stay in sync, self-fixing" organ. Roadmap: NISHI_IOT_HUB_ROADMAP.md Epoch 4 (SYNCHRONIZE). Closes the operator's ORIGINAL complaint -- "the lights blink and desync all the time" -- as a REPEATABLE, SELF-FIXING loop, not a one-off. THE DESYNC PROBLEM (operator, 2026-05-16 + 2026-06-20 "i still want the lights to sync that are blinking as a repeatable self fixing thing"): A scene (all lights = same colour/brightness/on) drifts apart because (a) lights get the command at slightly different times (skew), and (b) a light that drops WiFi + re-pairs comes back at its DEFAULT state -- out of sync with the rest -- and stays wrong until a human re-sets it. THE FIX (two layers, both already in the hub): 1. PREVENT skew: apply a scene ATOMICALLY -- all lights at the same tick (nx_iot_clock_master drains a scene all-or-nothing). The daemon wires that; this organ holds the SINGLE SOURCE OF TRUTH for what the scene SHOULD be. 2. SELF-FIX drift: this organ tracks, per device, which scene EPOCH it last applied. A device that dropped + healed (nx_iot_watchdog -> re-provision -> nx_iot_anchor re-adopt) is marked desynced; the loop re-applies the current desired scene to it -> back in sync. Every heal -> auto re-sync. REPEATABLE: each drop is fixed the same way, and the MEASURED `syncs_restored` counts the manual re-sets spared. WHAT THIS ORGAN IS: the pure SYNC-STATE machine. desired scene + per device applied-epoch + convergence (all_in_sync / needs_resync / resync). No network, no device writes -- the driver (kasa pt_light etc., already brick-safe) applies the computed scene; the clock master makes it atomic; the watchdog triggers the heal. Pure-buffer, so it gate-proves offline + is portable. Single-responsibility (#9): it owns "are the lights in sync, and what brings a stray one back". MEASURED-EXCEED (feedback-no-wave-measured-exceed; mirrors anchor's duplicates_prevented + watchdog's recover_count): `syncs_restored` is the count of times a drifted light was auto-pulled back to the scene -- the manual re-sets the operator did NOT have to do. The gate asserts it. genealogy_id: NISHI_IOT_HUB_ROADMAP.md Epoch 4 + project-iot-hub-multi-vendor-kickoff-2026-05-16 license_tier: ORIGINAL