Skip to main content

qualia_core_db/sensing/acquisition/
metadata.rs

1use super::{Error, ExactTime, Rate, Timing};
2use crate::sensing::SemanticId;
3/// Full-content reference; identifier is a registry key, not an integrity proof.
4#[derive(Clone, Copy, Debug, PartialEq, Eq)]
5pub struct ArtifactLink {
6    pub digest: [u8; 32],
7    pub identifier: SemanticId,
8}
9impl ArtifactLink {
10    pub fn validate(self) -> Result<(), Error> {
11        self.identifier.value().ok_or(Error::Identity).map(|_| ())
12    }
13}
14#[derive(Clone, Copy, Debug, PartialEq, Eq)]
15pub struct Quantity {
16    pub kind: SemanticId,
17    pub unit: SemanticId,
18}
19impl Quantity {
20    pub fn require_known(self) -> Result<(), Error> {
21        self.kind.value().ok_or(Error::Semantics)?;
22        self.unit.value().ok_or(Error::Semantics)?;
23        Ok(())
24    }
25}
26/// References are reported lineage only: no implicit affine conversion or traceability.
27#[derive(Clone, Copy, Debug, PartialEq, Eq)]
28pub enum SampleStage {
29    RawCodes,
30    ReportedPhysical,
31    DerivedPhysical,
32}
33#[derive(Clone, Copy, Debug, PartialEq, Eq)]
34pub struct UncertaintyLink {
35    pub artifact: ArtifactLink,
36    pub target: Quantity,
37}
38#[derive(Clone, Copy, Debug, PartialEq, Eq)]
39pub struct Context {
40    pub quantity: Quantity,
41    pub stage: SampleStage,
42    pub sensor: SemanticId,
43    pub geometry: Option<ArtifactLink>,
44    pub calibration: Option<ArtifactLink>,
45    /// Uncertainty artifact owns target quantity/component, unit, estimator and correlations.
46    pub uncertainty: Option<UncertaintyLink>,
47}
48impl Context {
49    pub fn validate(self) -> Result<(), Error> {
50        if let Some(u) = self.uncertainty {
51            u.artifact.validate()?;
52            u.target.require_known()?;
53            if u.target != self.quantity {
54                return Err(Error::Semantics);
55            }
56        }
57        for link in [self.geometry, self.calibration].into_iter().flatten() {
58            link.validate()?;
59        }
60        Ok(())
61    }
62}
63/// Clock origin/restart identity is mandatory; equal numeric epochs do not imply a join.
64#[derive(Clone, Copy, Debug, PartialEq, Eq)]
65pub struct Clock {
66    origin: SemanticId,
67    restart: u64,
68    timing: Timing,
69}
70impl Clock {
71    pub fn new(origin: SemanticId, restart: u64, timing: Timing) -> Result<Self, Error> {
72        origin.value().ok_or(Error::Identity)?;
73        timing.time_at(0).map_err(|_| Error::Clock)?;
74        Ok(Self {
75            origin,
76            restart,
77            timing,
78        })
79    }
80    pub fn origin(self) -> SemanticId {
81        self.origin
82    }
83    pub fn restart(self) -> u64 {
84        self.restart
85    }
86    pub fn timing(self) -> Timing {
87        self.timing
88    }
89    pub fn time_at(self, index: u64) -> Result<ExactTime, Error> {
90        self.timing.time_at(index).map_err(|_| Error::Clock)
91    }
92    pub fn tick_time(self, tick: i64) -> Result<ExactTime, Error> {
93        Timing {
94            start_tick: tick,
95            ..self.timing
96        }
97        .time_at(0)
98        .map_err(|_| Error::Clock)
99    }
100    pub fn require_same_domain(self, other: Self) -> Result<(), Error> {
101        if self.origin != other.origin
102            || self.restart != other.restart
103            || self.timing.scale != other.timing.scale
104            || self.timing.epoch_seconds != other.timing.epoch_seconds
105            || self.timing.epoch_nanoseconds != other.timing.epoch_nanoseconds
106            || self.timing.ticks != other.timing.ticks
107        {
108            return Err(Error::Clock);
109        }
110        Ok(())
111    }
112}
113/// Absence, unknown carrier, and a reported static field are distinct.
114#[derive(Clone, Copy, Debug, PartialEq)]
115pub enum Carrier {
116    Unknown,
117    AperiodicOrStatic,
118    Hertz(f64),
119}
120#[derive(Clone, Copy, Debug, PartialEq, Eq)]
121pub enum ComplexConvention {
122    RealPlusIImagPositiveExponent,
123    RealPlusIImagNegativeExponent,
124}
125/// Baseband bounds are signed offsets; never interchangeable with carrier or cadence.
126#[derive(Clone, Copy, Debug, PartialEq)]
127pub struct SignalAxes {
128    pub carrier: Carrier,
129    pub baseband_hz: Option<[f64; 2]>,
130    pub pulse_rate: Option<Rate>,
131    pub complex_convention: Option<ComplexConvention>,
132    pub phase_origin: Option<ArtifactLink>,
133}
134impl SignalAxes {
135    pub fn validate(self) -> Result<(), Error> {
136        if let Carrier::Hertz(hz) = self.carrier {
137            if !hz.is_finite() || hz <= 0.0 {
138                return Err(Error::Semantics);
139            }
140        }
141        if let Some([lo, hi]) = self.baseband_hz {
142            if !lo.is_finite() || !hi.is_finite() || lo >= hi {
143                return Err(Error::Semantics);
144            }
145        }
146        if let Some(r) = self.pulse_rate {
147            Rate::new(r.numerator, r.denominator).map_err(|_| Error::Clock)?;
148        }
149        if let Some(r) = self.phase_origin {
150            r.validate()?;
151        }
152        Ok(())
153    }
154}