Skip to main content

qualia_core_db/render/scene_graph/
ontology_binding.rs

1//! `.10d` `EONT1` Living Ontology & Affordance Scene-Graph Binding (`ontology_binding.rs`).
2//!
3//! Bridges [`EntityOntologyMiniHeader`], [`AffordanceBinaryRecord`], and
4//! [`DevelopmentalKeyframeRecord`] from `container_10d::entity_ontology_section` and
5//! [`evaluate_allometric_dimension`] from `container_10d::procedural_synthesis` directly into
6//! [`SceneNodeRecord`].
7//!
8//! All evaluation functions are strictly `HotZeroHeap` (zero heap allocations).
9
10use crate::container_10d::entity_ontology_section::{
11    AffordanceBinaryRecord, DevelopmentalKeyframeRecord, EntityOntologyMiniHeader,
12};
13use crate::container_10d::procedural_synthesis::evaluate_allometric_dimension;
14use crate::entity_view::entity_ontologies::LifecycleStage;
15use crate::render::scene_graph::pool::SceneNodeRecord;
16
17/// Ontogenetic developmental lifecycle stage of a living `.10d` entity.
18#[repr(u8)]
19#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
20pub enum DevelopmentalStage {
21    /// Dormant seed, spore, or egg.
22    SeedOrSpore = 0,
23    /// Growing seedling, sapling, or juvenile organism.
24    Juvenile = 1,
25    /// Morphologically mature adult organism.
26    #[default]
27    Adult = 2,
28    /// Post-reproductive senescent stage.
29    Senescent = 3,
30    /// Deceased / decomposing snags or remains.
31    Deceased = 4,
32}
33
34impl DevelopmentalStage {
35    /// Converts a raw `u8` stage code into a [`DevelopmentalStage`].
36    #[inline]
37    pub const fn from_u8(raw: u8) -> Self {
38        match raw {
39            0 => Self::SeedOrSpore,
40            1 => Self::Juvenile,
41            2 => Self::Adult,
42            3 => Self::Senescent,
43            4 => Self::Deceased,
44            _ => Self::Adult,
45        }
46    }
47
48    /// Converts from the general [`LifecycleStage`] enum.
49    #[inline]
50    pub const fn from_lifecycle_stage(stage: LifecycleStage) -> Self {
51        match stage {
52            LifecycleStage::SeedOrSpore => Self::SeedOrSpore,
53            LifecycleStage::Juvenile => Self::Juvenile,
54            LifecycleStage::Adult | LifecycleStage::Manufactured | LifecycleStage::Operational => {
55                Self::Adult
56            }
57            LifecycleStage::Senescent | LifecycleStage::Degraded => Self::Senescent,
58            LifecycleStage::Deceased | LifecycleStage::Decommissioned => Self::Deceased,
59        }
60    }
61}
62
63/// Live runtime metabolic and ontogenetic state bound to a scene node via `EONT1`.
64#[repr(C)]
65#[derive(Clone, Copy, Debug, PartialEq)]
66pub struct LivingOntologyState {
67    /// Current developmental stage.
68    pub stage: DevelopmentalStage,
69    /// Normalized ontogenetic growth progress in `[0.0, 1.0]`.
70    pub growth_progress_01: f32,
71    /// Current age in days since germination/birth.
72    pub age_days: f32,
73    /// Internal energy / biomass reserve in permill (`0..=1000`).
74    pub energy_permill: u16,
75    /// Physical or structural damage in permill (`0..=1000`).
76    pub damage_permill: u16,
77    /// Cellular hydration / turgor pressure in permill (`0..=1000`).
78    pub hydration_permill: u16,
79    /// Accumulated mechanical wear in permill (`0..=1000`).
80    pub wear_permill: u16,
81    /// Active behavioral state identifier.
82    pub active_state_id: u32,
83    /// Huxley allometric base constant $b$ ($y = b \cdot x^k$).
84    pub allometry_base_b: f32,
85    /// Huxley allometric power exponent $k$ ($y = b \cdot x^k$).
86    pub allometry_exponent_k: f32,
87}
88
89impl Default for LivingOntologyState {
90    #[inline]
91    fn default() -> Self {
92        Self {
93            stage: DevelopmentalStage::Adult,
94            growth_progress_01: 1.0,
95            age_days: 365.0,
96            energy_permill: 1000,
97            damage_permill: 0,
98            hydration_permill: 1000,
99            wear_permill: 0,
100            active_state_id: 0,
101            allometry_base_b: 1.0,
102            allometry_exponent_k: 1.0,
103        }
104    }
105}
106
107impl LivingOntologyState {
108    /// Initializes a live state directly from a decoded `.10d` [`EntityOntologyMiniHeader`].
109    #[inline]
110    pub const fn from_mini_header(header: &EntityOntologyMiniHeader) -> Self {
111        let stage = DevelopmentalStage::from_u8(header.stage);
112        let progress = match stage {
113            DevelopmentalStage::SeedOrSpore => 0.10,
114            DevelopmentalStage::Juvenile => 0.45,
115            DevelopmentalStage::Adult => 1.0,
116            DevelopmentalStage::Senescent => 0.95,
117            DevelopmentalStage::Deceased => 0.85,
118        };
119        Self {
120            stage,
121            growth_progress_01: progress,
122            age_days: progress * 365.0,
123            energy_permill: header.energy_permill,
124            damage_permill: header.damage_permill,
125            hydration_permill: header.hydration_permill,
126            wear_permill: header.wear_permill,
127            active_state_id: header.stage as u32,
128            allometry_base_b: 1.0,
129            allometry_exponent_k: 1.0,
130        }
131    }
132}
133
134/// Interpolated ontogenetic keyframe scales `(crown_scale, trunk_scale, lai_multiplier, mesh_asset_hash)`.
135#[inline]
136pub fn interpolate_ontogenetic_scales(
137    keyframes: &[DevelopmentalKeyframeRecord],
138    growth_progress_01: f32,
139) -> (f32, f32, f32, u64) {
140    if keyframes.is_empty() {
141        let p = growth_progress_01.clamp(0.05, 1.5);
142        return (p, p, p, 0);
143    }
144    if keyframes.len() == 1 {
145        let k = &keyframes[0];
146        return (
147            k.allometric_crown_scale,
148            k.allometric_trunk_scale,
149            k.lai_multiplier,
150            k.mesh_asset_hash,
151        );
152    }
153
154    let p = growth_progress_01.clamp(0.0, 1.0);
155    let first_age = keyframes[0].age_days;
156    let last_age = keyframes[keyframes.len() - 1]
157        .age_days
158        .max(first_age + 1e-4);
159    let target_age = first_age + p * (last_age - first_age);
160
161    let mut idx = 0usize;
162    while idx + 1 < keyframes.len() && keyframes[idx + 1].age_days < target_age {
163        idx += 1;
164    }
165
166    if idx + 1 >= keyframes.len() {
167        let k = &keyframes[keyframes.len() - 1];
168        return (
169            k.allometric_crown_scale,
170            k.allometric_trunk_scale,
171            k.lai_multiplier,
172            k.mesh_asset_hash,
173        );
174    }
175
176    let k0 = &keyframes[idx];
177    let k1 = &keyframes[idx + 1];
178    let span = (k1.age_days - k0.age_days).max(1e-5);
179    let t = ((target_age - k0.age_days) / span).clamp(0.0, 1.0);
180
181    let crown =
182        k0.allometric_crown_scale + t * (k1.allometric_crown_scale - k0.allometric_crown_scale);
183    let trunk =
184        k0.allometric_trunk_scale + t * (k1.allometric_trunk_scale - k0.allometric_trunk_scale);
185    let lai = k0.lai_multiplier + t * (k1.lai_multiplier - k0.lai_multiplier);
186    let mesh_hash = if t < 0.5 {
187        k0.mesh_asset_hash
188    } else {
189        k1.mesh_asset_hash
190    };
191
192    (crown, trunk, lai, mesh_hash)
193}
194
195/// Applies `.10d` `EONT1` ontogenetic keyframe interpolation and Huxley power-law allometry
196/// ($y = b \cdot x^k$) directly to `node.local_scale`, stamping `node.changed_tick`.
197#[inline]
198pub fn apply_ontogenetic_allometry(
199    node: &mut SceneNodeRecord,
200    state: &LivingOntologyState,
201    _header: &EntityOntologyMiniHeader,
202    keyframes: &[DevelopmentalKeyframeRecord],
203    current_tick: u32,
204) {
205    let (crown_kf, trunk_kf, _lai_kf, _mesh_hash) =
206        interpolate_ontogenetic_scales(keyframes, state.growth_progress_01);
207
208    let huxley_factor = evaluate_allometric_dimension(
209        state.growth_progress_01.max(0.05),
210        state.allometry_base_b.max(0.05),
211        state.allometry_exponent_k.max(0.1),
212    );
213
214    // Turgor/hydration factor: severe dehydration (< 300‰) causes slight crown droop.
215    let hydration_factor = if state.hydration_permill < 300 {
216        0.85 + 0.15 * (state.hydration_permill as f32 / 300.0)
217    } else {
218        1.0
219    };
220
221    let radial_scale = (trunk_kf * huxley_factor).max(0.01);
222    let vertical_scale = (crown_kf * huxley_factor * hydration_factor).max(0.01);
223
224    node.local_scale = [radial_scale, vertical_scale, radial_scale];
225    node.changed_tick = current_tick;
226}
227
228/// Outcome returned when a deontic- and capability-gated `.10d` affordance is dispatched.
229#[repr(C)]
230#[derive(Clone, Copy, Debug, PartialEq)]
231pub struct AffordanceDispatchOutcome {
232    /// Action identifier hash that was triggered.
233    pub action_id: u64,
234    /// Topic hash emitted to the semantic journal.
235    pub emitted_topic_hash: u64,
236    /// Skeletal/procedural animation clip ID triggered (`0` = none).
237    pub animation_clip_id: u32,
238    /// New behavioral state ID transitioned into.
239    pub target_state_id: u32,
240    /// Physical impulse magnitude generated by the affordance.
241    pub impulse_magnitude: f32,
242    /// Updated energy permill (`0..=1000`).
243    pub energy_permill: u16,
244    /// Updated damage permill (`0..=1000`).
245    pub damage_permill: u16,
246    /// Updated hydration permill (`0..=1000`).
247    pub hydration_permill: u16,
248    /// Updated wear permill (`0..=1000`).
249    pub wear_permill: u16,
250}
251
252/// Evaluates and dispatches a matching [`AffordanceBinaryRecord`] against `state`.
253///
254/// Enforces:
255/// 1. `deontic_permitted == true`,
256/// 2. `actor_capability_mask` satisfies `required_capability_hash` (when non-zero),
257/// 3. Metabolic preconditions (`min_energy_permill`, `max_damage_permill`, `min_hydration_permill`, `max_wear_permill`).
258#[inline]
259pub fn dispatch_affordance(
260    state: &mut LivingOntologyState,
261    affordances: &[AffordanceBinaryRecord],
262    trigger_predicate_hash: u64,
263    actor_capability_mask: u32,
264    deontic_permitted: bool,
265) -> Option<AffordanceDispatchOutcome> {
266    if !deontic_permitted {
267        return None;
268    }
269
270    let mut i = 0usize;
271    while i < affordances.len() {
272        let rec = &affordances[i];
273        if rec.action_id == trigger_predicate_hash {
274            // 1. Check capability mask against required capability hash
275            if rec.required_capability_hash != 0 {
276                let req_mask = (rec.required_capability_hash & 0xFFFF_FFFF) as u32;
277                if (actor_capability_mask & req_mask) != req_mask {
278                    return None;
279                }
280            }
281
282            // 2. Check metabolic & structural preconditions
283            if state.energy_permill < rec.min_energy_permill
284                || state.damage_permill > rec.max_damage_permill
285                || state.hydration_permill < rec.min_hydration_permill
286                || state.wear_permill > rec.max_wear_permill
287            {
288                return None;
289            }
290
291            // 3. Apply metabolic state transitions
292            state.energy_permill =
293                ((state.energy_permill as i32) + (rec.energy_delta as i32)).clamp(0, 1000) as u16;
294            state.damage_permill =
295                ((state.damage_permill as i32) + (rec.damage_delta as i32)).clamp(0, 1000) as u16;
296            state.hydration_permill = ((state.hydration_permill as i32)
297                + (rec.hydration_delta as i32))
298                .clamp(0, 1000) as u16;
299            state.wear_permill =
300                ((state.wear_permill as i32) + (rec.wear_delta as i32)).clamp(0, 1000) as u16;
301
302            if state.damage_permill >= 1000 {
303                state.stage = DevelopmentalStage::Deceased;
304            } else if state.damage_permill >= 750 {
305                state.stage = DevelopmentalStage::Senescent;
306            }
307
308            let target_state_id = if rec.reserved_u16 != 0 {
309                rec.reserved_u16 as u32
310            } else {
311                (rec.category as u32) + 1
312            };
313            state.active_state_id = target_state_id;
314
315            let impulse_magnitude = ((rec.damage_delta.unsigned_abs() as f32) * 0.5
316                + (rec.energy_delta.unsigned_abs() as f32) * 0.1)
317                .max(1.0);
318
319            return Some(AffordanceDispatchOutcome {
320                action_id: rec.action_id,
321                emitted_topic_hash: rec.emitted_topic_hash,
322                animation_clip_id: rec.animation_clip_id,
323                target_state_id,
324                impulse_magnitude,
325                energy_permill: state.energy_permill,
326                damage_permill: state.damage_permill,
327                hydration_permill: state.hydration_permill,
328                wear_permill: state.wear_permill,
329            });
330        }
331        i += 1;
332    }
333
334    None
335}
336
337#[cfg(test)]
338mod tests {
339    use super::*;
340    use crate::container_10d::entity_ontology_section::MAGIC_EONT;
341    use crate::render::scene_graph::pool::NodeKind;
342
343    #[test]
344    fn ontogenetic_allometry_scales_node_and_stamps_tick() {
345        let header = EntityOntologyMiniHeader {
346            magic: MAGIC_EONT,
347            version: 1,
348            stage: DevelopmentalStage::Juvenile as u8,
349            reserved_u8: 0,
350            entity_did_hash: 0x1234,
351            taxon_iri_hash: 0x5678,
352            energy_permill: 900,
353            damage_permill: 0,
354            hydration_permill: 900,
355            wear_permill: 0,
356            affordance_count: 0,
357            reserved_u32: 0,
358        };
359        let mut state = LivingOntologyState::from_mini_header(&header);
360        state.growth_progress_01 = 0.5;
361        state.allometry_base_b = 1.0;
362        state.allometry_exponent_k = 1.0;
363
364        let keyframes = [
365            DevelopmentalKeyframeRecord {
366                age_days: 0.0,
367                stage: 0,
368                reserved_u8: 0,
369                reserved_u16: 0,
370                allometric_crown_scale: 0.2,
371                allometric_trunk_scale: 0.2,
372                lai_multiplier: 0.1,
373                reserved_u32: 0,
374                mesh_asset_hash: 1,
375            },
376            DevelopmentalKeyframeRecord {
377                age_days: 100.0,
378                stage: 2,
379                reserved_u8: 0,
380                reserved_u16: 0,
381                allometric_crown_scale: 1.0,
382                allometric_trunk_scale: 0.8,
383                lai_multiplier: 1.0,
384                reserved_u32: 0,
385                mesh_asset_hash: 2,
386            },
387        ];
388
389        let mut node = SceneNodeRecord::new(0x1234, NodeKind::MeshBRep);
390        apply_ontogenetic_allometry(&mut node, &state, &header, &keyframes, 77);
391
392        assert_eq!(node.changed_tick, 77);
393        assert!((node.local_scale[0] - 0.25).abs() < 1e-4);
394        assert!((node.local_scale[1] - 0.30).abs() < 1e-4);
395    }
396
397    #[test]
398    fn affordance_dispatch_enforces_deontic_and_capability_gates() {
399        let mut state = LivingOntologyState::default();
400        let affordances = [AffordanceBinaryRecord {
401            action_id: 0xCAFE,
402            required_capability_hash: 0b0101,
403            emitted_topic_hash: 0xBEEF,
404            category: 3,
405            min_observer_status: 0,
406            min_energy_permill: 200,
407            max_damage_permill: 800,
408            min_hydration_permill: 100,
409            max_wear_permill: 900,
410            energy_delta: -150,
411            damage_delta: 40,
412            hydration_delta: -50,
413            wear_delta: 25,
414            reserved_u16: 9,
415            animation_clip_id: 14,
416        }];
417
418        // Denied when deontic_permitted is false.
419        assert!(dispatch_affordance(&mut state, &affordances, 0xCAFE, 0b0111, false).is_none());
420
421        // Denied when actor lacks capability bit.
422        assert!(dispatch_affordance(&mut state, &affordances, 0xCAFE, 0b0001, true).is_none());
423
424        // Permitted when both deontic and capability gates pass.
425        let outcome = dispatch_affordance(&mut state, &affordances, 0xCAFE, 0b0111, true).unwrap();
426        assert_eq!(outcome.action_id, 0xCAFE);
427        assert_eq!(outcome.emitted_topic_hash, 0xBEEF);
428        assert_eq!(outcome.animation_clip_id, 14);
429        assert_eq!(outcome.target_state_id, 9);
430        assert_eq!(state.energy_permill, 850);
431        assert_eq!(state.damage_permill, 40);
432        assert_eq!(state.hydration_permill, 950);
433        assert_eq!(state.wear_permill, 25);
434    }
435}