From d47dc0d992727d760e01e4b8a47c36183be9384a Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Thu, 20 Aug 2026 22:08:41 -0500
Subject: [PATCH] Pin fingerprint stability and sensitivity behaviorally, note
 the platform pairing

---
 esphome/components/esp8266/boards.py          |  3 ++
 .../components/esp8266/test_build_surgery.py  | 33 +++++++++++++++----
 2 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/esphome/components/esp8266/boards.py b/esphome/components/esp8266/boards.py
index 4f137e95cd..71681d99a3 100644
--- a/esphome/components/esp8266/boards.py
+++ b/esphome/components/esp8266/boards.py
@@ -365,6 +365,9 @@ BOARDS = {
 # Per-board Arduino core build metadata for the native (PlatformIO-free)
 # toolchain: the variant directory (supplies pins_arduino.h) and the
 # board-identity defines the PlatformIO builder passes via build.extra_flags.
+# Valid for platform 4.x only (older tags differ, e.g. esp8285's variant);
+# the native toolchain's validator enforces that pairing by requiring core
+# >= 3.1.1 and rejecting a custom platform_version.
 # -DESP8266 and -DARDUINO_ARCH_ESP8266 are shared by every board and added by
 # the generator; only the per-board defines are listed here.
 #
diff --git a/tests/unit_tests/components/esp8266/test_build_surgery.py b/tests/unit_tests/components/esp8266/test_build_surgery.py
index 7e6e7ea680..b1c3fd7be8 100644
--- a/tests/unit_tests/components/esp8266/test_build_surgery.py
+++ b/tests/unit_tests/components/esp8266/test_build_surgery.py
@@ -107,16 +107,35 @@ def test_board_build_covers_every_board() -> None:
     assert set(BOARDS) <= set(ESP8266_BOARD_BUILD)
 
 
-def test_surgery_fingerprint_covers_module_source() -> None:
-    """Pins the mechanism: the fingerprint is the sha256 of the module
-    source (behavioral coverage follows from that, not from this test)."""
-    import hashlib
-    import inspect
+def test_surgery_fingerprint_is_stable_and_sensitive(tmp_path) -> None:
+    """The properties the linker-script cache depends on: the fingerprint is
+    stable across calls and changes when the module's source changes."""
+    import importlib.util
+    from pathlib import Path as _Path
+    import sys
 
     from esphome.components.esp8266 import build_surgery
 
-    expected = hashlib.sha256(inspect.getsource(build_surgery).encode()).hexdigest()
-    assert build_surgery.surgery_fingerprint() == expected
+    first = build_surgery.surgery_fingerprint()
+    assert first == build_surgery.surgery_fingerprint()
+    assert len(first) == 64
+    int(first, 16)  # sha256 hex digest
+
+    # A modified copy of the module must fingerprint differently
+    copy = tmp_path / "build_surgery_variant.py"
+    copy.write_text(
+        _Path(build_surgery.__file__).read_text(encoding="utf-8")
+        + "\nEXTRA_BEHAVIORAL_INPUT = 1\n",
+        encoding="utf-8",
+    )
+    spec = importlib.util.spec_from_file_location("build_surgery_variant", copy)
+    variant = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = variant
+    try:
+        spec.loader.exec_module(variant)
+        assert variant.surgery_fingerprint() != first
+    finally:
+        del sys.modules[spec.name]
 
 
 def test_testing_memory_patches_present_but_unselected_raises() -> None: