From 753f0a23b7ff1fb463c518d1d75e2837fc606075 Mon Sep 17 00:00:00 2001 From: ruv Date: Sun, 24 May 2026 12:35:06 -0400 Subject: [PATCH] docs(adr-118): integrate Soul Signature into BFLD ADRs 118/120/121/122 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Wire the Soul Signature research (docs/research/soul/) into BFLD as a consent-based opt-in that runs at privacy_class = 1 (derived). BFLD becomes the policy-enforcement and compliance layer for Soul Signature; the two share the AETHER encoder, the witness chain, the RVF container, and cross_room.rs. ADR-118 §1.4 (new): comparison table of intents, consent models, ID spaces, and shared assets. Explains why the two systems are complementary, not antagonistic. ADR-120 §2.7 (new): dual-ID-space contract. - Default BFLD: class 2, daily-rotated rf_signature_hash for all. - Soul Signature opt-in: class 1, rotating hash for unenrolled + stable opaque person_id for enrolled. No collision. - Class 3 (restricted): Soul Signature disabled. Static enforcement via --features soul-signature feature gate. ADR-121 §2.6 (new): Soul Signature Recalibrate exemption + enrollment- quality gate. - SoulMatchOracle suppresses Recalibrate when high score traces to an enrolled person_id (matched outcome is intended, not an attack). - identity_risk_score doubles as enrollment-quality signal: Soul Signature enrollment requires score >= 0.65 sustained over the 60s window. - Exemption is asymmetric: unknown high-separability clusters still trigger Recalibrate. ADR-122 §2.7 (new): three Soul Signature HA entities exposed at class 1 only, structurally rejected at the Matter boundary. Fourth blueprint (enrolled-person arrival notification) ships under feature flag, default off, per-person opt-in. Co-Authored-By: claude-flow --- ...eamforming-feedback-layer-for-detection.md | 17 ++++++++++++++++- ...20-bfld-privacy-class-and-hash-rotation.md | 13 +++++++++++++ .../adr/ADR-121-bfld-identity-risk-scoring.md | 17 +++++++++++++++-- .../ADR-122-bfld-ruview-ha-matter-exposure.md | 19 +++++++++++++++++++ 4 files changed, 63 insertions(+), 3 deletions(-) diff --git a/docs/adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md b/docs/adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md index d6d0a62d..8951861e 100644 --- a/docs/adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md +++ b/docs/adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md @@ -9,6 +9,7 @@ | **Relates to** | [ADR-024](ADR-024-contrastive-csi-embedding-model.md) (AETHER), [ADR-027](ADR-027-cross-environment-domain-generalization.md) (MERIDIAN), [ADR-028](ADR-028-esp32-capability-audit.md) (witness), [ADR-029](ADR-029-ruvsense-multistatic-sensing-mode.md) (multistatic), [ADR-030](ADR-030-ruvsense-persistent-field-model.md) (field model), [ADR-031](ADR-031-ruview-sensing-first-rf-mode.md) (sensing-first), [ADR-032](ADR-032-multistatic-mesh-security-hardening.md) (mesh security), [ADR-095](ADR-095-rvcsi-edge-rf-sensing-platform.md) (rvCSI), [ADR-115](ADR-115-home-assistant-integration.md) (HA), [ADR-116](ADR-116-cog-ha-matter-seed.md) (Matter), [ADR-117](ADR-117-pip-wifi-densepose-modernization.md) (pip) | | **Sub-ADRs** | [ADR-119](ADR-119-bfld-frame-format-and-wire-protocol.md) (frame), [ADR-120](ADR-120-bfld-privacy-class-and-hash-rotation.md) (privacy), [ADR-121](ADR-121-bfld-identity-risk-scoring.md) (risk), [ADR-122](ADR-122-bfld-ruview-ha-matter-exposure.md) (RuView), [ADR-123](ADR-123-bfld-capture-path-nexmon-and-esp32.md) (capture) | | **Research bundle** | [`docs/research/BFLD/`](../research/BFLD/) (11 files, 13,544 words) | +| **Companion research** | [`docs/research/soul/`](../research/soul/) — Soul Signature multi-modal biometric. BFLD is the policy-enforcement and compliance layer for Soul Signature; the two share the AETHER encoder (ADR-024), the witness chain (ADR-110/028), the RVF container, and `cross_room.rs` (ADR-030). | | **Tracking issue** | TBD | --- @@ -36,7 +37,21 @@ This gap becomes a compliance and liability issue at deployment scale. An operat BFI is not only a threat vector — its compressed angle matrices carry multipath geometry useful for presence and motion detection, particularly in single-AP deployments where MIMO CSI is unavailable. BFLD treats BFI as an **optional input alongside CSI**, not a replacement. -### 1.4 What this ADR is *not* +### 1.4 Relationship to the Soul Signature research + +The Soul Signature research (`docs/research/soul/`) defines a 7-channel multi-modal biometric for **consent-based** passive re-identification of enrolled individuals. Where Soul Signature *intentionally produces* identity (with a 60-second enrollment protocol), BFLD *measures and gates* identity leakage from the same sensing substrate. The two systems are complementary by design: + +| Concern | Soul Signature | BFLD | +|---------|----------------|------| +| Intent | Create a biometric for enrolled persons | Measure and gate identity leakage | +| Consent model | Explicit enrollment, GDPR/HIPAA modes | Default-deny, all unenrolled persons | +| Operating class | Must run at `privacy_class = 1` (derived) | Defaults to class 2 (anonymous) | +| Shared assets | AETHER encoder (ADR-024), WitnessChain (ADR-110/028), RVF container, `cross_room.rs` (ADR-030) | Same | +| ID space | Long-lived opaque `person_id` per enrolled subject | Rotating `rf_signature_hash` per day per unenrolled person | + +BFLD becomes Soul Signature's enforcement layer: the `identity_risk_score` gates whether a zone is leaky enough to enroll, the witness bundle is the regulator-facing audit artifact, and the structural privacy invariants (I1/I2/I3) ensure unenrolled bystanders stay anonymous even in zones where Soul Signature is actively matching enrolled persons. See ADR-120 §2.7 and ADR-121 §2.7 for the integration points. + +### 1.5 What this ADR is *not* - Not a removal of the CSI pipeline. ADR-095/096 rvCSI stays authoritative for CSI. - Not a port of any external sniffer into the repo. The Nexmon capture path lives in a separate adapter (see ADR-123). diff --git a/docs/adr/ADR-120-bfld-privacy-class-and-hash-rotation.md b/docs/adr/ADR-120-bfld-privacy-class-and-hash-rotation.md index 592f32f0..13846279 100644 --- a/docs/adr/ADR-120-bfld-privacy-class-and-hash-rotation.md +++ b/docs/adr/ADR-120-bfld-privacy-class-and-hash-rotation.md @@ -7,6 +7,7 @@ | **Deciders** | ruv | | **Parent** | [ADR-118](ADR-118-bfld-beamforming-feedback-layer-for-detection.md) | | **Relates to** | [ADR-027](ADR-027-cross-environment-domain-generalization.md) (MERIDIAN no-cross-site), [ADR-032](ADR-032-multistatic-mesh-security-hardening.md) (mesh security), [ADR-106](ADR-106-dp-sgd-and-primitive-isolation.md) (primitive isolation), [ADR-115](ADR-115-home-assistant-integration.md) (privacy mode) | +| **Companion research** | [`docs/research/soul/`](../research/soul/) — Soul Signature operates at `privacy_class = 1` (derived). §2.7 defines the dual-ID-space contract. | | **Tracking issue** | TBD | --- @@ -114,6 +115,18 @@ A compile-time `#[forbid(serde::Serialize)]` lint on `IdentityEmbedding` ensures Every new field added to `BfldFrame` or `BfldEvent` must be tagged with `#[must_classify]` (a custom attribute macro). The macro fails compilation if the field is not listed in the per-class allow-list table. This forces future contributors to make an explicit privacy decision on every new field. +### 2.7 Dual-ID-space contract for Soul Signature deployments + +Soul Signature (`docs/research/soul/`) is a consent-based biometric system that *intentionally* produces long-lived per-person identity. It cannot operate at the default class 2 — the identity_embedding it needs is structurally absent there. The contract: + +| Deployment mode | `privacy_class` | ID space for unenrolled bystanders | ID space for enrolled persons | +|---|---|---|---| +| Default BFLD-only | 2 (anonymous) | Daily-rotated `rf_signature_hash` | n/a — no enrollment | +| Soul Signature opt-in | **1 (derived)** | Daily-rotated `rf_signature_hash` (unchanged) | Long-lived opaque `person_id` from Soul Signature graph | +| Restricted / care-home | 3 (restricted) | Suppressed | n/a — Soul Signature **disabled** at class 3 | + +Two ID spaces coexist with **no collision**: the rotating hash is the privacy-preserving identifier for everyone *not* on the consent roster; the stable `person_id` is reserved for enrolled subjects under their own GDPR/HIPAA mode. Soul Signature's `match_against_enrolled()` function consumes only the in-RAM `identity_embedding` (I2 still holds) and emits a `person_id` plus a calibrated similarity score; it never writes the embedding to disk or the wire. The class-1 requirement is enforced statically: the Soul Signature match API takes a `&IdentityEmbedding` parameter, which is only constructible when the BFLD crate is compiled with `--features soul-signature` against a class-1 frame. + --- ## 3. Consequences diff --git a/docs/adr/ADR-121-bfld-identity-risk-scoring.md b/docs/adr/ADR-121-bfld-identity-risk-scoring.md index 427ddae2..e17879d1 100644 --- a/docs/adr/ADR-121-bfld-identity-risk-scoring.md +++ b/docs/adr/ADR-121-bfld-identity-risk-scoring.md @@ -7,6 +7,7 @@ | **Deciders** | ruv | | **Parent** | [ADR-118](ADR-118-bfld-beamforming-feedback-layer-for-detection.md) | | **Relates to** | [ADR-024](ADR-024-contrastive-csi-embedding-model.md) (AETHER), [ADR-027](ADR-027-cross-environment-domain-generalization.md) (MERIDIAN), [ADR-029](ADR-029-ruvsense-multistatic-sensing-mode.md) (multistatic fusion), [ADR-086](ADR-086-edge-novelty-gate.md) (novelty gate precedent), [ADR-120](ADR-120-bfld-privacy-class-and-hash-rotation.md) (privacy class) | +| **Companion research** | [`docs/research/soul/`](../research/soul/) — risk score doubles as Soul Signature enrollment-quality signal; §2.7 defines the Recalibrate exemption. | | **Tracking issue** | TBD | --- @@ -93,7 +94,19 @@ The `Recalibrate` action triggers a forced site-salt rotation — an aggressive To prevent oscillation around the gate thresholds, the gate uses ±0.05 hysteresis and a 5-second debounce. A score must cross the boundary by the hysteresis margin and persist for the debounce window before the gate action changes. -### 2.6 Compute budget +### 2.6 Soul Signature interaction — Recalibrate exemption and enrollment-quality gate + +Soul Signature (`docs/research/soul/`) intentionally exists in a high-separability regime — the whole point of its 60-second enrollment protocol is to push `identity_separability_score` toward 1.0. The default coherence gate (§2.4) would therefore fire `Recalibrate` constantly inside Soul Signature zones, rotating `site_salt` every few seconds and breaking enrollment. + +Two integrations resolve this: + +1. **Recalibrate exemption.** When the gate is about to fire `Recalibrate`, it consults a `SoulMatchOracle` (provided by the Soul Signature crate when compiled with `--features soul-signature`). If the oracle reports that the current high-separability cluster matches an enrolled `person_id` above the Soul Signature acceptance threshold, the gate downgrades to `PredictOnly` instead. The high score is the *intended* outcome of a successful match, not an attack indicator. Without the `soul-signature` feature, the oracle is a no-op stub returning `MatchOutcome::NotEnrolled`, so the gate behaves exactly per §2.4. + +2. **Enrollment-quality gate.** Soul Signature's enrollment protocol (`scanning-process.md` §3) requires that the sensing zone meet a minimum identity-leakage regime — too low, and the resulting signature is unreliable. The BFLD `identity_risk_score` is exactly the right signal. Soul Signature gates enrollment on `score >= ENROLL_MIN` (default `0.65`) sustained over the 60-second window. If the score drops below threshold mid-enrollment, the protocol aborts and the operator is prompted to re-attempt in better RF conditions. + +The exemption is asymmetric: it suppresses `Recalibrate` only for known-enrolled matches. Unknown high-separability clusters (a real attacker-grade sniffer, or an unenrolled person whose identity is unexpectedly leaky) still trigger `Recalibrate` as designed. + +### 2.7 Compute budget | Stage | Target latency | Implementation | |-------|----------------|----------------| @@ -102,7 +115,7 @@ To prevent oscillation around the gate thresholds, the gate uses ±0.05 hysteres | Risk score | < 0.1 ms | scalar multiplicative | | Gate decision + hysteresis | < 0.1 ms | scalar | -Total p95 ≤ 10 ms per window on a Pi 5 core (8 ms target). Headroom on cognitum-v0 (Pi 5 + Hailo) is ample; ESP32-S3 hosts only the extraction stage (features computed; risk score is host-side per ADR-123). +Total p95 ≤ 10 ms per window on a Pi 5 core (8 ms target). Headroom on cognitum-v0 (Pi 5 + Hailo) is ample; ESP32-S3 hosts only the extraction stage (features computed; risk score is host-side per ADR-123). The `SoulMatchOracle` lookup (§2.6) adds < 1 ms when the `soul-signature` feature is enabled (RaBitQ index over enrolled centroids). --- diff --git a/docs/adr/ADR-122-bfld-ruview-ha-matter-exposure.md b/docs/adr/ADR-122-bfld-ruview-ha-matter-exposure.md index 56d46352..3ce7290b 100644 --- a/docs/adr/ADR-122-bfld-ruview-ha-matter-exposure.md +++ b/docs/adr/ADR-122-bfld-ruview-ha-matter-exposure.md @@ -7,6 +7,7 @@ | **Deciders** | ruv | | **Parent** | [ADR-118](ADR-118-bfld-beamforming-feedback-layer-for-detection.md) | | **Relates to** | [ADR-031](ADR-031-ruview-sensing-first-rf-mode.md) (sensing-first), [ADR-100](ADR-100-cog-packaging-specification.md) (cog packaging), [ADR-115](ADR-115-home-assistant-integration.md) (HA-DISCO + HA-MIND), [ADR-116](ADR-116-cog-ha-matter-seed.md) (Matter cog), [ADR-120](ADR-120-bfld-privacy-class-and-hash-rotation.md) (privacy class) | +| **Companion research** | [`docs/research/soul/`](../research/soul/) — Soul Signature deployments expose enrolled-match diagnostics only over HA, never Matter. See §2.7. | | **Tracking issue** | TBD | --- @@ -124,6 +125,24 @@ Three operator-ready blueprints under `cog-ha-matter/blueprints/`: 2. **Motion-aware HVAC** — `sensor.*_bfld_motion > 0.3` ⇒ raise HVAC setpoint by ΔT. 3. **Identity-risk anomaly notification** — `sensor.*_bfld_identity_risk` exceeds rolling z-score threshold ⇒ HA `notify.*` to the operator with the originating node and the 7-day baseline. +### 2.7 Soul Signature deployment posture + +When the cog is compiled with `--features soul-signature`, two additional HA entities are exposed **at class 1 only**, and **never** over Matter: + +| Entity ID | Type | Source | Class gate | Matter | +|-----------|------|--------|------------|--------| +| `sensor._soul_match_id` | string (opaque `person_id`) | Soul Signature match oracle | == 1 only | **rejected** | +| `sensor._soul_match_score` | gauge `[0,1]` | Match similarity | == 1 only | **rejected** | +| `sensor._soul_enrollment_quality` | gauge `[0,1]` | Mirror of `identity_risk_score` during enrollment | == 1 only | **rejected** | + +These entities are part of the consent-based diagnostic surface for operators running Soul Signature deployments (care homes with explicit GDPR Art. 9 basis, employment with consent, etc.). The Matter cluster boundary in §2.4 already rejects them by type — the `MatterSink` impl only accepts class-2/3 frames, so `soul_match_id` is structurally unreachable through Matter. + +Class-3 deployments **disable Soul Signature** entirely: the `match_against_enrolled()` call returns `MatchOutcome::Suppressed` and no soul entities are published. This makes class 3 the correct setting for any deployment where consent is uncertain or where regulators require Soul Signature to be unavailable. + +A fourth blueprint ships only when `--features soul-signature` is enabled: + +4. **Enrolled-person arrival notification** — `sensor.*_soul_match_id` transitions to a non-null value ⇒ HA `notify.*` to the enrolled person's configured contact (typically themselves or a designated caregiver). Default off; operator must opt in per enrolled person. + --- ## 3. Consequences