Skip to main content

qualia_core_db/governance/
cell_graph.rs

1//! Cellular Logic Graph Partitioning & Routing Kernel (WP-3.2).
2//!
3//! Partitions continuous hypermedia / simulation space into a topological
4//! network of independent logical cells.
5//!
6//! ### The 42 MiB Sentinel Contract
7//! - Each active cell executes its deterministic rules within its own
8//!   isolated 42 MiB `SlgArena` (917,504 `NQuin` capacity).
9//! - Cross-cell communication is strictly routed through Permissive Routing Lanes:
10//!   - `Spatial` (`0b11`): Proximity broadcasts, physical collisions, neighbor notifications.
11//!   - `Commons` (`0b01`): Ecological balances, shared stewardship rules, resource flows.
12//! - Cold geometry, high-resolution heightfields, and manifold weights live outside
13//!   in the decoupled 512 MiB caller-budgeted tier.
14
15use crate::{NQuin, PermissiveRoutingLane};
16use serde::{Deserialize, Serialize};
17
18/// Maximum adjacent topological neighbor cells tracked per cell.
19pub const MAX_CELL_NEIGHBORS: usize = 8;
20/// Maximum pending inter-cell routing messages per frame.
21pub const MAX_INTER_CELL_MESSAGES: usize = 64;
22
23/// Unique 64-bit topological identifier for a spatial cell.
24#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
25pub struct CellId(pub u64);
26
27/// Spatial descriptor of a logical cell in the world graph.
28#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
29pub struct LogicalCellDescriptor {
30    pub id: CellId,
31    pub name: String,
32    pub center_x: f64,
33    pub center_z: f64,
34    pub radius_meters: f64,
35    pub neighbor_count: usize,
36    pub neighbors: [CellId; MAX_CELL_NEIGHBORS],
37    pub is_active: bool,
38    pub resident_quin_count: u32,
39}
40
41/// An inter-cell message routed across logical cells via Permissive Routing Lanes.
42#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
43pub struct InterCellMessage {
44    pub source_cell_id: u64,
45    pub target_cell_id: u64,
46    pub lane_bits: u8,
47    pub reserved_u8: u8,
48    pub payload_kind: u16,
49    pub reserved_u32: u32,
50    pub quin: NQuin,
51}
52
53/// Manager tracking the topological network of 42 MiB cellular logical units.
54#[derive(Debug, Clone, Default, Serialize, Deserialize)]
55pub struct CellularLogicGraph {
56    pub cells: Vec<LogicalCellDescriptor>,
57    pub message_queue: Vec<InterCellMessage>,
58}
59
60impl CellularLogicGraph {
61    /// Creates a default `CellularLogicGraph`.
62    pub fn new() -> Self {
63        Self {
64            cells: Vec::new(),
65            message_queue: Vec::new(),
66        }
67    }
68
69    /// Register a new logical cell in the graph.
70    pub fn register_cell(
71        &mut self,
72        id: CellId,
73        name: impl Into<String>,
74        center_x: f64,
75        center_z: f64,
76        radius_meters: f64,
77    ) -> usize {
78        let descriptor = LogicalCellDescriptor {
79            id,
80            name: name.into(),
81            center_x,
82            center_z,
83            radius_meters,
84            neighbor_count: 0,
85            neighbors: [CellId(0); MAX_CELL_NEIGHBORS],
86            is_active: false,
87            resident_quin_count: 0,
88        };
89        let idx = self.cells.len();
90        self.cells.push(descriptor);
91        idx
92    }
93
94    /// Link two cells as topological neighbors.
95    pub fn link_neighbors(&mut self, a: CellId, b: CellId) -> bool {
96        let pos_a = self.cells.iter().position(|c| c.id == a);
97        let pos_b = self.cells.iter().position(|c| c.id == b);
98        if let (Some(ia), Some(ib)) = (pos_a, pos_b) {
99            let ca = &mut self.cells[ia];
100            if ca.neighbor_count < MAX_CELL_NEIGHBORS
101                && !ca.neighbors[..ca.neighbor_count].contains(&b)
102            {
103                ca.neighbors[ca.neighbor_count] = b;
104                ca.neighbor_count += 1;
105            }
106            let cb = &mut self.cells[ib];
107            if cb.neighbor_count < MAX_CELL_NEIGHBORS
108                && !cb.neighbors[..cb.neighbor_count].contains(&a)
109            {
110                cb.neighbors[cb.neighbor_count] = a;
111                cb.neighbor_count += 1;
112            }
113            true
114        } else {
115            false
116        }
117    }
118
119    /// Enqueue an inter-cell routing message. Enforces valid PermissiveRoutingLane bits.
120    pub fn route_message(&mut self, msg: InterCellMessage) -> bool {
121        if self.message_queue.len() >= MAX_INTER_CELL_MESSAGES {
122            return false;
123        }
124        // Verify lane is either SpatiotemporalAmbiguous (11) or Commons (01)
125        if msg.lane_bits != PermissiveRoutingLane::SpatiotemporalAmbiguous as u8
126            && msg.lane_bits != PermissiveRoutingLane::EnforcePermissiveCommons as u8
127        {
128            return false;
129        }
130        self.message_queue.push(msg);
131        true
132    }
133
134    /// Drain pending messages destined for a specific cell.
135    pub fn drain_messages_for(&mut self, target_cell: CellId) -> Vec<InterCellMessage> {
136        let mut target_messages = Vec::new();
137        let mut remaining = Vec::with_capacity(self.message_queue.len());
138        for msg in self.message_queue.drain(..) {
139            if msg.target_cell_id == target_cell.0 {
140                target_messages.push(msg);
141            } else {
142                remaining.push(msg);
143            }
144        }
145        self.message_queue = remaining;
146        target_messages
147    }
148}
149
150#[cfg(test)]
151mod tests {
152    use super::*;
153
154    #[test]
155    fn test_cellular_graph_topology_and_routing() {
156        let mut graph = CellularLogicGraph::new();
157        let kestrel = CellId(101);
158        let saltwind = CellId(102);
159
160        graph.register_cell(kestrel, "Kestrel Flats", 0.0, 0.0, 150.0);
161        graph.register_cell(saltwind, "Saltwind Reach", 300.0, 50.0, 200.0);
162        assert!(graph.link_neighbors(kestrel, saltwind));
163
164        let msg = InterCellMessage {
165            source_cell_id: kestrel.0,
166            target_cell_id: saltwind.0,
167            lane_bits: PermissiveRoutingLane::SpatiotemporalAmbiguous as u8,
168            reserved_u8: 0,
169            payload_kind: 1,
170            reserved_u32: 0,
171            quin: NQuin::default(),
172        };
173
174        assert!(graph.route_message(msg));
175        let delivered = graph.drain_messages_for(saltwind);
176        assert_eq!(delivered.len(), 1);
177        assert_eq!(delivered[0].source_cell_id, kestrel.0);
178        assert!(graph.message_queue.is_empty());
179    }
180}