tirtc-device-builder 0.3.0 → 0.5.0

package/skills/tirtc-esp32-builder/scripts/hardware_ir.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import re
 import shutil
 import sys
 from pathlib import Path
@@ -24,7 +25,40 @@ VERIFICATION_LEVELS = {
     "hardware_verified": 4,
     "hil_verified": 5,
 }
-READY_STATUSES = {"READY_TO_PORT", "HIL_VERIFIED"}
+ASSESSMENT_PHASES = {"intake", "build", "hil"}
+PHASE_SUCCESS_STATUSES = {
+    "intake": {"READY_TO_PORT", "HIL_VERIFIED"},
+    "build": {"BUILD_VERIFIED", "HIL_VERIFIED"},
+    "hil": {"HIL_VERIFIED"},
+}
+VIDEO_CONTRACTS = {
+    "mjpeg": "jpeg_complete_frames",
+    "h264": "h264_annex_b_access_units",
+    "h265": "h265_annex_b_access_units",
+}
+WIFI_METHOD_TYPES = {
+    "softap",
+    "ble",
+    "smartconfig",
+    "factory_nvs",
+    "development_config",
+    "custom",
+}
+BINDING_METHOD_TYPES = {
+    "verification_code",
+    "factory_bound",
+    "development_credentials",
+    "custom",
+}
+ACCEPTANCE_LEVELS = {"L-1", "L0", "L1", "L2", "L3", "L4", "L5", "L6", "L7"}
+FEATURE_HIL_LEVEL = {
+    "h5_live_audio": "L5",
+    "h5_live_video": "L5",
+    "h5_talkback": "L5",
+    "ai_talk": "L6",
+}
+SHA256_RE = re.compile(r"^[0-9a-fA-F]{64}$")
+Requirement = tuple[str, str, int]
 
 
 def load_ir(path: Path) -> dict[str, Any]:
@@ -51,17 +85,32 @@ def nonempty_string(value: Any, path: str, errors: list[str]) -> None:
         errors.append(f"{path} must be a non-empty string")
 
 
+def nullable_string(value: Any, path: str, errors: list[str]) -> None:
+    if value is not None and (not isinstance(value, str) or not value.strip()):
+        errors.append(f"{path} must be a non-empty string or null")
+
+
 def positive_int(value: Any, path: str, errors: list[str], allow_zero: bool = False) -> None:
     minimum = 0 if allow_zero else 1
     if isinstance(value, bool) or not isinstance(value, int) or value < minimum:
         errors.append(f"{path} must be an integer >= {minimum}")
 
 
+def nullable_positive_int(value: Any, path: str, errors: list[str]) -> None:
+    if value is not None:
+        positive_int(value, path, errors)
+
+
 def nullable_bool(value: Any, path: str, errors: list[str]) -> None:
     if value is not None and not isinstance(value, bool):
         errors.append(f"{path} must be true, false, or null")
 
 
+def validate_verification(value: Any, path: str, errors: list[str]) -> None:
+    if value not in VERIFICATION_LEVELS:
+        errors.append(f"{path} must be one of " + ", ".join(VERIFICATION_LEVELS))
+
+
 def validate_source_refs(
     section: dict[str, Any], path: str, source_ids: set[str], errors: list[str]
 ) -> None:
@@ -90,18 +139,268 @@ def validate_codec_list(value: Any, path: str, errors: list[str]) -> None:
         else:
             for rate_index, rate in enumerate(rates):
                 positive_int(rate, f"{prefix}.sample_rates_hz[{rate_index}]", errors)
-        verification = codec.get("verification")
-        if verification not in VERIFICATION_LEVELS:
+        validate_verification(codec.get("verification"), f"{prefix}.verification", errors)
+
+
+def validate_video_profiles(
+    camera: dict[str, Any], source_ids: set[str], errors: list[str]
+) -> None:
+    nullable_string(
+        camera.get("selected_video_profile"),
+        "camera.selected_video_profile",
+        errors,
+    )
+    profiles = camera.get("video_profiles")
+    if not isinstance(profiles, list):
+        errors.append("camera.video_profiles must be an array")
+        return
+    ids: set[str] = set()
+    for index, item in enumerate(profiles):
+        prefix = f"camera.video_profiles[{index}]"
+        profile = mapping(item, prefix, errors)
+        nonempty_string(profile.get("id"), f"{prefix}.id", errors)
+        profile_id = profile.get("id")
+        if isinstance(profile_id, str) and profile_id:
+            if profile_id in ids:
+                errors.append(f"duplicate video profile id {profile_id!r}")
+            ids.add(profile_id)
+        codec = profile.get("codec")
+        if codec not in VIDEO_CONTRACTS:
             errors.append(
-                f"{prefix}.verification must be one of "
-                + ", ".join(VERIFICATION_LEVELS)
+                f"{prefix}.codec must be one of " + ", ".join(VIDEO_CONTRACTS)
             )
