tirtc-device-builder 0.5.0 → 0.7.0

package/skills/tirtc-esp32-builder/assets/report-template.md

@@ -28,6 +28,21 @@
 | H5 talkback |  |  |
 | AI intercom |  |  |
 
+## Semantic build gates
+
+- Platform/Web video profiles: `{{PLATFORM_VIDEO_PROFILES}}`
+- Board-selected video profile: `{{BOARD_VIDEO_PROFILE}}`
+- Runtime contract path/SHA-256: `{{RUNTIME_CONTRACT}}`
+- Endpoint/callback/downlink/AI-session result: `{{RUNTIME_GATE}}`
+- Audio contract path/SHA-256: `{{AUDIO_CONTRACT}}`
+- Codec clock-table result: `{{AUDIO_CLOCK_GATE}}`
+- I2S mode/controller/slot/handoff result: `{{AUDIO_TOPOLOGY_GATE}}`
+- Video contract path/SHA-256: `{{VIDEO_CONTRACT}}`
+- Camera lock/PID/CPU/frame/backpressure result: `{{VIDEO_GATE}}`
+- Final ELF I2C driver-family result: `{{I2C_ELF_GATE}}`
+- Build artifact present in Hardware IR evidence: `{{BUILD_ARTIFACT_BINDING}}`
+- Compiler result versus requested-feature result: `{{COMPILE_VS_CAPABILITY}}`
+
 ## Acceptance
 
 | Level | PASS/FAIL/SKIP | Command and evidence |
@@ -45,7 +60,7 @@
 ## Firmware and flash record
 
 - Serial port/chip: `{{SERIAL_TARGET}}`
-- Firmware artifacts: `{{FIRMWARE_ARTIFACTS}}`
+- Project-relative firmware artifacts: `{{FIRMWARE_ARTIFACTS}}`
 - Firmware SHA-256: `{{FIRMWARE_SHA256}}`
 - Flash command/result: `{{FLASH_RESULT}}`
 

package/skills/tirtc-esp32-builder/assets/tirtc-runtime-contract.example.json

@@ -0,0 +1,10 @@
+{
+  "schema_version": 1,
+  "platform_contract": "platform-media-contract.json",
+  "files": {
+    "platform_client": "components/platform_client/src/platform_client.c",
+    "app_main": "main/app_main.c",
+    "starter_tirtc": "components/starter_tirtc/src/starter_tirtc.c",
+    "starter_runtime": "components/starter_runtime/src/starter_runtime.c"
+  }
+}

package/skills/tirtc-esp32-builder/references/audio-contract.md

@@ -0,0 +1,51 @@
+# Audio semantic contract
+
+Read this reference whenever a requested feature uses microphone capture or speaker playback. Its purpose is to turn codec clocks, I2S modes, channel mapping, and shared-signal ownership into one deterministic build gate.
+
+## Project contract
+
+Create `board-audio-contract.json` in the generated project. Start from `assets/board-audio-contract.example.json`, but replace every board value and evidence ID from the exact schematic, official BSP/example, datasheet, and locked component source. Keep every path project-relative.
+
+The contract must describe:
+
+- the PCM sample rate, MCLK ratio, resulting MCLK, and every clocked codec driver table;
+- capture/playback controller, role, and standard/TDM/DSP/PCM mode;
+- TDM enable, slot count/order, physical signal at each slot, selected slot, and mapping evidence when TDM is used;
+- shared clock GPIOs, whether directions are simultaneous, and the release/recreate handoff;
+- source assertions tying the normalized contract to the actual adapter implementation.
+
+A generic header comment such as “typically 256” is not coefficient evidence. After `idf.py reconfigure` resolves managed components, the selected `(MCLK, sample rate)` pair must exist in every locked codec table named by the contract.
+
+## Mandatory gate
+
+Run the gate before claiming an audio-capable build:
+
+```bash
+python3 <skill-dir>/scripts/audio_contract.py \
+  <project>/board-audio-contract.json \
+  --project <project> \
+  --evidence-out <project>/build/audio-contract-evidence.json
+```
+
+Then install it into every subsequent `idf.py build`:
+
+```bash
+python3 <skill-dir>/scripts/install_audio_gate.py <project>
+```
+
+The installer copies the verifier into the project and adds an `ALL` CMake dependency for the ELF. A moved project therefore retains its semantic gate without requiring the Skill installation path.
+
+Set `hardware_resources.audio_semantic_contract` to `board-audio-contract.json`. Build assessment must pass `--project <project>`; the assessor reruns the gate and blocks every requested audio feature when the contract is missing or fails.
+
+## Completion criterion
+
+Audio reaches `BUILD_VERIFIED` only when all of these are true:
+
+1. the contract has at least two authoritative source IDs;
+2. its arithmetic and codec table lookups pass;
+3. its topology, TDM mapping, and handoff are internally consistent;
+4. its adapter assertions pass;
+5. the gate is part of the ordinary build;
+6. the exact BIN/ELF is hashed after that build.
+
+Compilation without this gate is `COMPILE_PASS`, not audio `BUILD_VERIFIED`.

