tirtc-device-builder 0.7.3 → 0.8.1

package/skills/tirtc-esp32-builder/assets/hardware-ir-v2.example.json

@@ -83,6 +83,12 @@
       "resolved": null,
       "verification": "extracted"
     },
+    "duplex_audio": {
+      "simultaneous_capture_playback": null,
+      "playback_reference_available": null,
+      "aec_implementation_available": null,
+      "verification": "extracted"
+    },
     "camera_realtime": {
       "pipeline_safe": null,
       "verification": "extracted"
@@ -122,7 +128,9 @@
       "h5_live_audio",
       "h5_live_video",
       "h5_talkback",
-      "ai_talk"
+      "ai_talk",
+      "device_call",
+      "wechat_voip"
     ]
   }
 }

package/skills/tirtc-esp32-builder/assets/lckfb-szpi-esp32s3-portable-prompt.md

@@ -7,7 +7,7 @@ $tirtc-esp32-builder
 前置条件（必须由开发者在启动本次 Codex 会话前完成，不属于本提示词内的操作）：
 
 ```bash
-npx --yes tirtc-device-builder@0.7.3 setup esp32 --install --force-skill
+npx --yes tirtc-device-builder@0.8.1 setup esp32 --install --force-skill
 ```
 
 该命令只允许在当前用户目录安装固定版本的 Skill、managed ESP32 Device Kit、ESP-IDF 和工具链；禁止 sudo、系统级包变更和修改 shell profile。安装完成后，开发者必须关闭原 Codex 会话，再从本 clean-room 工作区启动一个新会话，然后粘贴本提示词。
@@ -15,11 +15,11 @@ npx --yes tirtc-device-builder@0.7.3 setup esp32 --install --force-skill
 本轮第一步先只读运行：
 
 ```bash
-npx --yes tirtc-device-builder@0.7.3 --version
-npx --yes tirtc-device-builder@0.7.3 setup esp32
+npx --yes tirtc-device-builder@0.8.1 --version
+npx --yes tirtc-device-builder@0.8.1 setup esp32
 ```
 
-必须根据命令的实际输出和本机文件确认：npm 包为 0.7.3、已安装 Skill 的 `VERSION` 为 0.7.3、所选 Device Kit 的 `manifest.json` 中 `kit_version` 为 1.1.1，并且 Doctor 对 `--expected-kit 1.1.1` 输出 `OVERALL: PASS`。Plugin manifest 不属于这种 npm 安装方式的运行时前置条件，不得把不可访问的 Plugin 版本当作阻塞项。如果版本不一致、Skill 是在当前会话启动后才安装，或环境检查未通过，停止并报告前置条件不成立；不要在当前会话中替换 Skill 后继续生成工程。
+必须根据命令的实际输出和本机文件确认：npm 包为 0.8.1、已安装 Skill 的 `VERSION` 为 0.8.1、所选 Device Kit 的 `manifest.json` 中 `kit_version` 为 1.1.1，并且 Doctor 对 `--expected-kit 1.1.1` 输出 `OVERALL: PASS`。Plugin manifest 不属于这种 npm 安装方式的运行时前置条件，不得把不可访问的 Plugin 版本当作阻塞项。如果版本不一致、Skill 是在当前会话启动后才安装，或环境检查未通过，停止并报告前置条件不成立；不要在当前会话中替换 Skill 后继续生成工程。
 
 工作区与 clean-room 边界：
 - 将启动 Codex 时的当前目录定义为 `WORKSPACE_ROOT`。
@@ -55,7 +55,7 @@ npx --yes tirtc-device-builder@0.7.3 setup esp32
 - 每次视频调用必须发送一张完整 JPEG，禁止截断帧或裸分片。
 - 音频 G.711 A-law、8 kHz、mono。
 - stream：H5 上行 10、视频 11、H5 下行 14、AI 1。
