Clinical Commander

All dossiers
pulm.osa.core.v1

Obstructive sleep apnea (adult chronic — AASM dx + PAP-first therapy ladder)

pulmonologychronicadultoutpatient
Start encounter →Print handoutPRODUCTION

NEW NET-NEW DOSSIER (2026-05-16): authored design-disease-first per memory feedback_design_disease_first.md — design brief (src/lib/dossiers/_briefs/pulm.osa.core.v1.md) + research bundle written BEFORE the .ts. PLANNED declared (no dedicated manifest/atoms/package yet); manifest repointed to prisma/seed/manifests/id.sepsis.core.v1.ts per the id.dengue.v1 nearest-ID precedent to clear the audit broken_pointers check. The audit-computed actual_status may be higher than PLANNED — acceptable for a content-rich net-new dossier per dispatch. PMID CORRECTION: the content-factory "expected" AASM diagnostic PMID 33960348 was WRONG (resolves to a Dalton Transactions chemistry erratum). Corrected to 28162150 (AASM 2017 Diagnostic Testing CPG, Kapur) + 30736887 (AASM 2019 PAP Treatment CPG, Patil) + 23066376 (AASM Manual scoring rules, Berry) via PubMed MCP search. All 11 evidence.pmids verified via get_article_metadata 2026-05-16 (title+journal+DOI); full table in _research-bundles/pulm.osa.core.v1.md §2. §5.5.1 ≥10 effect-size numbers (delivered 11) PMID-anchored: SAVE CV-event HR neutral + sleepiness/QoL benefit (27571048); SURMOUNT-OSA tirzepatide AHI −20 to −30/h (38912654); SERVE-HF ASV all-cause HR 1.28 / CV HR 1.34 (26323938); STAR HGNS AHI −68%, ODI −70%, withdrawal 7.6→25.8/h (24401051); Bratton CPAP SBP −2.5 / DBP −2.0 mmHg + MAD SBP −2.1 / DBP −1.9 + per-hour −1.5/−0.9 (26624827); Chiu STOP-BANG sens 90% moderate / 93% severe, ESS sens 47–58% (27919588); Sleep AHEAD AHI −9.7/h, weight −10.8 kg (19786682); AHI severity bands mild 5–14.9 / moderate 15–29.9 / severe ≥30 (23066376); OSA prevalence 9–38% at AHI≥5 (27568340). §5.5.2 differential as data: OSA vs CSA vs OHS vs narcolepsy vs chronic insomnia vs PLMD vs nocturnal GERD/asthma — encoded via severity_triggers (differential_osa_vs_csa_vs_ohs, differential_hypersomnia_osa_vs_narcolepsy_vs_insomnia_vs_plmd, overlap_syndrome_osa_plus_copd), DIFFERENTIAL/BRANCHING_WORKUP phase logic, workups[].branches_to and 3 sibling_differentiation blocks. Cross-dossier engine_ids (5, all verified on disk by grep 2026-05-16): pulm.copd.core.v1, pulm.pulmonary_htn_group2_to_5.v1, cardio.htn.resistant.v1, endo.dm2.core.v1, gi.gerd.core.v1; sibling pointer pulm.asthma.peds.v1 (pediatric-airway out-of-scope marker — closest pediatric sibling on disk; no dedicated pediatric-OSA dossier exists). cardio.afib.core.v1 referenced narratively in CV co-management (confirmed on disk) but not used as a branches_to target to keep workup routes tight. Therapy axis osa_therapy_ladder (PAP-first stepwise, 7 steps) + ≥6 special-population branches encoded as RegimenDrug.triggers + contraindication_rules: (1) obesity/OHS — NIV/BiPAP not plain CPAP if awake PaCO2 ≥45; (2) comorbid HFrEF + predominant CSA — ASV CONTRAINDICATED if LVEF ≤45 (SERVE-HF 26323938) encoded as contraindication data + life_threatening severity_trigger; (3) CV/AF/resistant-HTN — CPAP for symptom/BP only, no overstated CV claim (SAVE 27571048); (4) perioperative — STOP-BANG + PAP continuation + opioid caution; (5) pregnancy — CPAP safe/preferred, avoid tirzepatide; (6) commercial-driver/CDL — documented treatment + objective adherence before certification. RxCUI: tirzepatide rxcui 2601723 VERIFIED via RxNav REST /rxcui/2601723/properties.json 2026-05-16 (name=tirzepatide, TTY=IN ingredient). Modafinil rxcui 36117 (ingredient). Branded/combination products would need separate SCD/SBD validation → flagged NEEDS_RXNAV_VALIDATION; NO hand-authored product CUIs. All other ladder steps are non_pharm (PAP/MAD/positional/HGNS/surgery/bariatric/lifestyle) — completeness audit skips rxcui for non_pharm. Registry-id reuse (all confirmed to resolve in src/lib/systems/clinical-tools-registry.ts by grep 2026-05-16): calc.stop_bang (STOP-BANG OSA screen — exact-fit screening), calc.ibw_adjbw (BMI/dosing weight — there is no calc.bmi), calc.bsa, calc.ckd_epi_2021 (solriamfetol renal dosing); panels panel.abg (OHS hypercapnia), panel.cbc (erythrocytosis), panel.cardiac (HFrEF/cor pulmonale), panel.thyroid (hypothyroid mimic), panel.glucose_a1c, panel.lipid, panel.renal; workups workup.chronic_fatigue (sleepiness/fatigue entry — registry description explicitly lists OSA), workup.insomnia (insomnia pivot). NO invented unresolved ids. SCHEMA-GAP NOTES: (1) Epworth Sleepiness Scale, Berlin, NoSAS, AHI-severity-classifier, HSAT-interpretation, CPAP-compliance calculators are ABSENT from clinical-tools-registry.ts — encoded narratively in flow.phases purpose/advance_when, severity_triggers, calculator guideline_basis and regimen monitoring (NOT invented as unresolved ids — they would fail dossier:audit); (2) _types.ts has no first-class Bayesian-LR / pretest-prevalence / decision-threshold / special-population-matrix / effect-size field — encoded in severity_triggers, phase purpose, calculator guideline_basis, regimen rationale/triggers/contraindication_rules and _briefs/pulm.osa.core.v1.depth.md tables; (3) RequiredCalculator.drives enum lacks diagnostic_gate — calc.stop_bang uses screening; (4) no dedicated central-sleep-apnea or pediatric-OSA dossier on disk — sibling pointers use closest substrate/airway engines (pulm.pulmonary_htn_group2_to_5.v1, pulm.asthma.peds.v1) and CSA/OHS handled via severity_triggers + contraindication data. NEW-DOSSIER NEXT STEPS (PLANNED → higher): (1) author dedicated prisma/seed/manifests/pulm.osa.core.v1.ts + atoms + Tier3 package and repoint manifest; (2) run npm run research:rxnav:validate for any product-level modafinil/solriamfetol/pitolisant SCD/SBD codes (still NEEDS_RXNAV_VALIDATION); (3) add Epworth/Berlin/AHI-severity/CPAP-compliance calculators + HSAT-interpretation workup to clinical-tools-registry.ts then wire them here; (4) add an engine-specific test file under tests/ (currently uses the shared tests/dossiers/dossier-contract.test.ts). DEPTH-PASS-2 2026-05-17 (shard-07-cardio-chronic): (1) co-located _design-brief.md + _research-bundle.md per §5.5 items 1+2 — 20 verified PMIDs (chronic floor ≥15 ✅), named trials + effect sizes + 95% CI, retrieval-dated 2026-05-17, Consensus→WebSearch fallback logged; design_brief: repointed to the co-located src/lib/dossiers/pulm.osa.core.v1._design-brief.md. (2) Bayesian seed prisma/seed/ros-and-ddx/pulm.osa.core.v1.{differentials,ros,finding-lrs}.ts (ENGINE_ID pulm.osa.core.v1) — 11 differentials w/ referral-cohort priors (daytime-sleepiness/snoring/witnessed-apnea partition: OSA mild/moderate-severe/positional vs CSA vs OHS vs narcolepsy vs insufficient-sleep vs PLMD vs hypothyroid vs depression-fatigue vs simple-snoring), 14 ROS, 38 LR rows (≥30 LR+ / ≥36 LR− — chronic floor ≥15 each ✅), 3 conditional-dependency rules (STOP-BANG ≥3 vs ≥5 nested — chain highest only; HSAT-negative requires confirmatory in-lab PSG; AHI-band modality-specific PSG-supersedes-HSAT), T_test≈5% / T_treat≈50% in header. (3) 2nd regimen axis osa_phenotype_comorbidity_matrix added (intervention × phenotype gating as DATA: resistant-HTN→prioritise CPAP/HIPARCO, AF-post-ablation→CPAP/Deng RR 0.60, HFpEF→CPAP+HF co-mgmt, obese→tirzepatide/SURMOUNT-OSA, positional, pregnancy→CPAP+avoid weight-loss-pharm, commercial-driver/CDL, HFrEF+CSA→ASV CONTRAINDICATED, OHS→NIV/BiPAP). (4) RxCUI bug fixed: modafinil rxcui 36117 resolved via RxNav REST to SALMETEROL (TTY=IN) — WRONG CUI REMOVED, no hand-authored substitute (NEEDS_RXNAV_VALIDATION non_pharm); tirzepatide 2601723 / semaglutide 1991302 / acetazolamide 167 all IN:OK via npm run research:rxnav:validate 2026-05-17 (match canonical DrugEffectProfile profiles). (5) Content refreshed to AASM current (not just tag): added AASM 2021 surgical-referral CPG (Kent 34351848) + AASM 2025 hospitalized-OSA CPG (Mehra 40838698, NET-NEW); CV-neutral-in-non-sleepy triangulated across SAVE+ISAACC+RICCADSA with adherence-conditional on-treatment signal; HIPARCO added for resistant-HTN BP; Phillips RCT replaces Bratton for CPAP-vs-MAD; Nagappa/Chung STOP-Bang meta replaces Chiu; Benjafield replaces Senaratna for prevalence prior; SURMOUNT-OSA effect sizes made exact w/ 95% CI; reconciled to ICSD-3-TR 2023; evidence.pmids 11→20. status: kept PLANNED per dispatch. DEPTH-PASS-3 2026-05-26 (lane-E): +NMA +USPSTF +Cochrane +ICER stubs +decision thresholds, side-car at pulm.osa.core.v1._depth-pass-3.md.