+        nullable_bool(profile.get("available"), f"{prefix}.available", errors)
+        nullable_string(profile.get("output_format"), f"{prefix}.output_format", errors)
+        nullable_bool(
+            profile.get("refresh_frame_control"),
+            f"{prefix}.refresh_frame_control",
+            errors,
+        )
+        nullable_positive_int(profile.get("stream_id"), f"{prefix}.stream_id", errors)
+        validate_verification(
+            profile.get("verification"), f"{prefix}.verification", errors
+        )
+        validate_source_refs(profile, prefix, source_ids, errors)
+    selected = camera.get("selected_video_profile")
+    if isinstance(selected, str) and selected and selected not in ids:
+        errors.append(
+            f"camera.selected_video_profile references unknown profile {selected!r}"
+        )
+
+
+def validate_hardware_resources(
+    data: dict[str, Any], source_ids: set[str], errors: list[str]
+) -> None:
+    resources = mapping(data.get("hardware_resources"), "hardware_resources", errors)
+    validate_source_refs(resources, "hardware_resources", source_ids, errors)
+
+    i2c = mapping(resources.get("i2c"), "hardware_resources.i2c", errors)
+    nullable_bool(i2c.get("used"), "hardware_resources.i2c.used", errors)
+    driver_family = i2c.get("driver_family")
+    if driver_family not in {None, "legacy", "ng", "none"}:
+        errors.append(
+            "hardware_resources.i2c.driver_family must be legacy, ng, none, or null"
+        )
+    nullable_bool(
+        i2c.get("single_driver_family"),
+        "hardware_resources.i2c.single_driver_family",
+        errors,
+    )
+    validate_verification(
+        i2c.get("verification"), "hardware_resources.i2c.verification", errors
+    )
+
+    i2s = mapping(resources.get("i2s"), "hardware_resources.i2s", errors)
+    nullable_bool(i2s.get("used"), "hardware_resources.i2s.used", errors)
+    nullable_bool(
+        i2s.get("controller_and_gpio_ownership_resolved"),
+        "hardware_resources.i2s.controller_and_gpio_ownership_resolved",
+        errors,
+    )
+    validate_verification(
+        i2s.get("verification"), "hardware_resources.i2s.verification", errors
+    )
+
+    mapping_section = mapping(
+        resources.get("audio_channel_mapping"),
+        "hardware_resources.audio_channel_mapping",
+        errors,
+    )
+    nullable_bool(
+        mapping_section.get("required"),
+        "hardware_resources.audio_channel_mapping.required",
+        errors,
+    )
+    nullable_bool(
+        mapping_section.get("resolved"),
+        "hardware_resources.audio_channel_mapping.resolved",
+        errors,
+    )
+    validate_verification(
+        mapping_section.get("verification"),
+        "hardware_resources.audio_channel_mapping.verification",
+        errors,
+    )
+
+    realtime = mapping(
+        resources.get("camera_realtime"),
+        "hardware_resources.camera_realtime",
+        errors,
+    )
+    nullable_bool(
+        realtime.get("pipeline_safe"),
+        "hardware_resources.camera_realtime.pipeline_safe",
+        errors,
+    )
+    validate_verification(
+        realtime.get("verification"),
+        "hardware_resources.camera_realtime.verification",
+        errors,
+    )
+
+    memory = mapping(resources.get("memory"), "hardware_resources.memory", errors)
+    nullable_bool(
+        memory.get("startup_and_media_budgeted"),
+        "hardware_resources.memory.startup_and_media_budgeted",
+        errors,
+    )
+    validate_verification(
+        memory.get("verification"), "hardware_resources.memory.verification", errors
+    )
+
+
+def validate_onboarding(
+    data: dict[str, Any], source_ids: set[str], errors: list[str]
+) -> None:
+    onboarding = mapping(data.get("onboarding"), "onboarding", errors)
+    validate_source_refs(onboarding, "onboarding", source_ids, errors)
+    wifi = mapping(onboarding.get("wifi_credentials"), "onboarding.wifi_credentials", errors)
+    nullable_string(
+        wifi.get("selected_method"), "onboarding.wifi_credentials.selected_method", errors
+    )
+    nullable_bool(
+        wifi.get("credentials_committed_to_source"),
+        "onboarding.wifi_credentials.credentials_committed_to_source",
+        errors,
+    )
+    nullable_bool(
+        wifi.get("reprovisioning_defined"),
+        "onboarding.wifi_credentials.reprovisioning_defined",
+        errors,
+    )
+    methods = wifi.get("methods")
+    method_ids: set[str] = set()
+    if not isinstance(methods, list):
+        errors.append("onboarding.wifi_credentials.methods must be an array")
+    else:
+        for index, item in enumerate(methods):
+            prefix = f"onboarding.wifi_credentials.methods[{index}]"
+            method = mapping(item, prefix, errors)
+            nonempty_string(method.get("id"), f"{prefix}.id", errors)
+            method_id = method.get("id")
+            if isinstance(method_id, str) and method_id:
+                if method_id in method_ids:
+                    errors.append(f"duplicate Wi-Fi method id {method_id!r}")
+                method_ids.add(method_id)
+            method_type = method.get("type")
+            if method_type not in WIFI_METHOD_TYPES:
+                errors.append(
+                    f"{prefix}.type must be one of " + ", ".join(sorted(WIFI_METHOD_TYPES))
+                )
+            nullable_bool(method.get("available"), f"{prefix}.available", errors)
+            validate_verification(
+                method.get("verification"), f"{prefix}.verification", errors
+            )
+            validate_source_refs(method, prefix, source_ids, errors)
+    selected = wifi.get("selected_method")
+    if isinstance(selected, str) and selected and selected not in method_ids:
+        errors.append(
+            f"onboarding.wifi_credentials.selected_method references unknown method {selected!r}"
+        )
+
+    binding = mapping(onboarding.get("device_binding"), "onboarding.device_binding", errors)
+    nullable_string(
+        binding.get("selected_method"),
+        "onboarding.device_binding.selected_method",
+        errors,
+    )
+    for field in (
+        "credentials_committed_to_source",
+        "stored_credential_state_handled",
+        "clear_binding_control",
+    ):
+        nullable_bool(binding.get(field), f"onboarding.device_binding.{field}", errors)
+    methods = binding.get("methods")
+    method_ids = set()
+    if not isinstance(methods, list):
+        errors.append("onboarding.device_binding.methods must be an array")
+    else:
+        for index, item in enumerate(methods):
+            prefix = f"onboarding.device_binding.methods[{index}]"
+            method = mapping(item, prefix, errors)
+            nonempty_string(method.get("id"), f"{prefix}.id", errors)
+            method_id = method.get("id")
+            if isinstance(method_id, str) and method_id:
+                if method_id in method_ids:
+                    errors.append(f"duplicate binding method id {method_id!r}")
+                method_ids.add(method_id)
+            method_type = method.get("type")
+            if method_type not in BINDING_METHOD_TYPES:
+                errors.append(
+                    f"{prefix}.type must be one of "
+                    + ", ".join(sorted(BINDING_METHOD_TYPES))
+                )
+            nullable_bool(method.get("available"), f"{prefix}.available", errors)
+            validate_verification(
+                method.get("verification"), f"{prefix}.verification", errors
+            )
+            validate_source_refs(method, prefix, source_ids, errors)
+    selected = binding.get("selected_method")
+    if isinstance(selected, str) and selected and selected not in method_ids:
+        errors.append(
+            f"onboarding.device_binding.selected_method references unknown method {selected!r}"
+        )
+
+
+def validate_runtime_evidence(
+    data: dict[str, Any], source_ids: set[str], errors: list[str]
+) -> None:
+    evidence = data.get("runtime_evidence")
+    if not isinstance(evidence, list):
+        errors.append("runtime_evidence must be an array")
+        return
+    for index, item in enumerate(evidence):
+        prefix = f"runtime_evidence[{index}]"
+        record = mapping(item, prefix, errors)
+        sha = record.get("artifact_sha256")
+        if not isinstance(sha, str) or not SHA256_RE.fullmatch(sha):
+            errors.append(f"{prefix}.artifact_sha256 must be a 64-character SHA-256")
+        levels = record.get("acceptance_levels")
+        if not isinstance(levels, list) or not levels:
+            errors.append(f"{prefix}.acceptance_levels must be a non-empty array")
+        else:
+            for level_index, level in enumerate(levels):
+                if level not in ACCEPTANCE_LEVELS:
+                    errors.append(
+                        f"{prefix}.acceptance_levels[{level_index}] must be a known acceptance level"
+                    )
+        features = record.get("features")
+        if not isinstance(features, list) or not features:
+            errors.append(f"{prefix}.features must be a non-empty array")
+        else:
+            for feature_index, feature in enumerate(features):
+                if feature not in FEATURES:
+                    errors.append(
+                        f"{prefix}.features[{feature_index}] must be a known feature"
+                    )
+        validate_source_refs(record, prefix, source_ids, errors)
 
 
 def validate_ir(data: dict[str, Any]) -> list[str]:
     errors: list[str] = []