-- 初版允许半双工；不得声明未经实机验证的全双工或 AEC。
+- AI 对讲必须实现全双工和 AEC；构建阶段必须证明同时采集播放、真实播放参考与 `echo_cancellation.enabled=true`，实机结果仍只能在 L2-L7 验证后声明。
 
 接入要求：
 - SoftAP 配网，凭证保存 NVS。

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

@@ -27,6 +27,9 @@
 | H5 live video |  |  |
 | H5 talkback |  |  |
 | AI intercom |  |  |
+| Device-to-device call |  |  |
+| WeChat VoIP |  |  |
+| Full-duplex AEC/reference path |  |  |
 
 ## Semantic build gates
 
@@ -37,6 +40,8 @@
 - Audio contract path/SHA-256: `{{AUDIO_CONTRACT}}`
 - Codec clock-table result: `{{AUDIO_CLOCK_GATE}}`
 - I2S mode/controller/slot/handoff result: `{{AUDIO_TOPOLOGY_GATE}}`
+- Simultaneous capture/playback and AEC result: `{{AEC_GATE}}`
+- Device-call/WeChat protocol and arbiter result: `{{BUSINESS_RUNTIME_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}}`
@@ -54,14 +59,17 @@
 | L3 Online |  |  |
 | L4 Media |  |  |
 | L5 H5 |  |  |
-| L6 AI |  |  |
+| L6 AI/CALL/VOIP/AEC |  |  |
 | L7 Stability |  |  |
 
 ## Firmware and flash record
 
+- Delivery mode (`development flash` or `evidence bundle`): `{{DELIVERY_MODE}}`
+- Application project/version: `{{FIRMWARE_PROJECT_VERSION}}`
 - Serial port/chip: `{{SERIAL_TARGET}}`
 - Project-relative firmware artifacts: `{{FIRMWARE_ARTIFACTS}}`
-- Firmware SHA-256: `{{FIRMWARE_SHA256}}`
+- Application-BIN SHA-256: `{{FIRMWARE_BIN_SHA256}}`
+- Descriptor/full ELF SHA-256: `{{FIRMWARE_ELF_SHA256}}`
 - Flash command/result: `{{FLASH_RESULT}}`
 
 ## Artifact-bound runtime evidence

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

@@ -6,5 +6,18 @@
     "app_main": "main/app_main.c",
     "starter_tirtc": "components/starter_tirtc/src/starter_tirtc.c",
     "starter_runtime": "components/starter_runtime/src/starter_runtime.c"
+  },
+  "business": {
+    "features": [],
+    "protocol_revision": null,
+    "session_arbiter": {
+      "single_foreground_owner": null,
+      "pending_capacity": null,
+      "generation_guard": null,
+      "monotonic_deadlines": null,
+      "deferred_lifecycle": null,
+      "restore_h5_after_call": null
+    },
+    "implementation_assertions": []
   }
 }

package/skills/tirtc-esp32-builder/knowledge/board-registry.json

@@ -0,0 +1,4 @@
+{
+  "schema_version": 1,
+  "boards": []
+}

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

@@ -36,6 +36,14 @@ directions are active, uses the hardware clock rate, and maps two distinct TDM
 signals. Implementation assertions must still bind the contract to the paired
 channel setup, AEC library configuration, and exact slot extraction code.
 
+AEC is not optional when Hardware IR requests `ai_talk`, `device_call`, or
+`wechat_voip`. For those features, `echo_cancellation.enabled=false`, missing
+playback-reference wiring, or non-simultaneous capture/playback is a hard
+`BLOCKED` result. Do not silently downgrade the product to push-to-talk. The
+contract verifier exports structured `simultaneous_capture_playback` and
+`echo_cancellation_enabled` results so the Hardware IR assessor enforces this
+rule rather than trusting summary text.
+
 ## Mandatory gate
 
 Run the gate before claiming an audio-capable build:

package/skills/tirtc-esp32-builder/references/board-knowledge.md

