tirtc-device-builder 0.4.0 → 0.6.0

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

@@ -1,6 +1,6 @@
 # Capability rules
 
-Run `hardware_ir.py assess --strict` before generation. Hardware IR v2 validates the selected product contract rather than assuming one video codec or provisioning method. Schema v1 remains readable for existing H.264 projects.
+Run `hardware_ir.py assess --phase intake --strict` before generation. Hardware IR v2 validates the selected product contract rather than assuming one video codec or provisioning method. Schema v1 remains readable for existing H.264 projects.
 
 ## Current starter contract
 
@@ -11,7 +11,9 @@ Run `hardware_ir.py assess --strict` before generation. Hardware IR v2 validates
 | `h5_talkback` | G.711 A-law, 8 kHz downlink decode and speaker path for stream 14; audio controller/GPIO ownership and memory budget resolved |
 | `ai_talk` | A-law 8 kHz microphone and speaker paths for AI stream 1, started only after `start_session`; audio ownership/channel mapping and memory budget resolved |
 
-The complete media path must be at least `corroborated` to become `READY_TO_PORT`. A path with unknown facts is `NEEDS_CONFIRMATION`; a confirmed missing or incompatible resource is `BLOCKED`.
+Hardware identity, wiring, the selected media contract, and the adapter/resource design must be at least `corroborated` to become `READY_TO_PORT`. At intake, `available=true` means a pinned source path can implement the selected profile; it does not claim that the final adapter or physical media path has run. Implementation composition, final ELF policy, runtime memory margin, browser media, and stability belong to the build or HIL phases.
+
+A design fact that is still unknown is `NEEDS_CONFIRMATION`; a confirmed missing or incompatible resource is `BLOCKED`. Facts that can be resolved safely through source inspection, adapter implementation, compilation, or post-link inspection should be resolved in that layer rather than converted into a request for HIL evidence.
 
 ## Selected video profiles
 
@@ -25,14 +27,16 @@ Hardware IR v2 stores one or more `camera.video_profiles` and exactly one select
 
 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.
 
-## Project gates
+## Phased project gates
 
-Schema v2 also requires:
+The intake phase requires:
 
-- one evidenced I2C driver family when I2C is used;
+- one selected and evidenced I2C driver-family plan when I2C is used;
 - a selected Wi-Fi credential method that is available, reprovisionable, and keeps credentials outside source control;
 - 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, channel/TDM mapping, realtime camera policy, and startup/media memory budget.
+- 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, semantic gate, compile result, or post-link gate establishes it. Build assessment reruns the applicable project-relative [audio contract](audio-contract.md) and [video contract](video-contract.md); self-declared `resolved=true`, `pipeline_safe=true`, or memory-budget booleans cannot replace them. The build phase requires an exact 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`.
 
@@ -43,7 +47,7 @@ SoftAP is one Wi-Fi option, not a universal requirement. BLE, SmartConfig, facto
 - Start AI media only after the successful `start_session` response; stop and flush media before disconnecting.
 - Copy SDK callback payloads into bounded queues before returning. Perform decoding, playback, HTTP, and lifecycle changes outside callbacks.
 - Use monotonic timestamps and session generation to reject stale frames and delayed callbacks.
-- Record runtime evidence with the exact BIN/ELF SHA-256. Use `assess --artifact-sha256 <sha>`; documentation verification alone never becomes v2 `HIL_VERIFIED`.
+- Record runtime evidence with the exact BIN/ELF SHA-256. Use `assess --phase hil --artifact-sha256 <sha>`; documentation verification alone never becomes v2 `HIL_VERIFIED`.
 
 ## Typical blocked cases
 

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

@@ -27,6 +27,8 @@ Verification levels are ordered:
 4. `hardware_verified`: the local peripheral works on the exact board revision.
 5. `hil_verified`: retained for legacy facts; schema v2 feature HIL additionally requires matching artifact evidence.
 
+Use the same fact across phases without overstating it. `corroborated` means authoritative sources establish an implementable design; `build_verified` means the generated source, locked dependencies, compile, or post-link gates establish that implementation; runtime behavior requires matching artifact evidence. For example, a corroborated single-I2C-family field records a dependency plan, while its build-verified form records the final ELF audit.
+
 ## Schema v2 contracts
 
 The IR contains:
@@ -35,10 +37,13 @@ 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;
 - `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.
 
@@ -46,13 +51,25 @@ The selected video profile controls assessment. An unselected H.264 fallback can
 
 ## Artifact-bound HIL
 
-Run:
+Run the phase gates in order:
 
 ```bash
 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 --project <generated-project> \
   --artifact-sha256 <64-character-sha256> --strict
 ```
 
