From bb20eea19163a9ce6f01ad1221438c89e8b97695 Mon Sep 17 00:00:00 2001 From: Marc Billow Date: Mon, 10 Aug 2026 10:16:00 +0000 Subject: [PATCH] laundry: a payload sitting there is not evidence of when it got there The Download-course candidate came from "Course_ read while a non-sentinel one-time payload is loaded". On the first rep after any restart that is indistinguishable from a payload left over from a previous run, so an appliance holding cloud payloads while sitting on an ordinary course proposed that ordinary course as the Download one. Accepting the prefill would then make selecting a downloaded program start, say, a cotton wash. Only a transition actually watched counts now. "Never observed" is a distinct state from "observed, nothing loaded" -- absent-then-loaded is a genuine selection and still counts -- so a restored store deliberately re-enters the unobserved state, since a restart cannot tell the two apart. Payloads are still learned from that first rep either way; which programs exist is device fact regardless of when they were loaded. It is only the inference about which course means Download that needs the timing. Both corpus dumps taken off the Download course show the appliance clearing its one-time token to the FFFF sentinel, so this may never fire on these boards. That is a reason to expect them to behave, not to depend on it. --- custom_components/localthings/cloudcourse.py | 24 +++++++++++-- docs/investigations/download-cycle.md | 22 ++++++++---- tests/test_cloud_courses.py | 38 +++++++++++++++++++- tests/test_cloud_courses_flow.py | 22 +++++++++++- 4 files changed, 95 insertions(+), 11 deletions(-) diff --git a/custom_components/localthings/cloudcourse.py b/custom_components/localthings/cloudcourse.py index bf91647..70fdaac 100644 --- a/custom_components/localthings/cloudcourse.py +++ b/custom_components/localthings/cloudcourse.py @@ -83,6 +83,11 @@ RAW_PREFIX = "cloud:" # its own CloudExtraCourse_ advertises. _SENTINEL_PREFIX = "FFFF" +# Distinct from None, which is a real observation that carried no payload. +# Only "never observed" suppresses a candidate; absent-then-loaded is a +# genuine transition and should count. +_UNOBSERVED = object() + # Byte offset within a blob that carries its slot id. _SLOT_BYTE = 2 _MIN_BLOB_BYTES = 4 @@ -226,8 +231,8 @@ class CloudCourses: # user confirmation (see download_candidates). self._candidates: dict[str, int] = {} # Last one-time payload seen, so a load can be told from a poll that - # merely re-reports one. None means "nothing observed yet". - self._last_oneshot: str | None = None + # merely re-reports one. _UNOBSERVED until the first rep arrives. + self._last_oneshot: object = _UNOBSERVED # -- learning --------------------------------------------------------- @@ -284,7 +289,20 @@ class CloudCourses: changed = before != {slot: rec["blob"] for slot, rec in self._slots.items()} course = option_value(options, COURSE_PREFIX) - if course and is_loaded(oneshot) and oneshot != self._last_oneshot: + # Only a transition we actually watched happen counts. On the + # first observation there is nothing to compare against, so a + # payload sitting there is equally consistent with "just loaded" + # and "left over from last week" -- and on a board that doesn't + # clear the token when leaving Download, believing the former + # proposes whatever ordinary course the appliance happens to be + # on. Accepting that prefill would start a real wash cycle. + # (The two dumps in the corpus taken off the Download course both + # show the appliance clearing it to the FFFF sentinel, so this + # may never fire in practice -- which is not a reason to rely on + # it.) Restores don't persist _last_oneshot, so every restart + # re-enters this first-observation state deliberately. + first_ever = self._last_oneshot is _UNOBSERVED + if course and is_loaded(oneshot) and not first_ever and oneshot != self._last_oneshot: self._candidates[course] = self._candidates.get(course, 0) + 1 self._last_oneshot = oneshot return changed diff --git a/docs/investigations/download-cycle.md b/docs/investigations/download-cycle.md index 9b8f5fc..10995ed 100644 --- a/docs/investigations/download-cycle.md +++ b/docs/investigations/download-cycle.md @@ -111,12 +111,22 @@ one of the only two devices available to check it against, which is why the code is learned by observation and confirmed by the user in the options flow instead of tabled. -The observation signal is "whatever `Course_` reads while a non-sentinel -`OneTimeCloudCourse_` is loaded." That is a *candidate*, never applied -directly: tokens in this array are replaced by prefix and never evicted, so -a stale program token outlives the run it belonged to and can be reported -next to an unrelated local course. Acting on that unconfirmed would start -the wrong wash cycle. +The observation signal is "whatever `Course_` reads at the moment a +non-sentinel `OneTimeCloudCourse_` *appears or changes*" — a transition that +was actually watched, not a state. Tokens in this array are replaced by +prefix and never evicted, so a payload merely sitting there says nothing +about when it got there; on the first rep after a restart it is equally +consistent with "just loaded" and "left over from last week". Believing it +would propose whatever ordinary course the appliance happens to be sitting +on, and accepting that prefill starts a real wash cycle. Even a genuine +transition is only ever a *candidate*, confirmed by the user before use. + +Both dumps in the corpus taken while off the Download course +(`washer_wa55a7700av` on `Course_01`, the `_B048` washer on `Course_1C`) +show the appliance clearing its one-time token to the `FFFF` sentinel, so +the saved default persists but the one-shot does not. That makes the stale +case unlikely on these boards — which is a reason to expect it to behave, +not a reason to depend on it. ## The dead end: bytes 5/7/9 do not decode portably diff --git a/tests/test_cloud_courses.py b/tests/test_cloud_courses.py index e2b7330..0fa71fa 100644 --- a/tests/test_cloud_courses.py +++ b/tests/test_cloud_courses.py @@ -97,13 +97,29 @@ class TestRealDumps: assert store.view() == {} def test_reporter_dump_proposes_its_download_course(self): + """Only once a load has actually been watched. A single observation + can't tell "just loaded" from "left over", so the dump alone proposes + nothing -- see test_a_single_observation_proposes_nothing.""" rep = _load_device("washer_ww5000c_cloud")["/course/vs/0"] store = cloudcourse.CloudCourses() - store.observe(rep) + store.observe(_rep(["CloudExtraCourse_556B", "Course_87", f"OneTimeCloudCourse_{SPORTS}"])) + store.observe(rep) # one-time token moves to Jeans while on Course_87 assert store.download_candidates() == ["87"] # A candidate is never used until confirmed. assert store.snapshot()["download_course"] is None + def test_a_single_observation_proposes_nothing(self): + """The case a user hits after any restart: the appliance has cloud + payloads from previous runs and is sitting on an ordinary course. If + the board doesn't clear its one-time token, believing the first + observation would propose that ordinary course as the Download one -- + and accepting the prefill would start a real wash cycle.""" + store = cloudcourse.CloudCourses() + store.observe(_rep(["CloudExtraCourse_55", "Course_1B", f"OneTimeCloudCourse_{SPORTS}"])) + assert store.download_candidates() == [] + # The payload is still learned -- that part is device fact. + assert store.snapshot()["slots"]["55"]["blob"] == SPORTS + def test_wa55_learns_its_saved_program_but_not_the_sentinel(self): rep = _load_device("washer_wa55a7700av")["/course/vs/0"] assert cloudcourse.advertised_slots(rep) == ["59", "58"] @@ -234,6 +250,7 @@ class TestStoreRules: store = cloudcourse.CloudCourses() loaded = _rep(["CloudExtraCourse_55", "Course_87", f"OneTimeCloudCourse_{SPORTS}"]) stale = _rep(["CloudExtraCourse_55", "Course_1B", f"OneTimeCloudCourse_{SPORTS}"]) + store.observe(_rep(["CloudExtraCourse_55", "Course_87"])) # baseline store.observe(loaded) for _ in range(200): # ~100 minutes sitting on a cotton cycle store.observe(stale) @@ -241,6 +258,7 @@ class TestStoreRules: def test_a_second_distinct_load_is_counted(self): store = cloudcourse.CloudCourses() + store.observe(_rep(["CloudExtraCourse_556B", "Course_87"])) # baseline store.observe(_rep(["CloudExtraCourse_556B", "Course_87", f"OneTimeCloudCourse_{SPORTS}"])) store.observe(_rep(["CloudExtraCourse_556B", "Course_87", f"OneTimeCloudCourse_{JEANS}"])) assert store.download_candidates() == ["87"] @@ -401,3 +419,21 @@ class TestOptionsMergePreservesSiblingTokens: options = [f"CloudCourse_{SPORTS}", f"OneTimeCloudCourse_{JEANS}", "Course_1C"] assert laundry.option_value(options, "Course") == "1C" assert cloudcourse.option_value(options, "Course") == "1C" + + def test_a_payload_appearing_while_watching_is_a_real_transition(self): + """Absent-then-loaded is the user selecting a program, and must count + -- only "never observed at all" suppresses a candidate.""" + store = cloudcourse.CloudCourses() + store.observe(_rep(["CloudExtraCourse_55", "Course_87"])) + store.observe(_rep(["CloudExtraCourse_55", "Course_87", f"OneTimeCloudCourse_{SPORTS}"])) + assert store.download_candidates() == ["87"] + + def test_a_stale_payload_across_a_restart_proposes_nothing(self): + """A restored store starts unobserved again on purpose: the first rep + after a restart is indistinguishable from a stale one, whatever was + persisted.""" + seeded = cloudcourse.CloudCourses() + seeded.observe(_rep(["CloudExtraCourse_55", "Course_87", f"OneTimeCloudCourse_{SPORTS}"])) + restored = cloudcourse.CloudCourses(seeded.snapshot()) + restored.observe(_rep(["CloudExtraCourse_55", "Course_1B", f"OneTimeCloudCourse_{SPORTS}"])) + assert restored.download_candidates() == [] diff --git a/tests/test_cloud_courses_flow.py b/tests/test_cloud_courses_flow.py index 18e71c9..1de369f 100644 --- a/tests/test_cloud_courses_flow.py +++ b/tests/test_cloud_courses_flow.py @@ -318,6 +318,7 @@ async def test_the_form_proposes_the_observed_download_course(hass: HomeAssistan assert result["description_placeholders"]["total"] == "9" # Two learned so far, seven still to walk through on the appliance. assert result["description_placeholders"]["found"] == "2" + _observe_program_load(coordinator, SPORTS) assert coordinator.cloud_courses.download_candidates() == ["87"] @@ -420,6 +421,23 @@ async def test_the_flow_rejects_a_name_shadowing_a_personal_course(hass: HomeAss # --------------------------------------------------------------------------- +def _observe_program_load(coordinator, blob, course="87"): + """Stand in for the user loading a program while Home Assistant watches. + A candidate Download course comes only from a transition that was + actually observed, so tests that expect one have to produce it.""" + coordinator._observe.apply( + COURSE, + { + "x.com.samsung.da.options": [ + "CloudExtraCourse_0A5C286B2D0C55301A", + f"Course_{course}", + f"OneTimeCloudCourse_{blob}", + ] + }, + source="poll", + ) + + def _stub_probe(coordinator, sequence): """Drive async_probe_cloud_courses from a scripted list of loaded slots, standing in for the user turning the dial. The last entry repeats.""" @@ -658,7 +676,9 @@ async def test_guided_setup_alone_produces_a_selectable_cycle(hass: HomeAssistan first = await handler.async_step_cloud_name() assert "download_course" in str(first["data_schema"].schema) - # Prefilled from the observation the fixture already carries. + # Prefilled once a load has actually been watched -- in real use the + # guided probe loop feeds observe() and produces exactly this. + _observe_program_load(coordinator, SPORTS) assert handler._cloud_course == "87" await handler.async_step_cloud_name({"name": "Sports", "download_course": "87"})