Skip to main content

qualia_core_db/render/
asset_package.rs

1//! Content-addressed HMC packaging and zero-copy resolution for compiled render assets.
2
3use super::compile_10d::CompiledAsset;
4use std::collections::BTreeMap;
5
6#[derive(Debug)]
7pub enum HmcAssetPackageError {
8    Bundle(crate::bundle::BundleError),
9    TextureDigestMismatch([u8; 32]),
10    TextureResourceMissing([u8; 32]),
11    TextureMetadataConflict([u8; 32]),
12    NoAssets,
13}
14
15impl std::fmt::Display for HmcAssetPackageError {
16    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
17        match self {
18            Self::Bundle(error) => write!(f, "HMC package: {error}"),
19            Self::TextureDigestMismatch(digest) => write!(
20                f,
21                "HMC package: texture payload digest mismatch for {}",
22                hex::encode(digest)
23            ),
24            Self::TextureResourceMissing(digest) => write!(
25                f,
26                "HMC package: texture resource is missing for {}",
27                hex::encode(digest)
28            ),
29            Self::TextureMetadataConflict(digest) => write!(
30                f,
31                "HMC package: conflicting metadata for shared texture {}",
32                hex::encode(digest)
33            ),
34            Self::NoAssets => write!(f, "HMC package: no compiled assets were supplied"),
35        }
36    }
37}
38
39impl std::error::Error for HmcAssetPackageError {}
40
41impl From<crate::bundle::BundleError> for HmcAssetPackageError {
42    fn from(value: crate::bundle::BundleError) -> Self {
43        Self::Bundle(value)
44    }
45}
46
47impl CompiledAsset {
48    /// Consume this asset into an HMC pack containing its `.10d` and each referenced original
49    /// texture payload. Texture keys are global SHA-256 paths, so identical images can be shared
50    /// across assets by an HMC pack assembler that de-duplicates resources before insertion.
51    pub fn build_hmc_bundle(self, asset_entry_key: &str) -> Result<Vec<u8>, HmcAssetPackageError> {
52        build_hmc_bundle([(asset_entry_key.to_owned(), self)])
53    }
54}
55
56/// Package one or more assets in a canonical order and store each equal image digest once.
57/// All payloads remain original encoded bytes; this builder does not decode or transcode images.
58pub fn build_hmc_bundle<I>(assets: I) -> Result<Vec<u8>, HmcAssetPackageError>
59where
60    I: IntoIterator<Item = (String, CompiledAsset)>,
61{
62    use sha2::{Digest, Sha256};
63
64    let mut assets = assets.into_iter().collect::<Vec<_>>();
65    if assets.is_empty() {
66        return Err(HmcAssetPackageError::NoAssets);
67    }
68    assets.sort_unstable_by(|left, right| left.0.cmp(&right.0));
69    if assets
70        .iter()
71        .any(|(key, _)| key.is_empty() || key.as_bytes().contains(&0))
72    {
73        return Err(HmcAssetPackageError::Bundle(
74            crate::bundle::BundleError::EmptyKey,
75        ));
76    }
77    if let Some(pair) = assets.windows(2).find(|pair| pair[0].0 == pair[1].0) {
78        return Err(HmcAssetPackageError::Bundle(
79            crate::bundle::BundleError::DuplicateKey(pair[0].0.clone()),
80        ));
81    }
82
83    let mut writer = crate::bundle::BundleWriter::new();
84    let mut textures = BTreeMap::new();
85    for (asset_key, asset) in assets {
86        writer.add_file(asset_key, "10d", asset.container_10d, None)?;
87        for dependency in asset.texture_dependencies {
88            let actual: [u8; 32] = Sha256::digest(&dependency.bytes).into();
89            if actual != dependency.digest {
90                return Err(HmcAssetPackageError::TextureDigestMismatch(
91                    dependency.digest,
92                ));
93            }
94            if let Some(existing) = textures.get(&dependency.digest) {
95                let existing: &super::assets::TextureDependency = existing;
96                if existing.mime_type != dependency.mime_type || existing.bytes != dependency.bytes
97                {
98                    return Err(HmcAssetPackageError::TextureMetadataConflict(
99                        dependency.digest,
100                    ));
101                }
102            } else {
103                textures.insert(dependency.digest, dependency);
104            }
105        }
106    }
107    for (_, dependency) in textures {
108        writer.add_file(
109            texture_hmc_key(&dependency.digest),
110            dependency.mime_type,
111            dependency.bytes,
112            None,
113        )?;
114    }
115    Ok(writer.build()?)
116}
117
118/// Stable HMC key for a content-addressed source image.
119pub fn texture_hmc_key(digest: &[u8; 32]) -> String {
120    format!("textures/sha256/{}", hex::encode(digest))
121}
122
123/// Borrowed image payload resolved from an integrity-checked HMC bundle.
124pub struct HmcTextureResource<'a> {
125    pub digest: [u8; 32],
126    pub mime_type: &'a str,
127    pub bytes: &'a [u8],
128}
129
130/// Resolve a MAT1 image digest from HMC by its stable SHA-256 key and verify both bundle index
131/// integrity and equality with the MAT1 resource digest before returning a zero-copy view.
132pub fn resolve_hmc_texture_resource<'a>(
133    bundle: &'a crate::bundle::BundleReader<'a>,
134    digest: &[u8; 32],
135) -> Result<HmcTextureResource<'a>, HmcAssetPackageError> {
136    let key = texture_hmc_key(digest);
137    let bytes = bundle
138        .get(&key)
139        .ok_or(HmcAssetPackageError::TextureResourceMissing(*digest))?;
140    if !bundle.verify_entry(&key) {
141        return Err(HmcAssetPackageError::TextureDigestMismatch(*digest));
142    }
143    let entry = bundle
144        .entry(&key)
145        .ok_or(HmcAssetPackageError::TextureResourceMissing(*digest))?;
146    if entry.sha256.as_slice() != digest.as_slice() {
147        return Err(HmcAssetPackageError::TextureDigestMismatch(*digest));
148    }
149    Ok(HmcTextureResource {
150        digest: *digest,
151        mime_type: &entry.kind,
152        bytes,
153    })
154}
155
156#[cfg(test)]
157mod tests {
158    use super::*;
159    use crate::render::assets::TextureDependency;
160    use sha2::{Digest, Sha256};
161
162    fn asset_with_texture(bytes: &[u8], mime_type: &str) -> CompiledAsset {
163        let mut asset = crate::render::compile_10d::compile_asset(
164            b"v 0 0 0\nv 1 0 0\nv 0 1 0\nf 1 2 3\n",
165            Some("obj"),
166            "urn:test:package-fixture",
167            "obj",
168        )
169        .unwrap();
170        let digest: [u8; 32] = Sha256::digest(bytes).into();
171        asset.texture_dependencies.push(TextureDependency {
172            digest,
173            mime_type: mime_type.to_owned(),
174            bytes: bytes.to_vec(),
175        });
176        asset
177    }
178
179    #[test]
180    fn multi_asset_bundle_sorts_assets_and_deduplicates_shared_images() {
181        let shared_payload = [7, 8, 9, 10];
182        let asset_a = asset_with_texture(&shared_payload, "image/png");
183        let asset_b = asset_a.clone();
184        let forward = build_hmc_bundle(vec![
185            ("assets/b.10d".to_owned(), asset_b.clone()),
186            ("assets/a.10d".to_owned(), asset_a.clone()),
187        ])
188        .unwrap();
189        let reverse = build_hmc_bundle(vec![
190            ("assets/a.10d".to_owned(), asset_a),
191            ("assets/b.10d".to_owned(), asset_b),
192        ])
193        .unwrap();
194        assert_eq!(forward, reverse);
195
196        let bundle = crate::bundle::BundleReader::parse(&forward).unwrap();
197        assert_eq!(bundle.entries().len(), 3);
198        assert_eq!(bundle.entries()[0].key, "assets/a.10d");
199        assert_eq!(bundle.entries()[1].key, "assets/b.10d");
200        let digest: [u8; 32] = Sha256::digest(shared_payload).into();
201        let resource = resolve_hmc_texture_resource(&bundle, &digest).unwrap();
202        assert_eq!(resource.bytes, shared_payload);
203        assert_eq!(resource.mime_type, "image/png");
204    }
205
206    #[test]
207    fn shared_digest_with_conflicting_mime_is_rejected() {
208        let payload = [7, 8, 9, 10];
209        let png = asset_with_texture(&payload, "image/png");
210        let webp = asset_with_texture(&payload, "image/webp");
211        assert!(matches!(
212            build_hmc_bundle(vec![
213                ("assets/a.10d".to_owned(), png),
214                ("assets/b.10d".to_owned(), webp),
215            ]),
216            Err(HmcAssetPackageError::TextureMetadataConflict(_))
217        ));
218    }
219}