rvCSI — Edge RF Sensing Runtime Domain Model

Domain-Driven Design Specification

Companion documents: rvCSI Platform PRD · ADR-095 — rvCSI Edge RF Sensing Platform

Domain

Camera-free RF spatial sensing from WiFi Channel State Information (CSI).

Core domain

RF field interpretation. rvCSI converts noisy radio channel measurements into validated events and temporal embeddings that represent changes in physical space. CSI is treated as a temporal delta stream against learned baselines — not as exact vision.

Supporting subdomains

Hardware adapter management · packet parsing · signal processing · calibration · event extraction · temporal memory · agent integration · replay and audit.

Generic subdomains

Logging · configuration · CLI parsing · WebSocket streaming · package publishing · dashboard visualization.

Ubiquitous Language

Bounded Contexts

┌─────────────┐   ┌──────────────┐   ┌────────────┐   ┌──────────────┐
│  Capture    │──▶│  Validation  │──▶│   Signal   │──▶│ Calibration  │
│  context    │   │   context    │   │  context   │   │   context    │
└─────────────┘   └──────────────┘   └─────┬──────┘   └──────┬───────┘
                                            │                 │
                                            ▼                 │
                                     ┌────────────┐           │
                                     │   Event    │◀──────────┘
                                     │  context   │
                                     └─────┬──────┘
                                            │
                              ┌─────────────┴─────────────┐
                              ▼                           ▼
                       ┌────────────┐              ┌────────────┐
                       │   Memory   │              │   Agent    │
                       │  context   │              │  context   │
                       └────────────┘              └────────────┘

• Capture upstreams raw input from sources.
• Validation protects every downstream context — nothing crosses into SDK/DSP/memory/agents unvalidated.
• Signal turns frames into windows.
• Calibration gives windows a room-specific baseline.
• Event converts deltas into meaning.
• Memory stores time, similarity, drift, and coherence (RuVector).
• Agent exposes safe actions and queries (MCP / TypeScript).

1. Capture context

Responsibility: connect to CSI sources and produce raw frames.

┌──────────────────────────────────────────────────────────────┐
│                      Capture Context                          │
├──────────────────────────────────────────────────────────────┤
│  ┌────────────┐   ┌─────────────────┐   ┌─────────────────┐   │
│  │  Source    │   │ CaptureSession  │   │ AdapterProfile  │   │
│  │ (adapter   │   │ (aggregate root)│   │ (capability     │   │
│  │  plugin)   │   │                 │   │  descriptor)    │   │
│  └────────────┘   └─────────────────┘   └─────────────────┘   │
│                                                                │
│  CsiSource trait: open · start · next_frame · stop · health    │
└──────────────────────────────────────────────────────────────┘

Commands: StartCapture · StopCapture · RestartCapture · InspectSource Domain events: CaptureStarted · CaptureStopped · SourceDisconnected · AdapterUnsupported

2. Validation context

Responsibility: make frames safe and trustworthy before any language-boundary crossing.

Commands: ValidateFrame · QuarantineFrame Domain events: FrameAccepted · FrameRejected · QualityDropped

3. Signal context

Responsibility: DSP and window features.

Frame stream ─▶ SignalPipeline ─▶ WindowBuffer ─▶ CsiWindow
              (DC removal, phase unwrap,        (mean amplitude,
               smoothing, Hampel filter,         phase variance,
               variance, baseline subtraction,   motion energy,
               motion energy, presence score)    presence/quality scores)

Commands: ProcessFrame · BuildWindow · EstimateBaselineDelta Domain events: WindowReady · BaselineDeltaMeasured

4. Calibration context

Responsibility: learn and version the normal RF state and room signatures.

Commands: StartCalibration · CompleteCalibration · UpdateBaseline · RejectUnstableCalibration Domain events: CalibrationStarted · CalibrationCompleted · CalibrationFailed · BaselineUpdated

5. Event context

Responsibility: semantic event extraction with confidence and evidence.

Commands: DetectEvents · PublishEvent · SuppressEvent Domain events (the CsiEventKind enum): PresenceStarted · PresenceEnded · MotionDetected · MotionSettled · BaselineChanged · SignalQualityDropped · DeviceDisconnected · BreathingCandidate · AnomalyDetected · CalibrationRequired

6. Memory context

Responsibility: RuVector storage and retrieval — RF memory.

Commands: StoreWindowEmbedding · StoreEventEmbedding · QuerySimilarWindows · ComputeDrift Domain events: EmbeddingStored · DriftDetected · SimilarPatternFound

Data stored: frame embeddings · window embeddings · room baseline vectors · event vectors · drift snapshots · sensor-topology graph edges · source health records. Retention policy applies at collection level. No orphan embeddings.

7. Agent context

Responsibility: MCP and TypeScript agent interaction — safe actions and queries.

