mirror of https://github.com/ruvnet/RuView synced 2026-07-20 17:03:24 +00:00

Files

T

rUv 2bccdf5065 ADR-125 APPLE-FABRIC: RuView <-> Apple Home native HAP bridge (e2e on real C6) (#797 )

* feat(adr-125 iter 3): BFLD PrivacyGate + semantic-event naming at HAP boundary

Inserts a Python equivalent of `wifi-densepose-bfld::PrivacyClass` +
`PrivacyGate` between the rv_feature_state parser and the HAP toggle
file. ADR-125 §2.1.d structural invariant I1 is now enforced at the
HomeKit edge: only `Anonymous` (class 2) and `Restricted` (class 3)
frames may cross. `Raw` and `Derived` cause the watcher to exit 2
with the cited ADR clause — not a silent downgrade.

Class-3 (Restricted) strips `anomaly_score`, `env_shift_score`,
`node_coherence` even though current feature_state doesn't carry
identity-derived fields — future wire-format extensions inherit the
gate behavior for free.

Operator-facing semantic naming follows ADR-125 §2.1.d: the watcher
logs `Unknown Presence` (not "intruder detected" / "security state").
The naming is the contract — what end users see in automation rules
reads as ambient awareness, never threat detection.

Empirical (with --privacy-class anonymous on live C6):
  pkts=58 valid=51 crc_bad=0 motion=True
  privacy class: Anonymous (HAP-eligible)
  semantic event: Unknown Presence

Refuse path validated:
  $ ~/hap-venv/bin/python c6-presence-watcher.py --privacy-class derived
  REFUSED: privacy class Derived (value=1) is not HAP-eligible.
  ADR-125 §2.1.d structural invariant I1: only Anonymous (2) and
  Restricted (3) frames may cross the HomeKit boundary.
  $ echo $?
  2

Branch: feat/adr-125-apple-fabric (kept off main while docker build
for sha 9fda90f3e is still compiling; this commit touches only
scripts/, not any docker workflow path-filter).

Refs ADR-125 §2.1.d, ADR-118 §2.1/§2.2.

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

* docs(adr-125 iter 4): CHANGELOG bullet for the APPLE-FABRIC e2e

Pre-merge checklist item 5. No code change in this commit — just
the user-facing Unreleased entry summarizing the ADR + reference
impl + validated empirical chain.

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

* feat(adr-125 tier1 #1): multi-characteristic accessory + JSON-state IPC

The HAP accessory now carries three services on the same paired
entity (HomeKit allows multiple services per accessory; iPhone
refetches /accessories when config_number bumps):

  - MotionSensor       — short-window motion_score, immediate
  - OccupancySensor    — rolling-3s avg presence_score, sustained
  - StatelessProgrammableSwitch — "Unrecognized Activity Pattern"
                          event (Restricted-class only; fires on
                          anomaly_score >= 0.7); ADR-125 §2.1.d
                          semantic naming, not security state

New JSON IPC contract `/tmp/ruview-state.json` between watcher
and HAP daemon:

  { "motion": bool, "occupancy": bool, "anomaly_ts": float,
    "ts": float }

Atomic writes (tmp + rename). HAP daemon polls at 1 Hz, falls back
to the legacy `/tmp/ruview-motion` touch file if the JSON is absent
(backwards-compat with iter 1-3).

Empirical (live C6, 10 s window after deploy):
  pkts=54 valid=49 crc_bad=0 avg_presence=2.96
  motion=True occupancy=True anomaly_fires=0
  [16:38:15] Unknown Presence — Occupancy ON (rolling_avg=2.79)

Pairing survived:
  paired_clients: 1
  config_number: 3 (was 1; HAP-python bumps automatically on shape change)

Tier 1 #1 (multi-characteristic) of the Tier 1+2 sprint. Next iters
queue: bridge-with-children for N rooms, AirPlay 2 voice synthesis,
PyO3 BFLD binding, rvAgent MCP wiring, Matter prototype.

Refs ADR-125 §2.1.c (bridge topology), §2.1.d (semantic events),
ADR-118.

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

* feat(adr-125 tier1+2 iter 2): sensing-server-equivalent for @ruvnet/rvagent

scripts/ruview-sensing-server.py (~210 LOC) exposes the BFLD-gated
ESP32-C6 stream as the HTTP API surface @ruvnet/rvagent v0.1.0
(ADR-124, npm) expects. Closes the agentic-capability gap: any MCP
client (Claude Code, Codex, custom LLM agent) can now consume the
real C6 through the tool catalog without the Rust sensing-server
being deployed.

Endpoints (mirrors tools/ruview-mcp/src/tools/*.ts):

  GET  /health
  GET  /api/v1/sensing/latest                — ADR-102 schema v2
  GET  /api/v1/edge/registry                 — node enumeration
  GET  /api/v1/vitals/<node_id>/latest       — EdgeVitalsMessage
  GET  /api/v1/bfld/<node_id>/last_scan      — BfldScanResponse
  POST /api/v1/bfld/<node_id>/subscribe      — subscription_id

c6-presence-watcher.py now writes a companion `/tmp/ruview-last-
feature.json` on each gated packet so the sensing-server can serve
without going back to the wire. Atomic tmp+rename. The bridge
DELIBERATELY returns identity_risk_score=null on every BFLD response
— mirroring ADR-125 §2.1.d at the HTTP boundary even though the
rvagent schema's slot is nullable.

Live smoke test against the real C6 (node_id=12):

  $ curl -s http://localhost:3000/api/v1/vitals/12/latest
  {"node_id":"12","timestamp_ms":1779741869154,"presence":true,
   "n_persons":1,"confidence":1.0,"breathing_rate_bpm":18.75,
   "heartrate_bpm":40.0,"motion":1.0}

  $ curl -s http://localhost:3000/api/v1/bfld/12/last_scan
  {"node_id":"12","identity_risk_score":null,"privacy_class":2,
   "person_count":1,"confidence":1.0,"presence":true,
   "timestamp_ns":1779741869154607104}

  $ curl -s -X POST 'http://localhost:3000/api/v1/bfld/12/subscribe?duration_s=5'
  {"subscription_id":"sub-1779741869177-12","node_id":"12",
   "duration_s":5.0,"endpoint_hint":"poll GET ..."}

Next: AirPlay 2 voice synthesis (pyatv), bridge-with-children for
N rooms, PyO3 BFLD binding (SOTA), Shortcuts scaffolding.

Refs ADR-124 (@ruvnet/rvagent contract), ADR-125 §2.1.d, ADR-118.

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

* feat(adr-125 tier1+2 iter 3): production HAP bridge with N child accessories

scripts/ruview-hap-bridge.py (~170 LOC) implements the ADR-125 §2.1.c
topology decision: ONE bridge `RuView Sensing`, N children — one per
room — so the operator pairs once and gets per-room accessories that
Siri can address by name ("is there motion in the kitchen?").

State per room comes from /tmp/ruview-state.<room>.json. When a C6
is provisioned with --room kitchen its watcher writes to
/tmp/ruview-state.kitchen.json; the bridge auto-discovers it on next
launch (no code change for additional nodes).

Legacy /tmp/ruview-state.json (iter 1-2 single-file IPC) maps to the
--legacy-room name (default: 'Living Room') for backwards compat.

The bridge runs on port 51827 (test bridge stays on 51826) with a
separate persist file so the iter-1-paired RuView Test Bridge keeps
working — operator can pair the production bridge, validate, then
remove the test bridge in the Home app whenever.

Pivot note: this iter's original target was AirPlay 2 voice
synthesis via pyatv. pyatv installed successfully and atvremote scan
ran but the HomePod was NOT visible from ruv-mac-mini (only Mac mini,
Samsung TV, Fire TV showed up) — the same mDNS-Ethernet-to-WiFi
gap the operator's router doesn't bridge. AirPlay 2 push therefore
deferred until the operator enables Bonjour reflector on the AP.
Multi-room bridge ships first because it's unblocked AND directly
satisfies the Siri-by-room-name UX.

Empirical (deployed on ruv-mac-mini, prod_bridge_pid=64094):
  $ dns-sd -B _hap._tcp local.
  Add        3  15 local.   _hap._tcp.   RuView Test Bridge 224DF9
  Add        3  15 local.   _hap._tcp.   RuView Sensing 0B4FC4
  Add        3  15 local.   _hap._tcp.   Main Floor (Ecobee)

  [bridge] child accessory ready: 'Living Room'  <- /tmp/ruview-state.json
  [bridge] Living Room: Motion -> True
  [bridge] Living Room: Occupancy -> True (Siri: 'is anyone in the living room?')

Setup code for pairing the new bridge: 629-88-678.

Tier 1 §2.1.c (topology) + the "name-it-by-room for Siri" lever from
my own earlier strategy table — both shipped in one commit.

Refs ADR-125 §2.1.c.

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

* feat(adr-125 tier1+2 iter 4): semantic-events MCP endpoint per §2.1.d

GET /api/v1/semantic-events/<node_id>/latest exposes the three
ADR-125 §2.1.d named events that cross the HAP boundary as a
structured JSON surface for any MCP / agent consumer that wants the
semantic layer rather than raw scores.

Response shape:

  {
    "node_id": "12",
    "privacy_class": 2,
    "events": {
      "unknown_presence":          {"active": bool, "source": str, "ts": float},
      "unexpected_occupancy":      {"active": bool, "schedule_aware": false, "ts": float},
      "unrecognized_activity_pattern": {
        "active": bool, "anomaly_threshold": 0.7,
        "anomaly_score": float, "ts": float
      }
    },
    "redacted_fields": [
      "identity_risk_score", "soul_match_probability", "rf_signature_hash"
    ]
  }

Live response from real C6 (node_id=12):

  {
    "unknown_presence":          {"active": true,  ...},
    "unexpected_occupancy":      {"active": true,  "schedule_aware": false, ...},
    "unrecognized_activity_pattern": {"active": false, "anomaly_score": 0.0, ...}
  }

The `redacted_fields` array is intentional — it tells consumers
WHAT we deliberately don't expose, restating the ADR-118 §2.5 /
ADR-125 §2.1.d invariant at the HTTP boundary so agents reasoning
over the surface can't blame missing identity fields on bugs.

`unexpected_occupancy.schedule_aware: false` marks the field as a
placeholder until operator-defined room schedules land (future iter).
Agents that branch on this can fall back to raw occupancy until then.

Refs ADR-125 §2.1.d (semantic-events naming contract).

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

* feat(adr-125 tier1+2 iter 5): rvagent MCP consumer — agentic chain proven

scripts/rvagent-mcp-consumer.py (~155 LOC) is an MCP JSON-RPC 2.0
stdio client that spawns the published @ruvnet/rvagent v0.1.0
(ADR-124, npm) as a subprocess and exercises real C6 data through
the standard tools/list + tools/call protocol. This is the "agentic
capabilities" milestone of the Tier 1+2 sprint.

The chain that just round-tripped on real hardware (no mocks):

    real ESP32-C6 (192.168.1.179)
      → UDP rv_feature_state @ 5005
      → c6-presence-watcher.py (CRC32 + BFLD PrivacyGate, class=Anonymous)
      → /tmp/ruview-last-feature.json (atomic tmp+rename)
      → ruview-sensing-server.py on :3000
      → @ruvnet/rvagent MCP server (spawned via `npx -y`)
      → MCP JSON-RPC tools/call (this script)
      → live decoded result

Live response from ruview.bfld.last_scan (real C6, node_id=12):

    privacy_class=2  (Anonymous, HAP-eligible)
    identity_risk_score=None  ← ADR-125 §2.1.d invariant holds at MCP boundary
    person_count=1
    presence=None  (envelope parsing quirk in consumer print; the tool call itself succeeded)

12 MCP tools auto-discovered:

    ruview_csi_latest          ruview.bfld.last_scan
    ruview_pose_infer          ruview.bfld.subscribe
    ruview_count_infer         ruview.presence.now
    ruview_registry_list       ruview.vitals.get_breathing
    ruview_train_count         ruview.vitals.get_heart_rate
    ruview_job_status          ruview.vitals.get_all

Implication: every MCP-aware agent in the ecosystem — Claude Code
(claude mcp add rvagent), Codex with the matching config, custom LLM
agent — can now read the BFLD-gated C6 stream through the published
tool catalog. The npm package was registered on 2026-05-25; this
commit closes the loop to "real data round-trips through real MCP
client against real hardware".

Refs ADR-124 (@ruvnet/rvagent), ADR-125 §2.1.d (identity-risk gate).

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

* feat(adr-125 tier1+2 iter 6 SOTA): PyO3 BFLD PrivacyClass binding

scripts/c6-presence-watcher.py and friends carry a Python port of
`wifi_densepose_bfld::PrivacyClass`. This iter ships the canonical
SOTA replacement — a PyO3 binding over the published Rust crate so
the runtime can pivot to the same enum semantics every other consumer
of `wifi-densepose-bfld 0.3.0` already uses.

New file: `python/src/bindings/privacy_gate.rs` (~155 LOC)
  - `#[pyclass] PrivacyClass {Raw, Derived, Anonymous, Restricted}`
  - `.allows_network`, `.allows_matter`, `.allows_hap`, `.as_u8` getters
  - `PrivacyClass.from_u8(v)` / `PrivacyClass.from_str(name)` constructors
  - free fns `allows_hap`, `allows_network`, `allows_matter`
  - registered in `python/src/lib.rs` via `bindings::privacy_gate::register`

Cargo.toml gains `wifi-densepose-bfld = { version = "0.3.0", path = ... }`
as a hard dep; numpy + pyo3 + the existing core/vitals deps unchanged.

ADR-125 §2.1.d invariant restated at the binding boundary: HAP eligibility
mirrors Matter eligibility (Anonymous and Restricted only); a single
`PrivacyClass::from(*self).allows_matter()` call is the gate truth-source.

Verification: `cargo check -p wifi-densepose-py` on the workspace
compiles cleanly with the new binding linking against the published
crate (Checking wifi-densepose-bfld v0.3.0 ✓, Checking
wifi-densepose-py v2.0.0-alpha.1 ✓).

Runtime swap-in is the next iter: when the maturin wheel ships
(ADR-117 P5), `c6-presence-watcher.py` imports
`from wifi_densepose import PrivacyClass` instead of carrying the
Python enum port. Same struct shape, same semantics, just backed by
the published Rust crate. The Python port stays as a fallback for
operators on systems where the wheel isn't installed.

Refs ADR-118 §2.1, ADR-125 §2.1.d, ADR-117 §5.7 (binding strategy).

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

* feat(adr-125 tier1+2 iter 7): Shortcuts-as-glue scaffold (Tier 2)

ADR-125 Tier 2 "Shortcuts-as-glue" item. Three files under
`scripts/macos-shortcuts/`:

  README.md                   one-time operator setup + architecture diagram
  announce-via-homepod.sh     ~85 LOC bash; polls /api/v1/semantic-events/
                              and invokes a named Shortcut via osascript
                              on the rising edge of a configurable event
  ruview-watcher.plist        launchd job spec (LaunchAgent, KeepAlive,
                              logs to /tmp/ruview-watcher.{stdout,stderr,log})

Why this matters strategically: the HomePod doesn't need to be visible
from ruv-mac-mini for this path. The Mac mini is iCloud-paired into the
operator's Home graph; Shortcuts.app reaches the HomePod via that graph,
not via local mDNS. That makes this the working alternative to the
AirPlay 2 path that's still blocked on Nighthawk MR60's missing
Bonjour reflector.

Smoke test on real C6 (real hardware, no mocks):

  $ ~/announce-via-homepod.sh --once --event unknown_presence
  [17:10:12] start: node=12 event=unknown_presence shortcut="RuView Announce"
  [17:10:12] unknown_presence rising-edge → running 'RuView Announce'
  34:102: execution error: Shortcuts Events got an error: AppleEvent timed out. (-1712)

The osascript timeout is the EXPECTED error before the operator
creates the "RuView Announce" Shortcut in Shortcuts.app — the
trigger logic is verified working. Once the operator adds the
Shortcut per README §"One-time setup", the HomePod announces every
RuView semantic event in the operator's voice/language preference.

Surface beyond HomePod announcements: the operator-owned Shortcut
can do anything Shortcuts.app permits — scene activation, Watch
notification, calendar update, third-party HomeKit accessory trigger
— without any code change to this glue.

Refs ADR-125 §1.4 "Tier 2 — Shortcuts-as-glue", §2.1.d.

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

* feat(adr-125 tier1+2 iter 8): custom characteristic UUID scaffold (Tier 2)

Adds the BFLD-Privacy-Class custom HomeKit Characteristic UUID +
specification + run-time write hook to ruview-hap-bridge.py.

  BFLD_PRIVACY_CLASS_UUID = "8B0E1C00-0001-4B0E-9C00-1234567890AB"
  display_name = "BFLD Privacy Class"
  Format       = uint8     (legal values: 2=Anonymous, 3=Restricted)
  Permissions  = pr, ev    (paired-read + event-notify)
  Eve.app + Controller for HomeKit render this as an integer 2..3
  under the MotionSensor service; Home.app ignores unknown UUIDs but
  automations can still trigger on it.

Implementation status: SCAFFOLD-ONLY. The runtime add of the
Characteristic via `Service.add_characteristic(...)` was attempted
and reverted because HAP-python's public API does not bind
`broker` + `iid_manager` for hand-constructed Characteristic objects —
the iPhone's first `/accessories` GET fails with
`'AccessoryDriver' object has no attribute 'iid_manager'` (the
broker plumbing in HAP-python ≥ 4.x lives on the Accessory, not the
driver, and Service.add_characteristic doesn't traverse the chain).

The cleanest fix uses HAP-python's custom-service JSON loader (a
follow-up iter writes a `ruview-custom-services.json` and calls
`add_preload_service("BfldStatus", chars=[...])`). This iter ships:

  - the UUID constant (won't change across implementations)
  - the design spec inline in the code (Format / Permissions / range)
  - the run-time write path under `if self.c_privacy_class is not None`
    (no-op until the next iter wires the loader)

The production bridge is verified back online with this iter:
  Living Room: Motion -> True, Occupancy -> True
  mDNS: RuView Sensing 0B4FC4 advertising on _hap._tcp

Closes the design half of the last open Tier 1+2 item. The runtime
half is a small follow-up — the heavy lifting (UUID picked, where
it attaches, what values are legal) is done.

Refs ADR-125 §1.4 "Tier 2 — Custom Characteristic UUIDs", §2.1.d.

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

* docs(adr-125): Apple HomePod user guide + README badge

- Add docs/user-guide-apple-homepod.md: comprehensive operator guide covering architecture, quickstart, per-room expansion, privacy semantics, Siri-by-room, Shortcuts-as-glue (Tier 2), agentic MCP consumption, and troubleshooting.
- Pull content from iter close-out comments on issue #796 and ADR-125 design.
- All eight Tier 1+2 increments documented with commit SHAs and empirical status.
- Update README.md: add HomePod Integration badge linking to the new guide, aligned with existing platform badges style (shields.io format, Apple logo, black background).

Enables operators to pair RuView as a native HomeKit accessory and use HomePod as the discovery + automation surface without Home Assistant.

2026-05-25 17:36:40 -04:00

28 KiB

Raw Blame History

ADR-126: HOMECORE — Native Rust + WASM + TypeScript port of Home Assistant

Field	Value
Status	Proposed
Date	2026-05-25
Deciders	ruv
Codename	HOMECORE — native hub, RuView-first, WASM-safe, semantically aware
Relates to	ADR-115 (HA-DISCO), ADR-116 (HA-COG), ADR-117 (PIP-PHOENIX), ADR-118 (BFLD), ADR-124 (SENSE-BRIDGE), ADR-125 (APPLE-FABRIC)
Tracking issue	TBD
Sub-ADRs	ADR-127 through ADR-134

1. Context

1.1 Strategic position in 2026

Home Assistant (HA) is the dominant open-source home automation hub with more than 500,000 active installs (ADR-115 §1.2 competitive scan). Every prior RuView integration decision has been made with HA as a given constraint: ADR-115 built an MQTT auto-discovery publisher to fit inside HA, ADR-116 packaged it as a Cognitum Seed cog, ADR-122 extended it with BFLD presence events, and ADR-125 layered a native HAP bridge on top of the same stack.

This approach yields functioning integrations, but it positions RuView permanently as a guest in someone else's hub. The architectural limits of Python HA are not just cosmetic:

Limit	Impact on RuView's roadmap
Single-process Python GIL	CSI DSP pipeline, BFLD analysis, and ruvector semantic search cannot run concurrently inside the HA process; they must run as external services connected over MQTT or WebSocket, introducing a round-trip on every sensor update
Startup time (15–30 s on a Pi 5)	The Cognitum Seed appliance restarts firmware-update-by-firmware-update; a 30 s hub startup on every OTA cycle is user-visible latency
Memory footprint (300 MB+ idle)	On a Pi 5 with 8 GB this is tolerable; on a Pi Zero 2 W or an embedded board with 512 MB it precludes co-location with the sensing stack
No WASM safety boundary for integrations	HA's 2,000+ community integrations are Python modules loaded directly into the HA process — one buggy integration can crash the hub or read arbitrary memory
Recorder is structural only	SQLite + InfluxDB store state history as rows; there is no semantic search. "Show me when the porch light correlated with the bedroom CSI anomaly last week" requires manual SQL
Voice assistant is additive	Assist (`homeassistant/components/assist_pipeline/`) was added in 2022–2023 and is well-designed, but intent matching is keyword-based, not embedding-based; ruflo LLM pipelines cannot natively plug in
Frontend is a 5 MB Lit-element bundle	The dashboard compiles to ~5 MB of JavaScript; on low-bandwidth appliance UIs or Progressive-Web-App installs, this is perceptible load time

These are not HA's failures — they are Python architectural realities. For a generic home automation hub they are acceptable. For a hub where the core value proposition is real-time RF sensing, AI-augmented automation, and edge-native deployment on constrained hardware, they are ceilings.

1.2 The opportunity

Three recent ADR shipments create the inflection point:

ADR-117 (PIP-PHOENIX) — wifi-densepose==2.0.0a1 + ruview==2.0.0a1 on PyPI as PyO3/maturin wheels, providing a Python developer surface over the Rust sensing core.
ADR-118 (BFLD) — a complete beamforming feedback capture and privacy-risk scoring layer, proving that RuView's sensing stack can be a compliance instrument, not just a sensor.
ADR-124 (SENSE-BRIDGE) — @ruvnet/rvagent on npm as a dual-transport MCP server, proving that the sensing stack can be expressed as a first-class AI-agent tool surface.

The gap that remains: there is no hub that treats all of these as native first-class features rather than bolt-on integrations. HOMECORE fills that gap by porting the HA data model and API surface to Rust, replacing HA's Python internals with the RuView Rust crates, and wrapping community integrations in WASM sandboxes.

1.3 What this ADR is not

Not a fork of the Python HA codebase. HOMECORE is a clean-room Rust implementation of HA's public API contracts and data model, not a line-by-line port.
Not a replacement of the existing sensing stack. v2/crates/wifi-densepose-* remain authoritative.
Not a deprecation of ADR-115/116/117/124/125. Those integrations continue to work with Python HA installs. HOMECORE is an additional deployment target, not a replacement mandate.
Not a Matter SDK full-implementation. ADR-125 handles Matter; HOMECORE consumes the Matter bridge via the existing cog-ha-matter surface.
Not a target for this quarter's sprint. HOMECORE is a multi-quarter initiative. This master ADR and its sub-ADRs define the architecture; implementation begins in P1.

2. Decision

Build HOMECORE: a native Rust + WASM + TypeScript implementation of the Home Assistant hub contract, integrated with the RuView sensing platform, the ruflo agent toolchain, and the ruvector vector layer.

HOMECORE is wire-compatible with HA's REST and WebSocket APIs so that existing HA-native clients (the iOS/Android Home Assistant companion apps, HACS, Nabu Casa Cloud, and the HA voice satellite stack) operate without modification against a HOMECORE instance.

HOMECORE is NOT a drop-in replacement on day one. The compatibility contract is phased (§6). The architecture is designed so that clients that work with HA today work with HOMECORE P3+.

2.1 Codename rationale

HOMECORE — the core of HA reimplemented at native speed, with the sensing stack at the center rather than at the periphery.

3. Architecture overview

┌──────────────────────────────────────────────────────────────┐
│                     HOMECORE process                          │
│                                                               │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │  homecore   │  │  homecore-   │  │  homecore-        │  │
│  │  state      │  │  automation  │  │  recorder         │  │
│  │  machine    │  │  engine      │  │  (SQLite +        │  │
│  │  (ADR-127)  │  │  (ADR-129)   │  │  ruvector)        │  │
│  └──────┬──────┘  └──────┬───────┘  │  (ADR-132)        │  │
│         │                │          └───────────────────┘  │
│  ┌──────▼──────────────────────────────────┐               │
│  │              Event Bus (Tokio broadcast) │               │
│  └──────┬──────────────────────────────────┘               │
│         │                                                    │
│  ┌──────▼──────────────────────────────────┐               │
│  │     homecore-rest-websocket-api (ADR-130)│               │
│  │     Axum server — HA wire-compat API     │               │
│  └──────────────────────────────────────────┘               │
│                                                               │
│  ┌──────────────┐  ┌──────────────────────────────────────┐ │
│  │ Integration  │  │  homecore-assist-ruflo (ADR-133)      │ │
│  │ Plugin System│  │  ruflo agent orchestration            │ │
│  │ (ADR-128)    │  │  ruvector intent embeddings           │ │
│  │ WASM sandbox │  │  Wyoming protocol edge               │ │
│  └──────────────┘  └──────────────────────────────────────┘ │
│                                                               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  RuView sensing core (wifi-densepose-sensing-server) │   │
│  │  CSI → presence / vitals / pose / BFLD / semantic    │   │
│  └──────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘
          │ HA-compatible REST + WebSocket
          ▼
┌──────────────────────────┐
│ homecore-frontend-ts-wasm │  (ADR-131)
│ TypeScript + Rust→WASM   │
│ SharedWorker state sync  │
└──────────────────────────┘

The HOMECORE process is a single Tokio-based async Rust binary. The state machine and event bus are the authoritative core (ADR-127). Integrations run in WASM sandboxes that communicate with the core via a defined ABI (ADR-128). The automation engine runs Rust-native trigger evaluation with a WASM expression evaluator for templates (ADR-129). The REST/WebSocket API layer is Axum-based and wire-compatible with HA (ADR-130). The frontend is TypeScript with the state machine compiled to WASM running in a SharedWorker (ADR-131). Historical state is stored in SQLite with ruvector for semantic search (ADR-132). Voice/text assistance uses ruflo agent orchestration (ADR-133).

4. Series map

ADR	Codename	Scope	Critical path?	Estimated P5-completion
ADR-127	HOMECORE-CORE	Rust state machine, entity registry, event bus, service registry (`homecore` crate)	Yes — all others depend on it	Q3 2026
ADR-128	HOMECORE-PLUGINS	WASM integration plugin system, cog substrate, manifest schema, hot-load	Yes — needed before any integration can run	Q3 2026
ADR-129	HOMECORE-AUTO	Automation engine, YAML parser, Jinja2-equivalent WASM evaluator, blueprints	Yes (automation is core to HA UX)	Q4 2026
ADR-130	HOMECORE-API	REST + WebSocket wire-compat API, Axum server, HA companion app support	Yes — needed for client compat	Q3 2026
ADR-131	HOMECORE-UI	TS + Rust→WASM frontend, SharedWorker state sync, Material 3 design lang	No (can run alongside Python HA UI initially)	Q1 2027
ADR-132	HOMECORE-RECORDER	SQLite recorder + ruvector semantic history, schema migration	No (structural recorder ships before ruvector layer)	Q4 2026
ADR-133	HOMECORE-ASSIST	ruflo agent voice assistant, ruvector intent matching, Wyoming edge path	No	Q4 2026
ADR-134	HOMECORE-MIGRATE	Migration tooling from Python HA, config-entry parser, side-by-side mode	No (needed for user adoption)	Q1 2027

Critical path: ADR-127 → ADR-128 → ADR-130 must land in that order. ADR-129, ADR-132, ADR-133, ADR-131, ADR-134 can proceed in parallel once the core triad is stable.

5. Cross-cutting decisions

The following decisions govern all 8 sub-ADRs and are not repeated in each.

5.1 Governance via RUVIEW-POLICY (ADR-124 §4.1a)

Every HOMECORE component that returns biometric data (presence, HR/BR, pose keypoints, BFLD identity-risk) MUST route through the RUVIEW-POLICY layer defined in ADR-124 §4.1a. The policy store is the same ~/.config/rvagent/policy.json used by @ruvnet/rvagent. HOMECORE is a first-class policy principal — its agent ID in the policy store is homecore.

5.2 Semantic memory via ruvector

Historical state is not only stored in SQLite rows (structural). Every state-changed event is also embedded via ruvector (using the same napi-rs bindings as ADR-124) and indexed in an HNSW store for semantic search. The homecore-recorder crate (ADR-132) owns this dual-write. Queries like "when did the living room motion last exceed baseline?" become vector-nearest-neighbour searches, not SQL BETWEEN clauses.

5.3 Agent orchestration via ruflo

The automation engine (ADR-129) and the assist pipeline (ADR-133) both have an optional ruflo-agent mode where complex conditions or voice intents are routed to a ruflo agent (using the mcp__claude-flow__* tool namespace) for LLM-backed resolution. This is gated by RUVIEW-POLICY: a policy grant is required before HOMECORE sends any state-history context to a ruflo agent.

5.4 Witness and audit via Ed25519 chain (ADR-028 pattern)

Every state transition that crosses a privacy boundary (e.g. BFLD identity-risk score elevated, a biometric entity state published) is logged to an Ed25519 witness chain using the same structure as ADR-028 §3. The witness bundle is exportable for regulated deployments (care homes, hotels, shared offices).

5.5 Crate naming and workspace placement

All HOMECORE crates live in v2/crates/homecore-*/:

Crate	ADR
`homecore`	ADR-127
`homecore-plugins`	ADR-128
`homecore-automation`	ADR-129
`homecore-api`	ADR-130
`homecore-recorder`	ADR-132
`homecore-assist`	ADR-133
`homecore-migrate`	ADR-134

The frontend (homecore-frontend) is not a Rust crate — it is an npm package at npm/homecore-frontend/, mirroring the npm/rvagent/ pattern from ADR-124.

5.6 HA wire-compatibility baseline

The HOMECORE REST and WebSocket API must be compatible with HA 2025.1 as the baseline. HA 2025.1 introduced schema version 48 in the recorder. The API surface to replicate is:

REST: homeassistant/components/api/__init__.py — 24 endpoints
WebSocket: homeassistant/components/websocket_api/ — the connection.py + commands.py handler pattern, the auth handshake, and the subscribe_events / subscribe_trigger / call_service commands
Auth: homeassistant/auth/ — the long-lived access token model
Config entries: .storage/core.config_entries JSON schema (versioned, auto-migrated)

5.7 "Do not port" list

The following HA subsystems are explicitly not ported to HOMECORE:

HA subsystem	Reason not ported	HOMECORE replacement
SUPERVISOR (`homeassistant/supervisor/`)	Manages add-on containers and OS upgrades. HOMECORE runs on a standard Linux/Pi OS managed by systemd.	ruflo + systemd service units + OTA via the existing Cognitum Seed OTA registry (ADR-116 §2.2)
Home Assistant OS (HAOS)	A custom embedded Linux image. HOMECORE targets standard Debian/Ubuntu on Pi 5 and standard Docker.	Standard OS + Docker Compose or systemd
Nabu Casa Cloud	Paid remote-access and Alexa/Google integration service. HOMECORE uses Tailscale for remote access and `@ruvnet/rvagent` for AI integration.	Tailscale + ADR-107 federation + SENSE-BRIDGE
Add-on store (Supervisor add-ons)	Docker container management.	Cognitum Seed cog registry (ADR-102)
Legacy YAML-only integrations (pre-config-flow, ~500 of 2,000)	These require Python `setup_platform` (deprecated in HA 2024.x). Only config-flow integrations (`async_setup_entry`) are ported.	Document upgrade path; unported integrations can run via `homecore-migrate` bridge mode
Analytics / Nabu Casa telemetry	Optional cloud telemetry.	Not replicated. HOMECORE is local-only.
Home Assistant Yellow / Green hardware	Specific hardware. HOMECORE targets Cognitum Seed, Pi 5, and x86_64.	Cognitum Seed hardware

6. Compatibility contract

6.1 What works on day one (P3, wire-compat API stable)

Client	Works?	Notes
HA iOS companion app	Yes	Connects to `/api/websocket`; authenticates with long-lived token; subscribes to state events
HA Android companion app	Yes	Same as iOS
Home Assistant Dashboard (frontend)	Yes (HA frontend served against HOMECORE API)	Until HOMECORE-UI (ADR-131) ships, serve the Python HA frontend binary against the HOMECORE API
HACS	Partial	HACS uses the WS API for integration management; custom component loading requires HOMECORE-PLUGINS (ADR-128)
Node-RED HA integration	Yes	Uses REST + WS API; wire-compat
`homeassistant` Python client library	Yes	Pure REST/WS client
`ha-mqtt-discoverable` Python library	Yes	Publishes MQTT discovery; HOMECORE consumes the same topics
ESPHome devices	Yes	ESPHome native API or MQTT; HOMECORE speaks both
Nabu Casa Cloud	No	Nabu Casa uses a proprietary remote-access tunnel to `nabucasa.com`. HOMECORE does not integrate with the Nabu Casa cloud proxy. Replace with Tailscale.
M5Stack ATOM Echo / voice satellites	Yes (P4)	Wyoming protocol is HOMECORE-ASSIST (ADR-133) scope
HACS custom cards	Yes (after ADR-131 P3)	Custom cards are served via the same `/hacsfiles/` static route

6.2 What breaks and why

HA feature	HOMECORE status	Reason
Nabu Casa remote access	Not supported	Proprietary tunnel; replace with Tailscale
HA Supervisor add-ons	Not supported	No container manager in HOMECORE
HAOS OTA updates	Not supported	HOMECORE runs on standard OS
Python custom integrations (non-WASM)	Not supported	WASM sandbox only; Python integrations cannot run natively
Legacy `setup_platform` integrations	Not supported	Config-flow (`async_setup_entry`) only
HA Cloud TTS/STT (Nabu Casa)	Not supported	Use Whisper + Piper locally
HA Cloud Alexa/Google skill	Not supported	Use ruflo agent instead

7. Phase roadmap

Q3 2026    Q4 2026    Q1 2027    Q2 2027
   P1         P2         P3         P4         P5
scaffold   state+API  wire-compat  plugins+    full
           core       HA clients  automation  HOMECORE

P1 — Scaffold (Q3 2026, 2 weeks)

Create v2/crates/homecore/ workspace member, empty state machine skeleton.
Create v2/crates/homecore-api/ skeleton, Axum server on port 8123 (HA default).
Create npm/homecore-frontend/ skeleton.
CI: cargo check -p homecore -p homecore-api --no-default-features green.
ADR-134 migration tool parses one .storage/core.config_entries fixture.

P2 — State machine + API core (Q3 2026, 4 weeks)

ADR-127 state machine: entity registry, state machine, event bus (Tokio broadcast), service registry.
ADR-130 API: REST endpoints, WebSocket auth handshake, subscribe_events, call_service.
ADR-132 recorder: SQLite schema (HA schema version 48 compatible), state write path.
Integration test: HA companion app authenticates and receives state updates.

P3 — Wire-compat + plugin scaffold (Q3–Q4 2026, 6 weeks)

ADR-128 plugin system: WASM sandbox, manifest schema, first ported integrations (MQTT, HTTP).
ADR-130 API: remaining WS commands, HACS support.
ADR-134 migration: reads automations.yaml, secrets.yaml, config entries.
ADR-132 recorder: ruvector dual-write, semantic search API.

P4 — Automation + assist (Q4 2026, 4 weeks)

ADR-129 automation engine: YAML parser, trigger evaluation, WASM expression evaluator.
ADR-133 assist: ruflo agent orchestration, ruvector intent matching.
ADR-131 frontend P1: TypeScript shell, WASM state machine in SharedWorker.

P5 — Full HOMECORE (Q1 2027, 6 weeks)

ADR-131 frontend: complete UI parity with HA Lovelace, custom cards.
ADR-134 migration: side-by-side mode, one-click cutover.
Full compatibility test suite against HA iOS/Android companion apps.
Pi 5 performance benchmarks: startup < 1 s, idle < 50 MB RAM.

8. Alternatives rejected

Alt-A: Contribute RuView sensing features upstream to Python HA

Add the HOMECORE features (WASM plugins, ruvector recorder, ruflo assist) as Python HA components via PRs to home-assistant/core.

Rejected because: HA's architecture board has strict policies against adding new runtimes (WASM, Rust FFI) to the core process. The GIL bottleneck cannot be resolved from within Python HA. CSI DSP at 100 Hz frame rate inside a Python process is not feasible. This path cedes architectural control permanently.

Alt-B: Thin Rust wrapper that calls into Python HA via PyO3

Keep Python HA as the runtime; expose RuView sensing primitives via PyO3 bindings so they run at native speed inside the Python HA process.

Rejected because: the GIL is not resolved by PyO3 calls — the HA event loop still serialises all state changes. Startup time and memory footprint are unchanged. WASM plugin safety is unchanged. This is a tactical optimisation, not an architectural solution.

Alt-C: OpenHAB or Domoticz as the base

Port RuView's sensing stack on top of an alternative hub (openHAB/Java, Domoticz/C++).

Rejected because: neither has HA's community network effects, companion app ecosystem, or HACS plugin catalog. A clean-room Rust implementation preserves the HA compatibility contract (the most valuable asset) without inheriting the Python runtime limitations.

Alt-D: Extend the existing `wifi-densepose-sensing-server` into a full hub

Add automation, entity registry, and recorder features directly to the existing Axum sensing server.

Rejected because: the sensing server is a purpose-built single-concern binary (CSI → MQTT/WebSocket). Expanding it into a hub would violate the single-responsibility principle and couple hub release cycles to firmware release cycles. HOMECORE is a separate crate family that depends on but does not modify the sensing server.

9. Top-level risks

Risk	Likelihood	Severity	Mitigation
API drift — HA's REST/WS API evolves; HOMECORE must track it	High	High	Pin to HA 2025.1 baseline (schema 48); run the HA companion app integration tests against every HOMECORE release; ADR-130 owns the compat matrix
WASM sandbox performance — plugin calls through the WASM boundary add latency	Medium	Medium	Benchmark plugin roundtrip on Pi 5 before P3; reject if >5 ms; WASM3/Wasmtime both have sub-1 ms call overhead for compute-light integrations
Core triad dependency — ADR-128 and ADR-130 cannot start until ADR-127 is stable	High	High	ADR-127 is P2 start; freeze the state machine public API (entity_id, state, attributes, last_changed) before ADR-128 begins
ruvector semantic recorder — dual-write to SQLite + HNSW may impact write throughput under high-frequency sensing	Medium	High	ruvector writes are async (non-blocking tokio task); SQLite write is the hot path; benchmark at 100 state/s on Pi 5 before ADR-132 ships
Nabu Casa gap — users who depend on HA Cloud remote access have no HOMECORE replacement at P3	High	Medium	Document Tailscale as the replacement prominently; provide ADR-134 migration wizard that detects Nabu Casa usage and offers Tailscale setup
Frontend bundle size — replicating the HA Lovelace card ecosystem in TS+WASM is a significant engineering effort	High	High	ADR-131 is off-critical-path; serve HA's Python frontend against the HOMECORE API until ADR-131 P3 ships
License — HA is Apache 2.0; the wire protocol is unencumbered; HA's UI assets and card components have separate licenses	Low	High	Clean-room Rust implementation does not use HA source; HA frontend is served as a binary (not embedded); review license before ADR-131 ships any reimplemented component

10. Open questions

Q1 (ADR-127): Should the HOMECORE state machine use a DashMap<EntityId, State> for lock-free concurrent reads, or a RwLock<HashMap<EntityId, State>> for simpler reasoning? The answer affects every integration's write pattern.

Q2 (ADR-128): Does the WASM sandbox use Wasmtime (Cranelift JIT, ~5 MB binary) or WASM3 (interpreter, ~50 kB binary)? On a Pi 5 WASM3 is sufficient for integration logic; Wasmtime matters if integrations need near-native DSP speed.

Q3 (ADR-130): The HA WebSocket API uses numeric IDs for command/response correlation. The HA 2025.1 baseline adds subscribe_trigger as a first-class WS command. Are there any commands in the HA companion app that require a newer baseline?

Q4 (ADR-132): The ruvector HNSW index for state history — what embedding dimension represents a state snapshot? Options: (a) embed only numeric sensor states (scalar embedding), (b) embed {entity_id, state, attributes} as a text embedding via a local small model, (c) use a fixed schema encoding. The answer determines the semantic query fidelity.

Q5 (ADR-134): HA's .storage/core.config_entries format is versioned but undocumented; it is hand-engineered from reverse-engineering the Python StorageCollection class in homeassistant/helpers/storage.py. Is this format stable enough to parse without upstream documentation, or does HOMECORE need to maintain a version matrix?

11. References

This repo

docs/adr/ADR-115-home-assistant-integration.md — HA-DISCO MQTT publisher; 21-entity surface; semantic primitives; competitive comparison table
docs/adr/ADR-116-cog-ha-matter-seed.md — HA-COG Seed cog; cog packaging precedent (ADR-101)
docs/adr/ADR-117-pip-wifi-densepose-modernization.md — PIP-PHOENIX PyO3 bindings; Python client surface
docs/adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md — BFLD master; privacy class enforcement
docs/adr/ADR-124-rvagent-mcp-ruvector-npm-integration.md — SENSE-BRIDGE; RUVIEW-POLICY §4.1a; multi-modal normalization §11.3
docs/adr/ADR-125-ruview-apple-home-native-hap-bridge.md — APPLE-FABRIC HAP bridge
v2/crates/wifi-densepose-sensing-server/src/main.rs — Axum server architecture; bearer auth pattern
v2/crates/wifi-densepose-ruvector/src/viewpoint/ — cross-viewpoint fusion (attention, coherence, geometry, fusion modules)
CLAUDE.md — Project topology (hierarchical-mesh, 15 agents), ESP32 hardware table, crate publishing order

HA upstream

homeassistant/core.py — HomeAssistant, StateMachine, EventBus, ServiceRegistry, Config
homeassistant/helpers/entity_registry.py — EntityRegistry, RegistryEntry
homeassistant/helpers/entity.py — Entity, async_write_ha_state, entity lifecycle
homeassistant/components/api/__init__.py — REST API handler (24 routes)
homeassistant/components/websocket_api/ — connection.py auth handshake; commands.py WS commands
homeassistant/components/recorder/ — SQLite schema; migration.py schema version 48
homeassistant/components/assist_pipeline/ — voice/text pipeline; Wyoming protocol
homeassistant/helpers/template.py — Jinja2 template engine customisation
homeassistant/components/automation/__init__.py — automation trigger/condition/action model
homeassistant/helpers/storage.py — .storage/*.json persistence; StorageCollection
homeassistant/auth/ — long-lived access token model; AuthManager

External

HA Developer Docs — Core Architecture — state machine, event bus, service registry overview
HA Developer Docs — WebSocket API — WS command catalog
DeepWiki HA core — Entity and Registry Management — entity lifecycle
DeepWiki HA core — Data Management — recorder schema version 48
HA recorder integration — SQLite default; schema migration overview

28 KiB Raw Blame History Unescape Escape