@@ -0,0 +1,72 @@
+# Board knowledge and identity
+
+Use this reference when identifying a board, reusing an existing adapter, or
+capturing lessons after bring-up. The registry is curated, versioned input. It
+does not train a model or mutate an installed Skill from conversation history.
+
+## Identity boundary
+
+An ESP32 can report its SoC target, revision, Flash/PSRAM, MAC and sometimes its
+module. Board firmware can probe camera PIDs, codec chip IDs and other bus
+devices. These observations identify components, not necessarily the carrier
+board sales model, PCB marking, hardware revision, wiring, power topology or
+acoustic path. Obtain those facts from the developer and board documents.
+
+Create a project-local identity file, merge the developer declaration with safe
+read-only observations, then query the registry:
+
+```bash
+python3 <skill-dir>/scripts/board_registry.py init-identity \
+  --output <project>/board-identity.json
+python3 <skill-dir>/scripts/board_registry.py match \
+  --identity <project>/board-identity.json
+```
+
+Use only an `exact` result with `safe_registered_reuse=true` to install a saved
+adapter. `probable` can supply hypotheses while missing revision or probe facts
+are resolved. `component` can supply component-level risks and driver patterns,
+but never GPIO, clock, DMA or adapter values. A conflict creates a new variant.
+
+Exact matching requires vendor, model or alias, hardware revision, SoC/resource
+compatibility, and every probe marked `required_for_exact`. Marketing names are
+not enough because vendors may substitute sensors or codecs without renaming a
+product.
+
+## Knowledge scopes
+
+- `generic`: an ESP32/TiRTC invariant. Promote only after two independent board
+  packages support it and a focused regression test enforces it.
+- `component`: a sensor, codec, amplifier or library observation. Reuse it on a
+  different carrier only as a hypothesis until that board supplies evidence.
+- `board`: a fact for one exact package identity. Apply it only to an exact
+  match.
+
+Registry package status controls reuse:
+
+- `knowledge_only`: lessons are usable, but the normal new-board intake remains
+  mandatory.
+- `adapter_verified`: the Hardware IR, adapter, configuration and semantic
+  contracts are complete enough for the registered-board workflow.
+- `hil_verified`: the reusable package also retains artifact-bound HIL evidence.
+
+An older HIL result is provenance, not proof for a newly built artifact.
+
+## Learning loop
+
+After the final assessment, create a project-local candidate:
+
+```bash
+python3 <skill-dir>/scripts/board_registry.py candidate \
+  --hardware-ir <project>/hardware-ir.json \
+  --output <project>/board-knowledge-candidate.json
+```
+
+Review the candidate before promotion. Add exact runtime probes, copy only
+portable project-relative adapter/config/contract inputs, classify each lesson's
+scope, attach the tested artifact SHA-256 for hardware or HIL claims, and add a
+regression test for every generic invariant. Then commit it to a maintained
+registry and publish a new Skill version. An installed Skill never edits itself
+or promotes an observation automatically.
+
+Keep credentials, MAC-derived identity, device keys, Wi-Fi secrets, tokens and
+user media out of identity files, candidates and registries.

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

@@ -9,7 +9,16 @@ Run `hardware_ir.py assess --phase intake --strict` before generation. Hardware
 | `h5_live_audio` | Microphone path producing G.711 A-law, 8 kHz, mono for stream 10; audio controller/channel ownership and memory budget resolved |
 | `h5_live_video` | Camera plus the selected MJPEG, H.264, or H.265 profile for stream 11; refresh/key-frame control, realtime pipeline, and memory budget resolved |
 | `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 |
+| `ai_talk` | A-law 8 kHz microphone and speaker paths for AI stream 1, started only after `start_session`; simultaneous capture/playback, physical reference, enabled AEC, audio ownership/channel mapping and memory budget resolved |
+| `device_call` | Device-call protocol and arbiter contract plus simultaneous A-law capture/playback, physical reference and enabled AEC |
+| `wechat_voip` | WeChat VoIP protocol and arbiter contract plus simultaneous A-law capture/playback, physical reference and enabled AEC |
+
+`ai_talk`, `device_call`, and `wechat_voip` are AEC-required features. They are
+`BLOCKED` when the board cannot capture a playback reference, cannot keep RX/TX
+active together, or has no evidenced AEC implementation. At build time the audio
+contract must explicitly report both simultaneous directions and enabled AEC;
+generic full-duplex labels, a software flag without reference routing, or a
+half-duplex fallback do not satisfy the gate.
 
 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.
 
@@ -45,6 +54,7 @@ SoftAP is one Wi-Fi option, not a universal requirement. BLE, SmartConfig, facto
 - Match the TiRTC precompiled SDK platform to the ESP-IDF target and its `manifest/build-contract.env` to the generated configuration.
 - Keep H5 stream IDs and formats stable unless the user explicitly authorizes a coordinated contract change across the server and consumers.
 - Start AI media only after the successful `start_session` response; stop and flush media before disconnecting.
+- Route AI, device-call and WeChat VoIP through the same foreground-session arbiter and keep AEC active for the entire simultaneous capture/playback interval.
 - 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 --phase hil --artifact-sha256 <sha>`; documentation verification alone never becomes v2 `HIL_VERIFIED`.

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

