feat(adr-125 iter 2): real C6 feature_state UDP → HAP characteristic

scripts/c6-presence-watcher.py parses the 60-byte
rv_feature_state_t struct (RV_FEATURE_STATE_MAGIC = 0xC5110006)
emitted by firmware/esp32-csi-node/main/rv_feature_state.[ch] at
1-10 Hz from the real ESP32-C6 on ruv.net, validates the IEEE CRC32
over bytes [0..end-4], gates on RV_QFLAG_PRESENCE_VALID, applies
hysteresis (entry 0.40 / release 0.20) plus a 5 s idle-release
fallback, and toggles /tmp/ruview-motion — the same touch-file
contract that the already-paired HAP bridge consumes.

E2E validated against real hardware (no mocks, no simulation):
  C6 (192.168.1.179, ch 5, RSSI -38)
   └─ UDP/5005 → mac-mini (192.168.1.166)
      └─ c6-presence-watcher.py (pid 8276)
         └─ /tmp/ruview-motion
            └─ hap-test-sensor.py (pid 84602)
               └─ HAP-1.1 over mDNS
                  └─ iPhone Home app: RuView Test Motion = True

10 s sample: pkts=63 valid=51 crc_bad=0  motion -> True

Iter 3 next: insert wifi-densepose-bfld PrivacyGate between the
UDP parse and the threshold so only class-2/3 frames cross the HAP
boundary (ADR-118 §2.2 invariant I1 holds at the HomeKit edge —
ADR-125 §2.1.d).

Refs ADR-125, ADR-118, ADR-081.

Co-Authored-By: claude-flow <ruv@ruv.net>

CLAUDE.md

@@ -73,9 +73,9 @@ All 5 ruvector crates integrated in workspace:
 
 | Device | Port | Chip | Role | Cost |
 |--------|------|------|------|------|
-| ESP32-S3 (8MB flash) | COM7 | Xtensa dual-core | WiFi CSI sensing node | ~$9 |
+| ESP32-S3 (8MB flash) | COM9 (ruvzen, was COM7) | Xtensa dual-core | WiFi CSI sensing node | ~$9 |
 | ESP32-S3 SuperMini (4MB) | — | Xtensa dual-core | WiFi CSI (compact) | ~$6 |
-| ESP32-C6 + Seeed MR60BHA2 | COM4 | RISC-V + 60 GHz FMCW | mmWave HR/BR/presence | ~$15 |
+| ESP32-C6 + Seeed MR60BHA2 | COM12 (ruvzen, was COM4) | RISC-V + 60 GHz FMCW | mmWave HR/BR/presence + WiFi CSI | ~$15 |
 | HLK-LD2410 | — | 24 GHz FMCW | Presence + distance | ~$3 |
 
 **Not supported:** ESP32 (original), ESP32-C3 — single-core, can't run CSI DSP pipeline.

docs/adr/ADR-125-ruview-apple-home-native-hap-bridge.md

@@ -167,6 +167,34 @@ matter = ["dep:hap"]          # ADR-125 §2.1.b
 
 with a runtime subcommand `cog-ha-matter --mode hap` that mirrors the Python advertiser's accessory set. Single binary, no Python interpreter in the image, matches the all-Rust ethos of the Cognitum Seed (ADR-116 §1.4).
 
