tirtc-device-builder 0.7.2 → 0.8.0

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

@@ -22,8 +22,18 @@ FEATURES = {
     "h5_live_video",
     "h5_talkback",
     "ai_talk",
+    "device_call",
+    "wechat_voip",
 }
-AUDIO_FEATURES = {"h5_live_audio", "h5_talkback", "ai_talk"}
+AUDIO_FEATURES = {
+    "h5_live_audio",
+    "h5_talkback",
+    "ai_talk",
+    "device_call",
+    "wechat_voip",
+}
+AEC_REQUIRED_FEATURES = {"ai_talk", "device_call", "wechat_voip"}
+BUSINESS_FEATURES = {"device_call", "wechat_voip"}
 VIDEO_FEATURES = {"h5_live_video"}
 VERIFICATION_LEVELS = {
     "extracted": 1,
@@ -63,6 +73,8 @@ FEATURE_HIL_LEVEL = {
     "h5_live_video": "L5",
     "h5_talkback": "L5",
     "ai_talk": "L6",
+    "device_call": "L6",
+    "wechat_voip": "L6",
 }
 SHA256_RE = re.compile(r"^[0-9a-fA-F]{64}$")
 SOURCE_SCHEME_RE = re.compile(r"^([A-Za-z][A-Za-z0-9+.-]*):")
@@ -345,6 +357,28 @@ def validate_hardware_resources(
         errors,
     )
 
+    duplex = mapping(
+        resources.get("duplex_audio", {}),
+        "hardware_resources.duplex_audio",
+        errors,
+    )
+    for field in (
+        "simultaneous_capture_playback",
+        "playback_reference_available",
+        "aec_implementation_available",
+    ):
+        nullable_bool(
+            duplex.get(field),
+            f"hardware_resources.duplex_audio.{field}",
+            errors,
+        )
+    if "verification" in duplex:
+        validate_verification(
+            duplex.get("verification"),
+            "hardware_resources.duplex_audio.verification",
+            errors,
+        )
+
     realtime = mapping(
         resources.get("camera_realtime"),
         "hardware_resources.camera_realtime",
@@ -826,6 +860,27 @@ def audio_mapping_requirement(
     )
 
 
+def aec_capability_requirement(
+    resources: dict[str, Any], minimum_verification: str = "corroborated"
+) -> Requirement:
+    duplex = resources.get("duplex_audio", {})
+    for field, label in (
+        ("simultaneous_capture_playback", "simultaneous capture and playback"),
+        ("playback_reference_available", "physical playback-reference capture path"),
+        ("aec_implementation_available", "AEC processor implementation"),
+    ):
+        requirement = verified_bool_requirement(
+            duplex, field, label, minimum_verification
+        )
+        if requirement[0] != "SATISFIED":
+            return requirement
+    return (
+        "SATISFIED",
+        "full-duplex audio, playback reference, and AEC implementation are resolved",
+        VERIFICATION_LEVELS.get(duplex.get("verification"), 0),
+    )
+
+
 def camera_realtime_requirement(
     resources: dict[str, Any], minimum_verification: str = "corroborated"
 ) -> Requirement:
@@ -979,20 +1034,22 @@ def project_requirements(data: dict[str, Any]) -> list[Requirement]:
         )
 
     target = data["soc"]["target"].strip().lower()
-    if target != "esp32s3":
+    if target not in {"esp32s3", "esp32p4"}:
         requirements.append(
             (
                 "BLOCKED",
-                f"current starter generator supports esp32s3, not {target}",
+                f"TiRTC ESP32 workflow supports esp32s3 or esp32p4, not {target}",
                 0,
             )
         )
     else:
-        requirements.append(("SATISFIED", "ESP32-S3 starter is available", 2))
+        requirements.append(
+            ("SATISFIED", f"{target} is a supported TiRTC target", 2)
+        )
 
     platform = data["toolchain"]["tirtc"]["platform"].strip().lower()
-    expected_platform = "espressif-esp32s3"
-    if target == "esp32s3" and platform != expected_platform:
+    expected_platform = f"espressif-{target}"
+    if target in {"esp32s3", "esp32p4"} and platform != expected_platform:
         requirements.append(
             (
                 "BLOCKED",
@@ -1113,6 +1170,8 @@ def assess_ir(
     artifact_sha256: str | None = None,
     phase: str | None = None,
     audio_gate: Requirement | None = None,
+    aec_gate: Requirement | None = None,
+    business_gate: Requirement | None = None,
     video_gate: Requirement | None = None,
     runtime_gate: Requirement | None = None,
     artifact_gate: Requirement | None = None,
@@ -1189,6 +1248,14 @@ def assess_ir(
                         audio_output, "audio_output", minimum_verification
                     ),
                 ]
+            if feature in AEC_REQUIRED_FEATURES:
+                requirements.append(
+                    (
+                        "NEEDS_CONFIRMATION",
+                        "AEC-required sessions need Hardware IR v2 duplex_audio evidence",
+                        0,
+                    )
+                )
             result[feature] = combine_requirements(
                 requirements,
                 success_status=success_status,
@@ -1223,6 +1290,10 @@ def assess_ir(
                 audio_mapping_requirement(resources, minimum_verification),
                 memory_requirement(resources, minimum_verification),
             ]
+        if feature in AEC_REQUIRED_FEATURES:
+            requirements.append(
+                aec_capability_requirement(resources, minimum_verification)
+            )
         if feature in AUDIO_FEATURES and selected_phase in {"build", "hil"}:
             requirements.append(
                 audio_gate
@@ -1232,6 +1303,15 @@ def assess_ir(
                     0,
                 )
             )
+        if feature in AEC_REQUIRED_FEATURES and selected_phase in {"build", "hil"}:
+            requirements.append(
+                aec_gate
+                or (
+                    "BLOCKED",
+                    "AEC semantic gate did not prove simultaneous full-duplex audio and enabled echo cancellation",
+                    0,
+                )
+            )
         if feature in VIDEO_FEATURES and selected_phase in {"build", "hil"}:
             requirements.append(
                 video_gate
@@ -1250,6 +1330,15 @@ def assess_ir(
                     0,
                 )
             )
+        if feature in BUSINESS_FEATURES and selected_phase in {"build", "hil"}:
+            requirements.append(
+                business_gate
+                or (
+                    "BLOCKED",
+                    "business runtime gate did not prove the requested call/VoIP protocol and session arbiter",
+                    0,
+                )
+            )
         result[feature] = combine_requirements(
             requirements, success_status=success_status
         )
@@ -1359,6 +1448,7 @@ def command_assess(args: argparse.Namespace) -> int:
     )
     project = (args.project or args.path.parent).expanduser().resolve()
     audio_gate: Requirement | None = None
+    aec_gate: Requirement | None = None
     audio_gate_result: dict[str, Any] | None = None
     if (
         data.get("schema_version") == 2
@@ -1394,6 +1484,24 @@ def command_assess(args: argparse.Namespace) -> int:
                     + str(audio_gate_result.get("summary", "verified")),
                     VERIFICATION_LEVELS["build_verified"],
                 )
+                if AEC_REQUIRED_FEATURES.intersection(
+                    data["features"]["requested"]
+                ):
+                    if (
+                        audio_gate_result.get("simultaneous_capture_playback") is True
+                        and audio_gate_result.get("echo_cancellation_enabled") is True
+                    ):
+                        aec_gate = (
+                            "SATISFIED",
+                            "AEC gate proved simultaneous capture/playback with echo cancellation enabled",
+                            VERIFICATION_LEVELS["build_verified"],
+                        )
+                    else:
+                        aec_gate = (
+                            "BLOCKED",
+                            "AI/call/VoIP requires simultaneous capture/playback and echo_cancellation.enabled=true",
+                            0,
+                        )
             else:
                 audio_gate = (
                     "BLOCKED",
@@ -1445,6 +1553,7 @@ def command_assess(args: argparse.Namespace) -> int:
                     0,
                 )
     runtime_gate: Requirement | None = None
+    business_gate: Requirement | None = None
     runtime_gate_result: dict[str, Any] | None = None
     if data.get("schema_version") == 2 and selected_phase in {"build", "hil"}:
         relative_contract = data["hardware_resources"].get(
@@ -1469,13 +1578,41 @@ def command_assess(args: argparse.Namespace) -> int:
                 }
             else:
                 runtime_gate_result = verify_runtime_contract(contract, project)
-            if runtime_gate_result["ok"]:
+            if runtime_gate_result.get("base_ok", runtime_gate_result["ok"]):
+                requested_business = (
+                    set(data["features"]["requested"]) & BUSINESS_FEATURES
+                )
+                verified_business = set(
+                    runtime_gate_result.get("business_features", [])
+                )
+                missing_business = requested_business - verified_business
                 runtime_gate = (
                     "SATISFIED",
-                    "TiRTC runtime semantic gate passed: "
+                    "TiRTC base runtime semantic gate passed: "
                     + str(runtime_gate_result.get("summary", "verified")),
                     VERIFICATION_LEVELS["build_verified"],
                 )
+                if requested_business and (
+                    runtime_gate_result.get("business_ok") is not True
+                    or missing_business
+                ):
+                    details = list(runtime_gate_result.get("business_errors", []))
+                    if missing_business:
+                        details.append(
+                            "missing features: " + ", ".join(sorted(missing_business))
+                        )
+                    business_gate = (
+                        "BLOCKED",
+                        "TiRTC business runtime gate failed: " + "; ".join(details),
+                        0,
+                    )
+                elif requested_business:
+                    business_gate = (
+                        "SATISFIED",
+                        "TiRTC business runtime gate verified: "
+                        + ", ".join(sorted(requested_business)),
+                        VERIFICATION_LEVELS["build_verified"],
+                    )
             else:
                 runtime_gate = (
                     "BLOCKED",
@@ -1494,6 +1631,8 @@ def command_assess(args: argparse.Namespace) -> int:
             artifact_sha256=args.artifact_sha256,
             phase=selected_phase,
             audio_gate=audio_gate,
+            aec_gate=aec_gate,
+            business_gate=business_gate,
             video_gate=video_gate,
             runtime_gate=runtime_gate,
             artifact_gate=artifact_gate,

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

@@ -6,6 +6,7 @@ from __future__ import annotations
 import argparse
 import json
 import re
+import subprocess
 import sys
 from pathlib import Path
 from typing import Any
@@ -13,8 +14,30 @@ from typing import Any
 
 ABSOLUTE_PATH = re.compile(r"(?:^|[\s\"'])(?:/home/|/root/|[A-Za-z]:[\\/])")
 BUILD_INPUT_NAMES = {"CMakeLists.txt", "idf_component.yml", "idf_component.yaml"}
-BUILD_INPUT_SUFFIXES = {".c", ".h", ".cmake", ".py", ".sh"}
+BUILD_INPUT_SUFFIXES = {
+    ".c",
+    ".cmake",
+    ".csv",
+    ".defaults",
+    ".env",
+    ".h",
+    ".json",
+    ".lock",
+    ".py",
+    ".sh",
+    ".txt",
+    ".yaml",
+    ".yml",
+}
 SKIP_PARTS = {"build", "managed_components", ".git"}
+REQUIRED_PROJECT_INPUTS = {
+    "dependencies.lock",
+    "hardware-ir.json",
+    "sdkconfig.defaults",
+}
+PARTITION_FILE_RE = re.compile(
+    r'^CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="([^"]+)"$', re.MULTILINE
+)
 
 
 def source_files(project: Path):
@@ -26,13 +49,156 @@ def source_files(project: Path):
             yield path
 
 
+def project_file(
+    project: Path, value: Any, label: str, errors: list[str]
+) -> Path | None:
+    if not isinstance(value, str) or not value.strip():
+        errors.append(f"{label} must be a non-empty project-relative path")
+        return None
+    relative = Path(value)
+    if relative.is_absolute():
+        errors.append(f"{label} must be project-relative, got {value!r}")
+        return None
+    resolved = (project / relative).resolve()
+    if project != resolved and project not in resolved.parents:
+        errors.append(f"{label} escapes project root: {value!r}")
+        return None
+    return resolved
+
+
+def load_hardware_ir(project: Path, errors: list[str]) -> dict[str, Any] | None:
+    path = project / "hardware-ir.json"
+    if not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        errors.append(f"hardware-ir.json is invalid: {exc}")
+        return None
+    if not isinstance(data, dict):
+        errors.append("hardware-ir.json root must be an object")
+        return None
+    return data
+
+
+def required_project_files(
+    project: Path, export: bool, errors: list[str]
+) -> set[Path]:
+    required = {(project / relative).resolve() for relative in REQUIRED_PROJECT_INPUTS}
+    ir = load_hardware_ir(project, errors)
+    if ir is not None:
+        schema_version = ir.get("schema_version")
+        requested = ir.get("features", {}).get("requested", [])
+        if schema_version == 2:
+            resources = ir.get("hardware_resources")
+            if not isinstance(resources, dict):
+                errors.append("hardware-ir.json hardware_resources must be an object")
+            else:
+                contract_fields = ["runtime_semantic_contract"]
+                if {"h5_live_audio", "h5_talkback", "ai_talk"}.intersection(
+                    requested
+                ):
+                    contract_fields.append("audio_semantic_contract")
+                if "h5_live_video" in requested:
+                    contract_fields.append("video_semantic_contract")
+                for field in contract_fields:
+                    path = project_file(
+                        project,
+                        resources.get(field),
+                        f"hardware_resources.{field}",
+                        errors,
+                    )
+                    if path is not None:
+                        required.add(path)
+        elif (
+            schema_version == 1
+            and "h5_live_video" in requested
+            and ir.get("camera", {}).get("h264", {}).get("available") is not True
+        ):
+            errors.append(
+                "schema v1 can only export the legacy H.264 video contract; "
+                "migrate Hardware IR to schema v2 for MJPEG or H.265"
+            )
+
+        if export:
+            artifacts = ir.get("build_evidence", {}).get("artifacts")
+            if not isinstance(artifacts, list) or not artifacts:
+                errors.append(
+                    "hardware-ir.json build_evidence.artifacts must retain at least "
+                    "one verified deliverable for export"
+                )
+            else:
+                for index, record in enumerate(artifacts):
+                    if not isinstance(record, dict):
+                        errors.append(
+                            f"build_evidence.artifacts[{index}] must be an object"
+                        )
+                        continue
+                    path = project_file(
+                        project,
+                        record.get("path"),
+                        f"build_evidence.artifacts[{index}].path",
+                        errors,
+                    )
+                    if path is not None:
+                        required.add(path)
+
+    for config_name in ("sdkconfig.defaults", "sdkconfig"):
+        config = project / config_name
+        if not config.is_file():
+            continue
+        text = config.read_text(encoding="utf-8", errors="replace")
+        match = PARTITION_FILE_RE.search(text)
+        if match:
+            path = project_file(
+                project,
+                match.group(1),
+                f"{config_name} custom partition table",
+                errors,
+            )
+            if path is not None:
+                required.add(path)
+    return required
+
+
+def git_root(project: Path) -> Path | None:
+    result = subprocess.run(
+        ["git", "-C", str(project), "rev-parse", "--show-toplevel"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        return None
+    return Path(result.stdout.strip()).resolve()
+
+
+def git_ignored(root: Path, path: Path) -> bool:
+    try:
+        relative = path.relative_to(root)
+    except ValueError:
+        return False
+    result = subprocess.run(
+        ["git", "-C", str(root), "check-ignore", "--quiet", "--", relative.as_posix()],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        check=False,
+    )
+    return result.returncode == 0
+
+
 def check_project(project_path: Path, export: bool = False) -> dict[str, Any]:
     project = project_path.expanduser().resolve()
     errors: list[str] = []
     if not (project / "CMakeLists.txt").is_file():
         return {"ok": False, "errors": ["CMakeLists.txt is missing"]}
-    if not (project / "dependencies.lock").is_file():
-        errors.append("dependencies.lock is missing")
+    required = required_project_files(project, export, errors)
+    for path in sorted(required):
+        if not path.is_file():
+            errors.append(
+                f"required portable input is missing: {path.relative_to(project)}"
+            )
     sdk_required = (
         project / "third_party" / "tirtc" / "include" / "tirtc" / "tiRTC.h",
         project / "third_party" / "tirtc" / "lib" / "libTiRTC.a",
@@ -43,6 +209,15 @@ def check_project(project_path: Path, export: bool = False) -> dict[str, Any]:
         errors.append("bundled TiRTC SDK is incomplete: " + ", ".join(missing_sdk))
     if export and (project / "build").exists():
         errors.append("export source contains a machine-bound build/ directory")
+    if export:
+        root = git_root(project)
+        if root is not None:
+            for path in sorted(required):
+                if path.is_file() and git_ignored(root, path):
+                    errors.append(
+                        "required portable input is ignored by Git: "
+                        f"{path.relative_to(project)}"
+                    )
 
     for path in source_files(project):
         relative = path.relative_to(project)

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

@@ -37,6 +37,30 @@ VIDEO_PROFILES = {
     "h264": ("TIRTC_VIDEO_H264", "annex_b_access_unit"),
     "h265": ("TIRTC_VIDEO_H265", "annex_b_access_unit"),
 }
+BUSINESS_FEATURES = {"device_call", "wechat_voip"}
+BUSINESS_PROTOCOL_TOKENS = {
+    "device_call": (
+        "/v1/call/request",
+        "/v1/call/device/info",
+        "/v1/call/reject",
+        "/v1/call/cancel",
+        "/v1/call/hangup",
+        "/v1/call/room",
+        "call_incoming",
+        "room_cancel",
+        "call_reject",
+    ),
+    "wechat_voip": (
+        "/v1/voip/device/profile",
+        "/v1/voip/device/contacts",
+        "/v1/voip/device/call",
+        "call_incoming",
+        "callers_update",
+        "wx_call_id",
+        "wxcall",
+    ),
+}
+GIT_SHA_RE = re.compile(r"^[0-9a-fA-F]{40}$")
 
 
 def sha256_file(path: Path) -> str:
@@ -150,6 +174,89 @@ def check_platform_contract(platform: Any, errors: list[str]) -> None:
         )
 
 
+def check_business_contract(
+    contract: dict[str, Any],
+    project: Path,
+    errors: list[str],
+    inputs: dict[str, str],
+) -> set[str]:
+    business = contract.get("business")
+    if business is None:
+        return set()
+    if not isinstance(business, dict):
+        errors.append("business must be an object")
+        return set()
+    features = business.get("features", [])
+    if not isinstance(features, list) or any(
+        not isinstance(feature, str) for feature in features
+    ):
+        errors.append("business.features must be an array of feature names")
+        return set()
+    selected = set(features)
+    unknown = selected - BUSINESS_FEATURES
+    if unknown:
+        errors.append(
+            "business.features contains unsupported features: "
+            + ", ".join(sorted(unknown))
+        )
+    if not selected:
+        return set()
+
+    revision = business.get("protocol_revision")
+    if not isinstance(revision, str) or not GIT_SHA_RE.fullmatch(revision):
+        errors.append(
+            "business.protocol_revision must pin the 40-character tirtc-server-example commit"
+        )
+    arbiter = business.get("session_arbiter")
+    if not isinstance(arbiter, dict):
+        errors.append("business.session_arbiter must be an object")
+    else:
+        for field in (
+            "single_foreground_owner",
+            "generation_guard",
+            "monotonic_deadlines",
+            "deferred_lifecycle",
+            "restore_h5_after_call",
+        ):
+            if arbiter.get(field) is not True:
+                errors.append(f"business.session_arbiter.{field} must be true")
+        if arbiter.get("pending_capacity") != 1:
+            errors.append("business.session_arbiter.pending_capacity must be 1")
+
+    assertions = business.get("implementation_assertions")
+    combined = ""
+    if not isinstance(assertions, list) or not assertions:
+        errors.append("business.implementation_assertions must be a non-empty array")
+    else:
+        for index, assertion in enumerate(assertions):
+            label = f"business.implementation_assertions[{index}]"
+            if not isinstance(assertion, dict):
+                errors.append(f"{label} must be an object")
+                continue
+            try:
+                source = project_file(project, assertion.get("file"), f"{label}.file")
+            except ValueError as exc:
+                errors.append(str(exc))
+                continue
+            if not source.is_file():
+                errors.append(f"{label}.file does not exist: {source}")
+                continue
+            text = source.read_text(encoding="utf-8", errors="replace")
+            combined += "\n" + text
+            inputs[str(source.relative_to(project))] = sha256_file(source)
+            for token in assertion.get("contains", []):
+                if not isinstance(token, str) or not token:
+                    errors.append(f"{label}.contains must contain non-empty strings")
+                elif token not in text:
+                    errors.append(f"{label} is missing token: {token}")
+
+    for feature in sorted(selected & BUSINESS_FEATURES):
+        for token in BUSINESS_PROTOCOL_TOKENS[feature]:
+            if token not in combined:
+                errors.append(f"business {feature} is missing protocol token: {token}")
+    return selected & BUSINESS_FEATURES
+
+
 def verify_contract(contract_path: Path, project_path: Path) -> dict[str, Any]:
     project = project_path.expanduser().resolve()
     contract_file = contract_path.expanduser().resolve()
@@ -275,9 +382,23 @@ def verify_contract(contract_path: Path, project_path: Path) -> dict[str, Any]:
     ):
         errors.append("AI media must start only from the validated command handler")
 
+    base_errors = list(errors)
+    business_errors: list[str] = []
+    business_features = check_business_contract(
+        contract, project, business_errors, inputs
+    )
+    errors.extend(business_errors)
+
     return {
         "ok": not errors,
-        "summary": "endpoint + callbacks + H5/AI stream and negotiation contract",
+        "base_ok": not base_errors,
+        "business_ok": not business_errors,
+        "summary": (
+            "endpoint + callbacks + H5/AI stream and negotiation contract; "
+            f"business={','.join(sorted(business_features)) or 'none'}"
+        ),
+        "business_features": sorted(business_features),
+        "business_errors": business_errors,
         "inputs": inputs,
         "errors": errors,
     }