Commands: SubscribeToEvents · RequestStatus · RequestCalibration · QueryMemory Domain events: AgentSubscribed · ToolExecuted · PermissionDenied

MCP tools (read by default; write-gated marked *): rvcsi_status · rvcsi_list_sources · rvcsi_start_capture * · rvcsi_stop_capture * · rvcsi_get_presence · rvcsi_get_recent_events · rvcsi_calibrate_room * · rvcsi_export_window * · rvcsi_query_ruvector · rvcsi_health_report.

Context Map

The CsiFrame schema is the shared kernel between Capture, Validation, Signal, and the language-boundary (napi-rs) layer. It is the FFI-safe object; nothing device-specific leaks past it.

Aggregates and Invariants

CaptureSession aggregate

Invariant: a capture session has exactly one source profile and one runtime configuration.

1. A session cannot emit frames before it is started.
2. A session cannot change channel without restart unless the adapter supports dynamic retune.
3. A session must emit SourceDisconnected before stopping due to device loss.

ValidatedFrame aggregate

Invariant: no frame crosses into SDK, DSP, memory, or agents unless its validation status is Accepted or Degraded.

1. Rejected frames go to quarantine when quarantine is enabled.
2. Degraded frames must carry quality-reason metadata.
3. Missing optional hardware metadata must not invalidate a frame.

CsiWindow aggregate

Invariant: a window contains frames from exactly one source and one session.

1. Mixed-source windows are not allowed.
2. Window start time must be strictly less than end time.
3. Window quality is bounded in [0, 1].

CalibrationProfile aggregate

Invariant: a calibration profile is linked to source, room, adapter profile, and configuration.

1. Calibration cannot complete if StabilityScore is below threshold.
2. Baseline updates must preserve version history.
3. Event detectors must declare which calibration version they used.

CsiEvent aggregate

Invariant: an event must have evidence.

1. Every event references at least one evidence window.
2. Confidence is bounded in [0, 1].
3. Event suppression must be explainable by policy.

RoomMemory aggregate

Invariant: stored embeddings are traceable to frame windows or event windows.

1. No orphan embeddings.
2. Retention policy applies at collection level.
3. Drift scores must include the baseline version.

Data Model

pub struct CsiFrame {
    pub frame_id: FrameId,
    pub session_id: SessionId,
    pub source_id: SourceId,
    pub adapter_kind: AdapterKind,
    pub timestamp_ns: u64,
    pub channel: u16,
    pub bandwidth_mhz: u16,
    pub rssi_dbm: Option<i16>,
    pub noise_floor_dbm: Option<i16>,
    pub antenna_index: Option<u8>,
    pub tx_chain: Option<u8>,
    pub rx_chain: Option<u8>,
    pub subcarrier_count: u16,
    pub i_values: Vec<f32>,
    pub q_values: Vec<f32>,
    pub amplitude: Vec<f32>,
    pub phase: Vec<f32>,
    pub validation: ValidationStatus,
    pub quality_score: f32,
    pub calibration_version: Option<String>,
}

pub struct CsiWindow {
    pub window_id: WindowId,
    pub session_id: SessionId,
    pub source_id: SourceId,
    pub start_ns: u64,
    pub end_ns: u64,
    pub frame_count: u32,
    pub mean_amplitude: Vec<f32>,
    pub phase_variance: Vec<f32>,
    pub motion_energy: f32,
    pub presence_score: f32,
    pub quality_score: f32,
}

pub enum CsiEventKind {
    PresenceStarted,
    PresenceEnded,
    MotionDetected,
    MotionSettled,
    BaselineChanged,
    SignalQualityDropped,
    DeviceDisconnected,
    BreathingCandidate,
    AnomalyDetected,
    CalibrationRequired,
}

pub struct CsiEvent {
    pub event_id: EventId,
    pub kind: CsiEventKind,
    pub session_id: SessionId,
    pub source_id: SourceId,
    pub timestamp_ns: u64,
    pub confidence: f32,
    pub evidence_window_ids: Vec<WindowId>,
    pub metadata_json: String,
}

pub struct AdapterProfile {
    pub adapter_kind: AdapterKind,
    pub chip: Option<String>,
    pub firmware_version: Option<String>,
    pub driver_version: Option<String>,
    pub supported_channels: Vec<u16>,
    pub supported_bandwidths_mhz: Vec<u16>,
    pub expected_subcarrier_counts: Vec<u16>,
    pub supports_live_capture: bool,
    pub supports_injection: bool,
    pub supports_monitor_mode: bool,
}

pub enum ValidationStatus { Accepted, Degraded, Rejected, Recovered }

Domain Services

Related

• rvCSI Platform PRD — requirements, success criteria, scope
• ADR-095 — rvCSI Edge RF Sensing Platform — the fifteen architectural decisions
• RuvSense Domain Model — adjacent multistatic sensing context
• Signal Processing Domain Model — the DSP primitives rvcsi-dsp reuses
• ADR Index