fix(flows): keep the caller's intent across a redeclared optional field

begin_step clears only filled, and the caller's key is popped from
remaining_config by the first step — so a later step declaring the same
optional field reached _redeclared_field_submission with nothing marking
it as the caller's, and keep_current_values handed it straight to the
backfill. That resubmitted the entry's stored value: a null clear was
silently undone, and a caller's new value was overwritten.

_ReuseState.recorded_value survives the whole walk (only filled is
per-step) and distinguishes a recorded None from no record, so it now
decides first: a recorded None keeps the field omitted, a recorded value
is resubmitted as the caller's through the existing claim_write path, and
only a field the caller never named falls through to the step's own value.

The required-field asymmetry predates this PR and is left alone.

Found by Patch76 review on #2256.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012d29UJTiH4Uy2Pm37SBPtr

Author: kingpanther13

src/ha_mcp/tools/config_entry_flow_form.py

@@ -442,11 +442,14 @@ def _redeclared_field_submission(
 
     1. The field is not required, or reuse is barred for this site because the
        caller named neither it nor the section holding it (``allow_reuse``).
-       Under ``keep_current_values`` the step's own value still goes back, per
-       :func:`_current_value_backfill` — it is the step's data, not the
-       caller's, so barring reuse does not bar it, and a section the backfill
-       itself materializes has to carry what it requires. Otherwise omit:
-       injecting into either on a create flow would invent data.
+       Under ``keep_current_values`` a value the caller recorded ANYWHERE
+       earlier in this walk wins first — resubmitted as theirs, or omitted
+       when it was ``None``, which is the clear. Failing that the step's own
+       value goes back, per :func:`_current_value_backfill` — it is the step's
+       data, not the caller's, so barring reuse does not bar it, and a section
+       the backfill itself materializes has to carry what it requires.
+       Otherwise omit: injecting into either on a create flow would invent
+       data.
     2. The step's own schema supplies a value — a suggestion or a constant's
        only legal value, per :func:`_step_owned_submission_value`: submit that.
        It is schema data rather than a caller key, so it is neither marked
@@ -476,6 +479,20 @@ def _redeclared_field_submission(
     if not allow_reuse or not field.get("required"):
         if not keep_current_values:
             return _NO_SUBMISSION
+        # The caller's intent outranks the step's stored value for the WHOLE
+        # walk. ``begin_step`` clears only ``filled``, so by a later step the
+        # caller's key is gone from ``remaining_config`` and nothing here
+        # marks the field as theirs — but ``scoped``/``flat`` still hold what
+        # they asked for. Backfilling over that resubmitted the stored value
+        # and undid it: a recorded ``None`` is the clear this mode documents,
+        # and a recorded value is the one the caller asked to write.
+        recorded = reuse_state.recorded_value(path_prefix, name)
+        if recorded is not _MISSING_DEFAULT:
+            if recorded is None:
+                return _NO_SUBMISSION
+            if not reuse_state.claim_write(dotted):
+                return _NO_SUBMISSION
+            return recorded, True
         return _current_value_backfill(field)
     step_owned = _step_owned_submission_value(field)
     if step_owned is not _MISSING_DEFAULT:

tests/src/unit/test_flow_options_preserve.py

@@ -525,6 +525,112 @@ async def test_required_redeclared_field_still_reuses_the_caller_value(
         }
         assert result["warnings"] == [_reuse_warning("friendly_name", "details")]
 
+    @staticmethod
+    def _redeclaring_step(step_id: str) -> dict[str, Any]:
+        """Two steps both declaring the same OPTIONAL field, both pre-filled."""
+        return {
+            "type": "form",
+            "step_id": step_id,
+            "data_schema": [
+                {
+                    "name": "province",
+                    "required": False,
+                    "optional": True,
+                    "description": {"suggested_value": "BW"},
+                    "selector": {"select": {"options": ["BW", "BY"]}},
+                },
+            ],
+        }
+
+    def test_a_clear_survives_a_later_step_redeclaring_the_field(self) -> None:
+        """``null`` must stay a clear for the whole walk, not just one step.
+
+        ``begin_step`` clears only ``filled``, and the caller's key was popped
+        from ``remaining_config`` by the first step — so by the second step
+        nothing marks the field as the caller's and the backfill used to
+        resubmit the stored value, silently undoing the clear the tool
+        descriptions promise (Patch76 review, #2256).
+        """
+        reuse_state = _ReuseState()
+        remaining: dict[str, Any] = {"province": None}
+
+        first = _handle_form_step(
+            "flow-2254",
+            self._redeclaring_step("one"),
+            remaining,
+            None,
+            set(),
+            reuse_state,
+            keep_current_values=True,
+        )
+        second = _handle_form_step(
+            "flow-2254",
+            self._redeclaring_step("two"),
+            remaining,
+            None,
+            set(),
+            reuse_state,
+            keep_current_values=True,
+        )
+
+        assert "province" not in first
+        assert "province" not in second, (
+            f"The later step resurrected the cleared field: {second}"
+        )
+
+    def test_a_callers_value_outranks_a_later_steps_suggestion(self) -> None:
+        """The caller asked for BY; the step still suggests the stored BW."""
+        reuse_state = _ReuseState()
+        remaining: dict[str, Any] = {"province": "BY"}
+
+        first = _handle_form_step(
+            "flow-2254",
+            self._redeclaring_step("one"),
+            remaining,
+            None,
+            set(),
+            reuse_state,
+            keep_current_values=True,
+        )
+        second = _handle_form_step(
+            "flow-2254",
+            self._redeclaring_step("two"),
+            remaining,
+            None,
+            set(),
+            reuse_state,
+            keep_current_values=True,
+        )
+
+        assert first["province"] == "BY"
+        assert second["province"] == "BY", (
+            f"The later step overwrote the caller's value: {second}"
+        )
+
+    def test_create_flow_still_drops_a_redeclared_optional_field(self) -> None:
+        """Flag off keeps the pre-#2254 shape: nothing goes back at all."""
+        reuse_state = _ReuseState()
+        remaining: dict[str, Any] = {"province": "BY"}
+
+        _handle_form_step(
+            "flow-2254",
+            self._redeclaring_step("one"),
+            remaining,
+            None,
+            set(),
+            reuse_state,
+        )
+        second = _handle_form_step(
+            "flow-2254",
+            self._redeclaring_step("two"),
+            remaining,
+            None,
+            set(),
+            reuse_state,
+        )
+
+        assert second == {}
+
     def test_required_field_with_only_a_static_default_is_still_omitted(self) -> None:
         """Voluptuous fills it, exactly as it does for the UI's own form."""
         step: dict[str, Any] = {