package/skills/tirtc-esp32-builder/references/capability-rules.md

@@ -17,7 +17,7 @@ A design fact that is still unknown is `NEEDS_CONFIRMATION`; a confirmed missing
 
 ## Selected video profiles
 
-Hardware IR v2 stores one or more `camera.video_profiles` and exactly one selected profile for H5 video:
+The current platform/Web contract supports all three profiles below on video stream 11. Hardware IR v2 separately stores the profiles the board can produce and exactly one selected profile for H5 video:
 
 | Codec | Required output contract |
 |---|---|
@@ -25,7 +25,7 @@ Hardware IR v2 stores one or more `camera.video_profiles` and exactly one select
 | `h264` | `h264_annex_b_access_units`: Annex-B access units with SPS/PPS and IDR request behavior |
 | `h265` | `h265_annex_b_access_units`: Annex-B access units with parameter-set and refresh behavior defined by the coordinated H5 contract |
 
-Available but unselected profiles do not satisfy or block the selected contract. Stream IDs and codec support must come from the applicable ThingConnect/H5 contract, not this table alone.
+Available but unselected board profiles do not satisfy or block the selected contract. A board may select MJPEG even though the platform also accepts H.264 and H.265. Stream IDs and codec support must be verified against the project-local platform contract rather than inferred from board hardware.
 
 ## Phased project gates
 
@@ -36,7 +36,7 @@ The intake phase requires:
 - one evidenced binding method—verification code, factory-bound identity, development credentials, or documented custom flow—plus stored-binding behavior and reset control;
 - feature-specific I2S/GPIO ownership plans, channel/TDM mapping, realtime camera policy, and a static startup/media memory budget.
 
-At intake, `corroborated` on these fields means the design is resolved from authoritative sources and is safe to implement. After compilation, promote a field to `build_verified` only when the generated source, component lock, compile result, or post-link gate establishes it. The build phase requires an exact artifact SHA-256 and returns `BUILD_VERIFIED`. Runtime measurements never need to be invented to pass intake or build.
+At intake, `corroborated` on these fields means the design is resolved from authoritative sources and is safe to implement. After compilation, promote a field to `build_verified` only when the generated source, component lock, semantic gate, compile result, or post-link gate establishes it. Build assessment reruns the applicable project-relative [audio contract](audio-contract.md), [video contract](video-contract.md), and mandatory [runtime contract](runtime-contract.md); self-declared `resolved=true`, `pipeline_safe=true`, or memory-budget booleans cannot replace them. The build phase requires an exact on-disk artifact SHA-256 and returns `BUILD_VERIFIED` only when every requested feature passes. Runtime measurements never need to be invented to pass intake or build.
 
 SoftAP is one Wi-Fi option, not a universal requirement. BLE, SmartConfig, factory NVS, development configuration, or a documented custom method can satisfy intake when the selected path is evidenced. Committed plaintext credentials are always `BLOCKED`.
 

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