@@ -48,15 +48,34 @@ For an explicitly selected legacy workspace, omit `--expected-kit`; otherwise re
 
 The default managed root is `<setup-root>/kits/esp32s3/<kit-version>`. The public ThingConnect workspace remains an optional legacy/development input; the doctor accepts either a Device Kit root, a repository root, or its `thing-connect/` child.
 
+The managed Kit currently contains the ESP32-S3 H5/AI starter. When the requested
+portfolio includes device-to-device calling or WeChat VoIP and the selected Kit
+does not contain `device-sim-c`, `device-call.md`, `device-voip.md`, and the API
+reference, use a full `tirtc-server-example` checkout pinned to a recorded commit
+for the simulator and porting source. Cloning is an external write and requires
+user authorization. Do not track a moving default branch as build evidence.
+
+ESP32-P4 uses a separate `espressif_esp32p4` SDK archive and RISC-V toolchain.
+The managed setup does not install that archive or generate a P4 starter. A P4
+task therefore needs an explicit BSP/network project plus the exact P4 SDK and
+`manifest/build-contract.env`; run Doctor with `--target esp32p4` and never accept
+the packaged S3 archive as a compatible fallback.
+
 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:
+For the evidence-bundle mode defined in
+[firmware-delivery.md](firmware-delivery.md), 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.
+Run it on a delivery copy and export source inputs only. CMake caches absolute
+source, toolchain, and Python paths under `build/`; `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.
 
 The export check also requires Hardware IR, every requested-feature semantic
 contract, `sdkconfig.defaults`, a referenced custom partition table, and each

package/skills/tirtc-esp32-builder/references/firmware-delivery.md

@@ -0,0 +1,83 @@
+# Firmware identity and delivery
+
+Read this reference whenever the task builds, flashes, hands off, compares, or
+retains firmware. Select the delivery mode from the user's immediate goal; do
+not force a release bundle onto a quick device-test loop.
+
+## Choose one mode explicitly
+
+### Development flash
+
+Use this mode for rapid build/flash/monitor iteration on one development
+machine. Keep the normal ESP-IDF `build/` tree and use the ordinary command:
+
+```bash
+idf.py -p <exact-port> flash monitor
+```
+
+Do not create a new archive or make the user manually flash bootloader,
+partition-table and application BIN files when `idf.py flash` can resolve the
+build metadata. Before flashing, record the application version and hash of the
+exact application BIN. A build assessment may bind to a project-relative file
+under `build/`; that evidence remains valid only while that exact file exists.
+
+If an experiment produces runtime evidence worth retaining, copy the unchanged
+BIN and matching ELF into `artifacts/` before the next rebuild, record their
+sizes and hashes, and update the report. Copying does not create a new firmware
+identity; a rebuild does.
+
+### Evidence bundle
+
+Use this mode for a portable handoff, release candidate, rollback image,
+retained HIL result, or source export. Keep project-relative copies of the exact
+application BIN and ELF, plus bootloader and partition-table files when the
+recipient needs manual flashing. Record byte sizes and SHA-256 values in
+Hardware IR, run strict build assessment, then run
+`project_portability.py --export` on the source-only delivery tree.
+
+When promoting a development build into an evidence bundle, copy the unchanged
+files first, then replace every retained `build/...` artifact path in Hardware
+IR and the report with its new `artifacts/...` path. Remove transient build
+records that are not being retained; do not merely add bundle records beside
+stale paths. Rerun strict build assessment against the copied application-BIN
+hash so the assessor reopens the new path. The source-only export is ready only
+when every `build_evidence.artifacts[]` path exists outside `build/` and the
+matching report identifies the same hashes.
+
+Only this export workflow requires removal of the machine-bound `build/` tree.
+Do not delete it during active iteration, and never delete a user-owned build
+tree merely to make a report look portable.
+
+## Make firmware self-identifying
+
+Set an explicit, human-readable `PROJECT_VER` before `project()` in the top-level
+ESP-IDF `CMakeLists.txt`. Keep it at 31 UTF-8 bytes or fewer so it fits the
+`esp_app_desc_t.version` field with its terminator. Use a label that states what
+the image is: for example `audio-repro.2`, `button-test.1`, `fix.3`, or a release
+version. A build that deliberately preserves a known bug is a reproduction or
+diagnostic image, not a fix.
+
+At boot, log `project_name`, `version`, build date/time, IDF version, and the
+full ELF SHA-256 from `esp_app_get_description()` or
+`esp_app_get_elf_sha256()`. If the product has a console, expose the same fields
+through `version` or `status`. This lets a tester distinguish a successful
+flash of the wrong image from a runtime regression.
+
+Verify the built application BIN before flash or handoff:
+
+```bash
+python3 <skill-dir>/scripts/firmware_identity.py build/<app>.bin \
+  --elf build/<app>.elf --expect-version <expected-version>
+```
+
+The script reads the embedded ESP-IDF application descriptor, verifies the
+explicit version, and confirms that the supplied ELF's full SHA-256 matches the
+descriptor. It accepts an application BIN, not a merged whole-flash image.
+
+## Name hashes precisely
+
+The outer application-BIN SHA-256 and the descriptor's full ELF SHA-256 identify
+different files. Record both with unambiguous labels; do not call either one
+simply “firmware hash.” Bind Hardware IR artifacts and HIL observations to the
+exact retained artifact SHA required by the assessor, and include the boot-log
+version/full ELF hash so the physical device can be reconciled with that record.

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

@@ -42,16 +42,23 @@ The IR contains:
 - exact board identity, module, Flash/PSRAM, ESP-IDF, TiRTC SDK and build contract;
 - 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;
+- `hardware_resources` for I2C, I2S/GPIO ownership, audio channel mapping,
+  full-duplex/AEC capability, 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;
+- project-relative `hardware_resources.runtime_semantic_contract` for every generated H5/AI/call/VoIP 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.
 
+When `ai_talk`, `device_call`, or `wechat_voip` is requested,
+`hardware_resources.duplex_audio` must establish simultaneous capture/playback,
+an actual playback-reference signal, and an AEC implementation. Unknown values
+remain `NEEDS_CONFIRMATION`; a confirmed missing value is `BLOCKED`. Build/HIL
+assessment also requires the project audio semantic gate to prove enabled AEC.
+
 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.
 
 The selected video profile controls assessment. An unselected H.264 fallback cannot make an MJPEG target pass, and missing H.264 cannot block an evidenced MJPEG target.
@@ -77,7 +84,9 @@ 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.
+H5 features require matching L5 evidence; AI, device-call and WeChat VoIP
+require 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

@@ -62,9 +62,37 @@ Disable Wi-Fi power saving for the realtime baseline unless the product contract
 
 Confirm SDK send return semantics and callback payload lifetimes from the selected SDK version. Keep SDK callbacks bounded and copy payloads before returning.
 
+## Repeated or duplicated downlink audio
+
+Do not label a build as a fix merely because it adds logs or makes the symptom
+less frequent. First produce a self-identifying reproduction build, then count
+the same frame across four boundaries: TiRTC receive callback, accepted queue
+item, playback dequeue, and codec/I2S write. Include mode and connection
+generation, stream/media type, payload length, bounded queue depth/drop counters,
+and an available transport sequence or timestamp. Sample payload hashes only as
+diagnostic evidence; do not blindly discard equal hashes because silence or
+legitimately repeated encoded frames may be identical.
+
+Carry one local trace ID from the accepted callback through queue and playback,
+and record write offset, requested bytes, returned bytes, and cumulative bytes.
+Multiple codec/I2S writes are valid when a frame is deliberately chunked or a
+partial write advances the offset; a local duplication exists only when the
+same byte/sample range is committed more than once or cumulative output exceeds
+the frame's decoded contract. Repeated callbacks with the same available
+transport identity point upstream or into SDK delivery. Unique downlink frames
+heard repeatedly require checking resampling, DMA/I2S replay and acoustic
+feedback separately. On stop/reconnect, reject stale generations and drain or
+invalidate queued audio. Verify the correction with repeated AI sessions, rapid
+stop/start, delayed callbacks and H5 recovery against the exact reproduction and
+candidate-fix firmware identities.
+
 ## Artifact discipline
 
-Record BIN/ELF SHA-256 for every build used in HIL. Runtime evidence applies only to the exact artifact. Diagnose one failing invariant, make the smallest correction, rerun that layer, and preserve the comparison in the report.
+Follow [firmware-delivery.md](firmware-delivery.md). Record the explicit firmware
+version, application-BIN SHA-256 and descriptor/full ELF SHA-256 for every build
+used in HIL. Runtime evidence applies only to the exact artifact. Diagnose one
+failing invariant, make the smallest correction, rerun that layer, and preserve
+the comparison in the report.
 
 Local intermediate snapshots may be ignored, but the Hardware IR, semantic
 contracts, `dependencies.lock`, custom partition input, and the artifact named

package/skills/tirtc-esp32-builder/references/product-controls.md

@@ -0,0 +1,76 @@
+# Product controls, reset, and power
+
+Read this reference when the product has buttons, touch inputs, reset controls,
+power keys, wake sources, or enclosure labels. Concrete pins and electrical
+behavior belong in the exact board/carrier evidence and adapter, never in this
+Skill.
+
+## Identify the physical product, not just the baseboard
+
+A retail or battery-powered device may combine a compute board with a carrier,
+PMIC, latch circuit, flex PCB, or enclosure controls that are absent from the
+baseboard schematic. When a user's physical observation conflicts with the
+available schematic, treat it as evidence of a missing or different variant.
+Do not declare a working control nonexistent. Request or inspect the exact
+carrier schematic, PCB markings, photographs, BSP definitions, or safe probe
+results and keep the unresolved mapping explicit.
+
+Classify each physical label before assigning software behavior:
+
+- MCU-readable GPIO button or touch input;
+- boot-strapping input;
+- reset/enable line;
+- PMIC or hardware power-latch control;
+- I/O-expander input;
+- indicator with no input function;
+- unknown control on a missing board layer.
+
+For an MCU-readable input, record the SoC GPIO, active level, external pull,
+debounce requirement, shared owner, wake capability, and any strapping role.
+Holding a strapping pin during reset can select a boot mode. A reset/enable line
+normally resets the MCU and cannot also be treated as an application button.
+A PMIC/latch power key and an MCU “enter deep sleep” action are different
+product contracts; do not substitute one for the other without circuit evidence.
+
+## Keep controls behind a narrow adapter
+
+Use a board/product-controls component to own GPIO setup, polling or ISR work,
+debounce, gestures, and boot-held suppression. It emits bounded product intents
+such as `AI_TOGGLE_REQUESTED`; it does not call TiRTC, HTTP, MQTT, media, or
+session lifecycle APIs from an ISR or polling callback.
+
+Prefer one `AI_TOGGLE_REQUESTED` event whose start/stop decision is serialized by
+the state-owning runtime. If the existing runtime exposes only separate start
+and stop intents, the adapter may map a public state snapshot to one of them,
+but the runtime must validate the intent again against its authoritative state.
+Define whether rapid gestures are queued, coalesced, or rejected so two reads of
+the same stale snapshot cannot silently violate the product behavior.
+
+The runtime remains responsible for session generation, callback ordering,
+media ownership, timeouts, cleanup, and late-event rejection. A toggle must
+define behavior for waiting, connecting, active, stopping, H5-owned, and
+error/recovery states instead of maintaining a second Boolean inside the button
+driver.
+
+## Deterministic button behavior
+
+For a mechanical active-low or active-high input, require all of the following:
+
+- a stable active interval before one press event;
+- no repeat event until a stable release;
+- a button already held during boot must be released before it can trigger;
+- short/long-press thresholds have an explicit product meaning;
+- queue overflow or rejected intents are logged and recover safely;
+- polling tasks and ISRs stay bounded and never block on network/session work.
+
+Test boot-held, bounce, rapid repeated presses, press during connection, press
+during active audio, press during stop, delayed SDK callbacks, and recovery to
+H5 or waiting state. For a battery product, separately test cold power-on,
+software shutdown/deep sleep, wake, charging/USB behavior, and reset; a passing
+AI toggle does not prove the power path.
+
+Keep debounce and gesture state transitions separable from GPIO/RTOS plumbing
+so host tests can prove boot-held suppression, one event per stable press,
+release re-arming, and the selected rapid-gesture policy. Add a focused runtime
+test for stale or duplicate control intents whenever the runtime performs the
+authoritative state validation.

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

@@ -13,16 +13,20 @@ Use [the report template](../assets/report-template.md) and preserve separate `P
 | 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 |
 | L5 H5 | Browser receives the declared video/audio and talkback reaches the device |
