Skip to main content

qualia_core_db/modalities/
botany.rs

1//! Botanical & Flora Biophysics Modality (`botany.rs`)
2//!
3//! Provides deterministic 10D ontological graph ledger bindings for procedural flora:
4//! - Metamer organ state, sapwood pipe count, and heartwood core
5//! - Continuous cellular turgor pressure and hydraulic potential
6//! - Thermal time phenology (Growing Degree Days $GDD$, vernalization chilling)
7//! - Ground cover ecotope patch (LAI, culm height, trample deformation)
8//! - Murray's Law vascular radius and Hagen-Poiseuille conductance
9//! - Raunkiær life-form classification and harsh-season dieback state
10//!
11//! Strictly zero heap in hot loops (`AGENTS.md` §0), 48-byte Super-Quin layout.
12
13use crate::NQuin;
14
15// ── Modality Opcodes (0x57–0x5C) ──────────────────────────────────────────
16
17/// Metamer organ state: Organ type, active sapwood pipes, retired heartwood pipes.
18pub const OP_BOTANY_METAMER: u8 = 0x57;
19/// Cellular turgor pressure in kPa + hydraulic water potential.
20pub const OP_BOTANY_TURGOR: u8 = 0x58;
21/// Thermal phenology: Accumulated GDD + chilling hours.
22pub const OP_BOTANY_PHENOLOGY: u8 = 0x59;
23/// Ground cover ecotope: LAI + mean culm height mm + trample matted ratio.
24pub const OP_BOTANY_ECOTOPE: u8 = 0x5A;
25/// Vascular venation: Murray's Law radius um + Poiseuille conductance.
26pub const OP_BOTANY_VASCULAR: u8 = 0x5B;
27/// Raunkiær life-form classification + seasonal dieback pruning flag.
28pub const OP_BOTANY_RAUNKIAER: u8 = 0x5C;
29
30/// Evaluated botanical assessment for a plant, branch, metamer, or ecotope patch.
31#[repr(C)]
32#[derive(Debug, Clone, Copy, PartialEq)]
33pub struct BotanyVerdict {
34    pub claim: NQuin,
35    pub organ_type: u8,
36    pub active_pipes: u16,
37    pub turgor_kpa: u16,
38    pub accumulated_gdd: f32,
39    pub is_dieback_active: bool,
40}
41
42#[derive(Debug, PartialEq, Eq)]
43pub enum BotanyError {
44    BufferOverflow,
45    InvalidQuinOpcode,
46}
47
48/// Packs a metamer's vascular pipe state into a 48-byte NQuin.
49pub fn pack_botany_metamer_quin(
50    plant_did: u64,
51    world_did: u64,
52    organ_type: u8,
53    active_pipes: u16,
54    retired_pipes: u16,
55    lamport: u32,
56) -> NQuin {
57    let subject = plant_did;
58    let predicate = (0x424F_5441_4E59_4D45u64 << 8) | (OP_BOTANY_METAMER as u64); // "BOTANYME"
59    let object = ((organ_type as u64) << 32) | ((active_pipes as u64) << 16) | (retired_pipes as u64);
60    let context = world_did;
61    let metadata = ((lamport as u64 & 0x1FFF_FFFF) << 32) | (active_pipes as u64 & 0xFFFF);
62    let parity = subject ^ predicate ^ object ^ context;
63
64    NQuin {
65        subject,
66        predicate,
67        object,
68        context,
69        metadata,
70        parity,
71    }
72}
73
74/// Packs cellular turgor pressure into an NQuin.
75pub fn pack_botany_turgor_quin(
76    plant_did: u64,
77    world_did: u64,
78    turgor_kpa: u16,
79    water_potential_kpa: i16,
80    lamport: u32,
81) -> NQuin {
82    let subject = plant_did;
83    let predicate = (0x424F_5441_4E59_5455u64 << 8) | (OP_BOTANY_TURGOR as u64); // "BOTANYTU"
84    let object = ((turgor_kpa as u64) << 16) | ((water_potential_kpa as u16) as u64);
85    let context = world_did;
86    let metadata = ((lamport as u64 & 0x1FFF_FFFF) << 32) | (turgor_kpa as u64);
87    let parity = subject ^ predicate ^ object ^ context;
88
89    NQuin {
90        subject,
91        predicate,
92        object,
93        context,
94        metadata,
95        parity,
96    }
97}
98
99/// Packs thermal phenology GDD into an NQuin.
100pub fn pack_botany_phenology_quin(
101    plant_did: u64,
102    world_did: u64,
103    accumulated_gdd: f32,
104    chilling_hours: f32,
105    lamport: u32,
106) -> NQuin {
107    let subject = plant_did;
108    let predicate = (0x424F_5441_4E59_5048u64 << 8) | (OP_BOTANY_PHENOLOGY as u64); // "BOTANYPH"
109    let gdd_u32 = (accumulated_gdd.max(0.0) * 10.0) as u32; // 0.1 degree-day precision
110    let chill_u32 = (chilling_hours.max(0.0) * 10.0) as u32;
111    let object = ((gdd_u32 as u64) << 32) | (chill_u32 as u64);
112    let context = world_did;
113    let metadata = (lamport as u64 & 0x1FFF_FFFF) << 32;
114    let parity = subject ^ predicate ^ object ^ context;
115
116    NQuin {
117        subject,
118        predicate,
119        object,
120        context,
121        metadata,
122        parity,
123    }
124}
125
126/// Unpacks a metamer Quin returning `(organ_type, active_pipes, retired_pipes)`.
127#[inline]
128pub fn unpack_botany_metamer_quin(quin: &NQuin) -> Option<(u8, u16, u16)> {
129    let opcode = (quin.predicate & 0xFF) as u8;
130    if opcode == OP_BOTANY_METAMER {
131        let organ = ((quin.object >> 32) & 0xFF) as u8;
132        let active = ((quin.object >> 16) & 0xFFFF) as u16;
133        let retired = (quin.object & 0xFFFF) as u16;
134        Some((organ, active, retired))
135    } else {
136        None
137    }
138}
139
140/// Unpacks a turgor Quin returning `turgor_kpa`.
141#[inline]
142pub fn unpack_botany_turgor_quin(quin: &NQuin) -> Option<u16> {
143    let opcode = (quin.predicate & 0xFF) as u8;
144    if opcode == OP_BOTANY_TURGOR {
145        let turgor = ((quin.object >> 16) & 0xFFFF) as u16;
146        Some(turgor)
147    } else {
148        None
149    }
150}
151
152/// Evaluates a frame of botanical Quins, outputting zero-alloc verdicts.
153pub fn evaluate_botanical_frame(
154    quins: &[NQuin],
155    plant_did: u64,
156    out: &mut [BotanyVerdict],
157) -> Result<usize, BotanyError> {
158    let mut count = 0;
159
160    for q in quins {
161        if plant_did != 0 && q.subject != plant_did {
162            continue;
163        }
164
165        let opcode = (q.predicate & 0xFF) as u8;
166        if opcode < OP_BOTANY_METAMER || opcode > OP_BOTANY_RAUNKIAER {
167            continue;
168        }
169
170        if count >= out.len() {
171            return Err(BotanyError::BufferOverflow);
172        }
173
174        let mut verdict = BotanyVerdict {
175            claim: *q,
176            organ_type: 0,
177            active_pipes: 0,
178            turgor_kpa: 0,
179            accumulated_gdd: 0.0,
180            is_dieback_active: false,
181        };
182
183        match opcode {
184            OP_BOTANY_METAMER => {
185                if let Some((organ, active, _retired)) = unpack_botany_metamer_quin(q) {
186                    verdict.organ_type = organ;
187                    verdict.active_pipes = active;
188                }
189            }
190            OP_BOTANY_TURGOR => {
191                if let Some(turgor) = unpack_botany_turgor_quin(q) {
192                    verdict.turgor_kpa = turgor;
193                }
194            }
195            OP_BOTANY_PHENOLOGY => {
196                let gdd_raw = (q.object >> 32) as u32;
197                verdict.accumulated_gdd = (gdd_raw as f32) / 10.0;
198            }
199            OP_BOTANY_RAUNKIAER => {
200                let dieback = (q.object & 0x1) != 0;
201                verdict.is_dieback_active = dieback;
202            }
203            _ => {}
204        }
205
206        out[count] = verdict;
207        count += 1;
208    }
209
210    Ok(count)
211}
212
213#[cfg(test)]
214mod tests {
215    use super::*;
216
217    #[test]
218    fn test_metamer_quin_roundtrip() {
219        let plant_did = 0x1234_5678_9ABC_DEF0;
220        let world_did = 0x9999_8888_7777_6666;
221        let quin = pack_botany_metamer_quin(plant_did, world_did, 2, 42, 108, 12);
222
223        assert_eq!((quin.predicate & 0xFF) as u8, OP_BOTANY_METAMER);
224        let unpacked = unpack_botany_metamer_quin(&quin).unwrap();
225        assert_eq!(unpacked, (2, 42, 108));
226
227        // Parity ECC check
228        let parity = quin.subject ^ quin.predicate ^ quin.object ^ quin.context;
229        assert_eq!(quin.parity, parity);
230    }
231
232    #[test]
233    fn test_botanical_frame_evaluator() {
234        let plant_did = 0xAAAA_BBBB_CCCC_DDDD;
235        let world_did = 0x1111_2222_3333_4444;
236
237        let q1 = pack_botany_metamer_quin(plant_did, world_did, 4, 15, 30, 1);
238        let q2 = pack_botany_turgor_quin(plant_did, world_did, 1200, -800, 2);
239        let q3 = pack_botany_phenology_quin(plant_did, world_did, 850.5, 420.0, 3);
240
241        let quins = [q1, q2, q3];
242        let mut verdicts = [BotanyVerdict {
243            claim: q1,
244            organ_type: 0,
245            active_pipes: 0,
246            turgor_kpa: 0,
247            accumulated_gdd: 0.0,
248            is_dieback_active: false,
249        }; 8];
250
251        let count = evaluate_botanical_frame(&quins, plant_did, &mut verdicts).unwrap();
252        assert_eq!(count, 3);
253        assert_eq!(verdicts[0].organ_type, 4);
254        assert_eq!(verdicts[0].active_pipes, 15);
255        assert_eq!(verdicts[1].turgor_kpa, 1200);
256        assert!((verdicts[2].accumulated_gdd - 850.5).abs() < 0.2);
257    }
258}