From 67ad8eeab6b2cc18107d4ac734291dbab55cf09c Mon Sep 17 00:00:00 2001 From: ruvnet Date: Thu, 27 Aug 2026 20:16:10 +0000 Subject: [PATCH] deploy: 27f5540663d5eb21753f9d9c0ec6c3f348b710eb --- ...4-adaptive-local-installation-discovery.md | 93 +++++++++++++++++++ api-docs/adr/README.md | 1 + 2 files changed, 94 insertions(+) create mode 100644 api-docs/adr/ADR-344-adaptive-local-installation-discovery.md diff --git a/api-docs/adr/ADR-344-adaptive-local-installation-discovery.md b/api-docs/adr/ADR-344-adaptive-local-installation-discovery.md new file mode 100644 index 00000000..ac37ecce --- /dev/null +++ b/api-docs/adr/ADR-344-adaptive-local-installation-discovery.md @@ -0,0 +1,93 @@ +# ADR-344: Adaptive local installation discovery + +## Status + +Accepted — local advertisement and mobile discovery implemented; physical +peer-link and hosted-relay qualification pending. + +## Context + +RuView installations previously depended on a manually stored IP address. +DHCP changes, access-point changes, and client isolation could therefore leave +a healthy sensing installation unreachable from the mobile app. Repeated +authentication-policy log entries did not prove that the selected endpoint was +reachable. + +Discovery must make commissioning recoverable without turning a service name +into authentication, leaking sensor data, scanning arbitrary subnets, or +silently moving private spatial data to a hosted service. + +## Decision + +The sensing server advertises one bounded `_ruview._tcp.local.` service when it +is bound to a routable interface. Loopback-only instances do not advertise, +and operators can disable advertisement with `--no-mdns`. + +The TXT contract is deliberately small: + +| Key | Required | Meaning | +|---|---:|---| +| `schema=ruview.installation.v1` | yes | Fail-closed protocol discriminator | +| `tls=0|1` | yes | HTTP or HTTPS origin construction | +| `installation=` | no | Bounded routing hint, never authentication | + +The advertisement contains no node inventory, room identifier, SSID, +credentials, CSI, vital estimates, pose, identity, or learning data. The +hostname is bounded and sanitized before registration. Advertisement failure +is recoverable and does not stop sensing. + +RuView Mobile resolves only the matching service and schema, validates the +resulting origin under its private-LAN/HTTPS policy, and requires an application +health probe before selection. Its adaptive broker retains the configured +origin preference and requires two failed configured probes plus two healthy +fallback probes before switching. Credentials remain scoped to their saved +origin. + +The recovery ladder is: + +1. configured private-LAN or HTTPS origin; +2. verified Bonjour local origin; +3. physically qualified Apple peer-to-peer local path; +4. explicit, authenticated HTTPS relay for bounded derived frames only; +5. optional administrator-managed WireGuard/Tailscale access. + +Only levels 1 and 2 are implemented and software-validated by this decision. +Peer-to-peer browsing is enabled on Apple platforms, but it is not a qualified +peer-link data plane. This repository does not provide a hosted relay and must +fail closed when no local endpoint is healthy. + +## Security and privacy consequences + +- Service discovery is routing evidence, not installation authentication. +- Public HTTP origins, credentials in URLs, malformed records, and records with + the wrong schema are rejected before use. +- Raw CSI, RSSI streams, camera/LiDAR frames, room geometry, pose labels, + identity data, and training examples remain local. +- Future relay work requires a separate consent, authentication, revocation, + minimization, and physical evidence review. +- ESP32-S3/C6 nodes remain provisioned to the sensing installation. This ADR + does not claim direct phone-to-node discovery or invent a firmware protocol. + +## Validation + +Software acceptance requires: + +- unit tests for bounded advertisement construction and hostname sanitation; +- mobile parser rejection, route scoring, anti-flapping, and Settings UI tests; +- Rust, TypeScript, lint, security, metaharness, Expo, and native compile gates; +- a real Bonjour resolve of the TXT contract followed by a successful + `/api/v1/status` probe. + +Physical qualification additionally requires installation discovery on an +iPhone, live frame and node-inventory receipt, DHCP-change recovery without +flapping, and a five-to-ten-minute zero-fusion-error burn-in. Simulator and +host-only results remain `MEASURED_SOFTWARE`; peer-link, relay, and physical +reconnection claims remain `NOT_MEASURED` until those captures exist. + +## Implementation references + +- `v2/crates/wifi-densepose-sensing-server/src/discovery.rs` +- `v2/crates/wifi-densepose-sensing-server/src/main.rs` +- Mobile companion decision: `cognitum-one/ruview-mobile`, + `docs/adr/ADR-026-adaptive-local-installation-discovery-and-transport-recovery.md` +- Related decisions: ADR-034, ADR-054, ADR-296 diff --git a/api-docs/adr/README.md b/api-docs/adr/README.md index 5071ace4..6ea87665 100644 --- a/api-docs/adr/README.md +++ b/api-docs/adr/README.md @@ -105,6 +105,7 @@ Statuses: **Proposed** (under discussion), **Accepted** (approved and/or impleme | [ADR-035](ADR-035-live-sensing-ui-accuracy.md) | Live Sensing UI Accuracy and Data Transparency | Accepted | | [ADR-036](ADR-036-rvf-training-pipeline-ui.md) | Training Pipeline UI Integration | Proposed | | [ADR-043](ADR-043-sensing-server-ui-api-completion.md) | Sensing Server UI API Completion (14 endpoints) | Accepted | +| [ADR-344](ADR-344-adaptive-local-installation-discovery.md) | Adaptive Local Installation Discovery | Accepted (local software path) | | [ADR-115](ADR-115-home-assistant-integration.md) | Home Assistant integration via MQTT auto-discovery + Matter bridge (HA-DISCO + HA-FABRIC + HA-MIND) | Accepted (MQTT track) / Proposed (Matter SDK P8b) | | [ADR-169](ADR-169-adam-mode-light-theme.md) | adam-mode — light theme toggle for the three.js realtime demo | Proposed | | [ADR-170](ADR-170-yoga-mode-pose-system.md) | yoga-mode — yoga pose detection, classification, and scoring for the three.js realtime demo | Proposed |