-| L6 AI | Token, WHIP, `start_session`, bidirectional audio, stop, and H5 recovery work |
+| L6 Sessions | AI, device-call and WeChat VoIP requested flows work; simultaneous capture/playback, AEC/double-talk, stop, timeout and H5 recovery are observed separately |
 | 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. 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.
+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. Follow [firmware-delivery.md](firmware-delivery.md) for artifact location, retention, and mode-transition rules. Record 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.
+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. 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.
+Record exact board revision, selected media, Wi-Fi, and binding profiles,
+toolchain and SDK versions, source/adapter revisions, commands, return codes,
+firmware version, application-BIN SHA-256, descriptor/full ELF SHA-256, serial
+port/chip, sanitized log paths, browser or platform observations, and every
+unavailable dependency. Never conflate the BIN and ELF hashes.
 
 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`.
 

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

@@ -1,6 +1,6 @@
 # TiRTC runtime protocol contract
 
-Use this gate for every generated H5/AI project. It verifies protocol behavior that is
+Use this gate for every generated H5/AI/call/VoIP 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.
 
@@ -30,5 +30,15 @@ The gate requires all of the following:
 - 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.
+- requested device-call/WeChat VoIP endpoints, MQTT event names, `call`/`wxcall`
+  commands and their pinned `tirtc-server-example` protocol revision are present
+  in implementation files;
+- one foreground-session arbiter owns STREAM/AI/CALL/VOIP state, allows one
+  pending request, rejects stale generations, uses monotonic deadlines, defers
+  lifecycle work outside callbacks and restores H5 after foreground calls.
 
-Compilation without this gate is not an H5/AI `BUILD_VERIFIED` result.
+For device-call or WeChat VoIP, populate the example contract's `business`
+section. An empty `business.features` list remains valid for H5/AI-only projects,
+but cannot satisfy Hardware IR that requests `device_call` or `wechat_voip`.
+
+Compilation without this gate is not an H5/AI/call/VoIP `BUILD_VERIFIED` result.