berkus
/
wifi-densepose
mirror of https://github.com/ruvnet/wifi-densepose.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
wifi-densepose/docs/research/soul/scanning-process.md

14 KiB
Raw Blame History

Soul Signature — Scanning Process

Status: Research Specification (Pre-Implementation) Date: 2026-05-24 Author: ruv

1. Hardware Prerequisites

1.1 Full Protocol (N ≥ 3 Nodes)

Component Minimum Recommended Notes
Sensing nodes 3 × ESP32-S3 (ADR-028) 5+ nodes Multi-node triangulation reduces angle-dependent blind spots; ADR-029 multistatic mesh
Compute appliance Cognitum Seed (Pi 5 + Hailo) Same Runs the field model, AETHER inference, vitals pipeline
Network link 2.4 GHz or 5 GHz AP Dedicated sensing AP Shared AP with user traffic degrades CSI frame rate
Firmware version ADR-110 v0.7.0+ Same Ed25519 witness chain required for attestation
Clock sync 802.15.4 time-sync (ESP32-C6) or NTP fallback 802.15.4 preferred ±100 µs alignment per ADR-110; NTP gives ±5 ms

1.2 Degraded Mode (1 Node)

A single-node enrollment produces an incomplete signature:

  • Skeletal proportions: degraded (single-angle view)
  • Subcarrier reflection profile: single orientation only (3-orientation protocol collapses to 1)
  • AETHER embedding: usable but lower confidence
  • Cardiac / respiratory: unaffected (single-node sufficient)
  • Gait timing: usable if node placement allows bidirectional walk

Single-node signatures MUST be tagged degraded_mode: true in the manifest. The match score uses only the channels that met minimum confidence thresholds. The soul signature is technically valid but should be re-enrolled with multi-node hardware when possible.

1.3 ESP32-C6 Uplift (Wi-Fi 6 HE-LTF)

When at least one ESP32-C6 node is present (ADR-110), the subcarrier count expands from 52 (HT-LTF, S3) to up to 242 (HE-LTF, C6). The MERIDIAN HardwareNormalizer (ADR-027) maps all nodes to a canonical 56-subcarrier representation for the AETHER backbone. The full 242-subcarrier profile is preserved in the SubcarrierReflectionProfile node for higher-fidelity matching when available. The C6's 802.15.4 time-sync (±100 µs) also improves multistatic coherence relative to NTP-only S3 meshes.

2. Structured 60-Second Enrollment Protocol

The enrollment protocol produces exactly one .rvf soul signature file. The protocol is structured into five phases with exact timing. A human-readable prompt sequence should be delivered to the subject via audio or display.

Phase 0 — Empty-Room Field Recalibration (T+0 to T+10)

Before the subject enters the sensing zone, the room must be empty and the ADR-030 field model must be current.

T+0s   : System checks field model age. Maximum age: 4 hours.
          If stale or absent → run field recalibration:
            Collect 1,200 CSI frames at 20 Hz (60 seconds of empty room)
            Compute per-link Welford mean and covariance
            Run SVD on covariance matrix → top-K=8 eigenmode vectors
            Store in field_model.rs::FieldNormalMode

T+0–10s: Quiet sampling of empty-room field state. No subject present.
          Operator prompt: "Please ensure the room is empty."
          System: verifies presence score < 0.1 (ADR-039 Tier 2 presence detection).
          Failure: if presence score ≥ 0.1, abort and report FAIL_ROOM_NOT_EMPTY.

This phase is skipped (not aborted) if the field model was updated within the last 4 hours AND the current empty-room sampling confirms presence score < 0.05.

Phase 1 — Deep Breathing Baseline (T+10 to T+25)

Subject enters the sensing zone and performs five deep breathing cycles.

T+10s  : Subject enters scan zone. System detects presence.
          Operator prompt: "Please stand still and breathe slowly and deeply."

T+10–25s: Subject stands at zone center, facing node cluster.
           Five complete breath cycles, each ≥ 4 seconds.
           System collects:
             - ADR-021 BreathingExtractor: baseline_bpm, depth_amplitude,
               inspiration_expiration_ratio, HRV_RSA
             - ADR-021 HeartRateExtractor: initial HR, HRV_SDNN (partial)
             - AETHER embedding: accumulates over 300 CSI frames (20 Hz × 15s)
           Quality gate: BreathingExtractor VitalCoherenceGate must emit
             PERMIT for ≥ 10 of the 15 seconds. Failure → FAIL_POOR_BREATHING_SIGNAL.

Phase 2 — Seated Rest (T+25 to T+35)