@@ -45,6 +45,14 @@ The default managed root is `<setup-root>/kits/esp32s3/<kit-version>`. The publi
 
 SDK resolution is independent after generation: an explicit `--sdk-dir` wins, followed by `<project>/third_party/tirtc`, then the SDK packaged in the resolved Device Kit or legacy workspace. The generated project remains diagnosable after it is moved away from the Kit.
 
+Before copying a generated project to another machine, run:
+
+```bash
+python3 <skill-dir>/scripts/project_portability.py <generated-project> --export
+```
+
+Copy source inputs only. Never export `build/`: CMake caches absolute source, toolchain, and Python paths from the originating machine. `managed_components/` may be regenerated from the committed `dependencies.lock`; the bundled `third_party/tirtc` SDK and its build contract must remain in the source package. CMake must invoke shell gates through `bash <script>` so the build does not depend on archive- or filesystem-specific executable bits.
+
 ## Required checks
 
 - `python3`, `git`, `idf.py`, and the target compiler are available in the active shell;

package/skills/tirtc-esp32-builder/references/hardware-ir.md

@@ -13,6 +13,7 @@ The initializer creates schema v2. The validator still accepts schema v1 for exi
 ## Evidence rules
 
 - Give every source a stable `id`, `kind`, `location`, and revision when available.
+- Use one resolvable location per source. Accept an IR-relative local path or an explicit `https:`, `http:`, `device-kit:`, `managed:`, `official:`, `user-input:`, or `user-supplied:` locator. Reject absolute machine paths, concatenated multi-source strings, invented schemes, missing local paths, and declared SHA-256 values that do not match the referenced local file.
 - Reference source IDs from board facts, selected profiles, onboarding methods, resources, and runtime evidence.
 - Use `null` for unknown facts. Retain contradictory values as explicit issues instead of choosing silently.
 - Hardware revision `unspecified` is valid during intake but blocks reusable-board readiness.
@@ -37,10 +38,14 @@ The IR contains:
 - camera identity evidence plus `video_profiles[]` and `selected_video_profile`;
 - audio input/output paths;
 - `hardware_resources` for I2C, I2S/GPIO ownership, audio channel mapping, camera realtime policy, and memory budget;
+- project-relative `hardware_resources.audio_semantic_contract` for every project requesting audio;
+- project-relative `hardware_resources.video_semantic_contract` for every project requesting video;
+- project-relative `hardware_resources.runtime_semantic_contract` for every generated H5/AI project;
 - `onboarding.wifi_credentials` with selectable SoftAP/BLE/SmartConfig/factory/development/custom methods;
 - selectable ThingConnect binding methods plus stored-binding states and reset control;
 - requested features;
 - optional `runtime_evidence[]`, each bound to a full firmware SHA-256.
+- `build_evidence.artifacts[]` containing each accepted BIN/ELF path, byte size, and full SHA-256.
 
 The selected Wi-Fi method must be available and corroborated, credentials must remain outside tracked source, and reprovisioning must be defined. A board without SoftAP is valid when another selected method meets those conditions.
 
@@ -54,10 +59,11 @@ Run the phase gates in order:
 python3 <skill-dir>/scripts/hardware_ir.py assess hardware-ir.json \
   --phase intake --strict
 python3 <skill-dir>/scripts/hardware_ir.py assess hardware-ir.json \
