Skip to main content

qualia_core_db/sensing/authority/
certificates_calibration.rs

1//! Single-application calibration series state and error definitions (C02-C05).
2
3use super::{
4    CalibrationCertificate, MAX_CALIBRATION_BATCH_SAMPLES, RationalInstant, SignalStageRelation,
5};
6use crate::sensing::SemanticId;
7
8/// Calibrated physical value state that records its `SignalStageRelation`, active
9/// stored scaling (`1.0`, `0.0` once in `PhysicalBaseUnits`), and lineage certificate digest.
10#[derive(Clone, Copy, Debug, PartialEq)]
11pub struct CalibratedSeriesState<const N: usize> {
12    stage: SignalStageRelation,
13    quantity: SemanticId,
14    unit: SemanticId,
15    units_per_stored_sample: f64,
16    stored_offset: f64,
17    lineage_certificate_digest: Option<[u8; 32]>,
18    samples: [f64; N],
19}
20
21impl<const N: usize> CalibratedSeriesState<N> {
22    /// Construct an uncalibrated `RawCounts` series (`units_per_stored_sample = 1.0`, `stored_offset = 0.0`).
23    pub fn from_raw_counts(
24        raw_quantity: SemanticId,
25        raw_unit: SemanticId,
26        samples: [f64; N],
27    ) -> Result<Self, CalibrationError> {
28        if N == 0 || N > MAX_CALIBRATION_BATCH_SAMPLES {
29            return Err(CalibrationError::InvalidBatchLength);
30        }
31        if raw_quantity.value().is_none() || raw_unit.value().is_none() {
32            return Err(CalibrationError::InvalidIdentifier);
33        }
34        if samples.iter().any(|s| !s.is_finite()) {
35            return Err(CalibrationError::NonFiniteSample);
36        }
37        Ok(Self {
38            stage: SignalStageRelation::RawCounts,
39            quantity: raw_quantity,
40            unit: raw_unit,
41            units_per_stored_sample: 1.0,
42            stored_offset: 0.0,
43            lineage_certificate_digest: None,
44            samples,
45        })
46    }
47
48    /// Re-open an already calibrated `PhysicalBaseUnits` series from storage (C02-C05, Schema 210).
49    pub fn reopen_physical_base_units(
50        physical_quantity: SemanticId,
51        physical_unit: SemanticId,
52        units_per_stored_sample: f64,
53        stored_offset: f64,
54        lineage_certificate_digest: [u8; 32],
55        samples: [f64; N],
56    ) -> Result<Self, CalibrationError> {
57        if N == 0 || N > MAX_CALIBRATION_BATCH_SAMPLES {
58            return Err(CalibrationError::InvalidBatchLength);
59        }
60        if physical_quantity.value().is_none()
61            || physical_unit.value().is_none()
62            || lineage_certificate_digest == [0u8; 32]
63        {
64            return Err(CalibrationError::InvalidIdentifier);
65        }
66        if units_per_stored_sample != 1.0 || stored_offset != 0.0 {
67            return Err(CalibrationError::PhysicalBaseUnitsRequiresIdentityScaleOffset);
68        }
69        if samples.iter().any(|s| !s.is_finite()) {
70            return Err(CalibrationError::NonFiniteSample);
71        }
72        Ok(Self {
73            stage: SignalStageRelation::PhysicalBaseUnits,
74            quantity: physical_quantity,
75            unit: physical_unit,
76            units_per_stored_sample: 1.0,
77            stored_offset: 0.0,
78            lineage_certificate_digest: Some(lineage_certificate_digest),
79            samples,
80        })
81    }
82
83    pub const fn stage(&self) -> SignalStageRelation {
84        self.stage
85    }
86    pub const fn quantity(&self) -> SemanticId {
87        self.quantity
88    }
89    pub const fn unit(&self) -> SemanticId {
90        self.unit
91    }
92    pub const fn units_per_stored_sample(&self) -> f64 {
93        self.units_per_stored_sample
94    }
95    pub const fn stored_offset(&self) -> f64 {
96        self.stored_offset
97    }
98    pub const fn lineage_certificate_digest(&self) -> Option<[u8; 32]> {
99        self.lineage_certificate_digest
100    }
101    pub const fn samples(&self) -> &[f64; N] {
102        &self.samples
103    }
104
105    /// Apply affine calibration `physical = scale * raw + offset` **exactly once**
106    /// on `RawCounts` stage at `observation_instant` (C02-C05).
107    pub fn apply_calibration_once(
108        &self,
109        cert: &CalibrationCertificate,
110        observation_instant: RationalInstant,
111        frequency_hz: Option<f64>,
112    ) -> Result<Self, CalibrationError> {
113        match self.stage {
114            SignalStageRelation::PhysicalBaseUnits => {
115                return Err(CalibrationError::DoubleCalibrationRejected);
116            }
117            SignalStageRelation::DigitalUnrelatedToPressure => {
118                return Err(CalibrationError::DigitalUnrelatedCannotCalibrateToPhysical);
119            }
120            SignalStageRelation::RawCounts => {}
121        }
122        if self.quantity != cert.input_quantity {
123            return Err(CalibrationError::InputQuantityMismatch);
124        }
125        cert.verify_applicable_at(observation_instant, frequency_hz)?;
126
127        let mut out = [0.0f64; N];
128        let mut i = 0;
129        while i < N {
130            let v = cert.affine_scale * self.samples[i] + cert.affine_offset;
131            if !v.is_finite() {
132                return Err(CalibrationError::NonFiniteSample);
133            }
134            out[i] = v;
135            i += 1;
136        }
137        Ok(Self {
138            stage: SignalStageRelation::PhysicalBaseUnits,
139            quantity: cert.output_quantity,
140            unit: cert.output_unit,
141            units_per_stored_sample: 1.0,
142            stored_offset: 0.0,
143            lineage_certificate_digest: Some(cert.certificate_digest()),
144            samples: out,
145        })
146    }
147}
148
149/// Apply single-application I/Q calibration on a complex `(I, Q)` pair (`C02-C05` / `EMF-A04`).
150pub fn calibrate_complex_iq_pair_once(
151    stage: SignalStageRelation,
152    iq_pair: (f64, f64),
153    input_quantity: SemanticId,
154    cert: &CalibrationCertificate,
155    observation_instant: RationalInstant,
156    carrier_hz: f64,
157) -> Result<((f64, f64), SignalStageRelation, f64, [u8; 32]), CalibrationError> {
158    match stage {
159        SignalStageRelation::PhysicalBaseUnits => {
160            return Err(CalibrationError::DoubleCalibrationRejected);
161        }
162        SignalStageRelation::DigitalUnrelatedToPressure => {
163            return Err(CalibrationError::DigitalUnrelatedCannotCalibrateToPhysical);
164        }
165        SignalStageRelation::RawCounts => {}
166    }
167    if cert.affine_offset != 0.0 {
168        return Err(CalibrationError::NonZeroScalarComplexOffsetRejected);
169    }
170    if input_quantity != cert.input_quantity {
171        return Err(CalibrationError::InputQuantityMismatch);
172    }
173    if !iq_pair.0.is_finite() || !iq_pair.1.is_finite() {
174        return Err(CalibrationError::NonFiniteSample);
175    }
176    cert.verify_applicable_at(observation_instant, Some(carrier_hz))?;
177    let i_cal = iq_pair.0 * cert.affine_scale;
178    let q_cal = iq_pair.1 * cert.affine_scale;
179    if !i_cal.is_finite() || !q_cal.is_finite() {
180        return Err(CalibrationError::NonFiniteSample);
181    }
182    Ok((
183        (i_cal, q_cal),
184        SignalStageRelation::PhysicalBaseUnits,
185        1.0,
186        cert.certificate_digest(),
187    ))
188}
189
190#[derive(Clone, Copy, Debug, PartialEq, Eq)]
191pub enum CalibrationError {
192    InvalidIdentifier,
193    InvalidClockInstant,
194    RationalOverflow,
195    ClockDomainMismatch,
196    InvalidValidityInterval,
197    CalibrationNotYetValid,
198    CalibrationExpiredAtOrAfterUntil,
199    ChildWindowExceedsIssuer,
200    InvalidAffineParameters,
201    InvalidReferenceLevel,
202    InvalidFrequencyBand,
203    FrequencyOutOfCalibrationBand,
204    InvalidUncertaintyKind,
205    InvalidUncertaintyValue,
206    UnlabeledUncertaintyRejected,
207    UncertaintyTargetMismatch,
208    InvalidSignature,
209    InvalidChainLength,
210    UntrustedRootAuthority,
211    BrokenParentDigestLink,
212    BrokenIssuerSubjectLink,
213    InvalidStageRelation,
214    InvalidBatchLength,
215    NonFiniteSample,
216    InputQuantityMismatch,
217    DoubleCalibrationRejected,
218    DigitalUnrelatedCannotCalibrateToPhysical,
219    PhysicalBaseUnitsRequiresIdentityScaleOffset,
220    NonZeroScalarComplexOffsetRejected,
221}