Subject sits to minimize motion and allow cardiac signal isolation.

T+25s  : Operator prompt: "Please sit down and rest quietly."

T+25–35s: Subject seated, minimal movement.
           System collects:
             - HeartRateExtractor: HR baseline, HRV_SDNN, HRV_RMSSD,
               LF/HF ratio, sinus rhythm classification
             - Cardiac_Waveform_Morphology: 64-coefficient wavelet decomposition
               of bandpass-filtered cardiac phase signal (0.8–2.0 Hz)
           Quality gate: HR confidence ≥ 0.6 for ≥ 7 of 10 seconds.
             Failure → FAIL_POOR_CARDIAC_SIGNAL (soft failure: cardiac nodes
             marked low-confidence; signature proceeds without them if AETHER
             and gait nodes pass their own thresholds).

Phase 3 — Gait Walk (T+35 to T+50)

Subject walks a 2-meter line twice in each direction.

T+35s  : Operator prompt: "Please walk a straight line of 2 meters back and
          forth twice at your natural pace."

T+35–50s: Subject walks: A→B, B→A, A→B, B→A (four transits, ≥ 8 strides total).
           System collects (via pose_tracker.rs, ADR-029 Sect 2.7):
             - GaitTimingNode: cadence, stride_period_variance,
               double_support_pct, asymmetry_index, step_width_m
             - SkeletalProportionsNode: torso/limb ratios from 17-keypoint
               trajectory accumulated over ≥ 8 strides
             - AETHER embedding: continues accumulating (300 more frames)
           Quality gate: ≥ 8 strides detected with confidence ≥ 0.7 per stride.
             Failure → FAIL_INSUFFICIENT_GAIT_DATA.
           Note: the ruvector-mincut DynamicPersonMatcher must confirm only one
           person is tracked. If two tracks are active → FAIL_MULTIPLE_SUBJECTS.

Phase 4 — Standing Orientation Scan (T+50 to T+60)

Subject stands at three orientations to capture the subcarrier reflection profile.

T+50s  : Operator prompt: "Please stand facing the wall. I will ask you to
          rotate in place twice."

T+50–53s: Orientation 0° (subject faces primary node cluster).
           System collects: SubcarrierReflectionProfile at 0°
           (ADR-030 field-subtracted, 56 subcarriers, amplitude + phase).

T+53s  : Operator prompt: "Please turn 90 degrees to your right."

T+53–56s: Orientation 90°.
           System collects: SubcarrierReflectionProfile at 90°.

T+56s  : Operator prompt: "Please turn 90 degrees to your right again."

T+56–60s: Orientation 180°.
           System collects: SubcarrierReflectionProfile at 180°.
           Body_Field_Coupling: computed from AETHER attention map weighted
           by ADR-030 top-K=8 eigenvectors (final computation at T=60s).

T+60s  : Enrollment window closes.
          AETHER embedding finalized: mean pool over all ~1,200 accumulated frames.
          All node confidence values computed.

3. Quality Gates

The enrollment FAILS and emits a structured error code if any of the following conditions are met. Failed enrollments do not produce a stored .rvf file.

Gate Condition for FAIL Error code
Room occupied Presence score ≥ 0.1 at Phase 0 end FAIL_ROOM_NOT_EMPTY
Multiple subjects ≥ 2 active pose tracks during Phases 1–4 FAIL_MULTIPLE_SUBJECTS
Intermittent presence Subject exits sensing zone for > 3 consecutive seconds FAIL_SUBJECT_LEFT_ZONE
AETHER confidence low Final embedding confidence < 0.6 (HNSW search confidence) FAIL_AETHER_LOW_CONFIDENCE
Breathing signal absent VitalCoherenceGate PERMIT rate < 67% during Phase 1 FAIL_POOR_BREATHING_SIGNAL
Gait data insufficient Fewer than 8 strides detected with confidence ≥ 0.7 FAIL_INSUFFICIENT_GAIT_DATA
Field model dirty Field model age > 4 hours and recalibration refused FAIL_STALE_FIELD_MODEL
Adversarial detection RuvSense adversarial.rs flags physically impossible signal FAIL_ADVERSARIAL_SIGNAL
Node count below minimum Fewer than 2 nodes online during Phases 3–4 WARN_DEGRADED_MODE (not a hard fail; produces degraded signature)

Soft failures (cardiac signal only) do not abort the enrollment; they mark those nodes as low-confidence and reduce the match weight for those channels at recognition time.

4. Fast Scan (10-Second Degraded Identification)

A fast scan produces a partial query embedding, not a stored profile. It is used for recognition of already-enrolled subjects, not for new enrollment.