-  --phase build --artifact-sha256 <64-character-sha256> --strict
+  --phase build --project <generated-project> \
+  --artifact-sha256 <64-character-sha256> --strict
 ```
 
-The intake phase returns `READY_TO_PORT`; the build phase returns `BUILD_VERIFIED`. Missing serial or browser access does not block either phase.
+The intake phase returns `READY_TO_PORT`; the build phase returns `BUILD_VERIFIED`. Build assessment only accepts a hash already present in `build_evidence.artifacts[]`, reopens that project-relative artifact to verify its byte size and SHA-256, and reruns the project-local audio, video, and runtime contracts through `--project`. Missing serial or browser access does not block either phase.
 
 Run:
 

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

@@ -8,7 +8,7 @@ Use [the report template](../assets/report-template.md) and preserve separate `P
 |---|---|
 | L-1 Environment | ESP-IDF version, target compiler, TiRTC SDK, build contract, and requested serial access pass doctor checks |
 | L0 Generate | Project and Hardware IR exist; no existing output was overwritten |
-| L1 Build | Hardware IR valid, SDK contract checked, `idf.py build` succeeds, artifacts recorded |
+| L1 Build | Hardware IR valid, SDK contract and requested-feature semantic gates pass, `idf.py build` succeeds, artifacts recorded |
 | L2 Boot | Exact chip/port resolved, flash succeeds, firmware boots without panic |
 | L3 Online | Wi-Fi provisioning, binding, MQTT, and TiRTC reach ready state |
 | L4 Media | Camera/microphone/speaker local paths work and counters/measurements are captured |
