tirtc-device-builder 0.6.0 → 0.7.0

package/skills/tirtc-esp32-builder/references/workflow.md

@@ -62,12 +62,14 @@ The adapter owns:
 - DMA buffers, hardware clocks, power, reset, GPIO, refresh/key-frame requests, and realtime task allocation;
 - bounded stop, resource release, and generation-aware flushing.
 
-The stable modules own stream IDs, negotiated/contracted formats, TiRTC callback copying, connection handles, session generation, and H5/AI sequencing.
+The stable modules own the discovered TiRTC service endpoint, stream IDs, negotiated/contracted formats, TiRTC callback copying, connection handles, session generation, and H5/AI sequencing. SDK lifecycle changes such as disconnect run in a worker/state-machine context, never directly inside an SDK callback.
 
 ## Verification loop
 
 Use a bounded loop per layer: diagnose one failing invariant, make the smallest correction, and rerun that layer before moving forward. Change one high-risk variable per HIL comparison. Turn reusable invariants into tests or post-link gates. Stop and report when the remaining failure requires unavailable hardware, credentials, a new SDK binary, a public protocol change, or a user choice.
 
+For every generated H5/AI project, validate `tirtc-runtime-contract.json` and run `install_runtime_gate.py <project>` before the ordinary build. Audio and video projects additionally install their media gates. A build that bypasses any applicable gate is not `BUILD_VERIFIED`.
+
 Run the assessor once per layer:
 
 - `--phase intake`: corroborated design evidence; success is `READY_TO_PORT`.

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

