qualia_core_db/governance/
cell_graph.rs1use crate::{NQuin, PermissiveRoutingLane};
16use serde::{Deserialize, Serialize};
17
18pub const MAX_CELL_NEIGHBORS: usize = 8;
20pub const MAX_INTER_CELL_MESSAGES: usize = 64;
22
23#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
25pub struct CellId(pub u64);
26
27#[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#[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#[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 pub fn new() -> Self {
63 Self {
64 cells: Vec::new(),
65 message_queue: Vec::new(),
66 }
67 }
68
69 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 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 pub fn route_message(&mut self, msg: InterCellMessage) -> bool {
121 if self.message_queue.len() >= MAX_INTER_CELL_MESSAGES {
122 return false;
123 }
124 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 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}