@@ -16,7 +16,9 @@ Use [the report template](../assets/report-template.md) and preserve separate `P
 | L6 AI | Token, WHIP, `start_session`, bidirectional audio, stop, and H5 recovery work |
 | L7 Stability | Requested weak-network, repeated-session, resource, and soak criteria pass |
 
-Run and record the intake assessment before L0, the build assessment with the exact artifact SHA-256 at L1, and the HIL assessment only when matching runtime evidence exists. Missing serial or browser access is a `SKIP` for the affected L2-L7 levels, not an L0/L1 failure.
+Run and record the intake assessment before L0, the build assessment with `--project` and the exact artifact SHA-256 at L1, and the HIL assessment only when matching runtime evidence exists. Before assessment, copy final deliverable BIN/ELF files to project-relative `artifacts/` paths and record their actual byte size and SHA-256 in `build_evidence.artifacts[]`; the assessor reopens the file and rejects stale metadata. Missing serial or browser access is a `SKIP` for the affected L2-L7 levels, not an L0/L1 failure.
+
+Keep `COMPILE_PASS` separate from `BUILD_VERIFIED`. When the compiler succeeds but a required runtime, audio, or video semantic gate fails or is missing, record the compiler result and report the feature and project as blocked. After build assessment, remove `build/` without rebuilding and run `project_portability.py --export`; the source deliverable may retain verified `artifacts/` copies but not a machine-bound build tree. H5 image display is L5 evidence, never an inference from L1.
 
 ## Evidence
 

package/skills/tirtc-esp32-builder/references/runtime-contract.md

@@ -0,0 +1,34 @@
+# TiRTC runtime protocol contract
+
+Use this gate for every generated H5/AI project. It verifies protocol behavior that is
+neither a board clock fact nor a camera fact: service discovery wiring, SDK callback
+lifecycle, stream/media metadata, and AI session negotiation.
+
+Copy `assets/tirtc-runtime-contract.example.json` to
+`<project>/tirtc-runtime-contract.json`. Keep the file paths project-relative. The
+Device Kit generator supplies `platform-media-contract.json`; do not recreate it from
+the prompt or replace it with board capability claims.
+
+Run and install the gate before the final build:
+
+```bash
+python3 <skill-dir>/scripts/runtime_contract.py \
+  <project>/tirtc-runtime-contract.json \
+  --project <project> \
+  --evidence-out <project>/build/runtime-contract-evidence.json
+python3 <skill-dir>/scripts/install_runtime_gate.py <project>
+```
+
+The gate requires all of the following:
+
+- discovered `tirtc-srv` is passed to `TIRTC_OPT_SERVICE_ENDPOINT`;
+- SDK callbacks copy/queue work and never call Disconnect, Stop, or Uninit;
+- H5 streams 10/11/14 and AI stream 1 use the platform media contract;
+- downlink accepts only G.711 A-law, 8 kHz, mono metadata before decoding;
+- platform video capability includes MJPEG, H.264, and H.265 while the board contract
+  selects exactly one;
+- AI media starts only after a matching response provides a non-empty session ID and
+  authoritative input/output audio formats matching the implemented codec;
+- remote `end_session` converges through the runtime control task.
+
+Compilation without this gate is not an H5/AI `BUILD_VERIFIED` result.

package/skills/tirtc-esp32-builder/references/video-contract.md

@@ -0,0 +1,31 @@
+# Video semantic contract
+
+Use this branch whenever a requested feature sends camera video. Create `board-video-contract.json` inside the generated project from the exact board evidence, selected codec/profile, locked components, Device Kit contract, and adapter design. Set its project-relative `platform_contract` to the generated `platform-media-contract.json`.
+
+The project-local contract must establish:
+
+- the exact camera component and ESP-IDF versions from `dependencies.lock`;
+- camera event processing isolation from the configured Wi-Fi core, with both task-core selections verified from resolved configuration rather than assumed defaults;
+- selected frame-buffer count and memory location;
+- the platform/Web contract exposes stream 11 profiles for MJPEG, H.264, and H.265, with the media symbol and framing boundary for each;
+- the board contract selects exactly one codec it can actually produce: `camera.codec` plus the matching SDK media symbol, and one complete MJPEG JPEG, H.264 access unit, or H.265 access unit per SDK send according to that profile;
+- stream ID, SDK media symbol, refresh semantics, and send return handling;
+- maximum encoded frame enforced before send, TiRTC max send buffer, and a lower backpressure threshold;
+- exact accepted sensor identities and rejection of every uncorroborated PID;
+- implementation assertions against `sdkconfig.defaults`, resolved `sdkconfig`, adapter source, TiRTC wrapper, and product composition root.
+
+For MJPEG use `complete_jpeg_per_send` and `max_complete_jpeg_bytes`; for H.264/H.265 use `complete_access_unit_per_send` and `max_complete_access_unit_bytes`. The media symbol must match the codec. The LCKFB V1.0.1 board selects MJPEG because its evidenced camera path produces JPEG; this board limitation must not be generalized into a platform limitation. A complete JPEG must fit at or below the backpressure threshold, which must remain below the TiRTC max send buffer. Camera event work and Wi-Fi must use different cores. These are project contract values, not board-agnostic Skill defaults.
+
+After `idf.py reconfigure`, run:
+
+```bash
+python3 <skill-dir>/scripts/video_contract.py \
+  <project>/board-video-contract.json \
+  --project <project> \
+  --evidence-out <project>/build/video-contract-evidence.json
+python3 <skill-dir>/scripts/install_video_gate.py <project>
+```
+
+The installer copies the verifier into `tools/` and makes every `idf.py build` depend on it. Set `hardware_resources.video_semantic_contract` to the project-relative contract path and pass `--project` to build assessment.
+
+Compilation without this gate is `COMPILE_PASS / VIDEO_CAPABILITY_BLOCKED`. H5 image display remains L5 and requires runtime evidence bound to the exact artifact.

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

@@ -62,16 +62,18 @@ 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`.
-- `--phase build --artifact-sha256 <sha>`: compile/post-link evidence; success is `BUILD_VERIFIED`.
+- `--phase build --project <project> --artifact-sha256 <sha>`: compile/semantic/post-link evidence; success is `BUILD_VERIFIED`.
 - `--phase hil --artifact-sha256 <sha>`: matching L5/L6 runtime evidence; success is `HIL_VERIFIED`.
 
 No serial authorization is required for L0/L1. When serial, browser, account, service, or network access is unavailable, complete the safe build work and report the affected L2-L7 levels as `SKIP`.

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