+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[]` and reruns the project-local media contracts through `--project`. Missing serial or browser access does not block either phase.
+
+Run:
+
+```bash
+python3 <skill-dir>/scripts/hardware_ir.py assess hardware-ir.json \
+  --phase hil --artifact-sha256 <64-character-sha256> --strict
+```
+
 H5 features require matching L5 evidence; AI requires matching L6 evidence. Evidence from an older firmware remains provenance but does not verify the current artifact.
 
 ## Intake quality

package/skills/tirtc-esp32-builder/references/porting-risks.md

@@ -36,7 +36,7 @@ For every method, keep device credentials outside source control, handle an alre
 
 Platform service discovery and the TiRTC SDK service endpoint are different settings. Record both. HTTPS requires valid time, DNS, certificate validation, TLS client/TLS 1.2, and enough contiguous internal memory.
 
-Before sizing TiRTC buffers, measure internal free/largest blocks, PSRAM, frame size distribution, queue watermarks, and send/drop rates. A larger queue can prevent drops, exhaust startup memory, or add buffer latency. If an authorized HTTP baseline exists, stage transport changes separately from media changes and retain the HTTPS requirements as a pending acceptance item.
+Define a conservative static budget before implementation using the locked SDK contract, framebuffer geometry, DMA/queue bounds, task stacks, and an internal-memory reserve. Before claiming runtime margin or tuning TiRTC buffers, measure internal free/largest blocks, PSRAM, frame size distribution, queue watermarks, and send/drop rates on the exact artifact. A larger queue can prevent drops, exhaust startup memory, or add buffer latency. If an authorized HTTP baseline exists, stage transport changes separately from media changes and retain the HTTPS requirements as a pending acceptance item.
 
 ## Network and media evidence
 

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,11 +16,15 @@ 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 `--project` and the exact artifact SHA-256 at L1, and the HIL assessment only when matching runtime evidence exists. The L1 hash must already appear in `build_evidence.artifacts[]`; a syntactically valid unrecorded hash is a failure. 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 requested audio or video semantic gate fails or is missing, record the compiler result and report the feature and project as blocked. H5 image display is L5 evidence, never an inference from L1.
+
 ## Evidence
 
 Record exact board revision, selected media, Wi-Fi, and binding profiles, toolchain and SDK versions, source/adapter revisions, commands, return codes, firmware size and SHA-256, serial port/chip, sanitized log paths, browser or platform observations, and every unavailable dependency.
 
-Runtime evidence belongs to one artifact. Label superseded artifacts and keep their observations as history; do not promote them to the current BIN/ELF. For HIL assessment, add the full SHA-256 to `runtime_evidence` and run `hardware_ir.py assess --artifact-sha256 <sha> --strict`.
+Runtime evidence belongs to one artifact. Label superseded artifacts and keep their observations as history; do not promote them to the current BIN/ELF. For HIL assessment, add the full SHA-256 to `runtime_evidence` and run `hardware_ir.py assess --phase hil --artifact-sha256 <sha> --strict`.
 
 For L3-L7 media runs, capture the signals that distinguish software regressions from environment changes: onboarding/binding state, BSSID/channel/RSSI, reconnect or roaming events, audio/video send/receive/drop/error counters, queue watermarks, camera overflow count, internal heap/largest block, PSRAM, and measured latency when available. Never record credential values.
 

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

@@ -0,0 +1,30 @@
+# 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.
+
+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;
+- `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 the selected 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. For the LCKFB V1.0.1 MJPEG profile, 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

@@ -23,8 +23,8 @@ Use this branch when the user supplies a board model, vendor URL, schematic, BOM
 3. Prefer official schematic/BOM and BSP facts. For a PDF schematic, inspect page labels and net names; prefer an exported netlist, pin CSV, or vendor board definition when available.
 4. Cross-check critical pins, clocks, power enables, reset lines, sensor/codec variants, ESP-IDF version, resource ownership, and onboarding behavior across at least two independent artifacts when possible.
 5. Create the Hardware IR v2. Use `null` for unknown facts and retain contradictory values as an explicit issue instead of selecting one silently. Store concrete board values in the IR/adapter rather than Skill files.
-6. Validate and assess requested features. Ask only for unresolved facts that block the next safe step. SoftAP is optional when another evidenced Wi-Fi credential method is available, keeps credentials outside source, and defines reprovisioning.
-7. When all requirements reach `READY_TO_PORT`, generate the starter and implement the board adapter. When requirements remain blocked, generate only the IR, capability report, and an optional compile-safe skeleton if requested.
+6. Validate and run the intake assessment. Classify unresolved facts by their next evidence source: source, implementation, build, HIL, or user input. Ask only for `user_blocked` facts that prevent a safe design. SoftAP is optional when another evidenced Wi-Fi credential method is available, keeps credentials outside source, and defines reprovisioning.
+7. When hardware identity, wiring, product contracts, and an evidenced resource plan reach `READY_TO_PORT`, generate the starter and implement the board adapter. Generate a compile-safe adapter by default when remaining uncertainty is implementation-, build-, or HIL-resolvable. Stop at the IR/report only when missing user evidence or an incompatible dependency makes a safe implementation impossible.
 
 The branch is complete when every supplied artifact maps to an IR fact, provenance entry, contradiction, or declared irrelevant item.
 
@@ -68,4 +68,12 @@ The stable modules own stream IDs, negotiated/contracted formats, TiRTC callback
 
 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.
 
+Run the assessor once per layer:
+
+- `--phase intake`: corroborated design evidence; success is `READY_TO_PORT`.
+- `--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`.
+
 Do not use successful compilation as evidence for camera frames, speaker output, Web rendering, AI audio, or long-run stability. Bind every runtime conclusion to the tested firmware SHA-256.

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