tirtc-device-builder 0.5.0 → 0.7.0

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
@@ -11,6 +12,10 @@ import sys
 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
+
 
 FEATURES = {
     "h5_live_audio",
@@ -18,6 +23,8 @@ FEATURES = {
     "h5_talkback",
     "ai_talk",
 }
+AUDIO_FEATURES = {"h5_live_audio", "h5_talkback", "ai_talk"}
+VIDEO_FEATURES = {"h5_live_video"}
 VERIFICATION_LEVELS = {
     "extracted": 1,
     "corroborated": 2,
@@ -58,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]
 
 
@@ -73,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")
@@ -220,6 +293,36 @@ def validate_hardware_resources(
     validate_verification(
         i2s.get("verification"), "hardware_resources.i2s.verification", errors
     )
+    audio_contract = resources.get("audio_semantic_contract")
+    nullable_string(
+        audio_contract,
+        "hardware_resources.audio_semantic_contract",
+        errors,
+    )
+    if isinstance(audio_contract, str) and Path(audio_contract).is_absolute():
+        errors.append(
+            "hardware_resources.audio_semantic_contract must be project-relative"
+        )
+    video_contract = resources.get("video_semantic_contract")
+    nullable_string(
+        video_contract,
+        "hardware_resources.video_semantic_contract",
+        errors,
+    )
+    if isinstance(video_contract, str) and Path(video_contract).is_absolute():
+        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"),
@@ -396,6 +499,27 @@ def validate_runtime_evidence(
         validate_source_refs(record, prefix, source_ids, errors)
 
 
+def validate_build_evidence(data: dict[str, Any], errors: list[str]) -> None:
+    if "build_evidence" not in data:
+        return
+    evidence = mapping(data.get("build_evidence"), "build_evidence", errors)
+    artifacts = evidence.get("artifacts")
+    if not isinstance(artifacts, list):
+        errors.append("build_evidence.artifacts must be an array")
+        return
+    for index, item in enumerate(artifacts):
+        prefix = f"build_evidence.artifacts[{index}]"
+        record = mapping(item, prefix, errors)
+        path_value = record.get("path")
+        nonempty_string(path_value, f"{prefix}.path", errors)
+        if isinstance(path_value, str) and Path(path_value).is_absolute():
+            errors.append(f"{prefix}.path must be project-relative")
+        positive_int(record.get("size_bytes"), f"{prefix}.size_bytes", errors)
+        sha = record.get("sha256")
+        if not isinstance(sha, str) or not SHA256_RE.fullmatch(sha):
+            errors.append(f"{prefix}.sha256 must be a 64-character SHA-256")
+
+
 def validate_ir(data: dict[str, Any]) -> list[str]:
     errors: list[str] = []
     schema_version = data.get("schema_version")
@@ -416,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:
@@ -483,6 +612,7 @@ def validate_ir(data: dict[str, Any]) -> list[str]:
     if schema_version == 2:
         validate_hardware_resources(data, source_ids, errors)
         validate_onboarding(data, source_ids, errors)
+        validate_build_evidence(data, errors)
         validate_runtime_evidence(data, source_ids, errors)
     return errors
 
@@ -818,6 +948,24 @@ def combine_requirements(
     return {"status": status, "reasons": reasons}
 
 
+def constrain_project_gate(
+    project_gate: dict[str, Any], feature_assessments: dict[str, dict[str, Any]]
+) -> None:
+    """Prevent a project-level pass while a requested feature is unresolved."""
+    feature_states = {item["status"] for item in feature_assessments.values()}
+    if "BLOCKED" in feature_states:
+        project_gate["status"] = "BLOCKED"
+        project_gate["reasons"].append("at least one requested feature is blocked")
+    elif (
+        "NEEDS_CONFIRMATION" in feature_states
+        and project_gate["status"] != "BLOCKED"
+    ):
+        project_gate["status"] = "NEEDS_CONFIRMATION"
+        project_gate["reasons"].append(
+            "at least one requested feature still needs confirmation"
+        )
+
+
 def project_requirements(data: dict[str, Any]) -> list[Requirement]:
     requirements: list[Requirement] = []
     revision = data["board"]["hardware_revision"].strip().lower()
@@ -887,11 +1035,40 @@ def matching_runtime_evidence(
     return None
 
 
-def artifact_requirement(artifact_sha256: str | None) -> Requirement:
+def matching_build_artifact(
+    data: dict[str, Any], artifact_sha256: str | None
+) -> dict[str, Any] | None:
+    if artifact_sha256 is None:
+        return None
+    normalized = artifact_sha256.lower()
+    build_evidence = data.get("build_evidence", {})
+    if not isinstance(build_evidence, dict):
+        return None
+    artifacts = build_evidence.get("artifacts", [])
+    if not isinstance(artifacts, list):
+        return None
+    for record in artifacts:
+        if (
+            isinstance(record, dict)
+            and str(record.get("sha256", "")).lower() == normalized
+        ):
+            return record
+    return None
+
+
+def artifact_requirement(
+    data: dict[str, Any], 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
+    if matching_build_artifact(data, artifact_sha256) is None:
+        return (
+            "BLOCKED",
+            f"artifact {artifact_sha256} is not present in build_evidence.artifacts",
+            0,
+        )
     return (
         "SATISFIED",
         f"build evidence is bound to artifact {artifact_sha256}",
@@ -899,10 +1076,46 @@ def artifact_requirement(artifact_sha256: str | None) -> 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:
@@ -947,7 +1160,7 @@ def assess_ir(
         resources = {}
 
     if selected_phase in {"build", "hil"}:
-        project.append(artifact_requirement(artifact_sha256))
+        project.append(artifact_gate or artifact_requirement(data, artifact_sha256))
 
     for feature in requested:
         if schema_version == 1:
@@ -1010,6 +1223,33 @@ def assess_ir(
                 audio_mapping_requirement(resources, minimum_verification),
                 memory_requirement(resources, minimum_verification),
             ]
+        if feature in AUDIO_FEATURES and selected_phase in {"build", "hil"}:
+            requirements.append(
+                audio_gate
+                or (
+                    "NEEDS_CONFIRMATION",
+                    "audio semantic gate was not executed for this project",
+                    0,
+                )
+            )
+        if feature in VIDEO_FEATURES and selected_phase in {"build", "hil"}:
+            requirements.append(
+                video_gate
+                or (
+                    "NEEDS_CONFIRMATION",
+                    "video semantic gate was not executed for this project",
+                    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
         )
@@ -1019,6 +1259,7 @@ def assess_ir(
         success_status=success_status,
         legacy_hil_from_levels=(schema_version == 1 and selected_phase == "intake"),
     )
+    build_artifact = matching_build_artifact(data, artifact_sha256)
     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()
@@ -1046,6 +1287,8 @@ def assess_ir(
                 f"all requested features have matching artifact evidence for {artifact_sha256}"
             )
 
+    constrain_project_gate(project_gate, result)
+
     assessment: dict[str, Any] = {
         "schema_version": schema_version,
         "phase": selected_phase,
@@ -1059,7 +1302,8 @@ def assess_ir(
         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
+        assessment["build_artifact_evidence_matched"] = build_artifact is not None
+        assessment["runtime_artifact_evidence_matched"] = evidence is not None
     return assessment
 
 
@@ -1085,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)
@@ -1100,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)
@@ -1110,15 +1354,159 @@ def command_assess(args: argparse.Namespace) -> int:
     ):
         print("error: --artifact-sha256 must be a 64-character SHA-256", file=sys.stderr)
         return 2
+    selected_phase = args.phase or (
+        "hil" if args.artifact_sha256 is not None else "intake"
+    )
+    project = (args.project or args.path.parent).expanduser().resolve()
+    audio_gate: Requirement | None = None
+    audio_gate_result: dict[str, Any] | None = None
+    if (
+        data.get("schema_version") == 2
+        and selected_phase in {"build", "hil"}
+        and AUDIO_FEATURES.intersection(data["features"]["requested"])
+    ):
+        relative_contract = data["hardware_resources"].get(
+            "audio_semantic_contract"
+        )
+        if not isinstance(relative_contract, str) or not relative_contract:
+            audio_gate = (
+                "NEEDS_CONFIRMATION",
+                "hardware_resources.audio_semantic_contract is missing",
+                0,
+            )
+            audio_gate_result = {
+                "ok": False,
+                "errors": ["audio semantic contract is missing"],
+            }
+        else:
+            contract = (project / relative_contract).resolve()
+            if project != contract and project not in contract.parents:
+                audio_gate_result = {
+                    "ok": False,
+                    "errors": ["audio semantic contract escapes project root"],
+                }
+            else:
+                audio_gate_result = verify_audio_contract(contract, project)
+            if audio_gate_result["ok"]:
+                audio_gate = (
+                    "SATISFIED",
+                    "audio semantic gate passed: "
+                    + str(audio_gate_result.get("summary", "verified")),
+                    VERIFICATION_LEVELS["build_verified"],
+                )
+            else:
+                audio_gate = (
+                    "BLOCKED",
+                    "audio semantic gate failed: "
+                    + "; ".join(audio_gate_result.get("errors", [])),
+                    0,
+                )
+    video_gate: Requirement | None = None
+    video_gate_result: dict[str, Any] | None = None
+    if (
+        data.get("schema_version") == 2
+        and selected_phase in {"build", "hil"}
+        and VIDEO_FEATURES.intersection(data["features"]["requested"])
+    ):
+        relative_contract = data["hardware_resources"].get(
+            "video_semantic_contract"
+        )
+        if not isinstance(relative_contract, str) or not relative_contract:
+            video_gate = (
+                "NEEDS_CONFIRMATION",
+                "hardware_resources.video_semantic_contract is missing",
+                0,
+            )
+            video_gate_result = {
+                "ok": False,
+                "errors": ["video semantic contract is missing"],
+            }
+        else:
+            contract = (project / relative_contract).resolve()
+            if project != contract and project not in contract.parents:
+                video_gate_result = {
+                    "ok": False,
+                    "errors": ["video semantic contract escapes project root"],
+                }
+            else:
+                video_gate_result = verify_video_contract(contract, project)
+            if video_gate_result["ok"]:
+                video_gate = (
+                    "SATISFIED",
+                    "video semantic gate passed: "
+                    + str(video_gate_result.get("summary", "verified")),
+                    VERIFICATION_LEVELS["build_verified"],
+                )
+            else:
+                video_gate = (
+                    "BLOCKED",
+                    "video semantic gate failed: "
+                    + "; ".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,
             artifact_sha256=args.artifact_sha256,
-            phase=args.phase,
+            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)
         return 2
+    if audio_gate_result is not None:
+        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()}
@@ -1161,6 +1549,11 @@ def parse_args() -> argparse.Namespace:
         "--artifact-sha256",
         help="bind build or HIL assessment to this exact firmware artifact",
     )
+    assess_parser.add_argument(
+        "--project",
+        type=Path,
+        help="generated project root; defaults to the Hardware IR directory",
+    )
     assess_parser.set_defaults(handler=command_assess)
     return parser.parse_args()
 

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

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Install the portable audio semantic gate into a generated ESP-IDF project."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+
+MARKER = "# tirtc-audio-semantic-gate-v1"
+BLOCK = f"""
+
+{MARKER}
+add_custom_target(tirtc_audio_semantic_gate ALL
+    COMMAND "${{PYTHON}}"
+            "${{CMAKE_CURRENT_LIST_DIR}}/tools/verify_audio_contract.py"
+            "${{CMAKE_CURRENT_LIST_DIR}}/board-audio-contract.json"
+            --project "${{CMAKE_CURRENT_LIST_DIR}}"
+            --evidence-out "${{CMAKE_BINARY_DIR}}/audio-contract-evidence.json"
+    COMMENT "Validating codec clocks, I2S topology, slots and shared-signal handoff"
+    VERBATIM
+)
+add_dependencies(${{CMAKE_PROJECT_NAME}}.elf tirtc_audio_semantic_gate)
+"""
+
+
+def install(project: Path) -> None:
+    project = project.expanduser().resolve()
+    cmake = project / "CMakeLists.txt"
+    contract = project / "board-audio-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"audio 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_audio_contract.py"
+    source = Path(__file__).resolve().with_name("audio_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 audio semantic gate: {args.project.resolve()}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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())