1use std::collections::VecDeque;
9
10use crate::bundle::streaming_loader::StreamPriorityTier;
11use crate::container_10d::crc32c::crc32c;
12use crate::render::texture_transcode::{
13 decode_astc_4x4_block, decode_bc7_block, decode_etc2_eac_rgba_block,
14};
15use sha2::{Digest, Sha256};
16
17pub const CAP_VERIFY_CRC32C: u32 = 1 << 0;
19pub const CAP_VERIFY_SHA256: u32 = 1 << 1;
21pub const CAP_DECODE_MESH_10D: u32 = 1 << 2;
23pub const CAP_TRANSCODE_KTX2: u32 = 1 << 3;
25pub const CAP_ADMIT_Q42_SLICE: u32 = 1 << 4;
27pub const CAP_ALL_HYDRATION: u32 = CAP_VERIFY_CRC32C
29 | CAP_VERIFY_SHA256
30 | CAP_DECODE_MESH_10D
31 | CAP_TRANSCODE_KTX2
32 | CAP_ADMIT_Q42_SLICE;
33
34#[repr(C)]
36#[derive(Debug, Clone, Copy, PartialEq, Eq)]
37pub struct HydrationCapabilityToken {
38 pub holder_did_hash: u64,
39 pub granted_mask: u32,
40 pub max_tier_allowed: u8,
41 pub _pad: [u8; 3],
42 pub fuel_remaining: u64,
43 pub byte_budget_remaining: u64,
44 pub parity_seal: u64,
45}
46
47impl HydrationCapabilityToken {
48 #[inline]
50 pub const fn new_sealed(
51 holder_did_hash: u64,
52 granted_mask: u32,
53 max_tier: StreamPriorityTier,
54 fuel_budget: u64,
55 byte_budget: u64,
56 ) -> Self {
57 let max_tier_allowed = max_tier as u8;
58 let parity_seal = Self::compute_seal(
59 holder_did_hash,
60 granted_mask,
61 max_tier_allowed,
62 fuel_budget,
63 byte_budget,
64 );
65 Self {
66 holder_did_hash,
67 granted_mask,
68 max_tier_allowed,
69 _pad: [0; 3],
70 fuel_remaining: fuel_budget,
71 byte_budget_remaining: byte_budget,
72 parity_seal,
73 }
74 }
75
76 #[inline]
77 const fn compute_seal(
78 holder_did_hash: u64,
79 granted_mask: u32,
80 max_tier_allowed: u8,
81 fuel_remaining: u64,
82 byte_budget_remaining: u64,
83 ) -> u64 {
84 let mixed = holder_did_hash
85 ^ ((granted_mask as u64) << 17)
86 ^ ((max_tier_allowed as u64) << 49)
87 ^ fuel_remaining.rotate_left(13)
88 ^ byte_budget_remaining.rotate_left(37);
89 mixed.wrapping_mul(0x9E37_79B9_7F4A_7C15)
90 }
91
92 #[inline]
94 pub const fn verify_seal(&self) -> bool {
95 self.parity_seal
96 == Self::compute_seal(
97 self.holder_did_hash,
98 self.granted_mask,
99 self.max_tier_allowed,
100 self.fuel_remaining,
101 self.byte_budget_remaining,
102 )
103 }
104
105 pub fn authorize_and_deduct(
107 &mut self,
108 required_cap: u32,
109 tier: StreamPriorityTier,
110 fuel_cost: u64,
111 byte_cost: u64,
112 ) -> Result<(), GovernancePoolError> {
113 if !self.verify_seal() {
114 return Err(GovernancePoolError::InvalidTokenSeal);
115 }
116 if (self.granted_mask & required_cap) != required_cap {
117 return Err(GovernancePoolError::CapabilityDenied {
118 required: required_cap,
119 granted: self.granted_mask,
120 });
121 }
122 if (tier as u8) > self.max_tier_allowed {
123 return Err(GovernancePoolError::TierForbidden {
124 requested: tier,
125 max_allowed: self.max_tier_allowed,
126 });
127 }
128 if self.fuel_remaining < fuel_cost {
129 return Err(GovernancePoolError::FuelExhausted {
130 needed: fuel_cost,
131 remaining: self.fuel_remaining,
132 });
133 }
134 if self.byte_budget_remaining < byte_cost {
135 return Err(GovernancePoolError::ByteBudgetExceeded {
136 needed: byte_cost,
137 remaining: self.byte_budget_remaining,
138 });
139 }
140 self.fuel_remaining -= fuel_cost;
141 self.byte_budget_remaining -= byte_cost;
142 self.parity_seal = Self::compute_seal(
143 self.holder_did_hash,
144 self.granted_mask,
145 self.max_tier_allowed,
146 self.fuel_remaining,
147 self.byte_budget_remaining,
148 );
149 Ok(())
150 }
151}
152
153#[derive(Debug, Clone, PartialEq, Eq)]
155pub enum GovernancePoolError {
156 InvalidTokenSeal,
157 CapabilityDenied { required: u32, granted: u32 },
158 TierForbidden { requested: StreamPriorityTier, max_allowed: u8 },
159 FuelExhausted { needed: u64, remaining: u64 },
160 ByteBudgetExceeded { needed: u64, remaining: u64 },
161 QueueFull { capacity: usize },
162 IntegrityMismatch { task_id: u64 },
163}
164
165#[derive(Debug, Clone, Copy, PartialEq, Eq)]
167pub enum TranscodeCodec {
168 Bc7,
169 Etc2EacRgba8,
170 Astc4x4,
171}
172
173#[derive(Debug, Clone)]
175pub enum HydrationTaskKind {
176 VerifySectionCrc32c {
178 payload: Vec<u8>,
179 expected_crc32c: u32,
180 },
181 VerifyEntrySha256 {
183 payload: Vec<u8>,
184 expected_sha256: [u8; 32],
185 },
186 TranscodeTextureBlock {
188 codec: TranscodeCodec,
189 block: [u8; 16],
190 },
191}
192
193impl HydrationTaskKind {
194 #[inline]
195 pub fn required_capability(&self) -> u32 {
196 match self {
197 HydrationTaskKind::VerifySectionCrc32c { .. } => CAP_VERIFY_CRC32C,
198 HydrationTaskKind::VerifyEntrySha256 { .. } => CAP_VERIFY_SHA256,
199 HydrationTaskKind::TranscodeTextureBlock { .. } => CAP_TRANSCODE_KTX2,
200 }
201 }
202
203 #[inline]
204 pub fn byte_cost(&self) -> u64 {
205 match self {
206 HydrationTaskKind::VerifySectionCrc32c { payload, .. } => payload.len() as u64,
207 HydrationTaskKind::VerifyEntrySha256 { payload, .. } => payload.len() as u64,
208 HydrationTaskKind::TranscodeTextureBlock { .. } => 64,
209 }
210 }
211
212 #[inline]
213 pub fn fuel_cost(&self) -> u64 {
214 match self {
215 HydrationTaskKind::VerifySectionCrc32c { payload, .. } => {
216 10 + (payload.len() as u64 / 64)
217 }
218 HydrationTaskKind::VerifyEntrySha256 { payload, .. } => {
219 25 + (payload.len() as u64 / 32)
220 }
221 HydrationTaskKind::TranscodeTextureBlock { .. } => 16,
222 }
223 }
224}
225
226#[derive(Debug, Clone)]
228pub struct HydrationTask {
229 pub task_id: u64,
230 pub tier: StreamPriorityTier,
231 pub kind: HydrationTaskKind,
232}
233
234#[derive(Debug, Clone, PartialEq, Eq)]
236pub struct HydrationReceipt {
237 pub task_id: u64,
238 pub tier: StreamPriorityTier,
239 pub verified: bool,
240 pub transcoded_rgba8_4x4: Option<[u8; 64]>,
241}
242
243#[inline]
245pub fn execute_crc_or_transcode_zero_heap(
246 codec: Option<TranscodeCodec>,
247 block_16: &[u8; 16],
248 crc_slice: &[u8],
249 expected_crc32c: u32,
250 rgba_out: &mut [u8; 64],
251) -> bool {
252 if let Some(c) = codec {
253 let pixels: &mut [[u8; 4]; 16] = bytemuck::cast_mut(rgba_out);
254 match c {
255 TranscodeCodec::Bc7 => decode_bc7_block(block_16, pixels),
256 TranscodeCodec::Etc2EacRgba8 => decode_etc2_eac_rgba_block(block_16, pixels),
257 TranscodeCodec::Astc4x4 => decode_astc_4x4_block(block_16, pixels),
258 }
259 true
260 } else {
261 crc32c(crc_slice) == expected_crc32c
262 }
263}
264
265pub struct GovernedHydrationPool {
267 queues: [VecDeque<HydrationTask>; 3],
268 max_queue_capacity: usize,
269 completed_count: u64,
270}
271
272impl GovernedHydrationPool {
273 pub fn new(max_queue_capacity: usize) -> Self {
275 let cap = max_queue_capacity.max(1);
276 Self {
277 queues: [
278 VecDeque::with_capacity(cap.min(64)),
279 VecDeque::with_capacity(cap.min(64)),
280 VecDeque::with_capacity(cap.min(64)),
281 ],
282 max_queue_capacity: cap,
283 completed_count: 0,
284 }
285 }
286
287 pub fn submit(
289 &mut self,
290 token: &mut HydrationCapabilityToken,
291 task: HydrationTask,
292 ) -> Result<(), GovernancePoolError> {
293 let tier_idx = task.tier as usize;
294 if self.queues[tier_idx].len() >= self.max_queue_capacity {
295 return Err(GovernancePoolError::QueueFull {
296 capacity: self.max_queue_capacity,
297 });
298 }
299 token.authorize_and_deduct(
300 task.kind.required_capability(),
301 task.tier,
302 task.kind.fuel_cost(),
303 task.kind.byte_cost(),
304 )?;
305 self.queues[tier_idx].push_back(task);
306 Ok(())
307 }
308
309 #[inline]
311 pub fn pending_count(&self) -> usize {
312 self.queues[0].len() + self.queues[1].len() + self.queues[2].len()
313 }
314
315 #[inline]
317 pub fn completed_count(&self) -> u64 {
318 self.completed_count
319 }
320
321 pub fn step_one(&mut self) -> Result<Option<HydrationReceipt>, GovernancePoolError> {
323 let task = if let Some(t) = self.queues[0].pop_front() {
324 t
325 } else if let Some(t) = self.queues[1].pop_front() {
326 t
327 } else if let Some(t) = self.queues[2].pop_front() {
328 t
329 } else {
330 return Ok(None);
331 };
332
333 let receipt = match &task.kind {
334 HydrationTaskKind::VerifySectionCrc32c {
335 payload,
336 expected_crc32c,
337 } => {
338 let mut dummy = [0u8; 64];
339 let ok = execute_crc_or_transcode_zero_heap(
340 None,
341 &[0u8; 16],
342 payload,
343 *expected_crc32c,
344 &mut dummy,
345 );
346 if !ok {
347 return Err(GovernancePoolError::IntegrityMismatch {
348 task_id: task.task_id,
349 });
350 }
351 HydrationReceipt {
352 task_id: task.task_id,
353 tier: task.tier,
354 verified: true,
355 transcoded_rgba8_4x4: None,
356 }
357 }
358 HydrationTaskKind::VerifyEntrySha256 {
359 payload,
360 expected_sha256,
361 } => {
362 let mut hasher = Sha256::new();
363 hasher.update(payload);
364 if hasher.finalize().as_slice() != expected_sha256.as_slice() {
365 return Err(GovernancePoolError::IntegrityMismatch {
366 task_id: task.task_id,
367 });
368 }
369 HydrationReceipt {
370 task_id: task.task_id,
371 tier: task.tier,
372 verified: true,
373 transcoded_rgba8_4x4: None,
374 }
375 }
376 HydrationTaskKind::TranscodeTextureBlock { codec, block } => {
377 let mut rgba = [0u8; 64];
378 execute_crc_or_transcode_zero_heap(Some(*codec), block, &[], 0, &mut rgba);
379 HydrationReceipt {
380 task_id: task.task_id,
381 tier: task.tier,
382 verified: true,
383 transcoded_rgba8_4x4: Some(rgba),
384 }
385 }
386 };
387 self.completed_count += 1;
388 Ok(Some(receipt))
389 }
390
391 pub fn drain_bounded(
393 &mut self,
394 max_tasks: usize,
395 ) -> Result<Vec<HydrationReceipt>, GovernancePoolError> {
396 let mut out = Vec::with_capacity(max_tasks.min(self.pending_count()));
397 for _ in 0..max_tasks {
398 match self.step_one()? {
399 Some(r) => out.push(r),
400 None => break,
401 }
402 }
403 Ok(out)
404 }
405}
406
407#[cfg(test)]
408mod tests {
409 use super::*;
410 use crate::specialized_libs::computational_geometry::allocation_counter::assert_zero_alloc;
411
412 #[test]
413 fn capability_token_enforces_seal_capabilities_and_budgets() {
414 let mut token = HydrationCapabilityToken::new_sealed(
415 0xABCD_1234,
416 CAP_VERIFY_CRC32C | CAP_TRANSCODE_KTX2,
417 StreamPriorityTier::Tier2HighPolyAndMip0,
418 100,
419 1024,
420 );
421 assert!(token.verify_seal());
422
423 let mut pool = GovernedHydrationPool::new(16);
424
425 let sha_task = HydrationTask {
427 task_id: 1,
428 tier: StreamPriorityTier::Tier0SemanticAndProcedural,
429 kind: HydrationTaskKind::VerifyEntrySha256 {
430 payload: vec![1, 2, 3],
431 expected_sha256: [0; 32],
432 },
433 };
434 assert!(matches!(
435 pool.submit(&mut token, sha_task),
436 Err(GovernancePoolError::CapabilityDenied { .. })
437 ));
438
439 let mut block = [0u8; 16];
441 block[0] = 1 << 6; pool.submit(
443 &mut token,
444 HydrationTask {
445 task_id: 20,
446 tier: StreamPriorityTier::Tier2HighPolyAndMip0,
447 kind: HydrationTaskKind::TranscodeTextureBlock {
448 codec: TranscodeCodec::Bc7,
449 block,
450 },
451 },
452 )
453 .unwrap();
454
455 let payload = b"tier0 procedural twin section".to_vec();
456 let expected_crc = crc32c(&payload);
457 pool.submit(
458 &mut token,
459 HydrationTask {
460 task_id: 10,
461 tier: StreamPriorityTier::Tier0SemanticAndProcedural,
462 kind: HydrationTaskKind::VerifySectionCrc32c {
463 payload: payload.clone(),
464 expected_crc32c: expected_crc,
465 },
466 },
467 )
468 .unwrap();
469
470 let receipts = pool.drain_bounded(4).unwrap();
471 assert_eq!(receipts.len(), 2);
472 assert_eq!(receipts[0].task_id, 10);
473 assert_eq!(receipts[1].task_id, 20);
474 assert!(receipts[1].transcoded_rgba8_4x4.is_some());
475
476 let mut rgba = [0u8; 64];
478 assert_zero_alloc("worker_pool_hot_transcode", || {
479 assert!(execute_crc_or_transcode_zero_heap(
480 Some(TranscodeCodec::Bc7),
481 &block,
482 &[],
483 0,
484 &mut rgba
485 ));
486 });
487 }
488}