@@ -124,8 +124,14 @@ def compare_contract(
         actual = config.get(key)
         if expected is None:
             mismatches.append(f"SDK contract does not declare {key}")
+        elif actual is None and expected.lower() == "off":
+            # ESP-IDF omits some disabled child booleans from the final sdkconfig
+            # when their parent dependency is off. An absent boolean therefore has
+            # the same effective value as "# ... is not set" for this fixed set of
+            # SDK ABI options. Expected-on and scalar values remain strict.
+            continue
         elif actual is None:
-            mismatches.append(f"project does not explicitly configure {key}={expected}")
+            mismatches.append(f"project does not configure required {key}={expected}")
         elif actual.lower() != expected.lower():
             mismatches.append(f"{key}: expected {expected}, got {actual}")
     return mismatches

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

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import argparse
+import hashlib
 import json
 import re
 import shutil
@@ -12,6 +13,7 @@ from pathlib import Path
 from typing import Any
 
 from audio_contract import verify_contract as verify_audio_contract
+from runtime_contract import verify_contract as verify_runtime_contract
 from video_contract import verify_contract as verify_video_contract
 
 
@@ -63,6 +65,16 @@ FEATURE_HIL_LEVEL = {
     "ai_talk": "L6",
 }
 SHA256_RE = re.compile(r"^[0-9a-fA-F]{64}$")
+SOURCE_SCHEME_RE = re.compile(r"^([A-Za-z][A-Za-z0-9+.-]*):")
+ALLOWED_SOURCE_SCHEMES = {
+    "http",
+    "https",
+    "device-kit",
+    "managed",
+    "official",
+    "user-input",
+    "user-supplied",
+}
 Requirement = tuple[str, str, int]
 
 
@@ -78,6 +90,62 @@ def load_ir(path: Path) -> dict[str, Any]:
     return data
 
 
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def validate_source_locations(data: dict[str, Any], ir_directory: Path) -> list[str]:
+    """Resolve local evidence and reject invented or machine-bound source locators."""
+    errors: list[str] = []
+    root = ir_directory.expanduser().resolve()
+    sources = data.get("sources")
+    if not isinstance(sources, list):
+        return errors
+    for index, item in enumerate(sources):
+        if not isinstance(item, dict):
+            continue
+        prefix = f"sources[{index}]"
+        location = item.get("location")
+        if not isinstance(location, str) or not location.strip():
+            continue
+        if ";" in location:
+            errors.append(
+                f"{prefix}.location must identify exactly one source, not a semicolon list"
+            )
+            continue
+        scheme_match = SOURCE_SCHEME_RE.match(location)
+        if scheme_match is not None:
+            scheme = scheme_match.group(1).lower()
+            if scheme not in ALLOWED_SOURCE_SCHEMES:
+                errors.append(
+                    f"{prefix}.location uses unsupported source scheme {scheme!r}"
+                )
+            continue
+        relative = Path(location)
+        if relative.is_absolute():
+            errors.append(
+                f"{prefix}.location must be IR-relative or a supported source URI"
+            )
+            continue
+        resolved = (root / relative).resolve()
+        if not resolved.exists():
+            errors.append(
+                f"{prefix}.location does not resolve from the IR directory: {location}"
+            )
+            continue
+        expected_sha = item.get("sha256")
+        if expected_sha is not None:
+            if not resolved.is_file():
+                errors.append(f"{prefix}.sha256 can only describe a regular file")
+            elif sha256_file(resolved).lower() != str(expected_sha).lower():
+                errors.append(f"{prefix}.sha256 does not match {location}")
+    return errors
+
+
 def mapping(value: Any, path: str, errors: list[str]) -> dict[str, Any]:
     if not isinstance(value, dict):
         errors.append(f"{path} must be an object")
@@ -245,6 +313,16 @@ def validate_hardware_resources(
         errors.append(
             "hardware_resources.video_semantic_contract must be project-relative"
         )
+    runtime_contract = resources.get("runtime_semantic_contract")
+    nullable_string(
+        runtime_contract,
+        "hardware_resources.runtime_semantic_contract",
+        errors,
+    )
+    if isinstance(runtime_contract, str) and Path(runtime_contract).is_absolute():
+        errors.append(
+            "hardware_resources.runtime_semantic_contract must be project-relative"
+        )
 
     mapping_section = mapping(
         resources.get("audio_channel_mapping"),
@@ -462,6 +540,11 @@ def validate_ir(data: dict[str, Any]) -> list[str]:
             source = mapping(item, prefix, errors)
             for key in ("id", "kind", "location"):
                 nonempty_string(source.get(key), f"{prefix}.{key}", errors)
+            source_sha = source.get("sha256")
+            if source_sha is not None and (
+                not isinstance(source_sha, str) or not SHA256_RE.fullmatch(source_sha)
+            ):
+                errors.append(f"{prefix}.sha256 must be a 64-character SHA-256")
             source_id = source.get("id")
             if isinstance(source_id, str) and source_id:
                 if source_id in source_ids:
@@ -993,12 +1076,46 @@ def artifact_requirement(
     )
 
 
+def artifact_file_requirement(
+    data: dict[str, Any], artifact_sha256: str | None, project: Path
+) -> Requirement:
+    recorded = artifact_requirement(data, artifact_sha256)
+    if recorded[0] != "SATISFIED" or artifact_sha256 is None:
+        return recorded
+    record = matching_build_artifact(data, artifact_sha256)
+    if record is None:
+        return "BLOCKED", "matching build artifact record disappeared", 0
+    value = record.get("path")
+    if not isinstance(value, str) or not value:
+        return "BLOCKED", "matching build artifact path is missing", 0
+    relative = Path(value)
+    if relative.is_absolute():
+        return "BLOCKED", "matching build artifact path is not project-relative", 0
+    root = project.expanduser().resolve()
+    path = (root / relative).resolve()
+    if root != path and root not in path.parents:
+        return "BLOCKED", "matching build artifact path escapes project root", 0
+    if not path.is_file():
+        return "BLOCKED", f"recorded build artifact does not exist: {value}", 0
+    if path.stat().st_size != record.get("size_bytes"):
+        return "BLOCKED", f"recorded build artifact size is stale for {value}", 0
+    if sha256_file(path).lower() != artifact_sha256.lower():
+        return "BLOCKED", f"recorded build artifact SHA-256 is stale for {value}", 0
+    return (
+        "SATISFIED",
+        f"artifact file {value} matches size and SHA-256",
+        VERIFICATION_LEVELS["build_verified"],
+    )
+
+
 def assess_ir(
     data: dict[str, Any],
     artifact_sha256: str | None = None,
     phase: str | None = None,
     audio_gate: Requirement | None = None,
     video_gate: Requirement | None = None,
+    runtime_gate: Requirement | None = None,
+    artifact_gate: Requirement | None = None,
 ) -> dict[str, Any]:
     selected_phase = phase or ("hil" if artifact_sha256 else "intake")
     if selected_phase not in ASSESSMENT_PHASES:
@@ -1043,7 +1160,7 @@ def assess_ir(
         resources = {}
 
     if selected_phase in {"build", "hil"}:
-        project.append(artifact_requirement(data, artifact_sha256))
+        project.append(artifact_gate or artifact_requirement(data, artifact_sha256))
 
     for feature in requested:
         if schema_version == 1:
@@ -1124,6 +1241,15 @@ def assess_ir(
                     0,
                 )
             )
+        if selected_phase in {"build", "hil"}:
+            requirements.append(
+                runtime_gate
+                or (
+                    "NEEDS_CONFIRMATION",
+                    "TiRTC runtime semantic gate was not executed for this project",
+                    0,
+                )
+            )
         result[feature] = combine_requirements(
             requirements, success_status=success_status
         )
@@ -1203,7 +1329,7 @@ def command_validate(args: argparse.Namespace) -> int:
     except ValueError as exc:
         print(str(exc), file=sys.stderr)
         return 2
-    errors = validate_ir(data)
+    errors = validate_ir(data) + validate_source_locations(data, args.path.parent)
     if errors:
         for error in errors:
             print(f"error: {error}", file=sys.stderr)
@@ -1218,7 +1344,7 @@ def command_assess(args: argparse.Namespace) -> int:
     except ValueError as exc:
         print(str(exc), file=sys.stderr)
         return 2
-    errors = validate_ir(data)
+    errors = validate_ir(data) + validate_source_locations(data, args.path.parent)
     if errors:
         for error in errors:
             print(f"error: {error}", file=sys.stderr)
@@ -1318,6 +1444,50 @@ def command_assess(args: argparse.Namespace) -> int:
                     + "; ".join(video_gate_result.get("errors", [])),
                     0,
                 )
+    runtime_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(
+            "runtime_semantic_contract"
+        )
+        if not isinstance(relative_contract, str) or not relative_contract:
+            runtime_gate = (
+                "NEEDS_CONFIRMATION",
+                "hardware_resources.runtime_semantic_contract is missing",
+                0,
+            )
+            runtime_gate_result = {
+                "ok": False,
+                "errors": ["TiRTC runtime semantic contract is missing"],
+            }
+        else:
+            contract = (project / relative_contract).resolve()
+            if project != contract and project not in contract.parents:
+                runtime_gate_result = {
+                    "ok": False,
+                    "errors": ["TiRTC runtime semantic contract escapes project root"],
+                }
+            else:
+                runtime_gate_result = verify_runtime_contract(contract, project)
+            if runtime_gate_result["ok"]:
+                runtime_gate = (
+                    "SATISFIED",
+                    "TiRTC runtime semantic gate passed: "
+                    + str(runtime_gate_result.get("summary", "verified")),
+                    VERIFICATION_LEVELS["build_verified"],
+                )
+            else:
+                runtime_gate = (
+                    "BLOCKED",
+                    "TiRTC runtime semantic gate failed: "
+                    + "; ".join(runtime_gate_result.get("errors", [])),
+                    0,
+                )
+    artifact_gate = (
+        artifact_file_requirement(data, args.artifact_sha256, project)
+        if selected_phase in {"build", "hil"}
+        else None
+    )
     try:
         assessment = assess_ir(
             data,
@@ -1325,6 +1495,8 @@ def command_assess(args: argparse.Namespace) -> int:
             phase=selected_phase,
             audio_gate=audio_gate,
             video_gate=video_gate,
+            runtime_gate=runtime_gate,
+            artifact_gate=artifact_gate,
         )
     except ValueError as exc:
         print(f"error: {exc}", file=sys.stderr)
@@ -1333,6 +1505,8 @@ def command_assess(args: argparse.Namespace) -> int:
         assessment["audio_semantic_gate"] = audio_gate_result
     if video_gate_result is not None:
         assessment["video_semantic_gate"] = video_gate_result
+    if runtime_gate_result is not None:
+        assessment["runtime_semantic_gate"] = runtime_gate_result
     print(json.dumps(assessment, ensure_ascii=False, indent=2))
     if args.strict:
         statuses = {item["status"] for item in assessment["features"].values()}

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

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Install the portable TiRTC runtime protocol gate into an ESP-IDF project."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+
+MARKER = "# tirtc-runtime-semantic-gate-v1"
+BLOCK = f"""
+
+{MARKER}
+add_custom_target(tirtc_runtime_semantic_gate ALL
+    COMMAND "${{PYTHON}}"
+            "${{CMAKE_CURRENT_LIST_DIR}}/tools/verify_runtime_contract.py"
+            "${{CMAKE_CURRENT_LIST_DIR}}/tirtc-runtime-contract.json"
+            --project "${{CMAKE_CURRENT_LIST_DIR}}"
+            --evidence-out "${{CMAKE_BINARY_DIR}}/runtime-contract-evidence.json"
+    COMMENT "Validating TiRTC endpoint, callbacks, streams and AI media negotiation"
+    VERBATIM
+)
+add_dependencies(${{CMAKE_PROJECT_NAME}}.elf tirtc_runtime_semantic_gate)
+"""
+
+
+def install(project: Path) -> None:
+    project = project.expanduser().resolve()
+    cmake = project / "CMakeLists.txt"
+    contract = project / "tirtc-runtime-contract.json"
+    if not cmake.is_file():
+        raise ValueError(f"ESP-IDF project CMakeLists.txt not found: {cmake}")
+    if not contract.is_file():
+        raise ValueError(
+            f"runtime contract not found: {contract}; create and verify it before installing the gate"
+        )
+    tools = project / "tools"
+    tools.mkdir(parents=True, exist_ok=True)
+    destination = tools / "verify_runtime_contract.py"
+    source = Path(__file__).resolve().with_name("runtime_contract.py")
+    if destination.exists() and destination.read_bytes() != source.read_bytes():
+        raise ValueError(f"refusing to overwrite a different gate: {destination}")
+    if not destination.exists():
+        shutil.copyfile(source, destination)
+    text = cmake.read_text(encoding="utf-8")
+    if MARKER not in text:
+        cmake.write_text(text.rstrip() + BLOCK + "\n", encoding="utf-8")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("project", type=Path)
+    args = parser.parse_args()
+    try:
+        install(args.project)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    print(f"installed TiRTC runtime semantic gate: {args.project.resolve()}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -41,8 +41,8 @@ def check_project(project_path: Path, export: bool = False) -> dict[str, Any]:
     missing_sdk = [str(path.relative_to(project)) for path in sdk_required if not path.is_file()]
     if missing_sdk:
         errors.append("bundled TiRTC SDK is incomplete: " + ", ".join(missing_sdk))
-    if export and (project / "build" / "CMakeCache.txt").exists():
-        errors.append("export source contains build/CMakeCache.txt from another machine")
+    if export and (project / "build").exists():
+        errors.append("export source contains a machine-bound build/ directory")
 
     for path in source_files(project):
         relative = path.relative_to(project)