Skip to main content

rufield_core/
lib.rs

1//! # rufield-core
2//!
3//! Core data model for **RuField MFS** — the RuField Multimodal Field Sensing
4//! Specification (ADR-260). Defines the wire types (`FieldEvent`,
5//! `FieldTensor`, `Observation`, `ProvenanceRef`, `CalibrationReceipt`,
6//! `FieldInference`, `FieldEmbedding`), the `Modality`/`FieldAxis`/`PrivacyClass`
7//! enums, and the `FieldAdapter`/`FieldEncoder`/`FusionEngine`/`PrivacyGuard`
8//! traits.
9//!
10//! All numbers produced by the v0.1 reference stack come from a deterministic
11//! **synthetic simulator** — there is no hardware in this stack. Nothing here
12//! claims field-validated accuracy.
13
14#![doc(html_root_url = "https://docs.rs/rufield-core/0.1.0")]
15
16pub mod error;
17pub mod event;
18pub mod inference;
19pub mod modality;
20pub mod privacy;
21pub mod tensor;
22pub mod traits;
23
24pub use error::CoreError;
25pub use event::{
26    CalibrationReceipt, FieldEvent, Observation, ProvenanceRef, SensorDescriptor,
27};
28pub use inference::{FieldEmbedding, FieldInference, InferenceQuery};
29pub use modality::{FieldAxis, Modality};
30pub use privacy::PrivacyClass;
31pub use tensor::{FieldTensor, SPEC_VERSION};
32pub use traits::{
33    AdapterCapabilities, Destination, FieldAdapter, FieldEncoder, FusionEngine,
34    PrivacyDecision, PrivacyGuard,
35};
36
37#[cfg(test)]
38mod spec_json_tests {
39    use super::*;
40
41    /// ADR-260 §7 — the canonical Field Event JSON example must round-trip
42    /// through our `FieldEvent` type. The §7 example uses a compact inline
43    /// `field` block (sensor PHY descriptor) rather than a full numeric tensor;
44    /// our wire type carries a real `FieldTensor`, so we assert round-trip on a
45    /// faithful representation of the §7 fields (sensor, observation,
46    /// provenance) plus a concrete tensor.
47    #[test]
48    fn section7_example_round_trips() {
49        let json = r#"{
50          "spec_version": "rufield.mfs.v0.1",
51          "event_id": "01J00000000000000000000000",
52          "timestamp_ns": 1791986400000000000,
53          "sensor": {
54            "modality": "wifi_csi",
55            "vendor": "esp32_c6",
56            "device_id": "sensor_room_01",
57            "placement": "ceiling_corner",
58            "clock_domain": "local_ptp"
59          },
60          "tensor": {
61            "spec_version": "rufield.mfs.v0.1",
62            "timestamp_ns": 1791986400000000000,
63            "modality": "wifi_csi",
64            "axes": ["frequency", "amplitude"],
65            "shape": [2, 2],
66            "values": [0.1, 0.2, 0.3, 0.4],
67            "confidence": 0.87,
68            "noise_floor": 0.02,
69            "calibration_id": "room_cal_2026_06_14",
70            "privacy_class": "P2"
71          },
72          "observation": {
73            "zone_id": "room_01",
74            "space_cell": [4, 2, 1],
75            "range_m": 3.42,
76            "velocity_mps": 0.18,
77            "motion_vector": [0.12, -0.03, 0.0],
78            "confidence": 0.87,
79            "labels": ["person_present"],
80            "privacy_class": "P2"
81          },
82          "provenance": {
83            "raw_hash": "sha256:raw_measurement_hash",
84            "firmware_hash": "sha256:firmware_hash",
85            "model_id": "ruvector_field_encoder_v1",
86            "calibration_id": "room_cal_2026_06_14",
87            "synthetic": false
88          }
89        }"#;
90
91        let ev: FieldEvent = serde_json::from_str(json).expect("parse §7 example");
92        assert_eq!(ev.spec_version, SPEC_VERSION);
93        assert_eq!(ev.sensor.modality, "wifi_csi");
94        assert_eq!(ev.observation.privacy_class, PrivacyClass::P2);
95        assert_eq!(ev.tensor.modality, Modality::WifiCsi);
96        ev.tensor.validate().expect("tensor valid");
97
98        // Re-serialize and parse again: stable round-trip.
99        let s = serde_json::to_string(&ev).unwrap();
100        let back: FieldEvent = serde_json::from_str(&s).unwrap();
101        assert_eq!(ev, back);
102    }
103}