Skip to main content

qualia_core_db/sensing/
association.rs

1//! Bounded association estimates for generic entities and ontology relations.
2//!
3//! Existing identity-fabric enumeration measures anchor coverage, and epistemic
4//! certainty bytes express assertion strength; neither is a calibrated
5//! probability. This path uses an explicit host model and preserves estimates
6//! as inferred beliefs. No address, NFC identifier, or posterior authenticates
7//! an entity or proves ownership, custody, proximity, or forensic integrity.
8
9use core::num::NonZeroU64;
10
11use super::uncertainty::EvidenceReference;
12use crate::epistemic::EpistemicState;
13
14#[path = "association_contract.rs"]
15mod contract;
16pub use contract::*;
17
18pub const MAX_ASSOCIATION_HYPOTHESES: usize = 32;
19pub const MAX_ASSOCIATION_EVIDENCE: usize = 64;
20
21#[derive(Clone, Copy, Debug, PartialEq, Eq)]
22pub enum UnassessedReason {
23    NoEvidence,
24    UnknownDependence,
25    MissingDependenceGroup,
26    ModelOutsideCoverage,
27}
28
29#[derive(Clone, Copy, Debug, PartialEq)]
30pub enum AssociationResult {
31    Unassessed(UnassessedReason),
32    /// Binary P(relation holds | supplied evidence, host model and context).
33    /// Different hypotheses are not assumed exhaustive or mutually exclusive.
34    Estimated {
35        probability: f64,
36    },
37}
38
39/// Borrows exact evidence for subsequent rule/audit use; storage and signed
40/// receipts are separate operations. Policy is rechecked before publication.
41#[derive(Clone, Copy, Debug, PartialEq)]
42pub struct AssociationEstimate<'a, 'data> {
43    hypothesis: AssociationHypothesis,
44    request: AssociationRequest,
45    model: AssociationModelReference,
46    dependence: DependenceAssumption,
47    evidence: &'a [AssociationEvidence<'data>],
48    evaluation_decision: EvidenceReference,
49    policy_decision: EvidenceReference,
50    result: AssociationResult,
51}
52
53impl<'a, 'data> AssociationEstimate<'a, 'data> {
54    pub const fn hypothesis(self) -> AssociationHypothesis {
55        self.hypothesis
56    }
57    pub const fn request(self) -> AssociationRequest {
58        self.request
59    }
60    pub const fn model(self) -> AssociationModelReference {
61        self.model
62    }
63    pub const fn dependence(self) -> DependenceAssumption {
64        self.dependence
65    }
66    pub const fn evidence(self) -> &'a [AssociationEvidence<'data>] {
67        self.evidence
68    }
69    pub const fn evaluation_decision(self) -> EvidenceReference {
70        self.evaluation_decision
71    }
72    pub const fn policy_decision(self) -> EvidenceReference {
73        self.policy_decision
74    }
75    pub const fn result(self) -> AssociationResult {
76        self.result
77    }
78    pub const fn epistemic_state(self) -> EpistemicState {
79        match self.result {
80            AssociationResult::Unassessed(_) => EpistemicState::Unknown,
81            AssociationResult::Estimated { .. } => EpistemicState::InferredBelief,
82        }
83    }
84}
85
86#[derive(Clone, Copy, Debug, PartialEq, Eq)]
87pub enum AssociationError {
88    CapacityExceeded,
89    OutputTooSmall,
90    DuplicateHypothesis,
91    DuplicateEvidence,
92    InvalidEvidence,
93    PermissionUnknown,
94    PermissionDenied,
95    InvalidModelValue,
96    ImpossibleEvidence,
97    NumericalRange,
98}
99
100/// Fixed stack scratch and deterministic group-ID order. Every failure leaves
101/// the entire caller output unchanged; success writes only the returned prefix.
102/// The host authority must serialize revocation against Evaluate/Publish if
103/// its policy requires stronger atomicity than these two checks can provide.
104pub fn estimate_associations<'a, 'data>(
105    request: AssociationRequest,
106    hypotheses: &[AssociationHypothesis],
107    evidence: &'a [AssociationEvidence<'data>],
108    dependence: DependenceAssumption,
109    model: &impl CalibratedAssociationModel,
110    authority: &mut impl AssociationAuthority,
111    output: &mut [Option<AssociationEstimate<'a, 'data>>],
112) -> Result<usize, AssociationError> {
113    if hypotheses.len() > MAX_ASSOCIATION_HYPOTHESES || evidence.len() > MAX_ASSOCIATION_EVIDENCE {
114        return Err(AssociationError::CapacityExceeded);
115    }
116    if output.len() < hypotheses.len() {
117        return Err(AssociationError::OutputTooSmall);
118    }
119    validate_inputs(hypotheses, evidence)?;
120    let reference = model.reference();
121    let decision = require_permission(authority.authorize(
122        AssociationPhase::Evaluate,
123        &request,
124        hypotheses,
125        evidence,
126        reference,
127        dependence,
128    ))?;
129    let mut planned = [None; MAX_ASSOCIATION_HYPOTHESES];
130    let mut proposed_results =
131        [AssociationResult::Unassessed(UnassessedReason::NoEvidence); MAX_ASSOCIATION_HYPOTHESES];
132    for (index, hypothesis) in hypotheses.iter().enumerate() {
133        let result = estimate_one(&request, hypothesis, evidence, dependence, model)?;
134        proposed_results[index] = result;
135        planned[index] = Some(AssociationEstimate {
136            hypothesis: *hypothesis,
137            request,
138            model: reference,
139            dependence,
140            evidence,
141            evaluation_decision: decision,
142            policy_decision: decision,
143            result,
144        });
145    }
146    let final_decision = require_permission(authority.authorize(
147        AssociationPhase::Publish {
148            results: &proposed_results[..hypotheses.len()],
149            evaluation_decision: decision,
150        },
151        &request,
152        hypotheses,
153        evidence,
154        reference,
155        dependence,
156    ))?;
157    // Publish exactly the inspected results; only attach the returned receipt.
158    for estimate in planned[..hypotheses.len()].iter_mut().flatten() {
159        estimate.policy_decision = final_decision;
160    }
161    output[..hypotheses.len()].copy_from_slice(&planned[..hypotheses.len()]);
162    Ok(hypotheses.len())
163}
164
165fn require_permission(
166    permission: AssociationPermission,
167) -> Result<EvidenceReference, AssociationError> {
168    match permission {
169        AssociationPermission::Approved { decision } => Ok(decision),
170        AssociationPermission::Unknown => Err(AssociationError::PermissionUnknown),
171        AssociationPermission::Denied => Err(AssociationError::PermissionDenied),
172    }
173}
174
175fn validate_inputs(
176    hypotheses: &[AssociationHypothesis],
177    evidence: &[AssociationEvidence<'_>],
178) -> Result<(), AssociationError> {
179    for (i, hypothesis) in hypotheses.iter().enumerate() {
180        if hypotheses[..i]
181            .iter()
182            .any(|other| other.id == hypothesis.id)
183        {
184            return Err(AssociationError::DuplicateHypothesis);
185        }
186    }
187    for (i, item) in evidence.iter().enumerate() {
188        if evidence[..i]
189            .iter()
190            .any(|other| other.observation_id == item.observation_id)
191        {
192            return Err(AssociationError::DuplicateEvidence);
193        }
194        if matches!(item.value, AssociationValue::Scalar { value, .. } if !value.is_finite()) {
195            return Err(AssociationError::InvalidEvidence);
196        }
197        if let Some(uncertainty) = item.uncertainty {
198            if item.field != Some(uncertainty.field()) {
199                return Err(AssociationError::InvalidEvidence);
200            }
201        }
202    }
203    Ok(())
204}
205
206fn estimate_one(
207    request: &AssociationRequest,
208    hypothesis: &AssociationHypothesis,
209    evidence: &[AssociationEvidence<'_>],
210    dependence: DependenceAssumption,
211    model: &impl CalibratedAssociationModel,
212) -> Result<AssociationResult, AssociationError> {
213    use UnassessedReason::*;
214    let unassessed = |reason| Ok(AssociationResult::Unassessed(reason));
215    if evidence.is_empty() {
216        return unassessed(NoEvidence);
217    }
218    if dependence == DependenceAssumption::Unknown {
219        return unassessed(UnknownDependence);
220    }
221    if matches!(dependence, DependenceAssumption::IndependentGroups { .. })
222        && evidence.iter().any(|item| item.dependence_group.is_none())
223    {
224        return unassessed(MissingDependenceGroup);
225    }
226    let Some(prior) = model.prior_probability(request, hypothesis) else {
227        return unassessed(ModelOutsideCoverage);
228    };
229    if !prior.is_finite() || !(0.0..=1.0).contains(&prior) {
230        return Err(AssociationError::InvalidModelValue);
231    }
232    let mut log_yes = prior.ln();
233    let mut log_no = (-prior).ln_1p();
234    if dependence == DependenceAssumption::Joint {
235        let group = AssociationEvidenceGroup {
236            evidence,
237            group: None,
238        };
239        let Some(likelihoods) = model.joint_log_likelihoods(request, hypothesis, group) else {
240            return unassessed(ModelOutsideCoverage);
241        };
242        add_likelihoods(&mut log_yes, &mut log_no, likelihoods)?;
243    } else {
244        let mut previous: Option<NonZeroU64> = None;
245        for _ in 0..evidence.len() {
246            let next = evidence
247                .iter()
248                .filter_map(|item| item.dependence_group)
249                .filter(|id| previous.is_none_or(|previous| *id > previous))
250                .min();
251            let Some(id) = next else {
252                break;
253            };
254            let group = AssociationEvidenceGroup {
255                evidence,
256                group: Some(id),
257            };
258            let Some(likelihoods) = model.joint_log_likelihoods(request, hypothesis, group) else {
259                return unassessed(ModelOutsideCoverage);
260            };
261            add_likelihoods(&mut log_yes, &mut log_no, likelihoods)?;
262            previous = Some(id);
263        }
264    }
265    if log_yes == f64::NEG_INFINITY && log_no == f64::NEG_INFINITY {
266        return Err(AssociationError::ImpossibleEvidence);
267    }
268    let probability = if log_yes >= log_no {
269        1.0 / (1.0 + (log_no - log_yes).exp())
270    } else {
271        let odds = (log_yes - log_no).exp();
272        odds / (1.0 + odds)
273    };
274    // Finite evidence cannot establish an exact endpoint. Do not silently
275    // publish floating-point saturation as model certainty.
276    if log_yes.is_finite() && log_no.is_finite() && (probability == 0.0 || probability == 1.0) {
277        return Err(AssociationError::NumericalRange);
278    }
279    Ok(AssociationResult::Estimated { probability })
280}
281
282fn add_likelihoods(
283    yes: &mut f64,
284    no: &mut f64,
285    likelihoods: BinaryLogLikelihoods,
286) -> Result<(), AssociationError> {
287    for value in [
288        likelihoods.given_association,
289        likelihoods.given_no_association,
290    ] {
291        if value.is_nan() || value == f64::INFINITY {
292            return Err(AssociationError::InvalidModelValue);
293        }
294    }
295    *yes = add_log(*yes, likelihoods.given_association)?;
296    *no = add_log(*no, likelihoods.given_no_association)?;
297    Ok(())
298}
299
300fn add_log(left: f64, right: f64) -> Result<f64, AssociationError> {
301    if left == f64::NEG_INFINITY || right == f64::NEG_INFINITY {
302        return Ok(f64::NEG_INFINITY);
303    }
304    let sum = left + right;
305    if !sum.is_finite() {
306        return Err(AssociationError::NumericalRange);
307    }
308    Ok(sum)
309}
310
311#[cfg(test)]
312#[path = "association_tests.rs"]
313mod tests;