+### 2.1.c — **Topology: one HAP bridge, N child accessories** (decided)
+
+The advertiser publishes a **single HAP bridge** (`RuView Sense`) that owns N child accessories — one per logical sensor surface (presence-bedroom, presence-office, vitals-bedroom, semantic-events, …). Operators pair the bridge once; child accessories appear automatically and can be re-assigned to rooms in the Apple Home app.
+
+The alternative — N independent accessories each advertised separately — was rejected. It forces operators to pair RuView once per room (`RuView Bedroom`, `RuView Office`, `RuView Wellness`, `RuView Presence`, …), which becomes messy after the second or third room, and diverges from how every reference HomeKit accessory in the Home app behaves (a Hue bridge with bulbs, an Eve Energy bridge, etc.). Single pairing also makes container restart / re-image trivial — one persisted pairing key, not N.
+
+### 2.1.d — **Identity-risk mapping: semantic events, not probabilistic surveillance** (decided)
+
+`identity_risk_score` is a continuous 0..1 confidence from the BFLD identity-features pipeline (ADR-121 §2.6). It must NOT cross the HomeKit boundary as a raw value, and must NOT be wired to `SecuritySystemCurrentState`. Apple-Home users read security-system state as **"intruder detected"** — exposing a probability there turns RuView into surveillance UX with all the false-positive blame that entails.
+
+Instead, the bridge exposes **thresholded semantic events** that read like ambient awareness, not threat detection:
+
+| Semantic event | HomeKit primitive | Trigger (illustrative) |
+|----------------|--------------------|-------------------------|
+| `Unknown Presence` | `MotionSensor` (programmable; stateful) | BFLD class-2 presence + no matching SoulMatch oracle hit (ADR-121 §2.6) for > 30 s |
+| `Unexpected Occupancy` | `OccupancySensor` (programmable) | Occupancy in a room outside its operator-defined "expected schedule" window |
+| `Unrecognized Activity Pattern` | Programmable `Switch` (stateful, momentary) | BFLD longitudinal drift gate (ADR-118 §2.3 / ADR-122 §2.7) fires Reject or Recalibrate |
+
+What stays internal:
+
+- Raw `identity_risk_score` (numeric 0..1) — never published
+- Soul-Signature match probability — never published
+- `rf_signature_hash` — never published (already enforced by ADR-118 §2.5 / ADR-122 §2.4 — this is the structural invariant restated at the HAP boundary)
+
+The naming is the contract. "Unknown Presence" is *who's-here-and-it's-fine-but-worth-noting*; an end user will write an automation ("turn on the porch light when Unknown Presence is detected after 9pm") without ever thinking it accuses anyone of being an intruder. That semantic framing is the difference between RuView becoming the calm-tech ambient substrate Apple Home needs vs. another paranoid surveillance widget.
+
+This is the part of the ADR that determines whether RuView's HomeKit story ages well or generates the wrong kind of headlines.
+
 ### 2.2 What we DO NOT do in 2.1.a or 2.1.b
 
 - **No Matter (CHIP) controller code.** Matter is the long-term play but its SDK in Rust is not yet stable and the certificate provisioning is heavy. HAP-1.1 over Bonjour gives 95% of the UX for 10% of the complexity, today.
@@ -239,10 +267,10 @@ docker restart hap
 
 ## 5. Open questions
 
-- Should `hap-accessory` advertise as **one bridge** with N child accessories (preferred — single pairing for all RuView sensors on the Seed), or **N independent accessories** (simpler code, worse Home-app UX)?
-- Setup code: derived deterministically from the Seed's Ed25519 witness key (so reinstalls re-use the same code), or random per launch (better security, worse UX)?
-- Map of BFLD events ↔ HomeKit characteristics: presence → `OccupancyDetected` is obvious; how do we surface `identity_risk_score` (continuous 0..1) — as a `SecuritySystemCurrentState`, a custom characteristic, or a `MotionSensor` proxy gated by a threshold?
-- Does the same advertiser run on a Cognitum Seed (ESP32-S3-class hardware) or only on the Seed's host appliance? If the ESP32 advertises directly, that's a future ADR — for now the bridge lives on the host.
+Two questions from the original draft were resolved during review (§2.1.c and §2.1.d). Genuinely-open questions that follow-up PRs will close:
+
+- **Setup-code derivation.** Derived deterministically from the Seed's Ed25519 witness key (so reinstalls re-use the same code, operator never re-enters), or random per launch (slightly better security, worse UX on container restarts)? Leaning deterministic + witness-key-derived; verify against Apple's HomeKit Accessory Protocol §5.6.5 (setup-code uniqueness) before committing.
+- **ESP32 / Cognitum-Seed-class hardware as a direct HAP advertiser** (not via the host appliance). The current decision parks the bridge on the host runtime; a future ADR can evaluate whether an ESP32-S3 with 8MB flash has enough headroom to run HAP-1.1 directly, which would remove the host appliance from the path entirely for single-room deployments.
 
 ---
 

