Skip to main content

qualia_core_db/render/
hmc_playback.rs

1//! Browser HMC mesh playback and resident-upload bookkeeping.
2//!
3//! The bundle reader owns byte validation and zero-copy entry access. This module owns the
4//! smaller lifecycle contract needed by the browser portal: resolve one verified `.10d` mesh,
5//! upload it at most once for a resident source digest, and retain enough receipt data for a
6//! playback caller to distinguish a new upload from a resident reuse.
7
8use crate::bundle::BundleReader;
9
10/// A verified `.10d` entry borrowed from an HMC bundle.
11#[derive(Debug)]
12pub struct HmcMeshSource<'a> {
13    pub bytes: &'a [u8],
14    pub digest: [u8; 32],
15}
16
17/// Resolve and verify one mesh entry without copying the HMC payload.
18pub fn resolve_hmc_mesh<'a>(bytes: &'a [u8], asset_key: &str) -> Result<HmcMeshSource<'a>, String> {
19    let bundle = BundleReader::parse(bytes).map_err(|error| format!("HMC bundle: {error}"))?;
20    let entry = bundle
21        .entry(asset_key)
22        .ok_or_else(|| format!("HMC asset is missing: {asset_key}"))?;
23    if entry.kind != "10d" {
24        return Err(format!(
25            "HMC asset {asset_key} has kind {:?}, expected 10d",
26            entry.kind
27        ));
28    }
29    if entry.sha256.len() != 32 || !bundle.verify_entry(asset_key) {
30        return Err(format!("HMC asset digest check failed: {asset_key}"));
31    }
32    let mut digest = [0u8; 32];
33    digest.copy_from_slice(&entry.sha256);
34    let payload = bundle
35        .get(asset_key)
36        .ok_or_else(|| format!("HMC asset payload is missing: {asset_key}"))?;
37    Ok(HmcMeshSource {
38        bytes: payload,
39        digest,
40    })
41}
42
43/// Receipt returned by the resident mesh lifecycle.
44#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
45pub struct HmcMeshResidencyReceipt {
46    pub digest: [u8; 32],
47    pub generation: u64,
48    pub upload_count: u32,
49    pub vertex_count: u32,
50    pub index_count: u32,
51    pub triangle_count: u32,
52}
53
54/// Tracks the one mesh currently bound by the browser portal.
55#[derive(Default)]
56pub struct HmcMeshResidency {
57    resident: Option<HmcMeshResidencyReceipt>,
58    generation: u64,
59    upload_count: u32,
60}
61
62impl HmcMeshResidency {
63    /// Return the existing receipt when the requested source is already resident.
64    pub fn resident(&self, digest: [u8; 32]) -> Option<HmcMeshResidencyReceipt> {
65        self.resident.filter(|receipt| receipt.digest == digest)
66    }
67
68    /// Return the current receipt, regardless of source digest.
69    pub fn current(&self) -> Option<HmcMeshResidencyReceipt> {
70        self.resident
71    }
72
73    /// Record a successful replacement upload and advance the lifecycle generation.
74    pub fn record_upload(
75        &mut self,
76        digest: [u8; 32],
77        vertex_count: u32,
78        index_count: u32,
79        triangle_count: u32,
80    ) -> HmcMeshResidencyReceipt {
81        self.generation = self.generation.saturating_add(1);
82        self.upload_count = self.upload_count.saturating_add(1);
83        let receipt = HmcMeshResidencyReceipt {
84            digest,
85            generation: self.generation,
86            upload_count: self.upload_count,
87            vertex_count,
88            index_count,
89            triangle_count,
90        };
91        self.resident = Some(receipt);
92        receipt
93    }
94
95    /// Invalidate the source identity when another mesh API replaces the portal mesh.
96    pub fn clear(&mut self) {
97        self.resident = None;
98    }
99}
100
101#[cfg(test)]
102mod tests {
103    use super::*;
104    use crate::bundle::BundleWriter;
105
106    #[test]
107    fn resolves_verified_mesh_without_copying_payload() {
108        let payload = b"verified-10d".to_vec();
109        let mut writer = BundleWriter::new();
110        writer
111            .add_file("scene.10d", "10d", payload.clone(), None)
112            .unwrap();
113        let bundle = writer.build().unwrap();
114
115        let source = resolve_hmc_mesh(&bundle, "scene.10d").unwrap();
116        assert_eq!(source.bytes, payload.as_slice());
117        assert_ne!(source.digest, [0; 32]);
118    }
119
120    #[test]
121    fn rejects_non_mesh_entry() {
122        let mut writer = BundleWriter::new();
123        writer
124            .add_file("scene.q42", "q42", b"graph".to_vec(), None)
125            .unwrap();
126        let bundle = writer.build().unwrap();
127
128        let error = resolve_hmc_mesh(&bundle, "scene.q42").unwrap_err();
129        assert!(error.contains("expected 10d"));
130    }
131
132    #[test]
133    fn resident_lifecycle_reuses_and_replaces_uploads() {
134        let mut residency = HmcMeshResidency::default();
135        let first_digest = [1; 32];
136        let second_digest = [2; 32];
137
138        assert!(residency.resident(first_digest).is_none());
139        let first = residency.record_upload(first_digest, 3, 6, 2);
140        assert_eq!(first.generation, 1);
141        assert_eq!(first.upload_count, 1);
142        assert_eq!(residency.resident(first_digest), Some(first));
143        assert!(residency.resident(second_digest).is_none());
144
145        let second = residency.record_upload(second_digest, 4, 9, 3);
146        assert_eq!(second.generation, 2);
147        assert_eq!(second.upload_count, 2);
148        assert!(residency.resident(first_digest).is_none());
149        assert_eq!(residency.resident(second_digest), Some(second));
150
151        residency.clear();
152        assert!(residency.resident(second_digest).is_none());
153    }
154}