carebundle 0.1.0__tar.gz

carebundle-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,211 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  schedule:
+    # Nightly full conformance matrix + fidelity report.
+    - cron: "0 6 * * *"
+  # So the nightly-only jobs can be exercised on demand. A job that has only ever been
+  # scheduled is a job nobody has watched fail.
+  workflow_dispatch:
+
+env:
+  VALIDATOR_URL: https://github.com/hapifhir/org.hl7.fhir.core/releases/latest/download/validator_cli.jar
+
+jobs:
+  # Fast gate. No JVM — this is the loop contributors wait on.
+  unit:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      # Every version in `requires-python`, because the README claims the whole range.
+      # Do not trim this to save minutes without trimming the claim to match.
+      #
+      # macOS and Windows carry one version each rather than the full grid: the package
+      # is pure Python, so the cross-platform risk is concentrated in the CLI's POSIX
+      # assumptions (SIGPIPE, os.dup2 on a real stdout fd) and in path handling, none of
+      # which vary by Python minor. `requires-python` names no platform, so leaving
+      # Windows untested would be claiming support nobody had checked.
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        include:
+          - os: macos-latest
+            python-version: "3.12"
+          - os: windows-latest
+            python-version: "3.12"
+    # Windows defaults to PowerShell, which quotes differently. Git Bash ships on the
+    # Windows runners, so pinning bash keeps all three platforms running the identical
+    # command rather than three dialects of it.
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v4
+      # Required, and not only for the matrix to mean anything: without it
+      # `uv pip install --system` targets the runner's system interpreter, which is
+      # PEP 668 externally-managed and refuses the install outright.
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v5
+      - name: Install
+        run: uv pip install --system -e ".[dev]"
+      - name: Confirm the matrix version is the one under test
+        run: python -c "import sys; assert '.'.join(map(str, sys.version_info[:2])) == '${{ matrix.python-version }}', sys.version"
+      - name: Lint
+        run: ruff check carebundle tests
+      - name: Unit, property and determinism tests
+        run: pytest tests/ -q -m "not conformance and not fidelity" --cov --cov-report=term-missing
+
+  # Guards the artefacts themselves. The unit job installs from the source tree, so it
+  # cannot catch a packaging fault: a missing py.typed, a data file left out of the
+  # wheel, or metadata PyPI will reject. This installs the built wheel into a clean
+  # environment, outside the repo, and exercises the README's entry points there.
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --quiet build twine
+          python -m build
+      - name: Check metadata renders on PyPI
+        run: twine check --strict dist/*
+      - name: Install the wheel into a clean environment
+        run: |
+          python -m venv /tmp/probe
+          /tmp/probe/bin/pip install --quiet dist/*.whl
+      - name: Smoke-test the installed package from outside the repo
+        working-directory: /tmp
+        run: |
+          /tmp/probe/bin/python -c "
+          import json, pathlib, carebundle
+          from carebundle import (generate_bundle, generate_history, generate_cohort,
+                                  to_json, Imperfection, inject_defects,
+                                  calibrate_profile, Quartiles)
+
+          bundle = json.loads(to_json(generate_bundle(profile='type2_diabetes', seed=42, sex='F')))
+          assert bundle['resourceType'] == 'Bundle', bundle['resourceType']
+          assert bundle['entry'], 'installed package generated an empty bundle'
+
+          # Every public entry point, because the source-tree job cannot catch a
+          # packaging fault and each of these is a separate import surface.
+          history = json.loads(to_json(generate_history(profile='hypertension', seed=42, visits=4)))
+          encounters = [e for e in history['entry'] if e['resource']['resourceType'] == 'Encounter']
+          assert len(encounters) == 4, encounters
+
+          _, defects = inject_defects(bundle, Imperfection(missing_field=0.3), seed=5)
+          assert defects, 'imperfection injected nothing'
+
+          calibrate_profile('ci_probe', base='type2_diabetes',
+                            marginals={'hba1c': Quartiles(median=8.4, q1=7.5, q3=9.8, low=6.0, high=13.5),
+                                       'glucose': Quartiles(median=190, q1=155, q3=240, low=90, high=420)})
+          assert json.loads(to_json(generate_bundle(profile='ci_probe', seed=42)))['entry']
+
+          assert len(list(generate_cohort(count=3, seed=1))) == 3
+
+          marker = pathlib.Path(carebundle.__file__).parent / 'py.typed'
+          assert marker.exists(), 'py.typed missing from the wheel'
+          data = pathlib.Path(carebundle.__file__).parent / 'calibration/data/nhanes_targets.json'
+          assert data.exists(), 'calibration data missing from the wheel'
+          print('installed package OK:', len(bundle['entry']), 'entries')
+          "
+          /tmp/probe/bin/carebundle profiles
+          /tmp/probe/bin/carebundle generate --profile healthy --seed 1 --out /tmp/fixtures
+      - name: A closed pipe must not print a traceback
+        working-directory: /tmp
+        run: |
+          /tmp/probe/bin/carebundle generate --profile healthy --seed 1 2>/tmp/err.txt | head -3
+          if [ -s /tmp/err.txt ]; then echo "::error::stderr noise on a closed pipe"; cat /tmp/err.txt; exit 1; fi
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+
+  # Authoritative conformance gate. The JVM lives HERE and only here — it is never a
+  # runtime or install dependency of the published package (build doc Section 10).
+  conformance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v5
+      - name: Install
+        run: uv pip install --system -e ".[dev]"
+      - name: Fetch HL7 validator
+        run: |
+          mkdir -p .tools
+          curl -sSL -o .tools/validator_cli.jar "$VALIDATOR_URL"
+      - name: Cache FHIR package registry
+        uses: actions/cache@v4
+        with:
+          path: ~/.fhir
+          key: fhir-packages-us-core-6.1.0
+      - name: Fetch R4 spec definitions
+        run: |
+          mkdir -p .tools/spec
+          curl -sSL -o .tools/spec/definitions.json.zip https://hl7.org/fhir/R4/definitions.json.zip
+          (cd .tools/spec && unzip -o -q definitions.json.zip)
+      - name: Verify generated models match the spec
+        run: |
+          python -m carebundle.spec.codegen
+          git diff --exit-code carebundle/models/r4.py \
+            || (echo "::error::carebundle/models/r4.py is stale — run 'python -m carebundle.spec.codegen' and commit" && exit 1)
+      - name: US Core conformance
+        # On PRs this runs a small sample to keep the loop tight; nightly runs the
+        # full profile x resource-type matrix.
+        run: |
+          if [ "${{ github.event_name }}" = "schedule" ]; then
+            pytest tests/ -q -m conformance --conformance-scale=full
+          else
+            pytest tests/ -q -m conformance --conformance-scale=sample
+          fi
+
+  # Re-check every shipped code against its source vocabulary. Curated subsets go
+  # stale (build doc Section 14), and a display that drifts is rejected outright by
+  # the HL7 validator. Nightly because it depends on three external APIs.
+  terminology:
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v5
+      - name: Install
+        run: uv pip install --system -e ".[dev]"
+      - name: Verify codes against LOINC, RxNorm and ICD-10-CM
+        run: python -m carebundle.terminology.verify
+
+  # Statistical evidence for the clinical-coherence claim (build doc Section 8).
+  # Nightly only: N=10,000 patients per profile is too slow for a PR gate.
+  fidelity:
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v5
+      - name: Install
+        run: uv pip install --system -e ".[dev]"
+      - name: Fidelity report
+        run: pytest tests/ -q -m fidelity
+      - uses: actions/upload-artifact@v4
+        with:
+          name: fidelity-report
+          path: FIDELITY.md

carebundle-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,134 @@
+name: Release
+
+# Publishes to PyPI when a v* tag is pushed. Uses Trusted Publishing (OIDC), so there
+# is no API token in this repository's secrets to leak or rotate — PyPI is configured
+# to trust this workflow in this repository instead.
+#
+# Before the first run, register the publisher at
+# https://pypi.org/manage/account/publishing/ with:
+#   project: carebundle | owner: 27jackson08 | repo: fhirfaker
+#   workflow: release.yml | environment: pypi
+#
+# workflow_dispatch runs everything EXCEPT the publish job, so the pipeline can be
+# rehearsed on a branch. Publishing is gated on `github.ref_type == 'tag'`, which a
+# manual dispatch on a branch can never satisfy — the dry run cannot upload by
+# accident. Rehearse before relying on this: the previous CI workflow was silently
+# broken for months precisely because nobody had watched it run.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # A tag that disagrees with pyproject is the classic release footgun: it publishes
+  # the wrong version under the right name, and PyPI will not let you reuse the number.
+  # Fail here rather than after upload.
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Tag must match the version in pyproject.toml
+        # Only meaningful on a tag; on a dispatch rehearsal GITHUB_REF_NAME is a branch.
+        if: github.ref_type == 'tag'
+        run: |
+          python - <<'PY'
+          import os, pathlib, re, sys, tomllib
+          tag = os.environ["GITHUB_REF_NAME"]
+          version = tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"]
+          if tag != f"v{version}":
+              sys.exit(f"::error::tag {tag} does not match pyproject version {version} (expected v{version})")
+          changelog = pathlib.Path("CHANGELOG.md").read_text()
+          if not re.search(rf"^## \[{re.escape(version)}\]", changelog, re.M):
+              sys.exit(f"::error::CHANGELOG.md has no '## [{version}]' section")
+          print(f"tag {tag} matches pyproject and CHANGELOG")
+          PY
+
+  # Do not publish something the gates have not passed. This duplicates ci.yml
+  # deliberately: a tag can be pushed at a commit CI never ran on.
+  gates:
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+      # Without this, `uv pip install --system` targets the runner's PEP 668
+      # externally-managed system interpreter and the install fails.
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v5
+      - name: Install
+        run: uv pip install --system -e ".[dev]"
+      - name: Lint
+        run: ruff check carebundle tests
+      - name: Unit, property and determinism tests
+        run: pytest tests/ -q -m "not conformance and not fidelity" --cov --cov-report=term-missing
+      - name: Fetch HL7 validator and R4 definitions
+        run: |
+          mkdir -p .tools/spec
+          curl -sSL -o .tools/validator_cli.jar \
+            "https://github.com/hapifhir/org.hl7.fhir.core/releases/latest/download/validator_cli.jar"
+          curl -sSL -o .tools/spec/definitions.json.zip https://hl7.org/fhir/R4/definitions.json.zip
+          (cd .tools/spec && unzip -o -q definitions.json.zip)
+      - name: US Core conformance (full matrix)
+        run: pytest tests/ -q -m conformance --conformance-scale=full
+
+  build:
+    needs: gates
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --quiet build twine
+          python -m build
+      - name: Check metadata
+        run: twine check --strict dist/*
+      - name: Smoke-test the wheel outside the repo
+        run: |
+          python -m venv /tmp/probe
+          /tmp/probe/bin/pip install --quiet dist/*.whl
+          cd /tmp && /tmp/probe/bin/python -c "
+          import json, carebundle
+          b = json.loads(carebundle.to_json(
+              carebundle.generate_bundle(profile='type2_diabetes', seed=42, sex='F')))
+          assert b['resourceType'] == 'Bundle' and b['entry']
+          print('wheel OK:', len(b['entry']), 'entries')
+          "
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    # Tags only. A workflow_dispatch rehearsal on a branch stops after `build`, so the
+    # irreversible step cannot be reached by anything except pushing a version tag.
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    # The environment gives you a manual approval gate: enable required reviewers on
+    # the `pypi` environment and the upload waits for a human. PyPI uploads cannot be
+    # undone — a deleted version number can never be reused.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/carebundle
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

carebundle-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.coverage
+build/
+dist/
+# Dev/CI tooling: the validator jar and FHIR spec archives are fetched, not vendored.
+.tools/
+# macOS Finder metadata — never wanted in a published sdist.
+.DS_Store

carebundle-0.1.0/BENCHMARK.md

@@ -0,0 +1,250 @@
+# Clinical quality measure benchmark
+
+Regenerate with `pytest -m fidelity tests/test_benchmark.py`. Measures are computed
+from the **emitted FHIR**, not from the internal draw — a measure engine reading the
+sampler's own state would be marking its own homework.
+
+## Why this benchmark and not another
+
+Synthea's published validation ([Chen et al., *BMC Med Inform Decis Mak* 2019](https://pmc.ncbi.nlm.nih.gov/articles/PMC6416981/))
+measured it against four CMS clinical quality measures. The result splits cleanly:
+
+| Measure | Type | Synthea | Real (MA) | Real (US) |
+|---|---|---:|---:|---:|
+| Colorectal cancer screening | process | 68.7% | 77.3% | 69.8% |
+| COPD 30-day mortality | outcome | 0.7% | 7.0% | 8.0% |
+| Complications after hip/knee replacement | outcome | **0%** | 2.9% | 2.8% |
+| Controlling high blood pressure | outcome | **0%** | 74.5% | 69.7% |
+
+Synthea tracks reality on the process measure and collapses on every outcome measure.
+The authors name the cause: synthetic generators "do not currently model for deviations
+in care and the potential outcomes that may result from care deviations."
+
+That is a statement about architecture, not a bug report. A state machine over care
+pathways can decide *whether a patient was screened*. It has no representation of what
+the blood pressure did after the thiazide started, so a control rate cannot emerge from
+it. This project models clinical state directly, which is the machinery an outcome
+measure needs.
+
+## Results
+
+| Measure | Synthea | **carebundle** | Real (US) | Real (MA) |
+|---|---:|---:|---:|---:|
+| Controlling high blood pressure (CBP) | 0% | **71.5%** | 69.7% | 74.5% |
+| Colorectal cancer screening | 68.7% | *not modelled* | 69.8% | 77.3% |
+| COPD 30-day mortality | 0.7% | *not modelled* | 8.0% | 7.0% |
+| Complications after hip/knee replacement | 0% | *not modelled* | 2.8% | 2.9% |
+
+**The three "not modelled" rows are published deliberately.** A benchmark that quietly
+dropped the measures it loses would be worthless as evidence. *Not modelled* is a
+different claim from 0%, and the measure engine keeps them distinguishable: a zero
+denominator is reported as a zero denominator, never as a rate.
+
+**They are also not going to be modelled**, and the reason is licensing rather than
+effort. All three need `Procedure` resources, and the procedures in question have no
+realistic public-domain coding:
+
+- Screening colonoscopy is **CPT 45378** in the ambulatory setting where screening
+  happens; CPT is AMA-licensed. Hip and knee replacement likewise.
+- SNOMED CT needs an affiliate licence and bars redistribution.
+- ICD-10-PCS *is* public domain and US Core accepts it, so `0DJD8ZZ` would validate —
+  but PCS is inpatient facility coding, and no real US ambulatory system emits it for a
+  screening colonoscopy. Conformant and wrong. Checked and rejected rather than used,
+  because winning a benchmark row with a code no real system emits would forfeit the
+  realism claim the row is meant to evidence.
+
+The measures this project can reach are those defined over labs, vitals and diagnoses —
+which it codes with LOINC and ICD-10-CM. That is a real and narrow boundary, and it is
+better stated than discovered.
+
+### Controlling high blood pressure, in detail
+
+Denominator is the HEDIS/NCQA definition — ages 18–85, coded hypertension diagnosis,
+an outpatient encounter, and a recorded blood pressure. Numerator is a most-recent
+reading below **140/90**, with both components required.
+
+| Population | Denominator | CBP rate |
+|---|---:|---:|
+| `hypertension` profile | 1500 | 70.3% |
+| `type2_diabetes` profile | 1045 | 70.8% |
+| `ckd_stage3` profile | 1197 | 71.8% |
+| **Mixed cohort (prevalence-drawn)** | **1822 / 4000** | **71.5%** |
+| `healthy` profile | 0 | *not in denominator* |
+
+## How the number was produced, and why it is not tuned
+
+This is the part that matters. A benchmark you fit to is worthless, so every input
+comes from a cited source and the rate is what those inputs imply.
+
+**Inputs (fitted to sources):**
+
+1. **Who is treated.** NHANES, August 2021–August 2023 ([NCHS Data Brief](https://www.ncbi.nlm.nih.gov/books/NBK612761/)):
+   59.2% of US adults with hypertension are aware of it, 51.2% take medication. So
+   51.2 / 59.2 = **86.5% of diagnosed hypertensives are on treatment**, and
+   diagnosed-and-in-care is exactly the population these profiles represent. The
+   per-drug prescribing probabilities are *solved* for that fraction rather than
+   hand-written, so the cited target and the emitted probabilities cannot drift apart.
+2. **How much treatment lowers pressure.** Law MR, Wald NJ, Morris JK, *BMJ*
+   2003;326:1427 — a meta-analysis of 354 randomised placebo-controlled trials. One
+   standard-dose agent lowers blood pressure by **9.1 systolic / 5.5 diastolic**, and
+   the reduction is larger from a higher starting pressure (1.0 mmHg more systolic per
+   10 mmHg higher pre-treatment). A [2025 *Lancet* meta-analysis](https://pubmed.ncbi.nlm.nih.gov/40885583/)
+   of 484 trials puts monotherapy at 8.7 (95% CI 8.2–9.2), bracketing the same figure.
+
+**Output (not fitted):** the control rate. Nothing in the model was adjusted to reach
+71.5%. Change either cited input and the number moves — which is exactly what happened
+when titration was added, and is documented below rather than smoothed over.
+
+The mechanism is the same computed-identity discipline used for eGFR and Friedewald
+LDL: the copula draws a *pre-treatment* pressure, the prescribing rules escalate on it
+(you add an agent because the patient is uncontrolled), and the *recorded* pressure is
+then computed from the regimen the patient actually received. Effects are applied per
+distinct drug class sequentially, so Law's baseline-dependence produces diminishing
+returns by construction rather than by a fudge factor. A bundle therefore cannot
+prescribe three antihypertensives beside an untreated-looking 168/102.
+
+## The titration hypothesis, tested and confirmed
+
+The first version of this benchmark measured **64.1%** against a US comparator of
+69.7% and published the 5.6-point shortfall rather than closing it, along with a
+specific, falsifiable explanation:
+
+> The most likely mechanism is dose titration: HEDIS scores the *most recent* reading
+> of a year in which clinicians repeatedly re-measure and escalate until the patient
+> reaches goal, whereas this models a single visit with a fixed regimen at standard
+> doses.
+
+**That prediction was then tested and it held.** Modelling titration moved the rate
+from 64.1% to **71.5%**, between the US (69.7%) and Massachusetts (74.5%) comparators.
+
+What makes this a real test rather than a fit:
+
+- The titration effect size comes from a **different study** than the base effect —
+  the [2025 *Lancet* meta-analysis](https://pubmed.ncbi.nlm.nih.gov/40885583/) of 484
+  trials, at 1.5 mmHg systolic per dose doubling — so the correction was not
+  calibrated against the residual it was predicting.
+- Escalation is **conditional on being above goal**, which is what titration is. A
+  patient already at target is never escalated, so the mechanism cannot inflate the
+  control rate from the wrong end by pushing controlled patients further down.
+- The ceiling of two doublings is clinically motivated (beyond roughly four times
+  standard dose, another agent is preferred to another doubling), not fitted. Raising
+  it would push the rate higher; it was fixed before the rate was measured.
+
+The direction of the original error also ruled out the obvious alternative. Law's
+figures are **trial efficacy**, and real-world effectiveness is normally *lower*
+because of adherence — so an adherence gap would have made the modelled rate too
+**high**, not too low. Undershooting pointed at a missing treatment intensity, which
+is what titration supplies.
+
+## Non-adherence: a prediction that failed, and was not shipped
+
+The previous section predicted that adding non-adherence "should push the rate down".
+It does — by far too much to be right.
+
+| Model | CBP rate |
+|---|---:|
+| Current (no explicit adherence term) | 74.7% |
+| 45% of patients take nothing ([Abegaz 2017 meta-analysis](https://pubmed.ncbi.nlm.nih.gov/28121920/)) | 50.4% |
+| Effect scaled by proportion-of-days-covered (62.2%) | 49.3% |
+| **Real-world comparators** | **69.7% – 74.5%** |
+
+Both formulations land roughly 20 points **below** reality. The prediction was right
+about direction and badly wrong about magnitude, and the honest conclusion is that the
+naive adherence term is a worse model, not a missing one. It is therefore **not
+shipped**. Two reasons it fails:
+
+- **The population-wide adherence figures do not transfer to this denominator.** HEDIS
+  CBP counts patients who are diagnosed *and* have an outpatient encounter — people
+  engaged enough with care to show up. Adherence meta-analyses are drawn from a much
+  broader population. Applying the broader figure to the narrower denominator imports
+  a selection effect that the denominator has already excluded.
+- **"Non-adherent" is not "untreated".** A patient with 62% days covered takes most of
+  their doses and gets most of the benefit. Modelling them as receiving nothing is a
+  category error, and the PDC-scaled variant fails for the related reason that response
+  is not linear in coverage.
+
+Recording this matters more than the result. The rate is close to reality *without*
+this term, so a naive version would have made the benchmark worse while sounding more
+sophisticated — and the reason it is excluded is that it contradicts the data by 20
+points, which is model falsification rather than parameter fitting. If adherence is
+modelled later it needs a dose-response formulation and a denominator-matched source.
+
+## Why there is no second measure: CMS122, and what it taught
+
+The obvious candidate for a second measure was **CMS122, Diabetes: HbA1c Poor Control
+(>9%)**. It needs only a diagnosis and a lab result, both of which this project codes
+with ICD-10-CM and LOINC, so unlike the colonoscopy measures it is not blocked by
+licensing. It is blocked by something more interesting.
+
+**The measure has no single national rate.** CMS's own
+[2024 quality benchmarks](https://www.cms.gov/files/document/2024-quality-benchmarks.csv)
+publish three, for the same measure in the same year:
+
+| Collection type | Average performance rate |
+|---|---:|
+| Medicare Part B Claims | 11.70% |
+| MIPS CQM | 27.30% |
+| eCQM (CMS122v12) | 43.53% |
+
+A four-fold spread is not measurement noise, and the numerator definition explains it:
+
+> "Patients whose most recent HbA1c level (performed during the measurement period) is
+> >9.0% **or is missing, or was not performed** during the measurement period"
+
+CMS122 does not measure glycaemic control. It measures glycaemic control **plus
+testing completeness**, summed into one number. The more a collection method depends on
+complete EHR capture, the more untested patients inflate the rate — which is exactly the
+ordering above.
+
+**A generator with perfect data capture cannot reproduce that.** Every diabetic here has
+an HbA1c, so this project would always score at the "everyone was tested" floor. Our
+generated rate above 9.0% is 12.9%, which sits near the claims figure and near NHANES's
+measured 12.9% — and that agreement would be *misleading* to publish as reproducing
+CMS122, because the measure it would claim to reproduce is counting something else.
+
+Two things follow, and both are worth more than the row would have been.
+
+**The blocker generalises.** Any quality measure whose numerator includes "or is
+missing" is partly a data-completeness measure, and synthetic data with complete capture
+can only ever reproduce the clinical half. That is a structural limit on benchmarking
+synthetic generators against real quality measures, and it applies to Synthea equally.
+
+**It is also a use for the imperfection module.** `carebundle.imperfection` exists to
+omit fields on purpose. A future version could model the missing-result component
+explicitly and reproduce the full measure — the only route to CMS122 that would not be
+quietly comparing two different quantities.
+
+**A caveat this exposed in the CBP measure above.** HEDIS CBP has the same shape: a
+member with no blood-pressure reading counts as not controlled. This implementation
+instead requires a reading to enter the denominator. It makes no difference to the
+number, because every generated patient has one — but it means the 71.5% figure is a
+*clinical* control rate compared against real-world rates that blend control with
+capture. The real-world comparators are therefore, if anything, slightly pessimistic
+relative to what is being measured here.
+
+## Remaining caveats
+
+- The comparators are from 2019 and reflect the plans and years measured then. The
+  national HEDIS figure has sat in the low-to-mid 60s in other years.
+- Titration is modelled here as an equilibrium: the recorded pressure is where a
+  titrated patient ends up, which is the right value for a most-recent-reading measure.
+  The trajectory behind it is now available separately via `generate_history`, which
+  emits the same patient across several reviews as therapy is escalated.
+
+## What this does and does not establish
+
+It establishes that a distributional model reproduces an outcome measure that a
+pathway simulator scores **0%** on, from independently cited inputs, checked in CI.
+
+It does not establish that this is a better synthetic data generator than Synthea.
+Synthea covers 231 conditions, a lifetime per patient, and three of the four measures
+in this very table. On breadth it is not close, and [ROADMAP.md](ROADMAP.md) does not
+propose competing there.
+
+## Sources
+
+- [Chen J et al., "The validity of synthetic clinical data … (Synthea) using clinical quality measures", *BMC Med Inform Decis Mak* 2019](https://pmc.ncbi.nlm.nih.gov/articles/PMC6416981/)
+- [NCHS Data Brief: Hypertension Prevalence, Awareness, Treatment, and Control, US, Aug 2021–Aug 2023](https://www.ncbi.nlm.nih.gov/books/NBK612761/)
+- [Law MR, Wald NJ, Morris JK, "Value of low dose combination treatment with blood pressure lowering drugs", *BMJ* 2003;326:1427](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC162261/)
+- [Blood pressure-lowering efficacy of antihypertensive drugs and their combinations, *Lancet* 2025](https://pubmed.ncbi.nlm.nih.gov/40885583/)
+- [NCQA HEDIS: Controlling High Blood Pressure (CBP)](https://www.ncqa.org/report-cards/health-plans/state-of-health-care-quality-report/controlling-high-blood-pressure-cbp/)