-    if data.get("schema_version") != 1:
-        errors.append("schema_version must be 1")
+    schema_version = data.get("schema_version")
+    if schema_version not in {1, 2}:
+        errors.append("schema_version must be 1 or 2")
 
     board = mapping(data.get("board"), "board", errors)
     for key in ("id", "vendor", "model", "hardware_revision"):
@@ -135,12 +434,9 @@ def validate_ir(data: dict[str, Any]) -> list[str]:
     nonempty_string(
         toolchain.get("framework_version"), "toolchain.framework_version", errors
     )
-    toolchain_verification = toolchain.get("verification")
-    if toolchain_verification not in VERIFICATION_LEVELS:
-        errors.append(
-            "toolchain.verification must be one of "
-            + ", ".join(VERIFICATION_LEVELS)
-        )
+    validate_verification(
+        toolchain.get("verification"), "toolchain.verification", errors
+    )
     tirtc = mapping(toolchain.get("tirtc"), "toolchain.tirtc", errors)
     for key in ("platform", "version", "sdk_path", "build_contract"):
         nonempty_string(tirtc.get(key), f"toolchain.tirtc.{key}", errors)
@@ -148,17 +444,17 @@ def validate_ir(data: dict[str, Any]) -> list[str]:
 
     camera = mapping(data.get("camera"), "camera", errors)
     nullable_bool(camera.get("present"), "camera.present", errors)
