Skip to main content

wellfare_core/anatomy/
observations.rs

1//! Extensible **body observations** — measurements and attributes from the person
2//! or from instruments (scale, tape, watch, clinical device, camera).
3//!
4//! New instruments add a **code** (LOINC / house IRI), not a new struct field.
5//! Drawing on the anatomy model requires a curated [`RepresentationBind`]. An
6//! unknown code is stored and listed; it is not painted.
7
8use qualia_cooperative_core::contextual_assertion::{
9    AssertionStatus, ContextualAssertion, StatementType, VerificationStatus,
10};
11use qualia_cooperative_core::contextual_evidence::{
12    BiologicalScope, ClaimBasis, EpistemicTier, EvidenceDetail, EvidenceValue, EvidencedAssertion,
13    ObservationMethod, ObserverRole, TemporalObservationAxis, TemporalStabilityClass, Uncertainty,
14};
15use serde::{Deserialize, Serialize};
16
17use crate::clinical::ClaimStatus;
18use crate::record::{
19    EpistemicStatus, EvidenceType, InstantBridge, RecordEnvelope, SensitivityClass,
20};
21
22/// Where a value came from. Extensible via [`InstrumentKind::Other`].
23#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
24#[serde(rename_all = "snake_case")]
25pub enum InstrumentKind {
26    /// The person typed or declared it.
27    Declared,
28    Scale,
29    Tape,
30    Watch,
31    ClinicalDevice,
32    Camera,
33    Other(String),
34}
35
36/// How (if at all) this observation may affect the rendered body.
37/// Closed on purpose: a new watch metric does not get a new shader until
38/// a bind is curated.
39#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
40#[serde(rename_all = "snake_case")]
41pub enum RepresentationBind {
42    /// Stored only — the default for unknown codes.
43    None,
44    /// Drives [`super::constitution::BodyFit`] stature.
45    FitStature,
46    /// Reserved for a future weight morph (not implemented).
47    FitWeight,
48    /// Tints eye meshes if present.
49    AppearanceEye,
50    /// Tints hair meshes if present.
51    AppearanceHair,
52    /// Tints skin envelope if present (declared; not a race code).
53    AppearanceSkin,
54    /// Pulse / rate overlay on the circulatory system.
55    CirculatoryRate,
56    /// Informs graph considerations (prevalence, pharmacology, screening).
57    /// **Never** the mesh shape, karyotype, or a skin/hair tint.
58    KnowledgeContext,
59    /// Generic overlay on a named body-system id.
60    OverlayOnSystem { system_id: String },
61}
62
63/// One coded observation about the subject. Integer value + UCUM unit
64/// (no float health arithmetic in the record).
65#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
66pub struct BodyObservation {
67    /// LOINC, UCUM-backed house IRI, or `q42:` token.
68    pub code: String,
69    pub value_milli: i64,
70    /// UCUM or a short token (`mm`, `g`, `bpm`, `{named}`).
71    pub unit: String,
72    pub instrument: InstrumentKind,
73    pub at_unix: u32,
74    /// Optional human caption (“left wrist watch”).
75    #[serde(default, skip_serializing_if = "Option::is_none")]
76    pub note: Option<String>,
77    /// Named value for `{named}` codes (ethnicity, eye/hair/skin). Integer `value_milli` stays 0.
78    #[serde(default, skip_serializing_if = "Option::is_none")]
79    pub named: Option<String>,
80}
81
82/// A seed code the environment already knows how to bind.
83#[derive(Debug, Clone, Copy, PartialEq, Eq)]
84pub struct KnownObservationCode {
85    pub code: &'static str,
86    pub label: &'static str,
87    pub unit: &'static str,
88    pub bind: RepresentationBindSeed,
89}
90
91/// Copy-friendly bind for the seed table (`OverlayOnSystem` is not in the seed).
92#[derive(Debug, Clone, Copy, PartialEq, Eq)]
93pub enum RepresentationBindSeed {
94    None,
95    FitStature,
96    FitWeight,
97    AppearanceEye,
98    AppearanceHair,
99    AppearanceSkin,
100    CirculatoryRate,
101    KnowledgeContext,
102}
103
104impl RepresentationBindSeed {
105    /// Converts into a bind.
106    pub fn into_bind(self) -> RepresentationBind {
107        match self {
108            Self::None => RepresentationBind::None,
109            Self::FitStature => RepresentationBind::FitStature,
110            Self::FitWeight => RepresentationBind::FitWeight,
111            Self::AppearanceEye => RepresentationBind::AppearanceEye,
112            Self::AppearanceHair => RepresentationBind::AppearanceHair,
113            Self::AppearanceSkin => RepresentationBind::AppearanceSkin,
114            Self::CirculatoryRate => RepresentationBind::CirculatoryRate,
115            Self::KnowledgeContext => RepresentationBind::KnowledgeContext,
116        }
117    }
118}
119
120/// Seed binds. New instruments: add a row here or register via the graph (W16).
121pub const KNOWN_OBSERVATION_CODES: &[KnownObservationCode] = &[
122    KnownObservationCode {
123        code: "8302-2",
124        label: "body height",
125        unit: "mm",
126        bind: RepresentationBindSeed::FitStature,
127    },
128    KnownObservationCode {
129        code: "29463-7",
130        label: "body weight",
131        unit: "g",
132        bind: RepresentationBindSeed::FitWeight,
133    },
134    KnownObservationCode {
135        code: "8867-4",
136        label: "heart rate",
137        unit: "/min",
138        bind: RepresentationBindSeed::CirculatoryRate,
139    },
140    KnownObservationCode {
141        code: "q42:eye-colour",
142        label: "eye colour (declared)",
143        unit: "{named}",
144        bind: RepresentationBindSeed::AppearanceEye,
145    },
146    KnownObservationCode {
147        code: "q42:hair-colour",
148        label: "hair colour (declared)",
149        unit: "{named}",
150        bind: RepresentationBindSeed::AppearanceHair,
151    },
152    KnownObservationCode {
153        code: "q42:skin-tone",
154        label: "skin tone (declared; not inferred from ethnicity)",
155        unit: "{named}",
156        bind: RepresentationBindSeed::AppearanceSkin,
157    },
158    KnownObservationCode {
159        code: "q42:ethnicity",
160        label: "self-identified ethnicity (declared, repeatable)",
161        unit: "{named}",
162        bind: RepresentationBindSeed::KnowledgeContext,
163    },
164    KnownObservationCode {
165        code: "q42:genetic-ancestry",
166        label: "genetic ancestry context (only if the person imported a record)",
167        unit: "{named}",
168        bind: RepresentationBindSeed::KnowledgeContext,
169    },
170    KnownObservationCode {
171        code: "38265-5",
172        label: "DEXA areal bone mineral density",
173        unit: "g/cm2",
174        bind: RepresentationBindSeed::None,
175    },
176    KnownObservationCode {
177        code: "q42:qct-vbmd",
178        label: "QCT volumetric bone mineral density",
179        unit: "mg/cm3",
180        bind: RepresentationBindSeed::None,
181    },
182    KnownObservationCode {
183        code: "q42:muscle-hu",
184        label: "CT skeletal muscle radiodensity",
185        unit: "[hnsf'U]",
186        bind: RepresentationBindSeed::None,
187    },
188];
189
190/// Bind for a code. Unknown → [`RepresentationBind::None`] (extensible store).
191pub fn bind_for_code(code: &str) -> RepresentationBind {
192    KNOWN_OBSERVATION_CODES
193        .iter()
194        .find(|k| k.code == code.trim())
195        .map(|k| k.bind.into_bind())
196        .unwrap_or(RepresentationBind::None)
197}
198
199///  when known-code.
200pub fn is_known_code(code: &str) -> bool {
201    KNOWN_OBSERVATION_CODES
202        .iter()
203        .any(|k| k.code == code.trim())
204}
205
206// ===========================================================================
207// BIO-WP-05: Evidenced Anatomical Observation Adapter & Sovereign Sealing
208// ===========================================================================
209
210/// Enforce sovereign biomedical privacy: personal/clinical anatomical records are
211/// never sealed as `SensitivityClass::Public` (upgraded to `Restricted`, while
212/// preserving `Classified`).
213fn enforce_private_sensitivity(sensitivity: SensitivityClass) -> SensitivityClass {
214    match sensitivity {
215        SensitivityClass::Public => SensitivityClass::Restricted,
216        SensitivityClass::Restricted => SensitivityClass::Restricted,
217        SensitivityClass::Classified => SensitivityClass::Classified,
218    }
219}
220
221/// Subject-scoped anatomical or densitometric observation wrapping
222/// [`EvidenceDetail`] (7-tier [`EpistemicTier`], `q42m:*` [`ObservationMethod`],
223/// [`ObserverRole`], and 4-axis [`TemporalObservationAxis`]).
224#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
225pub struct AnatomicalObservationRecord {
226    pub id: String,
227    pub subject_uri: String,
228    pub root_source_id: String,
229    pub scope_domain: String,
230    #[serde(default)]
231    pub derived_from_assertion_ids: Vec<String>,
232    pub sensitivity: SensitivityClass,
233    #[serde(default, skip_serializing_if = "Option::is_none")]
234    pub claim_status: Option<ClaimStatus>,
235    #[serde(default, skip_serializing_if = "Option::is_none")]
236    pub summary_label: Option<String>,
237    pub evidence: EvidenceDetail,
238}
239
240impl AnatomicalObservationRecord {
241    /// Physical anthropometry observation via flexible anthropometric tape measure.
242    #[allow(clippy::too_many_arguments)]
243    pub fn from_tape_measure(
244        id: impl Into<String>,
245        subject_uri: impl Into<String>,
246        property_iri: impl Into<String>,
247        value_mm: f64,
248        observer_role: ObserverRole,
249        phenomenon_time_ms: i64,
250        uncertainty_mm: Option<f64>,
251        part_iri: Option<String>,
252    ) -> Result<Self, String> {
253        let id = id.into();
254        let subject_uri = subject_uri.into();
255        let property_iri = property_iri.into();
256        if id.trim().is_empty() || subject_uri.trim().is_empty() {
257            return Err("id and subject_uri are required".into());
258        }
259        if !value_mm.is_finite() || value_mm <= 0.0 {
260            return Err("tape measure value_mm must be finite and positive".into());
261        }
262        let uncertainty = match uncertainty_mm {
263            Some(sd) => {
264                if !sd.is_finite() || sd < 0.0 {
265                    return Err("uncertainty_mm must be finite and non-negative".into());
266                }
267                Some(Uncertainty {
268                    standard_deviation: Some(sd),
269                    interval_confidence: Some(0.95),
270                    ..Default::default()
271                })
272            }
273            None => None,
274        };
275        let axis = TemporalObservationAxis::with_stability_class(
276            phenomenon_time_ms,
277            TemporalStabilityClass::SubacuteMetabolicGravidAndHealing,
278        );
279        let detail = EvidenceDetail {
280            property_iri,
281            basis: ClaimBasis::Measured,
282            value: Some(EvidenceValue::Quantity {
283                value: value_mm,
284                unit_iri: "http://qudt.org/vocab/unit/MilliM".into(),
285            }),
286            uncertainty,
287            method_iri: Some(ObservationMethod::FlexibleTapeCircumference.as_iri()),
288            scope: BiologicalScope {
289                part_iri,
290                individual_iri: Some(subject_uri.clone()),
291                ..Default::default()
292            },
293            epistemic_tier: Some(EpistemicTier::DirectlyObserved),
294            observation_method: Some(ObservationMethod::FlexibleTapeCircumference),
295            observer_role: Some(observer_role),
296            temporal_axis: Some(axis),
297            stability_class: Some(TemporalStabilityClass::SubacuteMetabolicGravidAndHealing),
298            ..Default::default()
299        };
300        detail.validate()?;
301        Ok(Self {
302            id: id.clone(),
303            subject_uri,
304            root_source_id: format!("src:tape:{id}"),
305            scope_domain: "welfare:anatomy:anthropometry".into(),
306            derived_from_assertion_ids: Vec::new(),
307            sensitivity: SensitivityClass::Restricted,
308            claim_status: None,
309            summary_label: Some("tape-measure anthropometry".into()),
310            evidence: detail,
311        })
312    }
313
314    /// Clinical DEXA areal bone mineral density (`g/cm^2`) observation.
315    #[allow(clippy::too_many_arguments)]
316    pub fn from_dexa_scan(
317        id: impl Into<String>,
318        subject_uri: impl Into<String>,
319        property_iri: impl Into<String>,
320        areal_bmd_g_cm2: f64,
321        phenomenon_time_ms: i64,
322        acquisition_time_ms: Option<i64>,
323        part_iri: Option<String>,
324        root_source_id: impl Into<String>,
325    ) -> Result<Self, String> {
326        let id = id.into();
327        let subject_uri = subject_uri.into();
328        let property_iri = property_iri.into();
329        let root_source_id = root_source_id.into();
330        if id.trim().is_empty()
331            || subject_uri.trim().is_empty()
332            || root_source_id.trim().is_empty()
333        {
334            return Err("id, subject_uri, and root_source_id are required".into());
335        }
336        if !areal_bmd_g_cm2.is_finite() || areal_bmd_g_cm2 < 0.0 {
337            return Err("areal_bmd_g_cm2 must be finite and non-negative".into());
338        }
339        let mut axis = TemporalObservationAxis::with_stability_class(
340            phenomenon_time_ms,
341            TemporalStabilityClass::OntogeneticAndSkeletalRemodeling,
342        );
343        axis.acquisition_time_ms = acquisition_time_ms;
344        let detail = EvidenceDetail {
345            property_iri,
346            basis: ClaimBasis::Measured,
347            value: Some(EvidenceValue::Quantity {
348                value: areal_bmd_g_cm2,
349                unit_iri: "http://qudt.org/vocab/unit/GM-PER-CentiM2".into(),
350            }),
351            method_iri: Some(ObservationMethod::DexaArealDensitometry.as_iri()),
352            scope: BiologicalScope {
353                part_iri,
354                individual_iri: Some(subject_uri.clone()),
355                ..Default::default()
356            },
357            epistemic_tier: Some(EpistemicTier::DirectlyObserved),
358            observation_method: Some(ObservationMethod::DexaArealDensitometry),
359            observer_role: Some(ObserverRole::ClinicianMeasured),
360            temporal_axis: Some(axis),
361            stability_class: Some(TemporalStabilityClass::OntogeneticAndSkeletalRemodeling),
362            ..Default::default()
363        };
364        detail.validate()?;
365        Ok(Self {
366            id,
367            subject_uri,
368            root_source_id,
369            scope_domain: "welfare:anatomy:densitometry:dexa".into(),
370            derived_from_assertion_ids: Vec::new(),
371            sensitivity: SensitivityClass::Restricted,
372            claim_status: Some(ClaimStatus::ClinicianConfirmed),
373            summary_label: Some("DEXA areal BMD".into()),
374            evidence: detail,
375        })
376    }
377
378    /// Quantitative CT volumetric bone mineral density (`mg HA/cm^3`) voxel observation.
379    #[allow(clippy::too_many_arguments)]
380    pub fn from_qct_voxel(
381        id: impl Into<String>,
382        subject_uri: impl Into<String>,
383        property_iri: impl Into<String>,
384        volumetric_bmd_mg_ha_cm3: f64,
385        phenomenon_time_ms: i64,
386        acquisition_time_ms: Option<i64>,
387        part_iri: Option<String>,
388        root_source_id: impl Into<String>,
389    ) -> Result<Self, String> {
390        let id = id.into();
391        let subject_uri = subject_uri.into();
392        let property_iri = property_iri.into();
393        let root_source_id = root_source_id.into();
394        if id.trim().is_empty()
395            || subject_uri.trim().is_empty()
396            || root_source_id.trim().is_empty()
397        {
398            return Err("id, subject_uri, and root_source_id are required".into());
399        }
400        if !volumetric_bmd_mg_ha_cm3.is_finite() || volumetric_bmd_mg_ha_cm3 < 0.0 {
401            return Err("volumetric_bmd_mg_ha_cm3 must be finite and non-negative".into());
402        }
403        let mut axis = TemporalObservationAxis::with_stability_class(
404            phenomenon_time_ms,
405            TemporalStabilityClass::OntogeneticAndSkeletalRemodeling,
406        );
407        axis.acquisition_time_ms = acquisition_time_ms;
408        let detail = EvidenceDetail {
409            property_iri,
410            basis: ClaimBasis::Measured,
411            value: Some(EvidenceValue::Quantity {
412                value: volumetric_bmd_mg_ha_cm3,
413                unit_iri: "http://qudt.org/vocab/unit/MilliGM-PER-CentiM3".into(),
414            }),
415            method_iri: Some(ObservationMethod::ClinicalCtQuantitativeQct.as_iri()),
416            scope: BiologicalScope {
417                part_iri,
418                individual_iri: Some(subject_uri.clone()),
419                ..Default::default()
420            },
421            epistemic_tier: Some(EpistemicTier::DirectlyObserved),
422            observation_method: Some(ObservationMethod::ClinicalCtQuantitativeQct),
423            observer_role: Some(ObserverRole::ClinicianMeasured),
424            temporal_axis: Some(axis),
425            stability_class: Some(TemporalStabilityClass::OntogeneticAndSkeletalRemodeling),
426            ..Default::default()
427        };
428        detail.validate()?;
429        Ok(Self {
430            id,
431            subject_uri,
432            root_source_id,
433            scope_domain: "welfare:anatomy:densitometry:qct".into(),
434            derived_from_assertion_ids: Vec::new(),
435            sensitivity: SensitivityClass::Restricted,
436            claim_status: Some(ClaimStatus::ClinicianConfirmed),
437            summary_label: Some("QCT volumetric BMD".into()),
438            evidence: detail,
439        })
440    }
441
442    /// Clinical FHIR / EHR / narrative record extraction preserving documentary provenance
443    /// and [`ClaimStatus`] honesty (unconfirmed records never launder into clinician evidence).
444    #[allow(clippy::too_many_arguments)]
445    pub fn from_clinical_record(
446        id: impl Into<String>,
447        subject_uri: impl Into<String>,
448        property_iri: impl Into<String>,
449        value: EvidenceValue,
450        claim_status: ClaimStatus,
451        reported_method: Option<ObservationMethod>,
452        phenomenon_time_ms: i64,
453        extraction_time_ms: i64,
454        source_document_id: impl Into<String>,
455    ) -> Result<Self, String> {
456        let id = id.into();
457        let subject_uri = subject_uri.into();
458        let property_iri = property_iri.into();
459        let source_document_id = source_document_id.into();
460        if id.trim().is_empty()
461            || subject_uri.trim().is_empty()
462            || source_document_id.trim().is_empty()
463        {
464            return Err("id, subject_uri, and source_document_id are required".into());
465        }
466        let method = reported_method.unwrap_or(ObservationMethod::ElectronicHealthRecordFhir);
467        let mut axis = TemporalObservationAxis::with_stability_class(
468            phenomenon_time_ms,
469            TemporalStabilityClass::OntogeneticAndSkeletalRemodeling,
470        );
471        axis.extraction_time_ms = Some(extraction_time_ms);
472        let detail = EvidenceDetail {
473            property_iri,
474            basis: ClaimBasis::Described,
475            value: Some(value),
476            method_iri: Some(method.as_iri()),
477            scope: BiologicalScope {
478                individual_iri: Some(subject_uri.clone()),
479                ..Default::default()
480            },
481            source_record_id: Some(source_document_id.clone()),
482            epistemic_tier: Some(EpistemicTier::ExtractedFromRecord),
483            observation_method: Some(method),
484            observer_role: Some(ObserverRole::CuratorExtracted),
485            temporal_axis: Some(axis),
486            stability_class: Some(TemporalStabilityClass::OntogeneticAndSkeletalRemodeling),
487            ..Default::default()
488        };
489        detail.validate()?;
490        Ok(Self {
491            id,
492            subject_uri,
493            root_source_id: source_document_id,
494            scope_domain: "welfare:anatomy:clinical_record".into(),
495            derived_from_assertion_ids: Vec::new(),
496            sensitivity: SensitivityClass::Restricted,
497            claim_status: Some(claim_status),
498            summary_label: Some("FHIR/EHR clinical record extraction".into()),
499            evidence: detail,
500        })
501    }
502
503    /// Compile this record into a [`EvidencedAssertion`] enforcing non-public sensitivity.
504    pub fn to_evidenced_assertion(
505        &self,
506        author_did: &str,
507        asserted_at_unix: u32,
508    ) -> Result<EvidencedAssertion, String> {
509        self.evidence.validate()?;
510        let statement_type = match self.evidence.epistemic_tier {
511            Some(EpistemicTier::InferredFromObservation)
512            | Some(EpistemicTier::LongitudinallyProjected)
513            | Some(EpistemicTier::StatisticallyCalibrated)
514            | Some(EpistemicTier::PhylogeneticallyBracketed) => StatementType::Inference,
515            Some(EpistemicTier::AuthorialIntent) => StatementType::Attestation,
516            _ => StatementType::Observation,
517        };
518        let verification_status = match self.claim_status {
519            Some(ClaimStatus::ClinicianConfirmed) => VerificationStatus::Verified,
520            Some(ClaimStatus::Disputed) => VerificationStatus::Disputed,
521            _ => VerificationStatus::Proposed,
522        };
523        let assertion_status = match self.claim_status {
524            Some(ClaimStatus::Disputed) => AssertionStatus::Challenged,
525            Some(ClaimStatus::Superseded) => AssertionStatus::Superseded,
526            _ => AssertionStatus::Active,
527        };
528        let ea = EvidencedAssertion {
529            assertion: ContextualAssertion {
530                id: self.id.clone(),
531                subject_uri: self.subject_uri.clone(),
532                statement_type,
533                assertion_status,
534                verification_status,
535                claim_summary: self
536                    .summary_label
537                    .clone()
538                    .unwrap_or_else(|| self.evidence.property_iri.clone()),
539                author_did: author_did.to_string(),
540                root_source_id: self.root_source_id.clone(),
541                derived_from_assertion_ids: self.derived_from_assertion_ids.clone(),
542                scope_domain: self.scope_domain.clone(),
543                sensitivity: enforce_private_sensitivity(self.sensitivity),
544                asserted_at_unix,
545                expires_at_unix: None,
546                superseded_by_id: None,
547                adjudicated_by_human_did: None,
548            },
549            evidence: self.evidence.clone(),
550        };
551        ea.validate()?;
552        Ok(ea)
553    }
554
555    /// Seal this observation into a sovereign [`RecordEnvelope`], enforcing at minimum
556    /// [`SensitivityClass::Restricted`] (upgrading `Public` to `Restricted`) and
557    /// preserving honest epistemic/evidence provenance.
558    pub fn seal_into_envelope(
559        &self,
560        owner_did: &str,
561        author_did: &str,
562        asserted_unix: u32,
563        blob_hash: Option<String>,
564    ) -> RecordEnvelope {
565        let (epistemic_status, evidence_type) = match self.claim_status {
566            Some(ClaimStatus::Disputed) => (EpistemicStatus::Disputed, EvidenceType::SelfReported),
567            Some(ClaimStatus::Draft | ClaimStatus::Submitted) => {
568                (EpistemicStatus::Hypothesis, EvidenceType::SelfReported)
569            }
570            Some(ClaimStatus::ClinicianConfirmed) => {
571                (EpistemicStatus::Asserted, EvidenceType::ClinicianObserved)
572            }
573            Some(ClaimStatus::Superseded) => (EpistemicStatus::Asserted, EvidenceType::SelfReported),
574            None => match self.evidence.epistemic_tier {
575                Some(EpistemicTier::DirectlyObserved) => match self.evidence.observer_role {
576                    Some(ObserverRole::ClinicianMeasured | ObserverRole::IsakCertified) => {
577                        (EpistemicStatus::Asserted, EvidenceType::ClinicianObserved)
578                    }
579                    Some(ObserverRole::AutomatedSensor) => {
580                        (EpistemicStatus::Asserted, EvidenceType::DeviceMeasured)
581                    }
582                    _ => match self.evidence.observation_method {
583                        Some(ObservationMethod::SubjectSelfReportQuestionnaire) => {
584                            (EpistemicStatus::Asserted, EvidenceType::SelfReported)
585                        }
586                        Some(_) => (EpistemicStatus::Asserted, EvidenceType::DeviceMeasured),
587                        None => (EpistemicStatus::Asserted, EvidenceType::SelfReported),
588                    },
589                },
590                Some(EpistemicTier::InferredFromObservation)
591                | Some(EpistemicTier::LongitudinallyProjected)
592                | Some(EpistemicTier::StatisticallyCalibrated)
593                | Some(EpistemicTier::PhylogeneticallyBracketed) => {
594                    (EpistemicStatus::Hypothesis, EvidenceType::Inferred)
595                }
596                Some(EpistemicTier::AuthorialIntent) => {
597                    (EpistemicStatus::Hypothesis, EvidenceType::SelfReported)
598                }
599                Some(EpistemicTier::ExtractedFromRecord) | None => {
600                    (EpistemicStatus::Asserted, EvidenceType::SelfReported)
601                }
602            },
603        };
604
605        let valid_start_instant = self.evidence.temporal_axis.map(|axis| {
606            let secs = axis.phenomenon_time_ms.div_euclid(1000);
607            let rem_ms = axis.phenomenon_time_ms.rem_euclid(1000) as u32;
608            InstantBridge::unix(secs, rem_ms * 1_000_000)
609        });
610        let valid_start_unix = valid_start_instant.map(|i| i.secs.max(0) as u32);
611
612        RecordEnvelope {
613            id: format!("urn:wellfair:anatomical_observation:{}", self.id),
614            owner_did: owner_did.to_string(),
615            author_did: author_did.to_string(),
616            proxy_did: None,
617            epistemic_status,
618            evidence_type,
619            sensitivity: enforce_private_sensitivity(self.sensitivity),
620            asserted_time_unix: asserted_unix,
621            asserted_instant: Some(InstantBridge::from_coarse(asserted_unix)),
622            valid_time_start_unix: valid_start_unix,
623            valid_time_start_instant: valid_start_instant,
624            valid_time_end_unix: None,
625            valid_time_end_instant: None,
626            predecessor_id: None,
627            blob_hash,
628            tombstone: false,
629        }
630    }
631}
632
633impl BodyObservation {
634    /// Convert a legacy [`BodyObservation`] into an [`AnatomicalObservationRecord`]
635    /// with explicit [`EpistemicTier`], [`ObservationMethod`], [`ObserverRole`], and
636    /// [`TemporalObservationAxis`].
637    pub fn to_anatomical_record(
638        &self,
639        id: impl Into<String>,
640        subject_uri: impl Into<String>,
641        scope_domain: impl Into<String>,
642    ) -> Result<AnatomicalObservationRecord, String> {
643        let id = id.into();
644        let subject_uri = subject_uri.into();
645        let scope_domain = scope_domain.into();
646        if id.trim().is_empty() || subject_uri.trim().is_empty() {
647            return Err("id and subject_uri are required".into());
648        }
649        let (method, role, tier, basis, stability) = match &self.instrument {
650            InstrumentKind::Tape => (
651                ObservationMethod::FlexibleTapeCircumference,
652                ObserverRole::SelfMeasured,
653                EpistemicTier::DirectlyObserved,
654                ClaimBasis::Measured,
655                TemporalStabilityClass::SubacuteMetabolicGravidAndHealing,
656            ),
657            InstrumentKind::Scale => (
658                ObservationMethod::GravimetricScale,
659                ObserverRole::SelfMeasured,
660                EpistemicTier::DirectlyObserved,
661                ClaimBasis::Measured,
662                TemporalStabilityClass::SubacuteMetabolicGravidAndHealing,
663            ),
664            InstrumentKind::Watch => (
665                ObservationMethod::WearablePpgSmartwatch,
666                ObserverRole::AutomatedSensor,
667                EpistemicTier::DirectlyObserved,
668                ClaimBasis::Measured,
669                TemporalStabilityClass::AcutePhysiological,
670            ),
671            InstrumentKind::ClinicalDevice => {
672                let m = if self.code.contains("qct") {
673                    ObservationMethod::ClinicalCtQuantitativeQct
674                } else {
675                    ObservationMethod::DexaArealDensitometry
676                };
677                (
678                    m,
679                    ObserverRole::ClinicianMeasured,
680                    EpistemicTier::DirectlyObserved,
681                    ClaimBasis::Measured,
682                    TemporalStabilityClass::OntogeneticAndSkeletalRemodeling,
683                )
684            }
685            InstrumentKind::Camera => (
686                ObservationMethod::MultiViewPhotogrammetry,
687                ObserverRole::AutomatedSensor,
688                EpistemicTier::DirectlyObserved,
689                ClaimBasis::Measured,
690                TemporalStabilityClass::SubacuteMetabolicGravidAndHealing,
691            ),
692            InstrumentKind::Declared => (
693                ObservationMethod::SubjectSelfReportQuestionnaire,
694                ObserverRole::SelfMeasured,
695                EpistemicTier::AuthorialIntent,
696                ClaimBasis::Described,
697                TemporalStabilityClass::SubacuteMetabolicGravidAndHealing,
698            ),
699            InstrumentKind::Other(_) => (
700                ObservationMethod::SubjectSelfReportQuestionnaire,
701                ObserverRole::SelfMeasured,
702                EpistemicTier::ExtractedFromRecord,
703                ClaimBasis::Described,
704                TemporalStabilityClass::SubacuteMetabolicGravidAndHealing,
705            ),
706        };
707
708        let value = if let Some(named) = self.named.as_ref().filter(|s| !s.trim().is_empty()) {
709            EvidenceValue::Text {
710                text: named.clone(),
711                language: None,
712            }
713        } else {
714            EvidenceValue::Quantity {
715                value: self.value_milli as f64 / 1000.0,
716                unit_iri: if self.unit.trim().is_empty() {
717                    "urn:ucum:1".into()
718                } else {
719                    format!("urn:ucum:{}", self.unit.trim())
720                },
721            }
722        };
723
724        let phenomenon_time_ms = (self.at_unix as i64) * 1000;
725        let axis = TemporalObservationAxis::with_stability_class(phenomenon_time_ms, stability);
726        let detail = EvidenceDetail {
727            property_iri: format!("urn:code:{}", self.code.trim()),
728            basis,
729            value: Some(value),
730            method_iri: Some(method.as_iri()),
731            scope: BiologicalScope {
732                individual_iri: Some(subject_uri.clone()),
733                ..Default::default()
734            },
735            epistemic_tier: Some(tier),
736            observation_method: Some(method),
737            observer_role: Some(role),
738            temporal_axis: Some(axis),
739            stability_class: Some(stability),
740            ..Default::default()
741        };
742        detail.validate()?;
743
744        Ok(AnatomicalObservationRecord {
745            id: id.clone(),
746            subject_uri,
747            root_source_id: format!("src:body_obs:{id}"),
748            scope_domain,
749            derived_from_assertion_ids: Vec::new(),
750            sensitivity: SensitivityClass::Restricted,
751            claim_status: None,
752            summary_label: self.note.clone().or_else(|| Some(self.code.clone())),
753            evidence: detail,
754        })
755    }
756
757    /// Bridge directly into a validated [`EvidencedAssertion`].
758    pub fn to_evidenced_assertion(
759        &self,
760        id: impl Into<String>,
761        subject_uri: impl Into<String>,
762        scope_domain: impl Into<String>,
763        author_did: &str,
764        asserted_at_unix: u32,
765    ) -> Result<EvidencedAssertion, String> {
766        self.to_anatomical_record(id, subject_uri, scope_domain)?
767            .to_evidenced_assertion(author_did, asserted_at_unix)
768    }
769}
770
771#[cfg(test)]
772mod tests {
773    use super::*;
774
775    #[test]
776    fn unknown_instrument_code_is_stored_not_drawn() {
777        let o = BodyObservation {
778            code: "99999-9".into(),
779            value_milli: 72_000,
780            unit: "/min".into(),
781            instrument: InstrumentKind::Watch,
782            at_unix: 1,
783            note: Some("new watch metric".into()),
784            named: None,
785        };
786        assert!(!is_known_code(&o.code));
787        assert_eq!(bind_for_code(&o.code), RepresentationBind::None);
788    }
789
790    #[test]
791    fn pulse_binds_to_circulatory_rate_not_skeleton() {
792        assert_eq!(bind_for_code("8867-4"), RepresentationBind::CirculatoryRate);
793        assert_ne!(
794            bind_for_code("8867-4"),
795            RepresentationBind::OverlayOnSystem {
796                system_id: "skeletal".into()
797            }
798        );
799    }
800
801    #[test]
802    fn ethnicity_is_knowledge_context_never_appearance_or_fit() {
803        let b = bind_for_code("q42:ethnicity");
804        assert_eq!(b, RepresentationBind::KnowledgeContext);
805        assert_ne!(b, RepresentationBind::AppearanceSkin);
806        assert_ne!(b, RepresentationBind::AppearanceHair);
807        assert_ne!(b, RepresentationBind::AppearanceEye);
808        assert_ne!(b, RepresentationBind::FitStature);
809        assert_eq!(
810            bind_for_code("q42:genetic-ancestry"),
811            RepresentationBind::KnowledgeContext
812        );
813    }
814
815    #[test]
816    fn stature_and_weight_and_appearance_are_seeded() {
817        assert_eq!(bind_for_code("8302-2"), RepresentationBind::FitStature);
818        assert_eq!(bind_for_code("29463-7"), RepresentationBind::FitWeight);
819        assert_eq!(
820            bind_for_code("q42:eye-colour"),
821            RepresentationBind::AppearanceEye
822        );
823        assert_eq!(
824            bind_for_code("q42:hair-colour"),
825            RepresentationBind::AppearanceHair
826        );
827        assert_eq!(
828            bind_for_code("q42:skin-tone"),
829            RepresentationBind::AppearanceSkin
830        );
831    }
832
833    #[test]
834    fn constructors_and_envelope_sealing_preserve_epistemic_honesty() {
835        use qualia_cooperative_core::contextual_evidence::EvidenceValue;
836        use qualia_cooperative_core::record::{
837            EpistemicStatus, EvidenceType, NQuin, SensitivityClass,
838        };
839
840        let tape = AnatomicalObservationRecord::from_tape_measure(
841            "obs:tape-1",
842            "did:qualia:person:ada",
843            "q42:fit/thigh-circumference",
844            520.0,
845            ObserverRole::SelfMeasured,
846            1_700_000_000_000,
847            Some(3.0),
848            Some("q42:anat/thigh-left".to_string()),
849        )
850        .expect("tape measure observation should succeed");
851        assert_eq!(
852            tape.evidence.epistemic_tier,
853            Some(EpistemicTier::DirectlyObserved)
854        );
855        assert_eq!(
856            tape.evidence.observation_method,
857            Some(ObservationMethod::FlexibleTapeCircumference)
858        );
859        assert_eq!(tape.evidence.observer_role, Some(ObserverRole::SelfMeasured));
860        assert_eq!(tape.sensitivity, SensitivityClass::Restricted);
861
862        let dexa = AnatomicalObservationRecord::from_dexa_scan(
863            "obs:dexa-1",
864            "did:qualia:person:ada",
865            "q42:densitometry/areal-bmd",
866            0.94,
867            1_700_000_010_000,
868            Some(1_700_000_012_000),
869            Some("q42:anat/femoral-neck-left".to_string()),
870            "dexa-report-001",
871        )
872        .expect("dexa scan observation should succeed");
873        assert_eq!(
874            dexa.evidence.epistemic_tier,
875            Some(EpistemicTier::DirectlyObserved)
876        );
877        assert_eq!(
878            dexa.evidence.observation_method,
879            Some(ObservationMethod::DexaArealDensitometry)
880        );
881        assert_eq!(
882            dexa.evidence.observer_role,
883            Some(ObserverRole::ClinicianMeasured)
884        );
885
886        let qct = AnatomicalObservationRecord::from_qct_voxel(
887            "obs:qct-1",
888            "did:qualia:person:ada",
889            "q42:densitometry/volumetric-bmd",
890            145.0,
891            1_700_000_020_000,
892            None,
893            None,
894            "qct-series-002",
895        )
896        .expect("qct voxel observation should succeed");
897        assert_eq!(
898            qct.evidence.epistemic_tier,
899            Some(EpistemicTier::DirectlyObserved)
900        );
901        assert_eq!(
902            qct.evidence.observation_method,
903            Some(ObservationMethod::ClinicalCtQuantitativeQct)
904        );
905
906        // Unconfirmed clinical claim must downgrade from ClinicianObserved to SelfReported.
907        let unconfirmed = AnatomicalObservationRecord::from_clinical_record(
908            "obs:ehr-draft",
909            "did:qualia:person:ada",
910            "q42:densitometry/t-score",
911            EvidenceValue::Quantity {
912                value: -2.6,
913                unit_iri: "urn:ucum:1".into(),
914            },
915            ClaimStatus::Draft,
916            Some(ObservationMethod::ElectronicHealthRecordFhir),
917            1_700_000_030_000,
918            1_700_000_040_000,
919            "fhir-bundle-1",
920        )
921        .expect("draft clinical record should build");
922        let unconfirmed_env = unconfirmed.seal_into_envelope(
923            "did:qualia:person:ada",
924            "did:qualia:agent:ingest",
925            1_700_000_040,
926            None,
927        );
928        assert_eq!(unconfirmed_env.evidence_type, EvidenceType::SelfReported);
929        assert_eq!(unconfirmed_env.sensitivity, SensitivityClass::Restricted);
930        assert_eq!(unconfirmed_env.epistemic_status, EpistemicStatus::Hypothesis);
931
932        // Disputed clinical claim must stay SelfReported and EpistemicStatus::Disputed.
933        let disputed = AnatomicalObservationRecord::from_clinical_record(
934            "obs:ehr-disputed",
935            "did:qualia:person:ada",
936            "q42:densitometry/t-score",
937            EvidenceValue::Quantity {
938                value: -2.6,
939                unit_iri: "urn:ucum:1".into(),
940            },
941            ClaimStatus::Disputed,
942            None,
943            1_700_000_030_000,
944            1_700_000_040_000,
945            "fhir-bundle-2",
946        )
947        .expect("disputed clinical record should build");
948        let disputed_env = disputed.seal_into_envelope(
949            "did:qualia:person:ada",
950            "did:qualia:agent:ingest",
951            1_700_000_040,
952            None,
953        );
954        assert_eq!(disputed_env.evidence_type, EvidenceType::SelfReported);
955        assert_eq!(disputed_env.epistemic_status, EpistemicStatus::Disputed);
956
957        // Confirmed clinical claim preserves ClinicianObserved and Asserted.
958        let confirmed = AnatomicalObservationRecord::from_clinical_record(
959            "obs:ehr-confirmed",
960            "did:qualia:person:ada",
961            "q42:densitometry/t-score",
962            EvidenceValue::Quantity {
963                value: -2.6,
964                unit_iri: "urn:ucum:1".into(),
965            },
966            ClaimStatus::ClinicianConfirmed,
967            None,
968            1_700_000_030_000,
969            1_700_000_040_000,
970            "fhir-bundle-3",
971        )
972        .expect("confirmed clinical record should build");
973        let confirmed_assertion = confirmed
974            .to_evidenced_assertion("did:qualia:clinician:1", 1_700_000_040)
975            .expect("evidenced assertion should build");
976        let mut quins = [NQuin::default(); 64];
977        let quin_count = confirmed_assertion.compile_to_quins(&mut quins);
978        assert!(quin_count > 0);
979
980        let confirmed_env = confirmed.seal_into_envelope(
981            "did:qualia:person:ada",
982            "did:qualia:clinician:1",
983            1_700_000_040,
984            None,
985        );
986        assert_eq!(confirmed_env.evidence_type, EvidenceType::ClinicianObserved);
987        assert_eq!(confirmed_env.epistemic_status, EpistemicStatus::Asserted);
988        assert_eq!(confirmed_env.sensitivity, SensitivityClass::Restricted);
989
990        // Even if sensitivity is overridden to Public, seal_into_envelope upgrades it to Restricted.
991        let mut forced_public = dexa.clone();
992        forced_public.sensitivity = SensitivityClass::Public;
993        let forced_env = forced_public.seal_into_envelope(
994            "did:qualia:person:ada",
995            "did:qualia:device:dexa",
996            1_700_000_012,
997            Some("blake3:deadbeef".to_string()),
998        );
999        assert_eq!(forced_env.sensitivity, SensitivityClass::Restricted);
1000
1001        // BodyObservation bridges cleanly into AnatomicalObservationRecord + EvidencedAssertion.
1002        let legacy = BodyObservation {
1003            code: "8302-2".to_string(),
1004            instrument: InstrumentKind::Tape,
1005            value_milli: 1_680_000,
1006            unit: "mm".to_string(),
1007            at_unix: 1_700_000_050,
1008            note: Some("clinic-visit-1".into()),
1009            named: None,
1010        };
1011        let bridged = legacy
1012            .to_anatomical_record("obs:legacy-1", "did:qualia:person:ada", "anthropometry")
1013            .expect("BodyObservation should convert");
1014        assert_eq!(
1015            bridged.evidence.observation_method,
1016            Some(ObservationMethod::FlexibleTapeCircumference)
1017        );
1018        let bridged_assertion = legacy
1019            .to_evidenced_assertion(
1020                "obs:legacy-1",
1021                "did:qualia:person:ada",
1022                "anthropometry",
1023                "did:qualia:clinician:1",
1024                1_700_000_055,
1025            )
1026            .expect("BodyObservation evidenced assertion should compile");
1027        let mut bridged_quins = [NQuin::default(); 64];
1028        let bridged_quin_count = bridged_assertion.compile_to_quins(&mut bridged_quins);
1029        assert!(bridged_quin_count > 0);
1030    }
1031}