1use crate::{q_hash, NQuin};
13
14pub const PRED_GEO_HAS_VERTEX: u64 = q_hash("geo:hasVertex");
16pub const PRED_GEO_HAS_PACKED_CENTROID: u64 = q_hash("geo:hasPackedCentroid");
17pub const PRED_GEO_HAS_PACKED_BBOX_MIN: u64 = q_hash("geo:hasPackedBboxMin");
18pub const PRED_GEO_HAS_PACKED_BBOX_MAX: u64 = q_hash("geo:hasPackedBboxMax");
19pub const PRED_GEO_HAS_SCALE_TIER: u64 = q_hash("geo:hasScaleTier");
20pub const PRED_GEO_HAS_TOPOLOGY_CLASS: u64 = q_hash("geo:hasTopologyClass");
21pub const PRED_GEO_HAS_PORTAL_LINK: u64 = q_hash("geo:hasPortalLink");
22
23pub const PRED_Q42_HAS_CONTAINER_10D: u64 = q_hash("q42:hasContainer10d");
25pub const PRED_Q42_HAS_M64_CHUNK: u64 = q_hash("q42:hasM64Chunk");
26pub const PRED_Q42_HAS_EMF_CHUNK: u64 = q_hash("q42:hasEmfChunk");
27pub const PRED_Q42_HAS_SPECTRAL_SHEET_V3: u64 = q_hash("q42:hasSpectralSheetV3");
28pub const PRED_Q42_HAS_HMC_BUNDLE: u64 = q_hash("q42:hasHmcBundle");
29pub const PRED_Q42_HAS_CLUSTER_DAG: u64 = q_hash("q42:hasClusterDag");
30
31pub const PRED_KIN_HAS_PGA_MOTOR: u64 = q_hash("kin:hasPgaMotor");
33pub const PRED_KIN_HAS_JOINT_PARENT: u64 = q_hash("kin:hasJointParent");
34pub const PBIO_HAS_HILL_MUSCLE_ALIAS: u64 = q_hash("bio:hasHillMuscle");
35pub const PRED_BIO_HAS_HILL_MUSCLE: u64 = PBIO_HAS_HILL_MUSCLE_ALIAS;
36pub const PRED_BIO_HAS_ALLOMETRIC_LAW: u64 = q_hash("bio:hasAllometricLaw");
37pub const PRED_MECH_HAS_FATIGUE_LAW: u64 = q_hash("mech:hasFatigueLaw");
38pub const PRED_PHYS_HAS_BOND_PORT: u64 = q_hash("phys:hasBondPort");
39
40pub const PRED_SENS_HAS_HOA_ORDER: u64 = q_hash("sens:hasHoaOrder");
42pub const PRED_SENS_HAS_SOFA_HRTF: u64 = q_hash("sens:hasSofaHrtf");
43pub const PRED_SENS_HAS_STOKES_VECTOR: u64 = q_hash("sens:hasStokesVector");
44pub const PRED_SENS_HAS_REFRACTIVE_INDEX: u64 = q_hash("sens:hasRefractiveIndex");
45
46pub const PRED_EPI_HAS_QUANTUM_RANGE: u64 = q_hash("epi:hasQuantumRange");
48pub const PRED_EPI_HAS_BIFURCATION_WING: u64 = q_hash("epi:hasBifurcationWing");
49pub const PRED_EPI_HAS_CONSENT_RECEIPT: u64 = q_hash("epi:hasConsentReceipt");
50
51pub const PRED_LLM_HAS_KV_SLOT: u64 = q_hash("llm:hasKvSlot");
53pub const PRED_LLM_HAS_SPARSE_ATOM_CODE: u64 = q_hash("llm:hasSparseAtomCode");
54
55pub const ALL_SPATIAL_SENSORY_PREDICATES: [u64; 28] = [
57 PRED_GEO_HAS_VERTEX,
58 PRED_GEO_HAS_PACKED_CENTROID,
59 PRED_GEO_HAS_PACKED_BBOX_MIN,
60 PRED_GEO_HAS_PACKED_BBOX_MAX,
61 PRED_GEO_HAS_SCALE_TIER,
62 PRED_GEO_HAS_TOPOLOGY_CLASS,
63 PRED_GEO_HAS_PORTAL_LINK,
64 PRED_Q42_HAS_CONTAINER_10D,
65 PRED_Q42_HAS_M64_CHUNK,
66 PRED_Q42_HAS_EMF_CHUNK,
67 PRED_Q42_HAS_SPECTRAL_SHEET_V3,
68 PRED_Q42_HAS_HMC_BUNDLE,
69 PRED_Q42_HAS_CLUSTER_DAG,
70 PRED_KIN_HAS_PGA_MOTOR,
71 PRED_KIN_HAS_JOINT_PARENT,
72 PRED_BIO_HAS_HILL_MUSCLE,
73 PRED_BIO_HAS_ALLOMETRIC_LAW,
74 PRED_MECH_HAS_FATIGUE_LAW,
75 PRED_PHYS_HAS_BOND_PORT,
76 PRED_SENS_HAS_HOA_ORDER,
77 PRED_SENS_HAS_SOFA_HRTF,
78 PRED_SENS_HAS_STOKES_VECTOR,
79 PRED_SENS_HAS_REFRACTIVE_INDEX,
80 PRED_EPI_HAS_QUANTUM_RANGE,
81 PRED_EPI_HAS_BIFURCATION_WING,
82 PRED_EPI_HAS_CONSENT_RECEIPT,
83 PRED_LLM_HAS_KV_SLOT,
84 PRED_LLM_HAS_SPARSE_ATOM_CODE,
85];
86
87#[inline]
91pub fn scale_tier_step_meters(tier: u8) -> f32 {
92 match tier {
93 0 => 0.001, 1 => 1.0e-9, 2 => 1.0e-6, 3 => 1.0, 4 => 1.0e3, 5 => 1.0e6, 6 => 1.496e11, 7 => 3.0857e16, _ => 0.001,
102 }
103}
104
105#[inline]
106fn sign_extend_20(v: u32) -> i32 {
107 let v = v & 0xF_FFFF;
108 if (v & 0x8_0000) != 0 {
109 (v | !0xF_FFFF) as i32
110 } else {
111 v as i32
112 }
113}
114
115#[inline]
117pub fn pack_coord_with_scale(x: f32, y: f32, z: f32, scale_tier: u8) -> u64 {
118 let step = scale_tier_step_meters(scale_tier);
119 let xi = ((x / step).round() as i64) & 0xF_FFFF;
120 let yi = ((y / step).round() as i64) & 0xF_FFFF;
121 let zi = ((z / step).round() as i64) & 0xF_FFFF;
122 let tier_bits = (scale_tier as u64 & 0x7) << 60;
123 tier_bits | ((xi as u64) << 40) | ((yi as u64) << 20) | (zi as u64)
124}
125
126#[inline]
128pub fn unpack_coord_with_scale(object: u64) -> (f32, f32, f32, u8) {
129 let tier = ((object >> 60) & 0x7) as u8;
130 let xi = sign_extend_20(((object >> 40) & 0xF_FFFF) as u32);
131 let yi = sign_extend_20(((object >> 20) & 0xF_FFFF) as u32);
132 let zi = sign_extend_20((object & 0xF_FFFF) as u32);
133 let step = scale_tier_step_meters(tier);
134 (xi as f32 * step, yi as f32 * step, zi as f32 * step, tier)
135}
136
137#[inline]
141pub fn make_spatial_coord_quin(
142 subject: u64,
143 predicate: u64,
144 x: f32,
145 y: f32,
146 z: f32,
147 scale_tier: u8,
148 context: u64,
149 metadata: u64,
150) -> NQuin {
151 let object = pack_coord_with_scale(x, y, z, scale_tier);
152 let parity = NQuin::calculate_parity(subject, predicate, object, context, metadata);
153 NQuin {
154 subject,
155 predicate,
156 object,
157 context,
158 metadata,
159 parity,
160 }
161}
162
163#[inline]
165pub fn decode_spatial_coord_quin(quin: &NQuin) -> (f32, f32, f32, u8) {
166 unpack_coord_with_scale(quin.object)
167}
168
169#[inline]
171pub fn make_container_link_quin(
172 subject: u64,
173 predicate: u64,
174 container_hash: u64,
175 section_offset: u32,
176 chunk_records: u16,
177 context: u64,
178) -> NQuin {
179 let object = container_hash & 0x0FFF_FFFF_FFFF_FFFF;
180 let metadata = ((section_offset as u64) << 32) | (chunk_records as u64);
181 let parity = NQuin::calculate_parity(subject, predicate, object, context, metadata);
182 NQuin {
183 subject,
184 predicate,
185 object,
186 context,
187 metadata,
188 parity,
189 }
190}
191
192#[inline]
194pub fn decode_container_link_quin(quin: &NQuin) -> (u64, u32, u16) {
195 let container_hash = quin.object & 0x0FFF_FFFF_FFFF_FFFF;
196 let section_offset = (quin.metadata >> 32) as u32;
197 let chunk_records = (quin.metadata & 0xFFFF) as u16;
198 (container_hash, section_offset, chunk_records)
199}
200
201#[inline]
203pub fn make_kinematic_quin(
204 subject: u64,
205 predicate: u64,
206 parent_or_type_hash: u64,
207 motor_slot: u32,
208 context: u64,
209) -> NQuin {
210 let object = parent_or_type_hash & 0x0FFF_FFFF_FFFF_FFFF;
211 let metadata = motor_slot as u64;
212 let parity = NQuin::calculate_parity(subject, predicate, object, context, metadata);
213 NQuin {
214 subject,
215 predicate,
216 object,
217 context,
218 metadata,
219 parity,
220 }
221}
222
223#[inline]
225pub fn decode_kinematic_quin(quin: &NQuin) -> (u64, u32) {
226 (quin.object & 0x0FFF_FFFF_FFFF_FFFF, quin.metadata as u32)
227}
228
229#[inline]
231pub fn make_sensory_quin(
232 subject: u64,
233 predicate: u64,
234 asset_hash: u64,
235 hoa_order_or_band: u32,
236 context: u64,
237) -> NQuin {
238 let object = asset_hash & 0x0FFF_FFFF_FFFF_FFFF;
239 let metadata = hoa_order_or_band as u64;
240 let parity = NQuin::calculate_parity(subject, predicate, object, context, metadata);
241 NQuin {
242 subject,
243 predicate,
244 object,
245 context,
246 metadata,
247 parity,
248 }
249}
250
251#[inline]
253pub fn decode_sensory_quin(quin: &NQuin) -> (u64, u32) {
254 (quin.object & 0x0FFF_FFFF_FFFF_FFFF, quin.metadata as u32)
255}
256
257#[inline]
259pub fn make_epistemic_quin(
260 subject: u64,
261 predicate: u64,
262 value: u64,
263 context: u64,
264 lamport_clock: u32,
265) -> NQuin {
266 let metadata = lamport_clock as u64;
267 let parity = NQuin::calculate_parity(subject, predicate, value, context, metadata);
268 NQuin {
269 subject,
270 predicate,
271 object: value,
272 context,
273 metadata,
274 parity,
275 }
276}
277
278#[inline]
280pub fn decode_epistemic_quin(quin: &NQuin) -> u64 {
281 quin.object
282}
283
284#[inline]
286pub fn make_llm_grounding_quin(
287 subject: u64,
288 predicate: u64,
289 kv_slot: u32,
290 parent_page_id: u64,
291 context: u64,
292) -> NQuin {
293 let object = kv_slot as u64;
294 let metadata = parent_page_id;
295 let parity = NQuin::calculate_parity(subject, predicate, object, context, metadata);
296 NQuin {
297 subject,
298 predicate,
299 object,
300 context,
301 metadata,
302 parity,
303 }
304}
305
306#[inline]
308pub fn decode_llm_grounding_quin(quin: &NQuin) -> (u32, u64) {
309 (quin.object as u32, quin.metadata)
310}
311
312#[cfg(test)]
313mod tests {
314 use super::*;
315
316 #[test]
317 fn all_28_predicates_are_unique_with_zero_collisions() {
318 let preds = ALL_SPATIAL_SENSORY_PREDICATES;
319 assert_eq!(preds.len(), 28);
320 for i in 0..preds.len() {
321 for j in (i + 1)..preds.len() {
322 assert_ne!(
323 preds[i], preds[j],
324 "Collision detected between predicate index {i} and {j}"
325 );
326 }
327 }
328 }
329
330 #[test]
331 fn spatial_coord_round_trip_millimeter() {
332 let quin = make_spatial_coord_quin(100, PRED_GEO_HAS_VERTEX, 1.25, -2.5, 3.75, 0, 0, 0);
333 assert!(quin.verify_ecc_parity());
334 let (x, y, z, tier) = decode_spatial_coord_quin(&quin);
335 assert_eq!(tier, 0);
336 assert!((x - 1.25).abs() < 0.002);
337 assert!((y - -2.5).abs() < 0.002);
338 assert!((z - 3.75).abs() < 0.002);
339 }
340
341 #[test]
342 fn spatial_coord_round_trip_meter_tier() {
343 let quin = make_spatial_coord_quin(101, PRED_GEO_HAS_PACKED_CENTROID, 120.0, -45.0, 300.0, 3, 0, 0);
344 assert!(quin.verify_ecc_parity());
345 let (x, y, z, tier) = decode_spatial_coord_quin(&quin);
346 assert_eq!(tier, 3);
347 assert!((x - 120.0).abs() < 1.0);
348 assert!((y - -45.0).abs() < 1.0);
349 assert!((z - 300.0).abs() < 1.0);
350 }
351
352 #[test]
353 fn container_link_round_trip() {
354 let quin = make_container_link_quin(200, PRED_Q42_HAS_M64_CHUNK, 0x1234_5678_9ABC_DEF0, 4096, 64, 1);
355 assert!(quin.verify_ecc_parity());
356 let (hash, offset, chunks) = decode_container_link_quin(&quin);
357 assert_eq!(hash, 0x1234_5678_9ABC_DEF0 & 0x0FFF_FFFF_FFFF_FFFF);
358 assert_eq!(offset, 4096);
359 assert_eq!(chunks, 64);
360 }
361
362 #[test]
363 fn kinematic_round_trip() {
364 let quin = make_kinematic_quin(300, PRED_KIN_HAS_PGA_MOTOR, 0x9999_8888, 12, 0);
365 assert!(quin.verify_ecc_parity());
366 let (hash, slot) = decode_kinematic_quin(&quin);
367 assert_eq!(hash, 0x9999_8888);
368 assert_eq!(slot, 12);
369 }
370
371 #[test]
372 fn sensory_round_trip() {
373 let quin = make_sensory_quin(400, PRED_SENS_HAS_HOA_ORDER, 0x7777, 3, 0);
374 assert!(quin.verify_ecc_parity());
375 let (hash, hoa) = decode_sensory_quin(&quin);
376 assert_eq!(hash, 0x7777);
377 assert_eq!(hoa, 3);
378 }
379
380 #[test]
381 fn epistemic_round_trip() {
382 let quin = make_epistemic_quin(500, PRED_EPI_HAS_QUANTUM_RANGE, 998, 0, 42);
383 assert!(quin.verify_ecc_parity());
384 assert_eq!(decode_epistemic_quin(&quin), 998);
385 assert_eq!(quin.extract_lamport_clock(), 42);
386 }
387
388 #[test]
389 fn llm_grounding_round_trip() {
390 let quin = make_llm_grounding_quin(600, PRED_LLM_HAS_KV_SLOT, 128, 0xABCDE, 0);
391 assert!(quin.verify_ecc_parity());
392 let (slot, page) = decode_llm_grounding_quin(&quin);
393 assert_eq!(slot, 128);
394 assert_eq!(page, 0xABCDE);
395 }
396}