T+0s   : System checks whether field model is current (age < 4 hours).
          If stale: recognition accuracy degraded; warn operator.

T+0–10s: Subject stands still at zone center, natural breathing.
          System collects: AETHER embedding (200 frames, 10s at 20 Hz).
          Cardiac HR: partial (confidence typically < 0.5).
          Gait: not available.
          Subcarrier reflection: 1 orientation only.

T+10s  : Query issued against all stored profiles in HNSW index.
          Match score computed using available channels only.
          Cardiac, gait, and skeletal proportions excluded from denominator
          (availability factor = 0 for absent channels).

Fast scan is acceptable for:

  • Returning resident recognition (already enrolled, low-friction use case)
  • Home automation triggers (occupancy attribution per ADR-115 HA-MIND)

Fast scan is NOT acceptable for:

  • Initial enrollment
  • High-assurance access control
  • Healthcare identification

5. Continuous Mode — Implicit Signature Refinement

In continuous operating mode, the system incrementally updates the online aggregator for enrolled persons as they go about their normal activities. The stored profile is re-published from the aggregator every 90 days (or on the re-scan cadence, whichever comes first). This means a deployed system becomes more accurate over time, not less.

Convergence property: the Welford online statistics in the aggregator are numerically stable and converge to the true population mean/variance as observation count increases. The AETHER embedding accumulated over thousands of natural-activity windows is more representative than a single 60-second enrollment. The stored profile is replaced (not amended) on each re-publish; the old profile is archived (not deleted) per the forward-secrecy requirements in security.md.

The continuous mode raises a consent concern: a person is effectively being re-enrolled continuously without explicit action. This is addressed in security.md §4 (Consent Architecture).

6. Multi-Room Enrollment

When a person moves across multiple sensing zones (e.g., living room and bedroom each with a Cognitum Seed node cluster), the cross-room signature works as follows:

  1. Full 60-second enrollment is performed in the primary room. This produces the initial stored profile with environment_normalized: false in the manifest.

  2. When the MERIDIAN domain generalization layer (ADR-027) is active, the HardwareNormalizer maps the enrollment embedding to the environment-invariant subspace. The stored profile is updated to environment_normalized: true.

  3. In subsequent rooms, a fast scan (10s) is sufficient to attribute identity. The MERIDIAN-normalized AETHER embedding handles the room shift.

  4. For healthcare deployments requiring room-by-room re-enrollment for regulatory reasons, a per-room enrollment protocol runs in each room and the signatures are linked by the opaque person_id field (never by raw PII).

7. Re-Scan Cadence

Deployment context Re-scan interval Rationale
Healthy adult (residential) 90 days Anatomy stable; continuous mode refines continuously
Child (growing skeleton) 30 days Skeletal proportions change; gait timing changes
Healthcare / clinical Per clinical event Post-surgery, post-illness, post-significant weight change
Post-exercise monitoring 7 days during active programs Body composition changes affect RF backscatter
Any On drift alert from longitudinal.rs (ADR-030 Tier 4) System-initiated; shown to user as "calibration recommended"

The longitudinal.rs module monitors five drift metrics (GaitSymmetry, StabilityIndex, BreathingRegularity, MicroTremor, ActivityLevel) using Welford statistics over daily observations. When any metric exceeds 2-sigma deviation sustained for 3 consecutive days, a DriftAlert is emitted. The system displays this as "signature drift detected — re-scan recommended," not as a health diagnosis.

8. Output Artifact

On successful completion, the enrollment pipeline produces:

  1. signature-<sha256>.rvf — the binary soul signature container. Content-addressed. Encrypted with the person's key (see security.md §5) before writing to disk.

  2. signature-<sha256>.json — the JSON-LD sidecar for human inspection and audit. Does not contain raw vector data. Safe to log.

  3. A row in the local HNSW index (ruvector-core::VectorIndex, person_track subindex per ADR-024 §2.4) linking the person_id to the AETHER embedding. This index is used for O(log n) recognition queries.

  4. An Ed25519 witness entry per ADR-110, signing (rvf_sha256 || timestamp_ns || enrolled_by_device_id). Stored in the RVF SEG_WITNESS segment AND in the node's local audit log.

The enrollment process does NOT:

  • Transmit raw CSI or raw biometrics to any external server.
  • Publish the soul signature to MQTT or Matter unless explicitly configured with --privacy-mode disabled (see security.md §6).
  • Store PII (name, email, account linkage) in the .rvf file. The person_id field is an opaque u64. PII linkage, if any, lives in the application layer and is governed by separate access control.