Entry points (6)

  • symptom
    Loud habitual snoring + witnessed apnea + daytime sleepiness (AASM 2017 dx CPG)
    snoring_witnessed_apnea_sleepiness
  • symptom
    Non-restorative sleep, nocturia, morning headache, choking/gasping arousals (AASM 2017)
    unrefreshing_sleep_nocturia_morning_headache
  • history
    Resistant hypertension / atrial fibrillation / stroke — OSA contributory cause; reciprocal screen (cardio.htn.resistant.v1, cardio.afib.core.v1)
    resistant_htn_af_stroke
  • demographic
    Obesity / T2DM / metabolic syndrome — high pretest OSA probability (Senaratna PMID 27568340; SURMOUNT-OSA PMID 38912654)
    obesity_metabolic
  • history
    Perioperative / bariatric-pre-op STOP-BANG screen (AASM 2017; perioperative-OSA branch)
    preoperative_or_bariatric_screen
  • problem_list
    Existing OSA — adherence review, re-titration, or annual follow-up visit
    osa_existing

Required inputs (19)

  • agerequired
    demographic • used at CONTEXT
    STOP-BANG age >50 item; OSA prevalence rises with age (Senaratna PMID 27568340)
  • sexrequired
    demographic • used at CONTEXT
    STOP-BANG male item; male:female prevalence ~2:1 (Senaratna PMID 27568340)
  • bmirequired
    vital • used at CONTEXT
    STOP-BANG BMI >35 item; obesity is the dominant modifiable risk factor; gates weight-loss pharmacotherapy/bariatric branch (SURMOUNT-OSA PMID 38912654; Sleep AHEAD PMID 19786682)
  • neck_circumference
    vital • used at CONTEXT
    STOP-BANG neck >40 cm item; upper-airway crowding surrogate (AASM 2017)
  • bprequired
    vital • used at CONTEXT
    STOP-BANG hypertension item; OSA is the commonest contributory cause of resistant HTN; CPAP lowers BP ~2–3 mmHg (Bratton PMID 26624827)
  • snoringrequired
    symptom • used at CONTEXT
    STOP-BANG snoring item + cardinal OSA symptom (AASM 2017)
  • tiredness_sleepinessrequired
    symptom • used at CONTEXT
    STOP-BANG tiredness item; Epworth ≥11 quantifies sleepiness — driving-safety gate (Chiu PMID 27919588)
  • observed_apnearequired
    symptom • used at CONTEXT
    STOP-BANG observed-apnea item; bed-partner report (AASM 2017)
  • comorbid_cardiopulmonaryrequired
    history • used at CONTEXT
    HF/COPD/CAD/AF/stroke/pulmonary HT — drives PSG-over-HSAT decision and CV-risk overlay (AASM 2017 — HSAT not validated with significant cardiopulmonary disease)
  • opioid_sedative_alcohol_use
    history • used at CONTEXT
    Opioid/sedative use raises CSA risk and perioperative hazard; alcohol worsens collapsibility (AASM 2017; perioperative branch)
  • occupation_driving_cdlrequired
    history • used at CONTEXT
    Commercial-driver / safety-sensitive occupation — DOT/CDL certification requires documented treatment + objective adherence (severity trigger)
  • pregnancy
    demographic • used at CONTEXT
    Pregnancy branch — CPAP safe/preferred; screen if gestational HTN/pre-eclampsia/obesity
  • ahi_rdirequired
    lab • used at RISK_STRATIFICATION
    Apnea-hypopnea / respiratory-disturbance index from HSAT or PSG — AASM/Berry scoring rules (PMID 23066376); severity band drives therapy intensity
  • odi_nadir_spo2
    lab • used at RISK_STRATIFICATION
    Oxygen-desaturation index + nadir SpO2 — hypoxic burden; very low nadir / OHS concern routes to ABG
  • venous_bicarb_or_abg
    lab • used at BRANCHING_WORKUP
    Awake hypercapnia pivot — serum HCO3 ≥27 prompts ABG; PaCO2 ≥45 mmHg = OHS (NIV/BiPAP not plain CPAP) (AASM 2017; OHS branch)
  • tsh
    lab • used at INITIAL_WORKUP
    Hypothyroidism is a reversible OSA contributor / sleepiness mimic (AASM 2017)
  • cbc_hct
    lab • used at INITIAL_WORKUP
    Chronic-hypoxemia secondary erythrocytosis screen (AASM 2017)
  • ecg_echo
    imaging • used at BRANCHING_WORKUP
    ECG if AF suspected; echo for cor pulmonale / HFrEF (ASV-contraindication gate per SERVE-HF PMID 26323938)
  • current_meds
    medication • used at CONTEXT
    Sedatives/opioids worsen events; tirzepatide/GLP-1 overlap with weight-loss branch and endo.dm2.core.v1

