Skip to main content

qualia_core_db/entity_view/
package.rs

1//! Bifurcated socio-cognitive package wings (layout + digests).
2//!
3//! Skeleton for private vs offered/commons representation - not encryption by itself.
4
5use super::entity_id::EntityId;
6use super::observer::RepresentationWing;
7use crate::hypermedia::fnv60;
8use serde::{Deserialize, Serialize};
9
10/// One wing of a bifurcated package (fixed header; bodies referenced by digest).
11#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
12pub struct PackageWing {
13    pub wing: RepresentationWing,
14    /// Entities included in this wing (bounded list in host; here free Vec for cold path).
15    pub entity_ids: Vec<u64>,
16    /// Content digest of wing payload bytes (0 if empty).
17    pub payload_digest: u64,
18}
19
20/// Bifurcated presentation / socio-cognitive package v1.
21#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
22pub struct BifurcatedPackage {
23    /// Layout version (`VERSION`).
24    pub version: u32,
25    /// `fnv60` of the caller's package key.
26    pub package_id: u64,
27    /// Entities visible only to the principal.
28    pub private_wing: PackageWing,
29    /// Entities offered under negotiated/conditional terms.
30    pub offered_wing: PackageWing,
31    /// Entities in the permissive commons.
32    pub commons_wing: PackageWing,
33    /// Combined digest of the three wing digests (ordering fixed).
34    pub package_digest: u64,
35}
36
37impl BifurcatedPackage {
38    pub const VERSION: u32 = 1;
39
40    /// Build a package from three wing entity lists; `package_id` is
41    /// `fnv60(package_key)` and `package_digest` folds the three wing
42    /// digests plus the id.
43    pub fn new(
44        package_key: &str,
45        private_ids: &[EntityId],
46        offered_ids: &[EntityId],
47        commons_ids: &[EntityId],
48    ) -> Self {
49        let private_wing = wing(RepresentationWing::Private, private_ids);
50        let offered_wing = wing(RepresentationWing::Offered, offered_ids);
51        let commons_wing = wing(RepresentationWing::Commons, commons_ids);
52        let package_id = fnv60(package_key.as_bytes());
53        let package_digest = fold_digests(&[
54            private_wing.payload_digest,
55            offered_wing.payload_digest,
56            commons_wing.payload_digest,
57            package_id,
58        ]);
59        Self {
60            version: Self::VERSION,
61            package_id,
62            private_wing,
63            offered_wing,
64            commons_wing,
65            package_digest,
66        }
67    }
68
69    /// Select wing for observer without exposing other wing entity lists to caller policy.
70    pub fn wing_for(&self, wing: RepresentationWing) -> &PackageWing {
71        match wing {
72            RepresentationWing::Private => &self.private_wing,
73            RepresentationWing::Offered => &self.offered_wing,
74            RepresentationWing::Commons => &self.commons_wing,
75        }
76    }
77}
78
79fn wing(kind: RepresentationWing, ids: &[EntityId]) -> PackageWing {
80    let entity_ids: Vec<u64> = ids.iter().map(|e| e.raw()).collect();
81    let mut bytes = Vec::with_capacity(entity_ids.len() * 8 + 1);
82    bytes.push(kind as u8);
83    for id in &entity_ids {
84        bytes.extend_from_slice(&id.to_le_bytes());
85    }
86    PackageWing {
87        wing: kind,
88        payload_digest: if entity_ids.is_empty() {
89            0
90        } else {
91            fnv60(&bytes)
92        },
93        entity_ids,
94    }
95}
96
97fn fold_digests(parts: &[u64]) -> u64 {
98    let mut bytes = Vec::with_capacity(parts.len() * 8);
99    for p in parts {
100        bytes.extend_from_slice(&p.to_le_bytes());
101    }
102    fnv60(&bytes)
103}
104
105#[cfg(test)]
106mod tests {
107    use super::*;
108    use crate::entity_view::entity_id::EntityId;
109
110    #[test]
111    fn bifurcate_package_stable_digest() {
112        let a = EntityId::from_uri("urn:a");
113        let b = EntityId::from_uri("urn:b");
114        let p1 = BifurcatedPackage::new("pkg:1", &[a], &[b], &[]);
115        let p2 = BifurcatedPackage::new("pkg:1", &[a], &[b], &[]);
116        assert_eq!(p1.package_digest, p2.package_digest);
117        assert_eq!(p1.private_wing.entity_ids.len(), 1);
118        assert_eq!(p1.offered_wing.entity_ids.len(), 1);
119        assert!(p1.commons_wing.entity_ids.is_empty());
120    }
121}