[red] require C3 post-OI NVS receipt

Signed-off-by: Viwat Vchirawongkwin <viwat.v@chula.ac.th>

Author: yyods

tests/firmware_tests/host/test_release_v060_private_gates.py

@@ -50,6 +50,7 @@
 PICO_GATES = ("GP0", "GP1", "GP2")
 VERSION = "0.6.0"
 RELEASE_DIGEST = "ab" * 32
+OI1_RAW_SHA256 = "cd" * 32
 
 
 def load_module(name: str, path: Path):
@@ -87,6 +88,33 @@ def sha256_bytes(value: bytes) -> str:
     return hashlib.sha256(value).hexdigest()
 
 
+def post_oi_nvs_binding(
+    artifact: bytes,
+    *,
+    release_digest: str = RELEASE_DIGEST,
+    oi1_raw_sha256: str = OI1_RAW_SHA256,
+) -> dict[str, object]:
+    summary = {
+        "schema_version": 1,
+        "profile_id": C3_PROFILE,
+        "candidate_release_json_sha256": release_digest,
+        "candidate_firmware_sha256": sha256_bytes(artifact),
+        "oi1_raw_sha256": oi1_raw_sha256,
+        "reset_samples": 10,
+        "partition_offset": 0x9000,
+        "partition_size": 0x6000,
+        "integrity": "passed",
+        "written_namespaces": [],
+    }
+    receipt = {"summary": summary, "inventory": []}
+    raw = canonical_json_bytes(receipt)
+    return {
+        "receipt_sha256": sha256_bytes(raw),
+        "receipt_size_bytes": len(raw),
+        "summary": summary,
+    }
+
+
 def private_result(
     profile_id: str,
     artifact: bytes,
@@ -101,7 +129,7 @@ def private_result(
         gate_names = PICO_GATES
     else:  # pragma: no cover - fixture misuse.
         raise AssertionError("unsupported private-gate fixture profile")
-    return {
+    result = {
         "schema_version": 1,
         "status": "passed",
         "profile_id": profile_id,
@@ -110,6 +138,12 @@ def private_result(
         digest_key: sha256_bytes(artifact),
         "gates": {name: "passed" for name in gate_names},
     }
+    if profile_id == C3_PROFILE:
+        result["post_oi_nvs"] = post_oi_nvs_binding(
+            artifact,
+            release_digest=release_digest,
+        )
+    return result
 
 
 def write_private_result(path: Path, value: object) -> None:
@@ -123,6 +157,7 @@ def expected_summary(
     artifact: bytes,
 ) -> dict[str, object]:
     value = private_result(profile_id, artifact)
+    value.pop("post_oi_nvs", None)
     value["qualification_result_sha256"] = sha256_bytes(result_path.read_bytes())
     return value
 
@@ -134,6 +169,7 @@ def test_pure_private_gate_module_and_api_exist(self) -> None:
             return
         for name in (
             "validate_result_file",
+            "validate_c3_result_for_observation",
             "validate_public_summary",
             "private_result_snapshot",
         ):
@@ -295,6 +331,80 @@ def test_artifact_kind_digest_and_bytes_cannot_be_substituted(self) -> None:
                 with self.assertRaises(GATE.QualificationError):
                     self.validate(profile_id)
 
+    def test_c3_post_oi_nvs_binding_is_exact_and_observation_bound(self) -> None:
+        original = private_result(C3_PROFILE, self.artifacts[C3_PROFILE])
+        observation = {
+            "raw_log_sha256": OI1_RAW_SHA256,
+            "reset_to_service_advertisement_ms": [1000] * 10,
+        }
+        summary = GATE.validate_c3_result_for_observation(
+            self.result_paths[C3_PROFILE],
+            artifact_path=self.artifact_paths[C3_PROFILE],
+            expected_version=VERSION,
+            candidate_release_json_sha256=RELEASE_DIGEST,
+            observation=observation,
+        )
+        self.assertNotIn("post_oi_nvs", summary)
+
+        mutations = {
+            "missing": lambda value: value.pop("post_oi_nvs"),
+            "receipt-digest": lambda value: value["post_oi_nvs"].__setitem__(
+                "receipt_sha256", "0" * 64
+            ),
+            "receipt-size": lambda value: value["post_oi_nvs"].__setitem__(
+                "receipt_size_bytes", 0
+            ),
+            "release": lambda value: value["post_oi_nvs"]["summary"].__setitem__(
+                "candidate_release_json_sha256", "0" * 64
+            ),
+            "firmware": lambda value: value["post_oi_nvs"]["summary"].__setitem__(
+                "candidate_firmware_sha256", "0" * 64
+            ),
+            "raw": lambda value: value["post_oi_nvs"]["summary"].__setitem__(
+                "oi1_raw_sha256", "0" * 64
+            ),
+            "resets": lambda value: value["post_oi_nvs"]["summary"].__setitem__(
+                "reset_samples", 9
+            ),
+            "offset": lambda value: value["post_oi_nvs"]["summary"].__setitem__(
+                "partition_offset", 0
+            ),
+            "size": lambda value: value["post_oi_nvs"]["summary"].__setitem__(
+                "partition_size", 0x5000
+            ),
+            "integrity": lambda value: value["post_oi_nvs"]["summary"].__setitem__(
+                "integrity", "failed"
+            ),
+            "phy": lambda value: value["post_oi_nvs"]["summary"].__setitem__(
+                "written_namespaces", ["phy"]
+            ),
+        }
+        for name, mutate in mutations.items():
+            with self.subTest(mutation=name):
+                changed = copy.deepcopy(original)
+                mutate(changed)
+                self.rewrite(C3_PROFILE, changed)
+                with self.assertRaises(GATE.QualificationError):
+                    self.validate(C3_PROFILE)
+
+        self.rewrite(C3_PROFILE, original)
+        for name, changed_observation in {
+            "wrong-raw": {**observation, "raw_log_sha256": "0" * 64},
+            "nine-resets": {
+                **observation,
+                "reset_to_service_advertisement_ms": [1000] * 9,
+            },
+        }.items():
+            with self.subTest(observation=name):
+                with self.assertRaises(GATE.QualificationError):
+                    GATE.validate_c3_result_for_observation(
+                        self.result_paths[C3_PROFILE],
+                        artifact_path=self.artifact_paths[C3_PROFILE],
+                        expected_version=VERSION,
+                        candidate_release_json_sha256=RELEASE_DIGEST,
+                        observation=changed_observation,
+                    )
+
     def test_gate_sets_require_every_exact_gate_passed(self) -> None:
         for profile_id, gate_names in (
             (C3_PROFILE, C3_GATES),
@@ -446,6 +556,7 @@ def payload(self) -> dict[str, object]:
     def summaries(self) -> tuple[dict[str, object], dict[str, object], dict[str, object]]:
         waveshare = {"schema_version": 1, "status": "passed"}
         c3 = private_result(C3_PROFILE, b"c3")
+        c3.pop("post_oi_nvs")
         c3["qualification_result_sha256"] = "2" * 64
         pico = private_result(PICO_PROFILE, b"pico")
         pico["qualification_result_sha256"] = "3" * 64
@@ -566,6 +677,14 @@ def test_finalizer_source_snapshots_validates_binds_and_rechecks_both_inputs(sel
             "each C3/Pico input must be snapshotted before and after promotion",
         )
 
+    def test_completion_and_finalizer_bind_c3_receipt_to_the_oi_observation(self) -> None:
+        seam = "_V060_PROFILE_GATE.validate_c3_result_for_observation"
+        self.assertIn(
+            seam,
+            inspect.getsource(RELEASE.create_hil_completion_fragment),
+        )
+        self.assertIn(seam, inspect.getsource(RELEASE.finalize_public_bundle))
+
     def test_public_tree_validator_revalidates_both_derived_summaries(self) -> None:
         source = inspect.getsource(RELEASE._validate_hil)
         self.assertIn("_V060_PROFILE_GATE.validate_public_summary", source)

tests/firmware_tests/host/test_target_runtime_contract.py

@@ -1128,24 +1128,19 @@ def test_c3_disables_phy_calibration_storage_without_relaxing_oi1(self):
         )
         thresholds = profile["thresholds"]
         self.assertEqual(
+            thresholds,
             {
-                key: thresholds[key]
-                for key in (
-                    "gc_free_min_bytes",
-                    "idf_internal_free_min_bytes",
-                    "idf_internal_largest_block_min_bytes",
-                    "idf_internal_minimum_free_min_bytes",
-                    "reset_to_service_advertisement_max_ms",
-                )
-            },
-            {
+                "application_headroom_min_bytes": 352880,
+                "application_image_max_bytes": 1678736,
                 "gc_free_min_bytes": 117760,
+                "get_verified_goodput_min_bytes_per_second": 27200,
                 "idf_internal_free_min_bytes": 66560,
                 "idf_internal_largest_block_min_bytes": 57344,
                 "idf_internal_minimum_free_min_bytes": 63488,
+                "put_committed_goodput_min_bytes_per_second": 15300,
                 "reset_to_service_advertisement_max_ms": 3000,
             },
-            "the PHY policy must not weaken any C3 heap or reset gate",
+            "the PHY policy must not weaken any C3 release threshold",
         )
 
 

tests/firmware_tests/host/test_v060_qualification_workflow.py

@@ -103,6 +103,35 @@ def canonical_json_bytes(value: object) -> bytes:
     ).encode("utf-8")
 
 
+def write_c3_post_oi_nvs_receipt(
+    path: Path,
+    *,
+    release_raw: bytes,
+    artifact: bytes,
+    namespaces: list[dict[str, object]] | None = None,
+    oi1_raw_sha256: str = "d" * 64,
+) -> tuple[dict[str, object], bytes]:
+    inventory = namespaces or []
+    summary = {
+        "schema_version": 1,
+        "profile_id": "esp32-c3-4mb",
+        "candidate_release_json_sha256": hashlib.sha256(release_raw).hexdigest(),
+        "candidate_firmware_sha256": hashlib.sha256(artifact).hexdigest(),
+        "oi1_raw_sha256": oi1_raw_sha256,
+        "reset_samples": 10,
+        "partition_offset": 0x9000,
+        "partition_size": 0x6000,
+        "integrity": "passed",
+        "written_namespaces": [item["namespace"] for item in inventory],
+    }
+    receipt = {"summary": summary, "inventory": inventory}
+    raw = canonical_json_bytes(receipt)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(raw)
+    path.chmod(0o600)
+    return summary, raw
+
+
 def candidate_release(artifact: bytes) -> dict[str, object]:
     esp_specs = {
         "esp32-4mb": (
@@ -407,7 +436,13 @@ def test_candidate_bound_no_replace_writer_api_exists(self):
             return
         self.assertEqual(
             set(inspect.signature(writer).parameters),
-            {"candidate_dir", "profile_id", "passed_gates", "output_path"},
+            {
+                "candidate_dir",
+                "profile_id",
+                "passed_gates",
+                "output_path",
+                "post_oi_nvs_receipt_path",
+            },
         )
 
     def test_private_gate_cli_exposes_only_derived_identity_inputs(self):
@@ -420,6 +455,14 @@ def test_private_gate_cli_exposes_only_derived_identity_inputs(self):
         self.assertEqual(completed.returncode, 0, completed.stderr)
         self.assertIn("create-result", completed.stdout)
         self.assertIn("--passed-gate", completed.stdout)
+        command_help = subprocess.run(
+            [sys.executable, str(GATE_PATH), "create-result", "--help"],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        self.assertEqual(command_help.returncode, 0, command_help.stderr)
+        self.assertIn("--post-oi-nvs-receipt", command_help.stdout)
         for forbidden in (
             "--status",
             "--firmware-version",
@@ -442,13 +485,20 @@ def test_writer_derives_exact_bytes_and_refuses_missing_gates(self):
             release_raw = canonical_json_bytes(candidate_release(artifact))
             (candidate / "release.json").write_bytes(release_raw)
             output = root / "private" / "c3-result.json"
+            receipt = root / "private" / "c3-post-oi-nvs.json"
+            receipt_summary, receipt_raw = write_c3_post_oi_nvs_receipt(
+                receipt,
+                release_raw=release_raw,
+                artifact=artifact,
+            )
             gates = ["C3-G%d" % index for index in range(7)]
 
             created = writer(
                 candidate_dir=candidate,
                 profile_id="esp32-c3-4mb",
                 passed_gates=gates,
                 output_path=output,
+                post_oi_nvs_receipt_path=receipt,
             )
             expected = {
                 "schema_version": 1,
@@ -460,6 +510,11 @@ def test_writer_derives_exact_bytes_and_refuses_missing_gates(self):
                 ).hexdigest(),
                 "candidate_firmware_sha256": hashlib.sha256(artifact).hexdigest(),
                 "gates": {name: "passed" for name in gates},
+                "post_oi_nvs": {
+                    "receipt_sha256": hashlib.sha256(receipt_raw).hexdigest(),
+                    "receipt_size_bytes": len(receipt_raw),
+                    "summary": receipt_summary,
+                },
             }
             self.assertEqual(Path(created), output)
             self.assertEqual(output.read_bytes(), canonical_json_bytes(expected))
@@ -472,6 +527,7 @@ def test_writer_derives_exact_bytes_and_refuses_missing_gates(self):
                     profile_id="esp32-c3-4mb",
                     passed_gates=gates,
                     output_path=output,
+                    post_oi_nvs_receipt_path=receipt,
                 )
             missing_output = root / "private" / "missing.json"
             with self.assertRaises(GATE.QualificationError):
@@ -480,9 +536,53 @@ def test_writer_derives_exact_bytes_and_refuses_missing_gates(self):
                     profile_id="esp32-c3-4mb",
                     passed_gates=gates[:-1],
                     output_path=missing_output,
+                    post_oi_nvs_receipt_path=receipt,
                 )
             self.assertFalse(missing_output.exists())
 
+            for name, receipt_path in (
+                ("missing-receipt", None),
+                ("non-exclusive-receipt", receipt),
+            ):
+                if receipt_path is not None:
+                    receipt.chmod(0o644)
+                rejected_output = root / "private" / (name + ".json")
+                with self.subTest(name=name), self.assertRaises(
+                    GATE.QualificationError
+                ):
+                    writer(
+                        candidate_dir=candidate,
+                        profile_id="esp32-c3-4mb",
+                        passed_gates=gates,
+                        output_path=rejected_output,
+                        post_oi_nvs_receipt_path=receipt_path,
+                    )
+                self.assertFalse(rejected_output.exists())
+                receipt.chmod(0o600)
+
+            phy_receipt = root / "private" / "phy-receipt.json"
+            write_c3_post_oi_nvs_receipt(
+                phy_receipt,
+                release_raw=release_raw,
+                artifact=artifact,
+                namespaces=[
+                    {
+                        "namespace": "phy",
+                        "keys": [{"key": "cal_data", "type": "blob"}],
+                    }
+                ],
+            )
+            phy_output = root / "private" / "phy-result.json"
+            with self.assertRaises(GATE.QualificationError):
+                writer(
+                    candidate_dir=candidate,
+                    profile_id="esp32-c3-4mb",
+                    passed_gates=gates,
+                    output_path=phy_output,
+                    post_oi_nvs_receipt_path=phy_receipt,
+                )
+            self.assertFalse(phy_output.exists())
+
     def test_writer_rejects_minimal_or_substituted_candidate_metadata(self):
         writer = GATE.create_result_file
         gates = ["C3-G%d" % index for index in range(7)]
@@ -660,6 +760,12 @@ def test_candidate_writer_rolls_back_post_write_validation_failure(self):
                 canonical_json_bytes(candidate_release(artifact))
             )
             output = root / "private" / "result.json"
+            receipt = root / "private" / "post-oi-nvs.json"
+            write_c3_post_oi_nvs_receipt(
+                receipt,
+                release_raw=(candidate / "release.json").read_bytes(),
+                artifact=artifact,
+            )
             with mock.patch.object(
                 GATE,
                 "validate_result_file",
@@ -670,6 +776,7 @@ def test_candidate_writer_rolls_back_post_write_validation_failure(self):
                     profile_id="esp32-c3-4mb",
                     passed_gates=gates,
                     output_path=output,
+                    post_oi_nvs_receipt_path=receipt,
                 )
             self.assertFalse(output.exists())