Skip to main content

qualia_core_db/governance/
worker_pool.rs

1//! Webizen-governed worker pool for background `.hmc` / `.10d` / `.q42` hydration.
2//!
3//! Enforces deontic capability tokens ([`HydrationCapabilityToken`]), fuel budgets,
4//! and byte budgets across three priority tiers ([`StreamPriorityTier`]) so that
5//! CRC-32C section verification, SHA-256 entry checks, and KTX2 block transcoding
6//! never exceed the caller's authorized compute or memory envelope.
7
8use 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
17/// Capability bit: verify `.10d` section CRC-32C checksums.
18pub const CAP_VERIFY_CRC32C: u32 = 1 << 0;
19/// Capability bit: verify `.hmc` entry SHA-256 digests.
20pub const CAP_VERIFY_SHA256: u32 = 1 << 1;
21/// Capability bit: decode `.10d` mesh / morph / skeleton sections.
22pub const CAP_DECODE_MESH_10D: u32 = 1 << 2;
23/// Capability bit: transcode KTX2 (BC7 / ETC2 / ASTC) compressed texture blocks.
24pub const CAP_TRANSCODE_KTX2: u32 = 1 << 3;
25/// Capability bit: admit `.q42` semantic slices.
26pub const CAP_ADMIT_Q42_SLICE: u32 = 1 << 4;
27/// All hydration capabilities enabled.
28pub 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/// Deontic capability token governing background hydration tasks.
35#[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    /// Construct and seal a new capability token for `holder_did_hash`.
49    #[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    /// Verify that the token seal has not been tampered with.
93    #[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    /// Deduct `fuel_cost` and `byte_cost` after checking `required_cap` and `tier`, updating the seal.
106    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/// Errors raised when scheduling or executing governed hydration work.
154#[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/// Compressed block codec for governed zero-heap texture transcoding.
166#[derive(Debug, Clone, Copy, PartialEq, Eq)]
167pub enum TranscodeCodec {
168    Bc7,
169    Etc2EacRgba8,
170    Astc4x4,
171}
172
173/// Hydration task descriptor queued into [`GovernedHydrationPool`].
174#[derive(Debug, Clone)]
175pub enum HydrationTaskKind {
176    /// Verify `.10d` section CRC-32C checksum.
177    VerifySectionCrc32c {
178        payload: Vec<u8>,
179        expected_crc32c: u32,
180    },
181    /// Verify `.hmc` entry SHA-256 digest.
182    VerifyEntrySha256 {
183        payload: Vec<u8>,
184        expected_sha256: [u8; 32],
185    },
186    /// Transcode a 16-byte compressed texture block to a 64-byte 4x4 RGBA8 tile.
187    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/// Queued task with priority tier and unique identifier.
227#[derive(Debug, Clone)]
228pub struct HydrationTask {
229    pub task_id: u64,
230    pub tier: StreamPriorityTier,
231    pub kind: HydrationTaskKind,
232}
233
234/// Completed task receipt returned by the governed worker pool.
235#[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/// Zero-heap hot execution kernel for a single 16-byte texture block or CRC-32C slice check.
244#[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
265/// Webizen-governed 3-tier hydration worker pool.
266pub struct GovernedHydrationPool {
267    queues: [VecDeque<HydrationTask>; 3],
268    max_queue_capacity: usize,
269    completed_count: u64,
270}
271
272impl GovernedHydrationPool {
273    /// Create a new governed hydration pool with bounded per-tier queue capacity.
274    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    /// Submit a hydration task after authorizing and deducting fuel + byte budgets from `token`.
288    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    /// Number of pending tasks across all tiers.
310    #[inline]
311    pub fn pending_count(&self) -> usize {
312        self.queues[0].len() + self.queues[1].len() + self.queues[2].len()
313    }
314
315    /// Total tasks completed so far.
316    #[inline]
317    pub fn completed_count(&self) -> u64 {
318        self.completed_count
319    }
320
321    /// Pop the highest-priority pending task (`Tier0` -> `Tier1` -> `Tier2`) and execute it.
322    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    /// Drain up to `max_tasks` in strict priority order (`Tier0` before `Tier1` before `Tier2`).
392    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        // Unauthorized SHA-256 task is rejected fail-closed
426        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        // Submit Tier 2 transcode first, then Tier 0 CRC check; Tier 0 must execute first!
440        let mut block = [0u8; 16];
441        block[0] = 1 << 6; // BC7 Mode 6
442        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        // Hot kernel is zero-heap
477        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}