Skip to main content

qualia_core_db/modalities/
hydrology.rs

1//! Hydrological & Atmospheric Modality (`hydrology.rs`)
2//!
3//! Provides deterministic 10D ontological graph ledger bindings for multi-scale fluid dynamics:
4//! - Submersion state transitions: Dry (0), Wading (1), Swimming (2), Diving (3)
5//! - Dynamic clothing / surface wetness ratio encoding
6//! - Barometric pressure, moist air density, and wind vectors
7//! - Downsampled hysteresis evaluation for agents in the `.q42` graph
8//!
9//! Adheres strictly to `AGENTS.md` §0 (Zero heap in hot paths, 48-byte Super-Quin layout).
10
11use crate::NQuin;
12
13// ── Modality Opcodes (0x51–0x56) ──────────────────────────────────────────
14
15/// Submersion state predicate (Dry, Wading, Swimming, Diving) + depth in mm.
16pub const OP_HYDRO_SUBMERSION: u8 = 0x51;
17/// Surface / clothing wetness ratio [0.0, 1.0] mapped to u16.
18pub const OP_HYDRO_WETNESS: u8 = 0x52;
19/// Fluid current velocity vector [vx, vz] in mm/s.
20pub const OP_HYDRO_CURRENT: u8 = 0x53;
21/// Thermal conductivity drain rate (hypothermia risk metric).
22pub const OP_HYDRO_THERMAL: u8 = 0x54;
23/// Precipitation intensity in mm/hr + Lifting Condensation Level (LCL).
24pub const OP_HYDRO_PRECIPITATION: u8 = 0x55;
25/// Synoptic barometric state: MSLP in hPa + wind vector.
26pub const OP_HYDRO_BAROMETRIC: u8 = 0x56;
27
28// ── Submersion Status Values ──────────────────────────────────────────────
29
30pub const SUBMERSION_DRY: u8 = 0;
31pub const SUBMERSION_WADING: u8 = 1;
32pub const SUBMERSION_SWIMMING: u8 = 2;
33pub const SUBMERSION_DIVING: u8 = 3;
34
35/// Evaluated hydrological assessment for an entity or spatial node.
36#[repr(C)]
37#[derive(Debug, Clone, Copy, PartialEq)]
38pub struct HydroVerdict {
39    pub claim: NQuin,
40    pub submersion_state: u8,
41    pub depth_mm: u16,
42    pub wetness_ratio: f32,
43    pub flow_speed_m_s: f32,
44}
45
46#[derive(Debug, PartialEq, Eq)]
47pub enum HydroError {
48    BufferOverflow,
49    InvalidQuinOpcode,
50}
51
52/// Packs an agent's fluid submersion transition into a 48-byte NQuin.
53///
54/// Layout:
55/// - `subject`: Agent DID hash
56/// - `predicate`: `(property_hash << 8) | OP_HYDRO_SUBMERSION`
57/// - `object`: `(submersion_level as u64) << 32 | (depth_mm as u64)`
58/// - `context`: World / Basin DID hash
59/// - `metadata`: Lamport logical clock in bits [32..60]
60/// - `parity`: XOR fold
61pub fn pack_hydro_submersion_quin(
62    agent_did: u64,
63    world_did: u64,
64    submersion: u8,
65    depth_mm: u16,
66    lamport: u32,
67) -> NQuin {
68    let subject = agent_did;
69    let predicate = (0x4859_4452_4F53_5542u64 << 8) | (OP_HYDRO_SUBMERSION as u64); // "HYDROSUB"
70    let object = ((submersion as u64) << 32) | (depth_mm as u64);
71    let context = world_did;
72    let metadata = ((lamport as u64 & 0x1FFF_FFFF) << 32) | (depth_mm as u64 & 0xFFFF);
73    let parity = subject ^ predicate ^ object ^ context;
74
75    NQuin {
76        subject,
77        predicate,
78        object,
79        context,
80        metadata,
81        parity,
82    }
83}
84
85/// Packs dynamic surface wetness into an NQuin.
86pub fn pack_hydro_wetness_quin(
87    agent_did: u64,
88    world_did: u64,
89    wetness_ratio: f32,
90    lamport: u32,
91) -> NQuin {
92    let subject = agent_did;
93    let predicate = (0x4859_4452_4F57_4554u64 << 8) | (OP_HYDRO_WETNESS as u64); // "HYDROWET"
94    let wetness_u16 = ((wetness_ratio.clamp(0.0, 1.0) * 65535.0) as u64) & 0xFFFF;
95    let object = wetness_u16;
96    let context = world_did;
97    let metadata = ((lamport as u64 & 0x1FFF_FFFF) << 32) | wetness_u16;
98    let parity = subject ^ predicate ^ object ^ context;
99
100    NQuin {
101        subject,
102        predicate,
103        object,
104        context,
105        metadata,
106        parity,
107    }
108}
109
110/// Packs synoptic barometric pressure and wind state into an NQuin.
111pub fn pack_hydro_barometric_quin(
112    world_did: u64,
113    mslp_hpa: f32,
114    wind_u_mps: f32,
115    wind_v_mps: f32,
116    lamport: u32,
117) -> NQuin {
118    let subject = world_did;
119    let predicate = (0x4859_4452_4F42_4152u64 << 8) | (OP_HYDRO_BAROMETRIC as u64); // "HYDROBAR"
120    let mslp_scaled = ((mslp_hpa.clamp(800.0, 1100.0) - 800.0) * 100.0) as u64; // 0.01 hPa precision
121    let u_packed = ((wind_u_mps.clamp(-100.0, 100.0) + 100.0) * 10.0) as u64;
122    let v_packed = ((wind_v_mps.clamp(-100.0, 100.0) + 100.0) * 10.0) as u64;
123    let object = (mslp_scaled << 32) | (u_packed << 16) | v_packed;
124    let context = world_did;
125    let metadata = (lamport as u64 & 0x1FFF_FFFF) << 32;
126    let parity = subject ^ predicate ^ object ^ context;
127
128    NQuin {
129        subject,
130        predicate,
131        object,
132        context,
133        metadata,
134        parity,
135    }
136}
137
138/// Unpacks a submersion Quin returning `(submersion_level, depth_mm)`.
139#[inline]
140pub fn unpack_hydro_submersion_quin(quin: &NQuin) -> Option<(u8, u16)> {
141    let opcode = (quin.predicate & 0xFF) as u8;
142    if opcode == OP_HYDRO_SUBMERSION {
143        let submersion = ((quin.object >> 32) & 0xFF) as u8;
144        let depth_mm = (quin.object & 0xFFFF) as u16;
145        Some((submersion, depth_mm))
146    } else {
147        None
148    }
149}
150
151/// Unpacks a wetness Quin returning the continuous wetness ratio in [0.0, 1.0].
152#[inline]
153pub fn unpack_hydro_wetness_quin(quin: &NQuin) -> Option<f32> {
154    let opcode = (quin.predicate & 0xFF) as u8;
155    if opcode == OP_HYDRO_WETNESS {
156        let raw = (quin.object & 0xFFFF) as f32;
157        Some(raw / 65535.0)
158    } else {
159        None
160    }
161}
162
163/// Evaluates a frame of Quins, filtering by optional agent DID hash and producing zero-alloc verdicts.
164pub fn evaluate_hydrological_frame(
165    quins: &[NQuin],
166    agent_did: u64,
167    out: &mut [HydroVerdict],
168) -> Result<usize, HydroError> {
169    let mut count = 0;
170
171    for q in quins {
172        if agent_did != 0 && q.subject != agent_did {
173            continue;
174        }
175
176        let opcode = (q.predicate & 0xFF) as u8;
177        if opcode < OP_HYDRO_SUBMERSION || opcode > OP_HYDRO_BAROMETRIC {
178            continue;
179        }
180
181        if count >= out.len() {
182            return Err(HydroError::BufferOverflow);
183        }
184
185        let mut verdict = HydroVerdict {
186            claim: *q,
187            submersion_state: SUBMERSION_DRY,
188            depth_mm: 0,
189            wetness_ratio: 0.0,
190            flow_speed_m_s: 0.0,
191        };
192
193        match opcode {
194            OP_HYDRO_SUBMERSION => {
195                if let Some((sub, depth)) = unpack_hydro_submersion_quin(q) {
196                    verdict.submersion_state = sub;
197                    verdict.depth_mm = depth;
198                }
199            }
200            OP_HYDRO_WETNESS => {
201                if let Some(wet) = unpack_hydro_wetness_quin(q) {
202                    verdict.wetness_ratio = wet;
203                }
204            }
205            OP_HYDRO_CURRENT => {
206                let speed_mm = (q.object & 0xFFFF) as f32;
207                verdict.flow_speed_m_s = speed_mm / 1000.0;
208            }
209            _ => {}
210        }
211
212        out[count] = verdict;
213        count += 1;
214    }
215
216    Ok(count)
217}
218
219#[cfg(test)]
220mod tests {
221    use super::*;
222
223    #[test]
224    fn test_hydro_submersion_quin_roundtrip() {
225        let q = pack_hydro_submersion_quin(12345, 67890, SUBMERSION_WADING, 450, 42);
226        assert_eq!((q.predicate & 0xFF) as u8, OP_HYDRO_SUBMERSION);
227        assert_eq!(q.subject, 12345);
228        assert_eq!(q.context, 67890);
229
230        let unpacked = unpack_hydro_submersion_quin(&q);
231        assert_eq!(unpacked, Some((SUBMERSION_WADING, 450)));
232    }
233
234    #[test]
235    fn test_hydro_wetness_quin_roundtrip() {
236        let q = pack_hydro_wetness_quin(555, 777, 0.75, 100);
237        let wetness = unpack_hydro_wetness_quin(&q).expect("wetness quin");
238        assert!((wetness - 0.75).abs() < 1e-4);
239    }
240
241    #[test]
242    fn test_evaluate_hydrological_frame() {
243        let q1 = pack_hydro_submersion_quin(101, 999, SUBMERSION_SWIMMING, 1200, 1);
244        let q2 = pack_hydro_wetness_quin(101, 999, 1.0, 2);
245        let q3 = pack_hydro_submersion_quin(202, 999, SUBMERSION_DRY, 0, 3);
246
247        let quins = [q1, q2, q3];
248        let mut verdicts = [HydroVerdict {
249            claim: q1,
250            submersion_state: 0,
251            depth_mm: 0,
252            wetness_ratio: 0.0,
253            flow_speed_m_s: 0.0,
254        }; 4];
255
256        // Filter for agent 101 only
257        let count = evaluate_hydrological_frame(&quins, 101, &mut verdicts).expect("eval");
258        assert_eq!(count, 2);
259        assert_eq!(verdicts[0].submersion_state, SUBMERSION_SWIMMING);
260        assert_eq!(verdicts[0].depth_mm, 1200);
261        assert!((verdicts[1].wetness_ratio - 1.0).abs() < 1e-4);
262    }
263}