@@ -0,0 +1,320 @@
+#!/usr/bin/env python3
+"""Verify an ESP32 board audio contract against locked source and adapter files."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+PAIR_PATTERN = re.compile(r"\{\s*(\d+)\s*,\s*(\d+)\s*,")
+AUDIO_MODES = {"standard", "tdm", "dsp", "pcm"}
+HANDOFF_POLICIES = {"none", "release_before_claim", "delete_recreate"}
+
+
+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 project_file(project: Path, value: Any, label: str) -> Path:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{label} must be a non-empty project-relative path")
+    relative = Path(value)
+    if relative.is_absolute():
+        raise ValueError(f"{label} must be project-relative, got {value!r}")
+    resolved = (project / relative).resolve()
+    if project != resolved and project not in resolved.parents:
+        raise ValueError(f"{label} escapes project root: {value!r}")
+    return resolved
+
+
+def require_mapping(value: Any, label: str, errors: list[str]) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        errors.append(f"{label} must be an object")
+        return {}
+    return value
+
+
+def require_positive_int(value: Any, label: str, errors: list[str]) -> int | None:
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        errors.append(f"{label} must be a positive integer")
+        return None
+    return value
+
+
+def require_nonempty_string(value: Any, label: str, errors: list[str]) -> str | None:
+    if not isinstance(value, str) or not value.strip():
+        errors.append(f"{label} must be a non-empty string")
+        return None
+    return value
+
+
+def check_clock(
+    project: Path,
+    contract: dict[str, Any],
+    errors: list[str],
+    inputs: dict[str, str],
+) -> None:
+    clock = require_mapping(contract.get("clock"), "clock", errors)
+    sample_rate = require_positive_int(
+        clock.get("sample_rate_hz"), "clock.sample_rate_hz", errors
+    )
+    ratio = require_positive_int(clock.get("mclk_ratio"), "clock.mclk_ratio", errors)
+    mclk = require_positive_int(clock.get("mclk_hz"), "clock.mclk_hz", errors)
+    if None not in (sample_rate, ratio, mclk) and sample_rate * ratio != mclk:
+        errors.append(
+            "clock tuple is inconsistent: "
+            f"{sample_rate}Hz x {ratio} != {mclk}Hz"
+        )
+
+    tables = clock.get("codec_tables")
+    if not isinstance(tables, list) or not tables:
+        errors.append("clock.codec_tables must list every clocked codec driver table")
+        return
+    if sample_rate is None or mclk is None:
+        return
+
+    for index, item in enumerate(tables):
+        label = f"clock.codec_tables[{index}]"
+        table = require_mapping(item, label, errors)
+        codec = require_nonempty_string(table.get("codec"), f"{label}.codec", errors)
+        try:
+            source = project_file(project, table.get("source"), f"{label}.source")
+        except ValueError as exc:
+            errors.append(str(exc))
+            continue
+        if not source.is_file():
+            errors.append(f"{label}.source does not exist: {source}")
+            continue
+        text = source.read_text(encoding="utf-8", errors="replace")
+        pairs = {(int(first), int(second)) for first, second in PAIR_PATTERN.findall(text)}
+        inputs[str(source.relative_to(project))] = sha256_file(source)
+        if not pairs:
+            errors.append(f"{label} contains no C initializer clock pairs")
+        elif (mclk, sample_rate) not in pairs:
+            errors.append(
+                f"{codec or label} rejects selected clock tuple: "
+                f"sample_rate={sample_rate}Hz mclk={mclk}Hz"
+            )
+
+
+def check_endpoint(
+    value: Any,
+    label: str,
+    errors: list[str],
+) -> dict[str, Any]:
+    endpoint = require_mapping(value, label, errors)
+    controller = endpoint.get("controller")
+    if isinstance(controller, bool) or not isinstance(controller, int) or controller < 0:
+        errors.append(f"{label}.controller must be an integer >= 0")
+    mode = endpoint.get("mode")
+    if mode not in AUDIO_MODES:
+        errors.append(f"{label}.mode must be one of {', '.join(sorted(AUDIO_MODES))}")
+    role = endpoint.get("role")
+    if role not in {"master", "slave"}:
+        errors.append(f"{label}.role must be master or slave")
+    return endpoint
+
+
+def check_topology(contract: dict[str, Any], errors: list[str]) -> None:
+    capture = check_endpoint(contract.get("capture"), "capture", errors)
+    playback = check_endpoint(contract.get("playback"), "playback", errors)
+
+    capture_mode = capture.get("mode")
+    tdm_enabled = capture.get("tdm_enabled")
+    if not isinstance(tdm_enabled, bool):
+        errors.append("capture.tdm_enabled must be true or false")
+    elif (capture_mode == "tdm") != tdm_enabled:
+        errors.append("capture.mode and capture.tdm_enabled disagree")
+
+    if capture_mode == "tdm":
+        slot_count = require_positive_int(
+            capture.get("slot_count"), "capture.slot_count", errors
+        )
+        slot_order = capture.get("slot_order")
+        slot_signals = capture.get("slot_signals")
+        selected_slot = capture.get("selected_slot")
+        selected_signal = capture.get("selected_signal")
+        if not isinstance(slot_order, list) or not slot_order:
+            errors.append("capture.slot_order must be a non-empty array in TDM mode")
+        if not isinstance(slot_signals, list) or not slot_signals:
+            errors.append("capture.slot_signals must be a non-empty array in TDM mode")
+        if slot_count is not None:
+            if isinstance(slot_order, list) and len(slot_order) != slot_count:
+                errors.append("capture.slot_order length must equal capture.slot_count")
+            if isinstance(slot_signals, list) and len(slot_signals) != slot_count:
+                errors.append("capture.slot_signals length must equal capture.slot_count")
+        if (
+            isinstance(selected_slot, bool)
+            or not isinstance(selected_slot, int)
+            or selected_slot < 0
+            or slot_count is None
+            or selected_slot >= slot_count
+        ):
+            errors.append("capture.selected_slot must select an available TDM slot")
+        elif isinstance(slot_signals, list) and selected_slot < len(slot_signals):
+            if selected_signal != slot_signals[selected_slot]:
+                errors.append(
+                    "capture.selected_signal does not match capture.slot_signals at "
+                    "capture.selected_slot"
+                )
+        require_nonempty_string(
+            capture.get("mapping_evidence"), "capture.mapping_evidence", errors
+        )
+    else:
+        require_nonempty_string(
+            capture.get("mapping_evidence"), "capture.mapping_evidence", errors
+        )
+
+    shared = require_mapping(contract.get("shared_clock"), "shared_clock", errors)
+    gpios = shared.get("gpios")
+    if not isinstance(gpios, list) or not gpios or any(
+        isinstance(gpio, bool) or not isinstance(gpio, int) or gpio < 0 for gpio in gpios
+    ):
+        errors.append("shared_clock.gpios must be a non-empty array of GPIO numbers")
+    simultaneous = shared.get("directions_simultaneous")
+    if not isinstance(simultaneous, bool):
+        errors.append("shared_clock.directions_simultaneous must be true or false")
+    handoff = shared.get("handoff")
+    if handoff not in HANDOFF_POLICIES:
+        errors.append(
+            "shared_clock.handoff must be one of "
+            + ", ".join(sorted(HANDOFF_POLICIES))
+        )
+    if simultaneous is False and handoff == "none":
+        errors.append("half-duplex shared clocks require an explicit handoff")
+    if simultaneous is True and capture.get("mode") != playback.get("mode"):
+        errors.append("simultaneous directions cannot use different I2S modes")
+    if (
+        capture.get("controller") == playback.get("controller")
+        and capture.get("mode") != playback.get("mode")
+        and handoff != "delete_recreate"
+    ):
+        errors.append(
+            "one I2S controller cannot retain different capture/playback modes; "
+            "use distinct controllers or delete_recreate handoff"
+        )
+
+
+def check_assertions(
+    project: Path,
+    contract: dict[str, Any],
+    errors: list[str],
+    inputs: dict[str, str],
+) -> None:
+    assertions = contract.get("implementation_assertions")
+    if not isinstance(assertions, list) or not assertions:
+        errors.append("implementation_assertions must be a non-empty array")
+        return
+    for index, item in enumerate(assertions):
+        label = f"implementation_assertions[{index}]"
+        assertion = require_mapping(item, label, errors)
+        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")
+        compact = re.sub(r"\s+", "", text)
+        inputs[str(source.relative_to(project))] = sha256_file(source)
+        for field, haystack, present in (
+            ("contains", text, True),
+            ("contains_compact", compact, True),
+            ("absent", text, False),
+            ("absent_compact", compact, False),
+        ):
+            needles = assertion.get(field, [])
+            if not isinstance(needles, list) or any(
+                not isinstance(needle, str) or not needle for needle in needles
+            ):
+                errors.append(f"{label}.{field} must be an array of non-empty strings")
+                continue
+            for needle in needles:
+                found = needle in haystack
+                if found != present:
+                    verb = "missing" if present else "contains forbidden"
+                    errors.append(f"{label} {verb} {field} token: {needle}")
+
+
+def verify_contract(contract_path: Path, project_path: Path) -> dict[str, Any]:
+    project = project_path.expanduser().resolve()
+    contract_file = contract_path.expanduser().resolve()
+    errors: list[str] = []
+    inputs: dict[str, str] = {}
+    if not project.is_dir():
+        return {"ok": False, "errors": [f"project directory does not exist: {project}"]}
+    if not contract_file.is_file():
+        return {"ok": False, "errors": [f"audio contract does not exist: {contract_file}"]}
+    if project != contract_file and project not in contract_file.parents:
+        return {"ok": False, "errors": ["audio contract must be inside the project"]}
+    try:
+        contract = json.loads(contract_file.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return {"ok": False, "errors": [f"invalid audio contract: {exc}"]}
+    if not isinstance(contract, dict):
+        return {"ok": False, "errors": ["audio contract root must be an object"]}
+    if contract.get("schema_version") != 1:
+        errors.append("schema_version must be 1")
+    evidence = contract.get("evidence")
+    if not isinstance(evidence, list) or len(evidence) < 2 or any(
+        not isinstance(item, str) or not item for item in evidence
+    ):
+        errors.append("evidence must contain at least two non-empty source IDs")
+    inputs[str(contract_file.relative_to(project))] = sha256_file(contract_file)
+    check_clock(project, contract, errors, inputs)
+    check_topology(contract, errors)
+    check_assertions(project, contract, errors, inputs)
+    clock = contract.get("clock", {})
+    return {
+        "ok": not errors,
+        "summary": (
+            f"sample_rate={clock.get('sample_rate_hz')}Hz "
+            f"mclk={clock.get('mclk_hz')}Hz ratio={clock.get('mclk_ratio')}"
+        ),
+        "inputs": inputs,
+        "errors": errors,
+    }
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Verify codec clocks, I2S topology, channel mapping, and adapter assertions."
+    )
+    parser.add_argument("contract", type=Path)
+    parser.add_argument("--project", type=Path, required=True)
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--evidence-out", type=Path)
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    result = verify_contract(args.contract, args.project)
+    if args.evidence_out is not None:
+        output = args.evidence_out.expanduser().resolve()
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(result, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    elif result["ok"]:
+        print(f"PASS: audio semantic contract: {result['summary']}")
+    else:
+        for error in result["errors"]:
+            print(f"FAIL: {error}", file=sys.stderr)
+    return 0 if result["ok"] else 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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