Skip to main content

qualia_vision/recipes/
biosense_observation_quins.rs

1//! Compile biosense HR results into epistemic VisionQuin observations (E1).
2//!
3//! Not ground truth — proposals with confidence in metadata low bits.
4//! Fail-closed: consent + deontic `ProcessingAct::Rppg` must Permit.
5
6use crate::biosense::{
7    evaluate_processing_act, BiosenseConsent, HrEstimate, PolicyDecision, ProcessingAct,
8};
9use crate::cv::error::CvError;
10use crate::semantic::{q_hash, VisionQuin, CTX_VISION};
11
12const P_PROPOSES_HR: &str = "https://ns.webizen.org/q42/proposesHeartRateBpm";
13const P_HR_CONFIDENCE: &str = "https://ns.webizen.org/q42/heartRateConfidence";
14const P_HR_SNR: &str = "https://ns.webizen.org/q42/heartRateSnr";
15
16/// Pack f32 into object field (low 32 bits of bits pattern) + reserved float-family tag.
17fn pack_f32_object(v: f32) -> u64 {
18    (v.to_bits() as u64) | (0x5u64 << 60)
19}
20
21/// Emit observation quins for an HR estimate after deontic gate.
22///
23/// Returns number written (3 on success), or error if consent/policy denies
24/// or the output buffer is too small.
25pub fn compile_hr_observation_quins(
26    consent: BiosenseConsent,
27    media_subject: u64,
28    hr: &HrEstimate,
29    out: &mut [VisionQuin],
30) -> Result<usize, CvError> {
31    if !consent.may_process() {
32        return Err(CvError::InvalidParameter);
33    }
34    // Deontic: rPPG is only permitted for WellfairSelfMonitor / Research purposes.
35    let decision = evaluate_processing_act(consent, ProcessingAct::Rppg);
36    if decision != PolicyDecision::Permit {
37        return Err(CvError::InvalidParameter);
38    }
39    if out.len() < 3 {
40        return Err(CvError::BufferTooSmall);
41    }
42
43    let ctx = q_hash(CTX_VISION);
44    let conf_meta = ((hr.confidence.clamp(0.0, 1.0) * 255.0) as u64).min(255);
45    out[0] = VisionQuin::with_parity(
46        media_subject,
47        q_hash(P_PROPOSES_HR),
48        pack_f32_object(hr.bpm),
49        ctx,
50        conf_meta,
51    );
52    out[1] = VisionQuin::with_parity(
53        media_subject,
54        q_hash(P_HR_CONFIDENCE),
55        pack_f32_object(hr.confidence),
56        ctx,
57        0,
58    );
59    out[2] = VisionQuin::with_parity(
60        media_subject,
61        q_hash(P_HR_SNR),
62        pack_f32_object(hr.snr),
63        ctx,
64        0,
65    );
66    Ok(3)
67}
68
69#[cfg(test)]
70mod tests {
71    use super::*;
72    use crate::biosense::{BiosenseConsent, BiosensePurpose, HrEstimate};
73
74    #[test]
75    fn no_consent_fails() {
76        let hr = HrEstimate {
77            bpm: 60.0,
78            confidence: 0.9,
79            snr: 5.0,
80        };
81        let mut out = [VisionQuin::with_parity(0, 0, 0, 0, 0); 8];
82        let c = BiosenseConsent::denied(BiosensePurpose::WellfairSelfMonitor);
83        assert!(compile_hr_observation_quins(c, 1, &hr, &mut out).is_err());
84    }
85
86    #[test]
87    fn security_purpose_forbids_rppg() {
88        let hr = HrEstimate {
89            bpm: 72.0,
90            confidence: 0.8,
91            snr: 4.0,
92        };
93        let mut out = [VisionQuin::with_parity(0, 0, 0, 0, 0); 8];
94        let c = BiosenseConsent::grant_security_template(1);
95        assert!(compile_hr_observation_quins(c, 0xABC, &hr, &mut out).is_err());
96    }
97
98    #[test]
99    fn self_monitor_emits_three() {
100        let hr = HrEstimate {
101            bpm: 72.0,
102            confidence: 0.8,
103            snr: 4.0,
104        };
105        let mut out = [VisionQuin::with_parity(0, 0, 0, 0, 0); 8];
106        let c = BiosenseConsent::grant_process(BiosensePurpose::WellfairSelfMonitor, 42);
107        let n = compile_hr_observation_quins(c, 0xABC, &hr, &mut out).expect("permit");
108        assert_eq!(n, 3);
109        assert_ne!(out[0].parity, 0);
110        assert_ne!(out[0].predicate, 0);
111    }
112
113    #[test]
114    fn buffer_too_small() {
115        let hr = HrEstimate {
116            bpm: 60.0,
117            confidence: 0.5,
118            snr: 2.0,
119        };
120        let mut out = [VisionQuin::with_parity(0, 0, 0, 0, 0); 2];
121        let c = BiosenseConsent::grant_process(BiosensePurpose::Research, 1);
122        assert!(matches!(
123            compile_hr_observation_quins(c, 1, &hr, &mut out),
124            Err(CvError::BufferTooSmall)
125        ));
126    }
127}