-    h264 = mapping(camera.get("h264"), "camera.h264", errors)
-    nullable_bool(h264.get("available"), "camera.h264.available", errors)
-    nullable_bool(
-        h264.get("key_frame_control"), "camera.h264.key_frame_control", errors
-    )
-    verification = h264.get("verification")
-    if verification not in VERIFICATION_LEVELS:
-        errors.append(
-            "camera.h264.verification must be one of "
-            + ", ".join(VERIFICATION_LEVELS)
+    if schema_version == 1:
+        h264 = mapping(camera.get("h264"), "camera.h264", errors)
+        nullable_bool(h264.get("available"), "camera.h264.available", errors)
+        nullable_bool(
+            h264.get("key_frame_control"), "camera.h264.key_frame_control", errors
+        )
+        validate_verification(
+            h264.get("verification"), "camera.h264.verification", errors
         )
+    elif schema_version == 2:
+        validate_video_profiles(camera, source_ids, errors)
     validate_source_refs(camera, "camera", source_ids, errors)
 
     for name in ("audio_input", "audio_output"):
@@ -183,10 +479,23 @@ def validate_ir(data: dict[str, Any]) -> list[str]:
                 errors.append(f"features.requested contains duplicate {feature!r}")
             else:
                 seen.add(feature)
+
+    if schema_version == 2:
+        validate_hardware_resources(data, source_ids, errors)
+        validate_onboarding(data, source_ids, errors)
+        validate_runtime_evidence(data, source_ids, errors)
     return errors
 
 
-def codec_requirement(media: dict[str, Any], section: str) -> tuple[str, str, int]:
+def minimum_verification_for_phase(phase: str) -> str:
+    if phase == "intake":
+        return "corroborated"
+    return "build_verified"
+
+
+def codec_requirement(
+    media: dict[str, Any], section: str, minimum_verification: str = "corroborated"
+) -> Requirement:
     present = media.get("present")
     if present is None:
         return "NEEDS_CONFIRMATION", f"{section} presence is unknown", 0
@@ -200,17 +509,20 @@ def codec_requirement(media: dict[str, Any], section: str) -> tuple[str, str, in
             continue
         verification = codec.get("verification")
         level = VERIFICATION_LEVELS.get(verification, 0)
-        if level < VERIFICATION_LEVELS["corroborated"]:
+        if level < VERIFICATION_LEVELS[minimum_verification]:
             return (
                 "NEEDS_CONFIRMATION",
-                f"{section} A-law 8 kHz path is only {verification}",
+                f"{section} A-law 8 kHz path is only {verification}; "
+                f"{minimum_verification} is required",
                 level,
             )
         return "SATISFIED", f"{section} provides A-law 8 kHz", level
     return "BLOCKED", f"{section} has no A-law 8 kHz path", 0
 
 
-def video_requirement(camera: dict[str, Any]) -> tuple[str, str, int]:
+def legacy_video_requirement(
+    camera: dict[str, Any], minimum_verification: str = "corroborated"
+) -> Requirement:
     present = camera.get("present")
     if present is None:
         return "NEEDS_CONFIRMATION", "camera presence is unknown", 0
@@ -234,16 +546,260 @@ def video_requirement(camera: dict[str, Any]) -> tuple[str, str, int]:
         return "BLOCKED", "key-frame requests cannot reach the encoder", 0
     verification = h264.get("verification")
     level = VERIFICATION_LEVELS.get(verification, 0)
-    if level < VERIFICATION_LEVELS["corroborated"]:
+    if level < VERIFICATION_LEVELS[minimum_verification]:
         return (
             "NEEDS_CONFIRMATION",
-            f"H.264 Annex-B path is only {verification}",
+            f"H.264 Annex-B path is only {verification}; "
+            f"{minimum_verification} is required",
             level,
         )
     return "SATISFIED", "camera provides H.264 Annex-B and IDR control", level
 
 
-def combine_requirements(requirements: list[tuple[str, str, int]]) -> dict[str, Any]:
+def selected_item(items: Any, selected_id: Any) -> dict[str, Any] | None:
+    if not isinstance(items, list) or not isinstance(selected_id, str):
+        return None
+    for item in items:
+        if isinstance(item, dict) and item.get("id") == selected_id:
+            return item
+    return None
+
+
+def video_requirement_v2(
+    camera: dict[str, Any], minimum_verification: str = "corroborated"
+) -> Requirement:
+    present = camera.get("present")
+    if present is None:
+        return "NEEDS_CONFIRMATION", "camera presence is unknown", 0
+    if present is False:
+        return "BLOCKED", "camera is not present", 0
+    selected_id = camera.get("selected_video_profile")
+    if not isinstance(selected_id, str) or not selected_id:
+        return "NEEDS_CONFIRMATION", "selected video profile is unknown", 0
+    profile = selected_item(camera.get("video_profiles"), selected_id)
+    if profile is None:
+        return "BLOCKED", f"selected video profile {selected_id!r} does not exist", 0
+    codec = profile.get("codec")
+    if codec not in VIDEO_CONTRACTS:
+        return "BLOCKED", f"selected video codec {codec!r} is unsupported", 0
+    available = profile.get("available")
+    if available is None:
+        return "NEEDS_CONFIRMATION", f"{codec} path availability is unknown", 0
+    if available is False:
+        return "BLOCKED", f"selected {codec} path is unavailable", 0
+    output_format = profile.get("output_format")
+    if output_format is None:
+        return "NEEDS_CONFIRMATION", f"{codec} output format is unknown", 0
+    expected = VIDEO_CONTRACTS[codec]
+    if str(output_format).lower() != expected:
+        return (
+            "BLOCKED",
+            f"selected {codec} profile requires output_format={expected}",
+            0,
+        )
+    refresh = profile.get("refresh_frame_control")
+    if refresh is None:
+        return "NEEDS_CONFIRMATION", "refresh/key-frame control is unknown", 0
+    if refresh is False:
+        return "BLOCKED", "H5 refresh requests cannot reach the media pipeline", 0
+    verification = profile.get("verification")
+    level = VERIFICATION_LEVELS.get(verification, 0)
+    if level < VERIFICATION_LEVELS[minimum_verification]:
+        return (
+            "NEEDS_CONFIRMATION",
+            f"selected {codec} path is only {verification}; "
+            f"{minimum_verification} is required",
+            level,
+        )
+    return (
+        "SATISFIED",
+        f"selected {codec} profile provides {expected} on stream {profile.get('stream_id')}",
+        level,
+    )
+
+
+def verified_bool_requirement(
+    section: dict[str, Any],
+    field: str,
+    label: str,
+    minimum_verification: str = "corroborated",
+) -> Requirement:
+    value = section.get(field)
+    if value is None:
+        return "NEEDS_CONFIRMATION", f"{label} is unknown", 0
+    if value is False:
+        return "BLOCKED", f"{label} is unresolved", 0
+    verification = section.get("verification")
+    level = VERIFICATION_LEVELS.get(verification, 0)
+    if level < VERIFICATION_LEVELS[minimum_verification]:
+        return (
+            "NEEDS_CONFIRMATION",
+            f"{label} is only {verification}; {minimum_verification} is required",
+            level,
+        )
+    return "SATISFIED", f"{label} is resolved", level
+
+
+def i2c_requirement(
+    resources: dict[str, Any], minimum_verification: str = "corroborated"
+) -> Requirement:
+    i2c = resources.get("i2c", {})
+    used = i2c.get("used")
+    if used is None:
+        return "NEEDS_CONFIRMATION", "I2C usage is unknown", 0
+    if used is False:
+        return "SATISFIED", "board media path does not use I2C", 2
+    family = i2c.get("driver_family")
+    if family is None:
+        return "NEEDS_CONFIRMATION", "I2C driver family is unknown", 0
+    if family == "none":
+        return "BLOCKED", "I2C is used but no driver family is selected", 0
+    return verified_bool_requirement(
+        i2c,
+        "single_driver_family",
+        f"single {family} I2C driver family plan",
+        minimum_verification,
+    )
+
+
+def i2s_requirement(
+    resources: dict[str, Any], minimum_verification: str = "corroborated"
+) -> Requirement:
+    i2s = resources.get("i2s", {})
+    used = i2s.get("used")
+    if used is None:
+        return "NEEDS_CONFIRMATION", "I2S usage is unknown", 0
+    if used is False:
+        return "SATISFIED", "audio path does not use I2S", 2
+    return verified_bool_requirement(
+        i2s,
+        "controller_and_gpio_ownership_resolved",
+        "I2S controller and GPIO ownership plan",
+        minimum_verification,
+    )
+
+
+def audio_mapping_requirement(
+    resources: dict[str, Any], minimum_verification: str = "corroborated"
+) -> Requirement:
+    channel = resources.get("audio_channel_mapping", {})
+    required = channel.get("required")
+    if required is None:
+        return "NEEDS_CONFIRMATION", "audio channel/TDM mapping requirement is unknown", 0
+    if required is False:
+        return "SATISFIED", "audio channel/TDM mapping is not required", 2
+    return verified_bool_requirement(
+        channel,
+        "resolved",
+        "audio channel/TDM mapping",
+        minimum_verification,
+    )
+
+
+def camera_realtime_requirement(
+    resources: dict[str, Any], minimum_verification: str = "corroborated"
+) -> Requirement:
+    return verified_bool_requirement(
+        resources.get("camera_realtime", {}),
+        "pipeline_safe",
+        "camera DMA/task realtime policy design",
+        minimum_verification,
+    )
+
+
+def memory_requirement(
+    resources: dict[str, Any], minimum_verification: str = "corroborated"
+) -> Requirement:
+    return verified_bool_requirement(
+        resources.get("memory", {}),
+        "startup_and_media_budgeted",
+        "static startup and media memory budget",
+        minimum_verification,
+    )
+
+
+def wifi_requirement(onboarding: dict[str, Any]) -> Requirement:
+    wifi = onboarding.get("wifi_credentials", {})
+    committed = wifi.get("credentials_committed_to_source")
+    if committed is None:
+        return "NEEDS_CONFIRMATION", "credential source-control policy is unknown", 0
+    if committed is True:
+        return "BLOCKED", "Wi-Fi credentials are committed to source", 0
+    reprovisioning = wifi.get("reprovisioning_defined")
+    if reprovisioning is None:
+        return "NEEDS_CONFIRMATION", "Wi-Fi reprovisioning path is unknown", 0
+    if reprovisioning is False:
+        return "BLOCKED", "Wi-Fi reprovisioning path is undefined", 0
+    selected_id = wifi.get("selected_method")
+    if not isinstance(selected_id, str) or not selected_id:
+        return "NEEDS_CONFIRMATION", "Wi-Fi credential method is not selected", 0
+    method = selected_item(wifi.get("methods"), selected_id)
+    if method is None:
+        return "BLOCKED", f"selected Wi-Fi method {selected_id!r} does not exist", 0
+    available = method.get("available")
+    if available is None:
+        return "NEEDS_CONFIRMATION", "selected Wi-Fi method availability is unknown", 0
+    if available is False:
+        return "BLOCKED", "selected Wi-Fi method is unavailable", 0
+    verification = method.get("verification")
+    level = VERIFICATION_LEVELS.get(verification, 0)
+    if level < VERIFICATION_LEVELS["corroborated"]:
+        return (
+            "NEEDS_CONFIRMATION",
+            f"selected Wi-Fi method is only {verification}",
+            level,
+        )
+    return (
+        "SATISFIED",
+        f"Wi-Fi credentials use {method.get('type')} outside source control",
+        level,
+    )
+
+
+def binding_requirement(onboarding: dict[str, Any]) -> Requirement:
+    binding = onboarding.get("device_binding", {})
+    committed = binding.get("credentials_committed_to_source")
+    if committed is None:
+        return "NEEDS_CONFIRMATION", "device credential source-control policy is unknown", 0
+    if committed is True:
+        return "BLOCKED", "device credentials are committed to source", 0
+    for field in ("stored_credential_state_handled", "clear_binding_control"):
+        value = binding.get(field)
+        if value is None:
+            return "NEEDS_CONFIRMATION", f"device binding {field} is unknown", 0
+        if value is False:
+            return "BLOCKED", f"device binding {field} is unsupported", 0
+    selected_id = binding.get("selected_method")
+    if not isinstance(selected_id, str) or not selected_id:
+        return "NEEDS_CONFIRMATION", "device binding method is not selected", 0
+    method = selected_item(binding.get("methods"), selected_id)
+    if method is None:
+        return "BLOCKED", f"selected binding method {selected_id!r} does not exist", 0
+    available = method.get("available")
+    if available is None:
+        return "NEEDS_CONFIRMATION", "selected binding method availability is unknown", 0
+    if available is False:
+        return "BLOCKED", "selected binding method is unavailable", 0
+    verification = method.get("verification")
+    level = VERIFICATION_LEVELS.get(verification, 0)
+    if level < VERIFICATION_LEVELS["corroborated"]:
+        return (
+            "NEEDS_CONFIRMATION",
+            f"selected binding method is only {verification}",
+            level,
+        )
+    return (
+        "SATISFIED",
+        f"device binding uses {method.get('type')} outside source control",
+        level,
+    )
+
+
+def combine_requirements(
+    requirements: list[Requirement],
+    success_status: str = "READY_TO_PORT",
+    legacy_hil_from_levels: bool = False,
+) -> dict[str, Any]:
     reasons = [reason for _, reason, _ in requirements]
     states = {state for state, _, _ in requirements}
     levels = [level for state, _, level in requirements if state == "SATISFIED"]
@@ -251,15 +807,19 @@ def combine_requirements(requirements: list[tuple[str, str, int]]) -> dict[str,
         status = "BLOCKED"
     elif "NEEDS_CONFIRMATION" in states:
         status = "NEEDS_CONFIRMATION"
-    elif levels and min(levels) >= VERIFICATION_LEVELS["hil_verified"]:
+    elif (
+        legacy_hil_from_levels
+        and levels
+        and min(levels) >= VERIFICATION_LEVELS["hil_verified"]
+    ):
         status = "HIL_VERIFIED"
     else:
-        status = "READY_TO_PORT"
+        status = success_status
     return {"status": status, "reasons": reasons}
 
 
-def project_requirements(data: dict[str, Any]) -> list[tuple[str, str, int]]:
-    requirements: list[tuple[str, str, int]] = []
+def project_requirements(data: dict[str, Any]) -> list[Requirement]:
+    requirements: list[Requirement] = []
     revision = data["board"]["hardware_revision"].strip().lower()
     if revision in {"unknown", "unspecified", "n/a"}:
         requirements.append(
@@ -312,31 +872,195 @@ def project_requirements(data: dict[str, Any]) -> list[tuple[str, str, int]]:
     return requirements
 
 
-def assess_ir(data: dict[str, Any]) -> dict[str, Any]:
+def matching_runtime_evidence(
+    data: dict[str, Any], artifact_sha256: str | None
+) -> dict[str, Any] | None:
+    if artifact_sha256 is None:
+        return None
+    normalized = artifact_sha256.lower()
+    for record in data.get("runtime_evidence", []):
+        if (
+            isinstance(record, dict)
+            and str(record.get("artifact_sha256", "")).lower() == normalized
+        ):
+            return record
+    return None
+
+
+def artifact_requirement(artifact_sha256: str | None) -> Requirement:
+    if artifact_sha256 is None:
+        return "NEEDS_CONFIRMATION", "exact build artifact SHA-256 is missing", 0
+    if not SHA256_RE.fullmatch(artifact_sha256):
+        return "BLOCKED", "build artifact SHA-256 is invalid", 0
+    return (
+        "SATISFIED",
+        f"build evidence is bound to artifact {artifact_sha256}",
+        VERIFICATION_LEVELS["build_verified"],
+    )
+
+
+def assess_ir(
+    data: dict[str, Any],
+    artifact_sha256: str | None = None,
+    phase: str | None = None,
+) -> dict[str, Any]:
+    selected_phase = phase or ("hil" if artifact_sha256 else "intake")
+    if selected_phase not in ASSESSMENT_PHASES:
+        raise ValueError(
+            f"assessment phase must be one of {', '.join(sorted(ASSESSMENT_PHASES))}"
+        )
+    minimum_verification = minimum_verification_for_phase(selected_phase)
+    success_status = (
+        "READY_TO_PORT" if selected_phase == "intake" else "BUILD_VERIFIED"
+    )
+    schema_version = data.get("schema_version")
     requested = data["features"]["requested"]
     audio_input = data["audio_input"]
     audio_output = data["audio_output"]
     camera = data["camera"]
     result: dict[str, Any] = {}
+    project = project_requirements(data)
+    selected_video: dict[str, Any] | None = None
+    selected_wifi: dict[str, Any] | None = None
+    selected_binding: dict[str, Any] | None = None
+
+    if schema_version == 2:
+        resources = data["hardware_resources"]
+        onboarding = data["onboarding"]
+        project.extend(
+            [
+                i2c_requirement(resources, minimum_verification),
+                wifi_requirement(onboarding),
+                binding_requirement(onboarding),
+            ]
+        )
+        selected_video = selected_item(
+            camera.get("video_profiles"), camera.get("selected_video_profile")
+        )
+        wifi = onboarding.get("wifi_credentials", {})
+        selected_wifi = selected_item(wifi.get("methods"), wifi.get("selected_method"))
+        binding = onboarding.get("device_binding", {})
+        selected_binding = selected_item(
+            binding.get("methods"), binding.get("selected_method")
+        )
+    else:
+        resources = {}
+
+    if selected_phase in {"build", "hil"}:
+        project.append(artifact_requirement(artifact_sha256))
+
     for feature in requested:
+        if schema_version == 1:
+            if feature == "h5_live_audio":
+                requirements = [
+                    codec_requirement(
+                        audio_input, "audio_input", minimum_verification
+                    )
+                ]
+            elif feature == "h5_live_video":
+                requirements = [
+                    legacy_video_requirement(camera, minimum_verification)
+                ]
+            elif feature == "h5_talkback":
+                requirements = [
+                    codec_requirement(
+                        audio_output, "audio_output", minimum_verification
+                    )
+                ]
+            else:
+                requirements = [
+                    codec_requirement(
+                        audio_input, "audio_input", minimum_verification
+                    ),
+                    codec_requirement(
+                        audio_output, "audio_output", minimum_verification
+                    ),
+                ]
+            result[feature] = combine_requirements(
+                requirements,
+                success_status=success_status,
+                legacy_hil_from_levels=(selected_phase == "intake"),
+            )
+            continue
+
         if feature == "h5_live_audio":
-            requirements = [codec_requirement(audio_input, "audio_input")]
+            requirements = [
+                codec_requirement(audio_input, "audio_input", minimum_verification),
+                i2s_requirement(resources, minimum_verification),
+                audio_mapping_requirement(resources, minimum_verification),
+                memory_requirement(resources, minimum_verification),
+            ]
         elif feature == "h5_live_video":
-            requirements = [video_requirement(camera)]
+            requirements = [
+                video_requirement_v2(camera, minimum_verification),
+                camera_realtime_requirement(resources, minimum_verification),
+                memory_requirement(resources, minimum_verification),
+            ]
         elif feature == "h5_talkback":
-            requirements = [codec_requirement(audio_output, "audio_output")]
+            requirements = [
+                codec_requirement(audio_output, "audio_output", minimum_verification),
+                i2s_requirement(resources, minimum_verification),
+                memory_requirement(resources, minimum_verification),
+            ]
         else:
             requirements = [
-                codec_requirement(audio_input, "audio_input"),
-                codec_requirement(audio_output, "audio_output"),
+                codec_requirement(audio_input, "audio_input", minimum_verification),
+                codec_requirement(audio_output, "audio_output", minimum_verification),
+                i2s_requirement(resources, minimum_verification),
+                audio_mapping_requirement(resources, minimum_verification),
+                memory_requirement(resources, minimum_verification),
             ]
-        result[feature] = combine_requirements(requirements)
-    return {
+        result[feature] = combine_requirements(
+            requirements, success_status=success_status
+        )
+
+    project_gate = combine_requirements(
+        project,
+        success_status=success_status,
+        legacy_hil_from_levels=(schema_version == 1 and selected_phase == "intake"),
+    )
+    evidence = matching_runtime_evidence(data, artifact_sha256)
+    if schema_version == 2 and selected_phase == "hil":
+        evidence_features = set(evidence.get("features", [])) if evidence else set()
+        evidence_levels = (
+            set(evidence.get("acceptance_levels", [])) if evidence else set()
+        )
+        for feature, feature_assessment in result.items():
+            if feature_assessment["status"] != "BUILD_VERIFIED":
+                continue
+            required_level = FEATURE_HIL_LEVEL[feature]
+            if feature in evidence_features and required_level in evidence_levels:
+                feature_assessment["status"] = "HIL_VERIFIED"
+                feature_assessment["reasons"].append(
+                    f"artifact {artifact_sha256} passed {required_level}"
+                )
+            else:
+                feature_assessment["reasons"].append(
+                    f"artifact {artifact_sha256} has no matching {required_level} runtime evidence"
+                )
+        if result and all(
+            item["status"] == "HIL_VERIFIED" for item in result.values()
+        ) and project_gate["status"] == "BUILD_VERIFIED":
+            project_gate["status"] = "HIL_VERIFIED"
+            project_gate["reasons"].append(
+                f"all requested features have matching artifact evidence for {artifact_sha256}"
+            )
+
+    assessment: dict[str, Any] = {
+        "schema_version": schema_version,
+        "phase": selected_phase,
         "board_id": data["board"]["id"],
         "hardware_revision": data["board"]["hardware_revision"],
-        "project_gate": combine_requirements(project_requirements(data)),
+        "project_gate": project_gate,
         "features": result,
     }
+    if schema_version == 2:
+        assessment["selected_video_profile"] = selected_video
+        assessment["selected_wifi_method"] = selected_wifi
+        assessment["selected_binding_method"] = selected_binding
+        assessment["artifact_sha256"] = artifact_sha256
+        assessment["artifact_evidence_matched"] = evidence is not None
+    return assessment
 
 
 def command_init(args: argparse.Namespace) -> int:
@@ -344,7 +1068,11 @@ def command_init(args: argparse.Namespace) -> int:
     if output.exists():
         print(f"refusing to overwrite existing file: {output}", file=sys.stderr)
         return 2
-    example = Path(__file__).resolve().parent.parent / "assets" / "hardware-ir.example.json"
+    example = (
+        Path(__file__).resolve().parent.parent
+        / "assets"
+        / "hardware-ir-v2.example.json"
+    )
     output.parent.mkdir(parents=True, exist_ok=True)
     shutil.copyfile(example, output)
     print(f"created Hardware IR: {output}")
@@ -377,14 +1105,26 @@ def command_assess(args: argparse.Namespace) -> int:
         for error in errors:
             print(f"error: {error}", file=sys.stderr)
         return 2
-    assessment = assess_ir(data)
+    if args.artifact_sha256 is not None and not SHA256_RE.fullmatch(
+        args.artifact_sha256
+    ):
+        print("error: --artifact-sha256 must be a 64-character SHA-256", file=sys.stderr)
+        return 2
+    try:
+        assessment = assess_ir(
+            data,
+            artifact_sha256=args.artifact_sha256,
+            phase=args.phase,
+        )
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
     print(json.dumps(assessment, ensure_ascii=False, indent=2))
     if args.strict:
-        statuses = {
-            item["status"] for item in assessment["features"].values()
-        }
+        statuses = {item["status"] for item in assessment["features"].values()}
         statuses.add(assessment["project_gate"]["status"])
-        if not statuses.issubset(READY_STATUSES):
+        allowed_statuses = PHASE_SUCCESS_STATUSES[assessment["phase"]]
+        if not statuses.issubset(allowed_statuses):
             return 3
     return 0
 
@@ -395,7 +1135,7 @@ def parse_args() -> argparse.Namespace:
     )
     subparsers = parser.add_subparsers(dest="command", required=True)
 
-    init_parser = subparsers.add_parser("init", help="create a new Hardware IR")
+    init_parser = subparsers.add_parser("init", help="create a new Hardware IR v2")
     init_parser.add_argument("output", type=Path)
     init_parser.set_defaults(handler=command_init)
 
@@ -410,7 +1150,16 @@ def parse_args() -> argparse.Namespace:
     assess_parser.add_argument(
         "--strict",
         action="store_true",
-        help="return non-zero unless every requested feature is ready or HIL verified",
+        help="return non-zero unless every requested feature passes the selected phase",
+    )
+    assess_parser.add_argument(
+        "--phase",
+        choices=sorted(ASSESSMENT_PHASES),
+        help="assessment phase; defaults to intake, or hil when an artifact SHA is supplied",
+    )
+    assess_parser.add_argument(
+        "--artifact-sha256",
+        help="bind build or HIL assessment to this exact firmware artifact",
     )
     assess_parser.set_defaults(handler=command_assess)
     return parser.parse_args()