scripts/c6-presence-watcher.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""
+c6-presence-watcher.py — ADR-125 iter 2.
+
+Bridges real ESP32-C6 ADR-081 `rv_feature_state` UDP frames to the HAP
+`MotionSensor` characteristic via the toggle file that
+`scripts/hap-test-sensor.py` already pairs against. No mocks, no
+simulation — consumes the exact 60-byte struct emitted by
+`firmware/esp32-csi-node/main/rv_feature_state.[ch]`.
+
+Wire format (RV_FEATURE_STATE_MAGIC = 0xC5110006, 60 bytes total,
+__attribute__((packed))):
+
+    offset  size  field            type
+    0       4     magic            u32   = 0xC5110006
+    4       1     node_id          u8
+    5       1     mode             u8
+    6       2     seq              u16
+    8       8     ts_us            u64
+    16      4     motion_score     f32   0..1, 100 ms window
+    20      4     presence_score   f32   0..1, 1 s window
+    24      4     respiration_bpm  f32
+    28      4     respiration_conf f32
+    32      4     heartbeat_bpm    f32
+    36      4     heartbeat_conf   f32
+    40      4     anomaly_score    f32
+    44      4     env_shift_score  f32
+    48      4     node_coherence   f32
+    52      2     quality_flags    u16
+    54      2     reserved         u16
+    56      4     crc32            u32
+
+`quality_flags & RV_QFLAG_PRESENCE_VALID (1<<0)` gates presence reads.
+`presence_score >= PRESENCE_THRESHOLD` toggles motion ON; below the
+release threshold (with hysteresis) toggles OFF. The toggle file
+is the contract between this watcher and the paired HAP bridge.
+
+Usage:
+    python3 c6-presence-watcher.py [--port 5005] [--toggle /tmp/ruview-motion]
+"""
+from __future__ import annotations
+import argparse
+import os
+import signal
+import socket
+import struct
+import sys
+import time
+import zlib
+
+RV_FEATURE_STATE_MAGIC = 0xC5110006
+RV_QFLAG_PRESENCE_VALID = 1 << 0
+PACKET_SIZE = 60
+
+# Hysteresis — entry / exit thresholds keep the HomeKit characteristic
+# from flapping when presence_score sits near the boundary.
+PRESENCE_ON_THRESHOLD = 0.40
+PRESENCE_OFF_THRESHOLD = 0.20
+# Idle releases motion after this many seconds with no valid presence
+# packets (covers the C6 falling off the air entirely).
+IDLE_RELEASE_S = 5.0
+
+# 60-byte packed layout (`<` = little-endian + no padding)
+# magic|node|mode|seq|ts|motion|presence|resp_bpm|resp_c|hb_bpm|hb_c|anom|env|coh|qflags|reserved|crc
+PACKET_STRUCT = struct.Struct("<IBBHQfffffffffHHI")
+assert PACKET_STRUCT.size == PACKET_SIZE, (
+    f"layout mismatch: struct {PACKET_STRUCT.size}, expected {PACKET_SIZE}"
+)
+
+
+def parse_packet(buf: bytes):
+    """Return parsed dict or None if not a feature_state packet."""
+    if len(buf) != PACKET_SIZE:
+        return None
+    fields = PACKET_STRUCT.unpack(buf)
+    (magic, node_id, mode, seq, ts_us, motion, presence,
+     resp_bpm, resp_conf, hb_bpm, hb_conf,
+     anomaly, env_shift, coherence,
+     qflags, _reserved, crc) = fields
+    if magic != RV_FEATURE_STATE_MAGIC:
+        return None
+    # CRC32 over bytes [0..end-4]. Firmware uses IEEE poly == zlib.crc32.
+    expected = zlib.crc32(buf[:-4]) & 0xFFFFFFFF
+    crc_ok = expected == crc
+    return {
+        "node_id": node_id, "mode": mode, "seq": seq, "ts_us": ts_us,
+        "motion": motion, "presence": presence,
+        "resp_bpm": resp_bpm, "resp_conf": resp_conf,
+        "hb_bpm": hb_bpm, "hb_conf": hb_conf,
+        "anomaly": anomaly, "env_shift": env_shift, "coherence": coherence,
+        "qflags": qflags, "crc_ok": crc_ok,
+        "presence_valid": bool(qflags & RV_QFLAG_PRESENCE_VALID),
+    }
+
+
+def set_motion(toggle_file: str, on: bool, current: bool) -> bool:
+    """Touch / unlink the toggle file iff state changes. Return new state."""
+    if on == current:
+        return current
+    if on:
+        with open(toggle_file, "w") as fh:
+            fh.write("1\n")
+    else:
+        try:
+            os.unlink(toggle_file)
+        except FileNotFoundError:
+            pass
+    print(f"[{time.strftime('%H:%M:%S')}] motion -> {on}", flush=True)
+    return on
+
+
+def main() -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--port", type=int, default=5005)
+    p.add_argument("--toggle", default="/tmp/ruview-motion")
+    p.add_argument("--bind", default="0.0.0.0")
+    args = p.parse_args()
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    if hasattr(socket, "SO_REUSEPORT"):
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
+    sock.bind((args.bind, args.port))
+    sock.settimeout(1.0)
+
+    print(f"[c6-presence] listening udp {args.bind}:{args.port}", flush=True)
+    print(f"[c6-presence] toggle file: {args.toggle}", flush=True)
+    print(f"[c6-presence] thresholds: on>={PRESENCE_ON_THRESHOLD}, "
+          f"off<={PRESENCE_OFF_THRESHOLD}, idle_release={IDLE_RELEASE_S}s",
+          flush=True)
+
+    running = True
+    def _stop(*_):
+        nonlocal running
+        running = False
+    signal.signal(signal.SIGTERM, _stop)
+    signal.signal(signal.SIGINT, _stop)
+
+    motion = os.path.exists(args.toggle)
+    last_packet_ts = 0.0
+    last_summary = time.time()
+    n_total = n_valid = n_crc_bad = 0
+    presence_sum = motion_sum = 0.0
+
+    while running:
+        try:
+            buf, _addr = sock.recvfrom(2048)
+        except socket.timeout:
+            buf = None
+
+        now = time.time()
+
+        if buf is not None:
+            n_total += 1
+            pkt = parse_packet(buf)
+            if pkt is not None:
+                if not pkt["crc_ok"]:
+                    n_crc_bad += 1
+                elif pkt["presence_valid"]:
+                    n_valid += 1
+                    presence_sum += pkt["presence"]
+                    motion_sum += pkt["motion"]
+                    last_packet_ts = now
+                    if not motion and pkt["presence"] >= PRESENCE_ON_THRESHOLD:
+                        motion = set_motion(args.toggle, True, motion)
+                    elif motion and pkt["presence"] <= PRESENCE_OFF_THRESHOLD:
+                        motion = set_motion(args.toggle, False, motion)
+
+        # Idle release — if the C6 stops sending entirely, clear motion.
+        if motion and last_packet_ts and (now - last_packet_ts) > IDLE_RELEASE_S:
+            motion = set_motion(args.toggle, False, motion)
+
+        # Periodic summary line (every 10 s) so we can see the watcher is alive
+        if now - last_summary >= 10.0:
+            avg_p = presence_sum / n_valid if n_valid else 0.0
+            avg_m = motion_sum / n_valid if n_valid else 0.0
+            print(
+                f"[{time.strftime('%H:%M:%S')}] 10s stats: "
+                f"pkts={n_total} valid={n_valid} crc_bad={n_crc_bad} "
+                f"avg_presence={avg_p:.2f} avg_motion={avg_m:.2f} motion={motion}",
+                flush=True,
+            )
+            n_total = n_valid = n_crc_bad = 0
+            presence_sum = motion_sum = 0.0
+            last_summary = now
+
+    sock.close()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/hap-test-sensor.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""
+hap-test-sensor.py — ADR-125 §2.1.a smoke test.
+
+Stands up a single HomeKit Accessory Protocol (HAP-1.1) bridge with one
+child MotionSensor named "RuView Test Motion". Once paired in the Apple
+Home app, the HomePod (acting as Home Hub) sees state changes when
+TOGGLE_FILE (default /tmp/ruview-motion) is touched / removed.
+
+Usage:
+    python3 hap-test-sensor.py
+
+Pair from iPhone: Home app -> Add Accessory -> More Options -> "RuView Test Bridge".
+The setup code is printed on stdout AND written to ~/.ruview-hap/setup-code.txt.
+
+Trigger motion:  touch /tmp/ruview-motion
+Clear motion:    rm   /tmp/ruview-motion
+
+State persists across restarts in ~/.ruview-hap/accessory.state.
+"""
+
+from pathlib import Path
+import os
+import sys
+import time
+import signal
+
+from pyhap.accessory import Accessory, Bridge
+from pyhap.accessory_driver import AccessoryDriver
+from pyhap.const import CATEGORY_SENSOR, CATEGORY_BRIDGE
+
+STATE_DIR = Path(os.path.expanduser("~/.ruview-hap"))
+STATE_DIR.mkdir(exist_ok=True)
+STATE_FILE = STATE_DIR / "accessory.state"
+SETUP_CODE_FILE = STATE_DIR / "setup-code.txt"
+TOGGLE_FILE = Path(os.environ.get("RUVIEW_MOTION_TOGGLE", "/tmp/ruview-motion"))
+
+
+class RuViewMotion(Accessory):
+    category = CATEGORY_SENSOR
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        serv = self.add_preload_service("MotionSensor")
+        self.char_motion = serv.configure_char("MotionDetected")
+        self._last = False
+
+    @Accessory.run_at_interval(1.0)
+    def run(self):
+        present = TOGGLE_FILE.exists()
+        if present != self._last:
+            self.char_motion.set_value(present)
+            self._last = present
+            print(
+                f"[hap-test] MotionDetected -> {present}  (toggle file: {TOGGLE_FILE})",
+                flush=True,
+            )
+
+
+def main() -> int:
+    driver = AccessoryDriver(port=51826, persist_file=str(STATE_FILE))
+
+    bridge = Bridge(driver, "RuView Test Bridge")
+    bridge.category = CATEGORY_BRIDGE
+    bridge.add_accessory(RuViewMotion(driver, "RuView Test Motion"))
+    driver.add_accessory(accessory=bridge)
+
+    setup_code = driver.state.pincode.decode() if hasattr(driver.state.pincode, "decode") else driver.state.pincode
+    SETUP_CODE_FILE.write_text(str(setup_code) + "\n")
+    print(f"[hap-test] HAP bridge advertising as 'RuView Test Bridge'")
+    print(f"[hap-test] iPhone pair flow: Home app -> Add Accessory -> More Options")
+    print(f"[hap-test] Setup code (also in {SETUP_CODE_FILE}):  {setup_code}")
+    print(f"[hap-test] Motion toggle file: {TOGGLE_FILE}")
+    print(f"[hap-test] State persists in: {STATE_FILE}")
+
+    signal.signal(signal.SIGTERM, lambda *_: driver.stop())
+    driver.start()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())