Skip to main content

qualia_client_core/
canvas_world.rs

1//! Chora — spatio-temporal commons canvas world configuration.
2//!
3//! A "world" is a bounded projection over the canvas substrate (doc 02 §2):
4//! `{ temporal range, ordered layer-stack, permitted nquins, governance norms }`.
5//! Worlds are configurations, not engine forks.
6
7use serde::{Deserialize, Serialize};
8
9/// Ontological stratum for a layer (doc 02 §1).
10#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
11pub enum WorldStratum {
12    /// Infrastructure, buildings, boundaries — authored human intent (a true digital twin).
13    WorldOfMan,
14    /// Biosphere, terrain, physics — computational approximation, never a twin.
15    WorldOfGod,
16    /// Records, claims, provenance — the informational environment.
17    Infosphere,
18    /// Human social relations — society as a stratum.
19    Sociosphere,
20}
21
22/// A dataset layer in the ordered stack (doc 02 §3).
23#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
24pub enum CanvasLayer {
25    GeoSpatial {
26        endpoint: String,
27        stratum: WorldStratum,
28    },
29    Council {
30        endpoint: String,
31    },
32    Historical {
33        endpoint: String,
34    },
35    Celestial {
36        endpoint: String,
37    },
38    Infosphere {
39        endpoint: String,
40    },
41    MicroScale {
42        endpoint: String,
43    },
44    Biosphere {
45        endpoint: String,
46    },
47    Custom {
48        name: String,
49        endpoint: String,
50        stratum: WorldStratum,
51    },
52}
53
54impl CanvasLayer {
55    /// Canvas-world endpoint.
56    pub fn endpoint(&self) -> &str {
57        match self {
58            Self::GeoSpatial { endpoint, .. }
59            | Self::Council { endpoint }
60            | Self::Historical { endpoint }
61            | Self::Celestial { endpoint }
62            | Self::Infosphere { endpoint }
63            | Self::MicroScale { endpoint }
64            | Self::Biosphere { endpoint }
65            | Self::Custom { endpoint, .. } => endpoint,
66        }
67    }
68
69    /// Canvas-world stratum.
70    pub fn stratum(&self) -> WorldStratum {
71        match self {
72            Self::GeoSpatial { stratum, .. } | Self::Custom { stratum, .. } => *stratum,
73            Self::Council { .. } | Self::Historical { .. } => WorldStratum::WorldOfMan,
74            Self::Celestial { .. } | Self::Biosphere { .. } | Self::MicroScale { .. } => {
75                WorldStratum::WorldOfGod
76            }
77            Self::Infosphere { .. } => WorldStratum::Infosphere,
78        }
79    }
80}
81
82/// A governed norm applied to this world (N3 rule URI or deontic contract hash).
83#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
84pub struct CanvasNorm {
85    pub rule_uri: String,
86    #[serde(default)]
87    pub description: String,
88}
89
90/// A planted or referenced asset in the world (content-addressed `.10d` or remote hash).
91#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
92pub struct CanvasAssetRef {
93    /// Content hash (hex) or `urn:qualia:asset:…` URI.
94    pub asset_id: String,
95    /// Optional geodetic anchor (degrees).
96    #[serde(default)]
97    pub lat: Option<f64>,
98    #[serde(default)]
99    pub lon: Option<f64>,
100    #[serde(default)]
101    pub alt_m: Option<f64>,
102    /// Valid-time interval (unix seconds). None = always visible.
103    #[serde(default)]
104    pub valid_from: Option<u64>,
105    #[serde(default)]
106    pub valid_until: Option<u64>,
107    /// Permissive licence (required for render gate).
108    pub licence: String,
109}
110
111/// A "world" configuration: a bounded projection over the canvas.
112#[derive(Debug, Clone, Serialize, Deserialize)]
113pub struct CanvasWorldConfig {
114    /// Unique identifier (e.g. `q42:world:council-sydney`).
115    pub id: String,
116    /// Human-readable title shown in the Chora panel.
117    pub title: String,
118    /// Optional temporal range: (start_epoch, end_epoch). None = full timeline.
119    pub temporal_range: Option<(u64, u64)>,
120    /// Ordered stack of dataset layers to composite.
121    pub layer_stack: Vec<CanvasLayer>,
122    /// Offline or seeded assets rendered in this world.
123    #[serde(default)]
124    pub assets: Vec<CanvasAssetRef>,
125    /// Whitelist of permitted nquin subject hashes. Empty = layer-stack bounds only.
126    #[serde(default)]
127    pub permitted_nquins: Vec<u64>,
128    /// Deontic norms / governance rules applied to this world.
129    #[serde(default)]
130    pub norms: Vec<CanvasNorm>,
131    /// Reference-frame origin for local ENU coordinates (degrees).
132    #[serde(default)]
133    pub origin_lat: f64,
134    #[serde(default)]
135    pub origin_lon: f64,
136    #[serde(default)]
137    pub origin_alt_m: f64,
138}
139
140impl Default for CanvasWorldConfig {
141    fn default() -> Self {
142        Self {
143            id: "q42:world:default".to_string(),
144            title: "Default World".to_string(),
145            temporal_range: None,
146            layer_stack: vec![],
147            assets: vec![],
148            permitted_nquins: vec![],
149            norms: vec![],
150            origin_lat: -33.8688,
151            origin_lon: 151.2093,
152            origin_alt_m: 0.0,
153        }
154    }
155}
156
157#[derive(Debug, PartialEq, Eq)]
158pub enum WorldConfigError {
159    EmptyId,
160    InvertedTemporalRange,
161    AssetMissingLicence { asset_id: String },
162    AssetInvertedValidity { asset_id: String },
163}
164
165impl std::fmt::Display for WorldConfigError {
166    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
167        match self {
168            Self::EmptyId => write!(f, "world id must not be empty"),
169            Self::InvertedTemporalRange => write!(f, "temporal_range start must be <= end"),
170            Self::AssetMissingLicence { asset_id } => {
171                write!(f, "asset {asset_id} requires a licence")
172            }
173            Self::AssetInvertedValidity { asset_id } => {
174                write!(f, "asset {asset_id} valid_from must be <= valid_until")
175            }
176        }
177    }
178}
179impl std::error::Error for WorldConfigError {}
180
181impl CanvasWorldConfig {
182    /// Validate the config contract (P0 freeze).
183    pub fn validate(&self) -> Result<(), WorldConfigError> {
184        if self.id.trim().is_empty() {
185            return Err(WorldConfigError::EmptyId);
186        }
187        if let Some((t0, t1)) = self.temporal_range {
188            if t0 > t1 {
189                return Err(WorldConfigError::InvertedTemporalRange);
190            }
191        }
192        for asset in &self.assets {
193            if asset.licence.trim().is_empty() {
194                return Err(WorldConfigError::AssetMissingLicence {
195                    asset_id: asset.asset_id.clone(),
196                });
197            }
198            if let (Some(vf), Some(vu)) = (asset.valid_from, asset.valid_until) {
199                if vf > vu {
200                    return Err(WorldConfigError::AssetInvertedValidity {
201                        asset_id: asset.asset_id.clone(),
202                    });
203                }
204            }
205        }
206        Ok(())
207    }
208
209    /// P0 demo world: one offline tile, Sydney origin, CC0 licence placeholder.
210    pub fn seed_demo() -> Self {
211        Self {
212            id: "q42:world:demo-offline".to_string(),
213            title: "Chora Demo (offline)".to_string(),
214            temporal_range: Some((1_700_000_000, 1_900_000_000)),
215            layer_stack: vec![CanvasLayer::GeoSpatial {
216                endpoint: "local://terrain/demo".to_string(),
217                stratum: WorldStratum::WorldOfGod,
218            }],
219            assets: vec![CanvasAssetRef {
220                asset_id: "local://assets/demo-tile.10d".to_string(),
221                lat: Some(-33.8688),
222                lon: Some(151.2093),
223                alt_m: Some(0.0),
224                valid_from: Some(1_700_000_000),
225                valid_until: None,
226                licence: "CC0".to_string(),
227            }],
228            norms: vec![CanvasNorm {
229                rule_uri: "urn:qualia:canvas:public-commons".to_string(),
230                description: "Permissive-commons read; planting requires placement right"
231                    .to_string(),
232            }],
233            origin_lat: -33.8688,
234            origin_lon: 151.2093,
235            origin_alt_m: 0.0,
236            ..Default::default()
237        }
238    }
239
240    /// Resolve layer endpoints in stack order (deduplicated).
241    pub fn layer_endpoints(&self) -> Vec<&str> {
242        let mut seen = std::collections::HashSet::new();
243        let mut out = Vec::new();
244        for layer in &self.layer_stack {
245            let ep = layer.endpoint();
246            if seen.insert(ep) {
247                out.push(ep);
248            }
249        }
250        out
251    }
252}
253
254#[cfg(test)]
255mod tests {
256    use super::*;
257
258    #[test]
259    fn demo_world_validates() {
260        let w = CanvasWorldConfig::seed_demo();
261        w.validate().unwrap();
262        assert_eq!(w.layer_stack.len(), 1);
263        assert_eq!(w.assets[0].licence, "CC0");
264    }
265
266    #[test]
267    fn rejects_inverted_temporal_range() {
268        let mut w = CanvasWorldConfig::default();
269        w.temporal_range = Some((2000, 1000));
270        assert_eq!(w.validate(), Err(WorldConfigError::InvertedTemporalRange));
271    }
272
273    #[test]
274    fn layer_endpoints_deduplicated() {
275        let w = CanvasWorldConfig {
276            layer_stack: vec![
277                CanvasLayer::GeoSpatial {
278                    endpoint: "a".into(),
279                    stratum: WorldStratum::WorldOfGod,
280                },
281                CanvasLayer::Council {
282                    endpoint: "b".into(),
283                },
284                CanvasLayer::GeoSpatial {
285                    endpoint: "a".into(),
286                    stratum: WorldStratum::WorldOfGod,
287                },
288            ],
289            ..Default::default()
290        };
291        assert_eq!(w.layer_endpoints(), vec!["a", "b"]);
292    }
293}