12-phase flow (12)

  1. 1FRAME
    Adult chronic OSA — outpatient sleep-clinic + primary-care shared care; scope = diagnosis + long-term therapy. Exclude pediatric OSA (sibling pointer) and pure CSA/OHS (route out). OSA = repetitive upper-airway collapse with preserved respiratory effort (vs CSA — absent effort) (AASM 2017)
    inputs: age, bmi
    advance: Adult chronic OSA in scope; pediatric / pure-CSA / OHS routed out
  2. 2ENTRY
    Triggered by snoring + witnessed apnea + sleepiness, OR incidental finding (resistant HTN, AF, nocturia, stroke, MVA, perioperative/bariatric screen) per AASM 2017
    inputs: snoring, observed_apnea, tiredness_sleepiness
    advance: Symptom-driven or incidental entry trigger identified
  3. 3CONTEXT
    BMI, neck circumference, Mallampati/craniofacial, bed-partner report; comorbidities (resistant HTN, AF, stroke, T2DM, HF, GERD, COPD); alcohol/sedative/opioid use; occupation + driving (CDL); pregnancy (AASM 2017)
    inputs: age, sex, bmi, neck_circumference, bp, snoring, tiredness_sleepiness, observed_apnea, comorbid_cardiopulmonary, occupation_driving_cdl, opioid_sedative_alcohol_use, pregnancy, current_meds
    actions: calc.stop_bang
    advance: Risk-factor + comorbidity + occupational sweep complete
  4. 4RED_FLAGS
    Severe sleepiness + driving/occupational hazard (Epworth ≥16 or near-miss MVA); suspected OHS (awake hypercapnia, HCO3 ≥27); decompensated cor pulmonale; suspected CSA in HFrEF — do NOT prescribe ASV (SERVE-HF PMID 26323938)
    inputs: tiredness_sleepiness, occupation_driving_cdl, venous_bicarb_or_abg, comorbid_cardiopulmonary
    actions: panel.abg
    advance: No emergent driving/OHS/cor-pulmonale/ASV-CSA hazard OR escalation initiated
  5. 5INITIAL_WORKUP
    STOP-BANG (+ Epworth) screen → objective sleep testing decision. HSAT acceptable for high pretest probability of moderate-severe OSA WITHOUT significant cardiopulmonary disease; in-lab PSG (gold standard) if comorbid cardiopulmonary disease, suspected CSA/OHS, or HSAT negative-but-symptomatic. Adjuncts: TSH (hypothyroid mimic), CBC/Hct (erythrocytosis) (AASM 2017 PMID 28162150)
    inputs: tsh, cbc_hct
    actions: calc.stop_bang, panel.thyroid, panel.cbc, workup.chronic_fatigue
    advance: Screen completed + HSAT-vs-PSG testing route chosen
  6. 6BRANCHING_WORKUP
    If CSA-predominant on PSG → CSA/HF workup (echo for LVEF; ASV CONTRAINDICATED if LVEF ≤45% — SERVE-HF PMID 26323938). If awake hypercapnia (PaCO2 ≥45) → OHS workup (ABG; NIV/BiPAP not plain CPAP). If normal study + persistent hypersomnia → alternative dx (narcolepsy → MSLT; PLMD; insomnia → workup.insomnia)
    inputs: venous_bicarb_or_abg, ecg_echo, comorbid_cardiopulmonary
    actions: panel.abg, panel.cardiac, workup.insomnia
    advance: CSA/OHS/narcolepsy/insomnia branch resolved or excluded
  7. 7DIFFERENTIAL
    §5.5.2 differential as data — OSA vs CSA (absent effort; HF/opioid/altitude substrate) vs OHS (awake PaCO2 ≥45) vs narcolepsy (REM-dissociation, cataplexy, MSLT MSL ≤8 min + ≥2 SOREMPs) vs chronic insomnia (sleep-onset/maintenance complaint, no respiratory events) vs PLMD (periodic limb movements, PLMI) vs nocturnal GERD/asthma (reflux/bronchospasm mimicking arousal). Pivots + test characteristics encoded in severity_triggers + sibling_differentiation
    inputs: ahi_rdi, venous_bicarb_or_abg
    actions: workup.insomnia, workup.chronic_fatigue
    advance: OSA confirmed (obstructive events predominate) + competing dx excluded or routed
  8. 8RISK_STRATIFICATION
    AHI/RDI severity band (mild 5–14.9, moderate 15–29.9, severe ≥30 events/h — AASM/Berry PMID 23066376) + ODI/nadir-SpO2 hypoxic burden + Epworth symptom burden + comorbid-CV-risk overlay → therapy intensity and driving-safety gate. Severe OSA + sleepiness + safety-sensitive occupation = treat-and-document-before-certification
    inputs: ahi_rdi, odi_nadir_spo2, tiredness_sleepiness, occupation_driving_cdl, bp
    actions: calc.stop_bang
    advance: Severity band + symptom burden + CV-risk + driving-safety gate assigned
  9. 9TREATMENT
    CPAP first-line/gold standard (fixed or APAP) + behavioural/educational/telemonitoring adherence sub-loop (compliance ≥4 h/night ≥70% nights). Alternative ladder if CPAP-intolerant: oral appliance (MAD), positional therapy, hypoglossal-nerve stimulation (Inspire — BMI <35, AHI 15–65, no concentric collapse on DISE; STAR PMID 24401051), weight-loss pharmacotherapy (tirzepatide — SURMOUNT-OSA PMID 38912654) / bariatric / intensive lifestyle (Sleep AHEAD PMID 19786682), upper-airway surgery; residual-sleepiness wake-promoting adjunct (solriamfetol/modafinil/pitolisant). Treat OHS (NIV/BiPAP) and CSA-in-HFrEF (NOT ASV — SERVE-HF PMID 26323938) distinctly. Honesty: CPAP improves symptoms/QoL/BP, NOT CV events (SAVE PMID 27571048)
    inputs: ahi_rdi, bmi, tiredness_sleepiness, comorbid_cardiopulmonary
    actions: calc.ibw_adjbw, calc.bsa
    advance: PAP-first regimen selected with adherence plan + special-population gating documented
  10. 10DISPOSITION
    Sleep-medicine referral if refractory or diagnostic uncertainty; ENT/oral-medicine for MAD or upper-airway surgery; Inspire/bariatric referral if eligible; continue shared care if adherent + controlled; CV-risk co-management (cardio.htn.resistant.v1, cardio.afib.core.v1, endo.dm2.core.v1)
    inputs: ahi_rdi
    advance: Disposition + referral pathway set
  11. 11MONITORING
    CPAP compliance download q3–6 mo (objective hours, residual AHI, mask leak; ≥4 h/night ≥70% nights threshold); Epworth trend; BP; weight; partner-reported snoring; nocturia. Each +1 h/night CPAP use = additional SBP −1.5 / DBP −0.9 mmHg (Bratton PMID 26624827)
    inputs: ahi_rdi, bp, tiredness_sleepiness
    actions: calc.stop_bang
    advance: Objective adherence + residual-AHI + symptom/BP trend reviewed
  12. 12FOLLOWUP
    Annual review; re-titration if ≥10% weight change or pregnancy; reinforce adherence (early adherence predicts long-term — adherence ~50% at 1 yr); driving-safety re-attestation for CDL; comorbidity (HTN/AF/T2DM/stroke) co-management; pregnancy re-evaluation post-partum
    inputs: bmi, occupation_driving_cdl
    advance: Annual review + re-titration triggers + driving re-attestation scheduled