sourcelock 0.1.0__py3-none-any.whl

hc_source/adapters/hcc.py

@@ -0,0 +1,1450 @@
+"""CMS-HCC risk adjustment route: ICD-10-CM -> HCC mapping, hierarchies, and
+community continuing-enrollee RAF scoring for models V24 and V28.
+
+Scope (v1): the COMMUNITY CONTINUING-ENROLLEE segments only (CNA/CND/CFA/CFD/
+CPA/CPD). Institutional, new-enrollee, C-SNP new-enrollee, ESRD, and RxHCC are
+out of scope and every receipt says so.
+
+Data: this module vendors compact tables derived from the real CMS model
+software (see ``_DATA_B85`` at the bottom and the ``vendor`` block inside it).
+Authority order per artifact:
+
+* dx->CC mappings, hierarchies, coefficients, labels, age/sex edits, and model
+  logic come from the SAS model software -- ``CMS-HCC software V2826.115.T1``
+  (V28, PY2026 midyear-final) and ``CMS-HCC software V2425.86.P1`` (V24,
+  PY2025 midyear-final; V24 is absent from PY2026+ bundles and will not
+  reappear).
+* the CMS Python package ``CMS_HCC_v28_2026_T_package_v3`` is the cross-check
+  lane (0 mapping/hierarchy/coefficient mismatches after accounting for its
+  encoding of the mandatory age edits; see tests/fixtures/hcc/derive_report.txt)
+  and the source of the documented 3-decimal score rounding.
+* coefficients cross-check against the Rate Announcements: V28 first published
+  in the CY2024 Rate Announcement Table VIII-1 (CNA_F65_69 = 0.330), V24 in the
+  CY2020 Rate Announcement Table VI-1 (CFA_F65_69 = 0.441).
+* normalization factors and payment-year blends come from the Rate
+  Announcements (see ``payment_years`` in the vendored data and
+  tests/fixtures/hcc/VERIFIED_ADDENDUM.md).
+
+Payment-year coverage: one software release is vendored per model, and which
+payment year it was published for is read from the vendored data's own
+``software_version`` string. ``hcc.score`` answers for that pair and refuses
+every other one -- ``data`` is null, the receipt says REFUSED, names the
+release actually held, lists the pairs this build can score, and points at
+``hcc.map``/``hcc.hierarchy_explain`` for working with the vendored revision
+directly. It does NOT run one year's tables under another year's normalization
+factor: a RAF to three decimals from the wrong year's mapping, edits,
+hierarchies and coefficients is a confident wrong answer, and a warning
+underneath one does not make it a right one. Widening the answer is a
+data-acquisition job (vendor the missing release); the scoreable pairs are
+computed from the vendored version strings, so they move on their own when it
+is done. Whether those upstream zips are still the ones the tables came from is
+the ``hcc.model_software_release`` canary's job -- every other hcc canary reads
+vendored bytes and cannot see CMS republish a zip in place.
+
+Hierarchy semantics: hierarchies are applied SEQUENTIALLY in ascending-parent
+order, which is the SAS software's file order and evaluation model (a parent
+zeroed by an earlier rule no longer suppresses its own children). The CMS
+Python package instead suppresses from the pre-hierarchy set; the two differ on
+chains such as V28 HCC62/63/202. The SAS payment software is the authority.
+
+Regeneration: ``python tests/fixtures/hcc/regenerate_vendored_data.py
+--source-dir <dir>`` where the dir holds the CMS artifacts listed in the
+vendored ``vendor.artifacts`` block (URLs + sha256 recorded there).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import zlib
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal, ROUND_HALF_UP
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from ..http import FetchResult, SourceUnreachable, fetch
+from ..interfaces import Canary, CanaryObservation, SourceAdapter, ToolResult, ToolSpec
+from ..receipts import build_receipt
+from ..schemas import CanaryStatus, SourceContract
+
+SOURCE_ID = "hcc"
+TRANSFORM_VERSION = "1"
+
+#: Environment override for the vendored data tables, used by the test suite to
+#: simulate vendored-data drift/tampering. Points at a JSON file with the same
+#: shape as the embedded canonical data.
+DATA_ENV_VAR = "HC_SOURCE_HCC_DATA"
+
+#: URL stamped on receipts when the answer came from the packaged tables.
+EMBEDDED_DATA_URL = "package://hc_source/data/hcc/hcc_data.json.zlib"
+
+#: The packaged vendored-data artifact (zlib-compressed canonical JSON).
+DATA_FILE = Path(__file__).resolve().parents[1] / "data" / "hcc" / "hcc_data.json.zlib"
+
+# Pinned upstream artifacts (identity checked by the release canary; sha256
+# values live in the vendored data's provenance block).
+SOFTWARE_2026_URL = "https://www.cms.gov/files/zip/2026-midyear-final-model-software.zip"
+SOFTWARE_2025_URL = "https://www.cms.gov/files/zip/2025-midyear/final-model-software.zip"
+SOFTWARE_2026_PY_URL = "https://www.cms.gov/files/zip/2026-midyear-final-model-software-python.zip"
+PY2028_PROBE_URL = "https://www.cms.gov/files/zip/2028-initial-model-software.zip"
+
+#: Prefix for the per-artifact URL overrides. Same shape as the provider route:
+#: the override exists so a slug rename is a config change rather than a
+#: release, and so drift can be rehearsed against a ``file://`` mirror.
+_ENV_PREFIX = "HC_SOURCE_HCC_"
+
+_PINNED_ARTIFACTS = (
+    # (short name, env-override name, url, content-length, last-modified date)
+    # verified 2026-08-01.
+    ("sw2026", "SOFTWARE_2026", SOFTWARE_2026_URL, "733317", "23 Dec 2025"),
+    ("sw2025", "SOFTWARE_2025", SOFTWARE_2025_URL, "802577", "10 Jan 2025"),
+    ("py2026", "SOFTWARE_2026_PY", SOFTWARE_2026_PY_URL, "332632", "02 Apr 2026"),
+)
+
+
+def _url(name: str, default: str) -> str:
+    return os.environ.get(f"{_ENV_PREFIX}{name}_URL", default)
+
+
+def _pinned_artifacts() -> tuple[tuple[str, str, str, str], ...]:
+    """(short name, url, pinned content-length, pinned last-modified date).
+
+    Read through the environment on every call rather than frozen at import, so
+    a test or an operator can point one artifact at a mirror without reloading
+    the module.
+    """
+    return tuple(
+        (name, _url(env, url), size, last_modified)
+        for name, env, url, size, last_modified in _PINNED_ARTIFACTS
+    )
+
+CONTRACT = SourceContract(
+    source_id=SOURCE_ID,
+    authority_url=(
+        "https://www.cms.gov/medicare/payment/medicare-advantage-rates-statistics/risk-adjustment"
+    ),
+    fallback_url=None,
+    license_notes=(
+        "US federal government works published on cms.gov: model software, mapping "
+        "workbooks, and Rate Announcements are public domain; no license gate or "
+        "click-through. Contains ICD-10-CM codes (CDC/NCHS, not AMA-licensed) and "
+        "CMS's own HCC labels; no CPT/HCPCS content in this route."
+    ),
+    cadence=(
+        "annual cycle: initial model software ~May of PY-1; midyear-final software "
+        "~Dec PY-1; Rate Announcement with normalization factors ~first week of "
+        "April; CMS also republishes zips in place (no ETag; pin CL+LM+sha256)"
+    ),
+    effective_date_semantics=(
+        "effective_from/effective_to bound the PAYMENT YEAR the answer is for. "
+        "hcc.score is asked for a payment year, so its interval is that year -- "
+        "its normalization factor and blend are that year's Rate Announcement "
+        "values. hcc.map and hcc.hierarchy_explain take no payment year, so "
+        "their interval is the payment year of the vendored model software "
+        "revision they read (V2826.115.T1 -> PY2026, V2425.86.P1 -> PY2025), "
+        "taken from that revision's own version string in the vendored data. The "
+        "vendored tables cover exactly one payment year per model, so a score "
+        "for any other year carries a warning naming the revision it used. "
+        "Diagnoses feeding a payment year are collected in PY-1; the mapping "
+        "workbook spans the two ICD-10-CM fiscal years of that window."
+    ),
+    invariants=[
+        "V28 has exactly 115 payment HCCs and V24 exactly 86",
+        "C2824T2N.csv CNA_F65_69 equals 0.330, the CY2024 Rate Announcement Table VIII-1 value",
+        "C2419P1M.csv CFA_F65_69 equals 0.441, the CY2020 Rate Announcement Table VI-1 value",
+        "pinned software zips keep their Content-Length and Last-Modified until CMS republishes",
+        "PY2028 model software does not exist yet (probe URL returns 404)",
+    ],
+)
+
+NON_CLAIMS_COMMON = [
+    "SEGMENT_SCOPE: results cover the CMS-HCC community continuing-enrollee segment "
+    "only; institutional, new-enrollee, C-SNP new-enrollee, ESRD, and RxHCC models "
+    "are out of scope of this route.",
+    "NOT_A_PAYMENT_GUARANTEE: a RAF score from published model tables is not a "
+    "payment amount or a payment guarantee; CMS payment additionally applies the MA "
+    "coding pattern difference adjustment (5.90 percent statutory minimum for "
+    "CY2024-CY2027), frailty adjustments, and plan- and enrollee-level rules this "
+    "tool does not model.",
+    "MODEL_YEAR_MAPPING: scores apply a model calibration year to a payment year "
+    "per the CMS mapping (V28 = 2024 CMS-HCC model scored with PY2026 midyear-final "
+    "software; V24 = 2020 CMS-HCC model scored with PY2025 midyear-final software, "
+    "its last release).",
+    "DOES_NOT_VALIDATE_DIAGNOSES: input codes are not checked for ICD-10-CM "
+    "validity on a date of service, nor for risk-adjustment eligibility of the "
+    "submitting provider type or setting; unmapped codes are reported, not scored.",
+]
+
+#: Non-claims for a receipt that refused. The common list above is written for
+#: an answer -- "results cover", "scores apply", "unmapped codes are reported" --
+#: and every one of those sentences is false about a call that returned
+#: ``data: null``. A refusal receipt that carries them describes a scoring run
+#: that never ran, which is precisely the failure this route was hardened to
+#: prevent; the receipt would then be the lie instead of the safeguard.
+NON_CLAIMS_REFUSED = [
+    "NO_SCORE_WAS_COMPUTED: this receipt reports a refusal. `data` is null, no "
+    "RAF was calculated, no normalization factor or blend weight was applied, "
+    "and nothing here may be read as a risk score for the requested payment "
+    "year -- not a low one, not a zero one.",
+    "DIAGNOSES_WERE_NOT_EXAMINED: beyond the shape check every parameter gets, "
+    "the submitted codes were not mapped to HCCs, not run through the mandatory "
+    "age/sex edits, and not checked against any ICD-10-CM release. The refusal "
+    "is about the (model, payment year) pair requested and says nothing about "
+    "the codes -- an absent HCC here is an absent computation, not a negative "
+    "finding.",
+    "THE_REASON_IS_IN_THE_WARNINGS: this receipt does not claim the pair is "
+    "unscoreable in principle, and the two reasons it can be refused are not "
+    "the same fact. Either CMS publishes no normalization factor pairing this "
+    "model with this payment year -- a fact about the program -- or it does and "
+    "the matching CMS model software is not vendored in this build, which is a "
+    "fact about this build and widens by vendoring the missing release. The "
+    "warnings say which.",
+    "SEGMENT_SCOPE: when this route does answer, it covers the CMS-HCC "
+    "community continuing-enrollee segment only; institutional, new-enrollee, "
+    "C-SNP new-enrollee, ESRD, and RxHCC models are out of scope of it.",
+]
+
+
+# --------------------------------------------------------------------------
+# Vendored data access
+# --------------------------------------------------------------------------
+
+
+def _embedded_bytes() -> bytes:
+    return zlib.decompress(DATA_FILE.read_bytes())
+
+
+def _data_fetch() -> FetchResult:
+    """Read the vendored tables through the receipt-friendly transport shape.
+
+    The embedded blob is the packaged artifact; ``DATA_ENV_VAR`` lets tests (and
+    a re-vendoring workflow) point at a JSON file instead, which travels through
+    ``hc_source.http.fetch`` so drift simulation uses the same code path.
+    """
+    override = os.environ.get(DATA_ENV_VAR)
+    if override:
+        return fetch(Path(override).absolute().as_uri())
+    content = _embedded_bytes()
+    # ``retrieved_at`` defaults to now, and that is the truthful stamp here: the
+    # packaged file is re-read on every call, so these bytes really were read at
+    # this moment. Only the parse is cached, never the FetchResult -- a cached
+    # result must keep the timestamp of the read that produced it.
+    return FetchResult(
+        url=EMBEDDED_DATA_URL,
+        status=None,
+        content=content,
+        sha256=hashlib.sha256(content).hexdigest(),
+        headers={},
+    )
+
+
+_PARSE_CACHE: dict[str, dict[str, Any]] = {}
+
+
+def _load() -> tuple[FetchResult, dict[str, Any]]:
+    result = _data_fetch()
+    cached = _PARSE_CACHE.get(result.sha256)
+    if cached is None:
+        try:
+            cached = json.loads(result.content)
+        except ValueError as exc:
+            raise SourceUnreachable(
+                result.url, f"vendored data is not valid JSON: {type(exc).__name__}"
+            )
+        _PARSE_CACHE.clear()
+        _PARSE_CACHE[result.sha256] = cached
+    return result, cached
+
+
+def _canonical_hash(payload: dict[str, Any]) -> str:
+    """Canonicalized-content hash: drift decisions key on this, never raw bytes."""
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(canonical).hexdigest()
+
+
+def _schema_hash(payload: dict[str, Any]) -> str:
+    """Hash the SHAPE of the vendored tables (key structure), not their values."""
+    shape = {
+        "top": sorted(payload),
+        "models": {
+            name: sorted(model)
+            for name, model in sorted(payload.get("models", {}).items())
+        },
+        "payment_years": sorted(payload.get("payment_years", {})),
+    }
+    return hashlib.sha256(
+        json.dumps(shape, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+
+
+_SOFTWARE_PY_RE = re.compile(r"\bPY(?P<year>20\d{2})\b")
+
+
+def _software_payment_year(software_version: str) -> int | None:
+    """The payment year a vendored software revision was published for.
+
+    Read out of the vendored data's own ``software_version`` string
+    ("V2826.115.T1 (PY2026 midyear-final)"), never from a table in this module.
+    A hard-coded table here is what let ``hcc.score(model='v28',
+    payment_year=2024)`` run the PY2026 software and stamp a PY2026 effective
+    interval on the receipt: the answer said 2026 while the caller asked about
+    2024, and nothing in the receipt admitted it.
+    """
+    match = _SOFTWARE_PY_RE.search(software_version)
+    return int(match.group("year")) if match else None
+
+
+@dataclass(frozen=True)
+class _Artifact:
+    """The vendored artifact an answer came from, and the window it covers.
+
+    ``effective_from``/``effective_to`` are what the receipt stamps. They come
+    from this record -- selected for the (model, payment year) pair actually
+    requested -- so the receipt can never describe a different year than the one
+    the answer is about.
+    """
+
+    model_key: str
+    software_version: str
+    software_payment_year: int | None
+    payment_year: int | None
+    effective_from: date | None
+    effective_to: date | None
+    warnings: tuple[str, ...] = ()
+
+
+def _select_artifact(
+    data: dict[str, Any], model_key: str, payment_year: int | None = None
+) -> _Artifact:
+    """Select the vendored artifact for a (model, payment year) pair.
+
+    The routes that take no payment year answer for the software revision
+    itself, so their window is that revision's own payment year. The scoring
+    route answers for a payment year, so its window is that year.
+
+    The vendored data holds one software release per model, so for most payment
+    years there are no tables to score with. This function reports that as a
+    fact about the vendored data -- which release is held, which year CMS
+    published it for -- and stops there. It does not describe what the caller
+    will get, because that is the scoring route's decision and the answer is a
+    refusal. Coverage is read from the vendored data's own metadata; this
+    function never invents it.
+    """
+    model = data["models"][model_key]
+    software_version = model["software_version"]
+    native = _software_payment_year(software_version)
+    warnings: list[str] = []
+
+    if native is None:
+        warnings.append(
+            f"the vendored software_version for {model_key} does not name a payment "
+            "year, so the payment year this revision covers cannot be established "
+            "from the vendored data; regenerate the tables from the pinned CMS "
+            "artifacts before relying on this receipt's dates."
+        )
+
+    if payment_year is None:
+        window = (date(native, 1, 1), date(native, 12, 31)) if native else (None, None)
+    else:
+        window = (date(payment_year, 1, 1), date(payment_year, 12, 31))
+        if native is not None and native != payment_year:
+            warnings.append(
+                f"model software mismatch: the vendored data holds no {model_key} "
+                f"software release for PY{payment_year}. The one release "
+                f"it holds for {model_key} is {software_version}, which CMS published "
+                f"for PY{native} -- its mapping, mandatory edits, hierarchies and "
+                f"coefficients are PY{native} tables and are not used to answer for "
+                f"another year."
+            )
+
+    return _Artifact(
+        model_key=model_key,
+        software_version=software_version,
+        software_payment_year=native,
+        payment_year=payment_year,
+        effective_from=window[0],
+        effective_to=window[1],
+        warnings=tuple(warnings),
+    )
+
+
+def _scoreable_pairs(data: dict[str, Any]) -> list[str]:
+    """The (model, payment year) pairs this build can actually score.
+
+    One line, computed from the vendored data: a model can score the payment
+    year its own software release was published for, and only if CMS pairs that
+    model with that year in the Rate Announcement. Everything else has no
+    tables. Never a literal list -- re-vendoring a newer release must move this
+    answer without anybody remembering to edit it.
+    """
+    pairs = []
+    for model_key, model in sorted(data.get("models", {}).items()):
+        native = _software_payment_year(model.get("software_version", ""))
+        if native is None:
+            continue
+        year = data.get("payment_years", {}).get(str(native))
+        if year and model_key in year.get("blend", {}):
+            pairs.append(f"{model_key}/PY{native}")
+    return pairs
+
+
+# --------------------------------------------------------------------------
+# Typed public parameters
+# --------------------------------------------------------------------------
+
+class NoParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+_CODE_RE = re.compile(r"^[A-Z][0-9][0-9A-Z]{1,5}$")
+
+
+def _normalize_codes(raw: str) -> list[str]:
+    """Split, normalise and validate a comma-separated ICD-10-CM list.
+
+    The rejection message names the POSITION of the bad token and describes the
+    rule; it never quotes the token. Round-1 finding C1 was exactly this line
+    interpolating the rejected value, which let an HL7 PID segment round-trip to
+    stdout and to an MCP client. A position is enough to fix a typo and carries
+    nothing that must not be logged.
+    """
+    codes: list[str] = []
+    for position, token in enumerate(raw.replace(";", ",").split(",")):
+        token = token.strip().upper().replace(".", "")
+        if not token:
+            continue
+        if not _CODE_RE.match(token):
+            raise ValueError(
+                f"diagnoses[{position}] is not a well-formed ICD-10-CM code "
+                "(expected a letter, a digit, then 1-5 more digits or letters, "
+                "with an optional dot after the third character -- e.g. E11.9 or E119)"
+            )
+        if token not in codes:
+            codes.append(token)
+    if not codes:
+        raise ValueError("diagnoses must contain at least one ICD-10-CM code")
+    if len(codes) > 200:
+        raise ValueError("diagnoses accepts at most 200 distinct codes per call")
+    return codes
+
+
+class MapParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    diagnoses: str = Field(
+        min_length=1,
+        max_length=4000,
+        description="Comma-separated ICD-10-CM codes, dots optional, e.g. 'E11.9,I50.9'.",
+    )
+    model: Literal["v24", "v28"] = Field(
+        description="CMS-HCC model: v24 (2020 model, 86 HCCs) or v28 (2024 model, 115 HCCs)."
+    )
+
+    @field_validator("diagnoses")
+    @classmethod
+    def _codes(cls, v: str) -> str:
+        _normalize_codes(v)
+        return v
+
+
+class ScoreParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    diagnoses: str = Field(
+        min_length=1,
+        max_length=4000,
+        description="Comma-separated ICD-10-CM codes, dots optional, e.g. 'E11.9,I50.9'.",
+    )
+    model: Literal["v24", "v28"] = Field(
+        description="CMS-HCC model: v24 (2020 model) or v28 (2024 model)."
+    )
+    payment_year: int = Field(
+        ge=2024,
+        le=2027,
+        description=(
+            "Medicare Advantage payment year (2024-2027; factors pinned per year). "
+            "A score is returned only for a (model, payment year) pair whose CMS "
+            "model software is vendored here -- the rest are refused with a receipt "
+            "rather than computed from another year's tables."
+        ),
+    )
+    age: int | None = Field(
+        default=None,
+        ge=0,
+        le=110,
+        description="Age in whole years during the payment year (categorical input, no dates). "
+        "Omitting it drops the demographic term and defaults to the aged segment.",
+    )
+    sex: Literal["f", "m"] | None = Field(
+        default=None,
+        description="Sex for the demographic cell and mandatory sex edits: 'f' or 'm', "
+        "case-insensitive.",
+    )
+    dual: Literal["non", "full", "partial"] = Field(
+        default="non", description="Medicaid dual status: non, full, or partial benefit."
+    )
+    orig_disabled: bool = Field(
+        default=False,
+        description="Originally entitled to Medicare by disability (OREC=1, 'originally "
+        "disabled'); applies to the aged community segments only.",
+    )
+
+    @field_validator("diagnoses")
+    @classmethod
+    def _codes(cls, v: str) -> str:
+        _normalize_codes(v)
+        return v
+
+    @field_validator("sex", mode="before")
+    @classmethod
+    def _sex(cls, v: Any) -> Any:
+        """Normalise case before the Literal is matched.
+
+        The CMS artifacts spell this value 'F' and 'M', and every other code-like
+        input on this route is case-folded before matching, so a caller who typed
+        the upstream spelling got a rejection that looked like a defect in the
+        tool. Normalising keeps the accepted set at two values -- widening the
+        Literal to four would put the caller's casing into the segment cell and
+        the receipt.
+        """
+        return v.lower() if isinstance(v, str) else v
+
+
+class HierarchyParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    diagnoses: str = Field(
+        min_length=1,
+        max_length=4000,
+        description="Comma-separated ICD-10-CM codes, dots optional.",
+    )
+    model: Literal["v24", "v28"] = Field(
+        description="CMS-HCC model: v24 (2020 model) or v28 (2024 model)."
+    )
+
+    @field_validator("diagnoses")
+    @classmethod
+    def _codes(cls, v: str) -> str:
+        _normalize_codes(v)
+        return v
+
+
+# --------------------------------------------------------------------------
+# Model engine (pure functions over the vendored tables)
+# --------------------------------------------------------------------------
+
+_AGE_BANDS = (
+    (0, 34, "0_34"), (35, 44, "35_44"), (45, 54, "45_54"), (55, 59, "55_59"),
+    (60, 64, "60_64"), (65, 69, "65_69"), (70, 74, "70_74"), (75, 79, "75_79"),
+    (80, 84, "80_84"), (85, 89, "85_89"), (90, 94, "90_94"), (95, 999, "95_GT"),
+)
+
+_SEGMENT_NAMES = {
+    "CNA": "Community, Non-dual, Aged",
+    "CND": "Community, Non-dual, Disabled",
+    "CFA": "Community, Full-benefit dual, Aged",
+    "CFD": "Community, Full-benefit dual, Disabled",
+    "CPA": "Community, Partial-benefit dual, Aged",
+    "CPD": "Community, Partial-benefit dual, Disabled",
+}
+
+_EDIT_WHEN_RE = re.compile(
+    r"^(?:sex == (?P<sex>[fm])"
+    r"|age < (?P<lt>\d+)"
+    r"|age >= (?P<ge>\d+)"
+    r"|age < (?P<lo>\d+) or age > (?P<hi>\d+))$"
+)
+
+
+def _edit_applies(when: str, age: int | None, sex: str | None) -> bool | None:
+    """True/False when decidable, None when the needed demographic is missing."""
+    m = _EDIT_WHEN_RE.match(when)
+    if not m:  # unknown rule text in (possibly overridden) data: skip, decidable
+        return False
+    if m.group("sex") is not None:
+        return None if sex is None else sex == m.group("sex")
+    if age is None:
+        return None
+    if m.group("lt") is not None:
+        return age < int(m.group("lt"))
+    if m.group("ge") is not None:
+        return age >= int(m.group("ge"))
+    return age < int(m.group("lo")) or age > int(m.group("hi"))
+
+
+def _map_codes(
+    model: dict[str, Any],
+    codes: list[str],
+    age: int | None,
+    sex: str | None,
+    warnings: list[str],
+) -> tuple[dict[str, list[int]], list[str], list[dict[str, Any]]]:
+    """Apply the dx->CC map plus the mandatory age/sex edits.
+
+    Returns (mapped {code: [cc,...]}, unmapped [code,...], edits_applied).
+    """
+    mapping: dict[str, list[int]] = model["mapping"]
+    mapped: dict[str, list[int]] = {}
+    unmapped: list[str] = []
+    edits_applied: list[dict[str, Any]] = []
+
+    for code in codes:
+        ccs = mapping.get(code)
+        if ccs is None:
+            unmapped.append(code)
+            continue
+        mapped[code] = list(ccs)
+
+    for rule in model.get("age_sex_edits", []):
+        hit = [c for c in mapped if c in rule["codes"]]
+        if not hit:
+            continue
+        applies = _edit_applies(rule["when"], age, sex)
+        if applies is None:
+            warnings.append(
+                f"codes {sorted(hit)} carry a mandatory CMS age/sex edit "
+                f"({rule['when']!r} -> CC {rule['set_cc'] if rule['set_cc'] else 'invalid'}); "
+                "age/sex not provided, so the default mapping was used."
+            )
+            continue
+        if not applies:
+            continue
+        for code in hit:
+            before = mapped[code]
+            if rule["set_cc"] is None:
+                mapped[code] = []
+                action = "dropped as invalid for this age/sex"
+            else:
+                mapped[code] = [int(rule["set_cc"])]
+                action = f"reassigned to CC {rule['set_cc']}"
+            edits_applied.append(
+                {"code": code, "was": before, "action": action, "cite": rule["cite"]}
+            )
+
+    if unmapped:
+        warnings.append(
+            f"{len(unmapped)} code(s) do not map to any payment HCC in this model and "
+            f"were excluded from scoring: {unmapped}. Unmapped codes are reported, "
+            "never silently dropped."
+        )
+    return mapped, unmapped, edits_applied
+
+
+def _apply_pre_hierarchy(
+    model: dict[str, Any], present: set[int]
+) -> tuple[set[int], list[dict[str, Any]]]:
+    applied = []
+    out = set(present)
+    for rule in model.get("pre_hierarchy_rules", []):
+        cc = int(rule["if_cc"])
+        if cc in out and not (out & {int(x) for x in rule["requires_any"]}):
+            out.discard(int(rule["else_zero"]))
+            applied.append(
+                {
+                    "rule": f"CC{cc} requires one of {rule['requires_any']}",
+                    "effect": f"CC{rule['else_zero']} zeroed",
+                    "cite": rule["cite"],
+                }
+            )
+    return out, applied
+
+
+def _apply_hierarchy(
+    model: dict[str, Any], present: set[int]
+) -> tuple[list[int], list[dict[str, int]]]:
+    """Sequential ascending-parent application (SAS file-order semantics)."""
+    alive = set(present)
+    suppressed: list[dict[str, int]] = []
+    hier: dict[str, list[int]] = model["hierarchies"]
+    for parent_key in sorted(hier, key=int):
+        parent = int(parent_key)
+        if parent not in alive:
+            continue
+        for child in hier[parent_key]:
+            if child in alive:
+                alive.discard(child)
+                suppressed.append({"hcc": child, "suppressed_by": parent})
+    return sorted(alive), suppressed
+
+
+def _category_flags(model: dict[str, Any], final_hccs: set[int]) -> dict[str, int]:
+    return {
+        name: int(any(h in final_hccs for h in members))
+        for name, members in model["categories"].items()
+    }
+
+
+def _interaction_flags(
+    model: dict[str, Any], final_hccs: set[int], categories: dict[str, int]
+) -> dict[str, int]:
+    def resolve(var: str) -> int:
+        if var.startswith("HCC") and var[3:].isdigit():
+            return int(int(var[3:]) in final_hccs)
+        return categories.get(var, 0)
+
+    return {
+        name: resolve(v1) * resolve(v2)
+        for name, (v1, v2) in model["interactions"].items()
+    }
+
+
+def _count_variable(n: int) -> str | None:
+    if n <= 0:
+        return None
+    return f"D{n}" if n < 10 else "D10P"
+
+
+def _dec(value: str) -> Decimal:
+    return Decimal(value).quantize(Decimal("0.001"))
+
+
+# --------------------------------------------------------------------------
+# Handlers
+# --------------------------------------------------------------------------
+
+
+def _hcc_entry(model: dict[str, Any], hcc: int) -> dict[str, Any]:
+    return {"hcc": hcc, "label": model["labels"].get(str(hcc), "")}
+
+
+def _map_handler(params: MapParams) -> ToolResult:
+    result, data = _load()
+    model = data["models"][params.model]
+    codes = _normalize_codes(params.diagnoses)
+    warnings: list[str] = []
+    mapped, unmapped, _ = _map_codes(model, codes, age=None, sex=None, warnings=warnings)
+
+    rows = []
+    for code in codes:
+        if code in mapped:
+            rows.append(
+                {
+                    "code": code,
+                    "hccs": [_hcc_entry(model, cc) for cc in mapped[code]],
+                    "payment": True,
+                }
+            )
+    payload = {
+        "model": params.model,
+        "model_name": model["cms_name"],
+        "software_version": model["software_version"],
+        "mapped": rows,
+        "unmapped": unmapped,
+        "mapping_provenance": {
+            "derived_from": data["vendor"]["artifacts"],
+            "note": "per-mapping authority: SAS dx->CC dump inside the model software "
+            "zip named in software_version; cross-checked against the CMS Python "
+            "package (V28) at vendor time.",
+        },
+    }
+    artifact = _select_artifact(data, params.model)
+    warnings.extend(artifact.warnings)
+    return ToolResult(
+        data=payload,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="hcc.map",
+            fetch=result,
+            source_version=model["software_version"],
+            transform_version=TRANSFORM_VERSION,
+            effective_from=artifact.effective_from,
+            effective_to=artifact.effective_to,
+            warnings=warnings,
+            non_claims=NON_CLAIMS_COMMON,
+        ),
+    )
+
+
+def _score_handler(params: ScoreParams) -> ToolResult:
+    result, data = _load()
+    model = data["models"][params.model]
+    codes = _normalize_codes(params.diagnoses)
+    warnings: list[str] = []
+
+    # Select the artifact for THIS (model, payment year) pair before anything
+    # else: the receipt's window and the software-revision caveat both come from
+    # it, and both are wrong if they are decided by the model alone.
+    artifact = _select_artifact(data, params.model, params.payment_year)
+    warnings.extend(artifact.warnings)
+
+    def _miss() -> ToolResult:
+        """A refusal, described as a refusal.
+
+        `NON_CLAIMS_REFUSED`, not the common list: the common list is written
+        for a receipt that has a score under it, and a receipt whose prose
+        narrates a computation that did not happen is the exact defect this
+        route's hard gate exists to prevent.
+        """
+        return ToolResult(
+            data=None,
+            receipt=build_receipt(
+                contract=CONTRACT,
+                route="hcc.score",
+                fetch=result,
+                source_version=model["software_version"],
+                transform_version=TRANSFORM_VERSION,
+                effective_from=artifact.effective_from,
+                effective_to=artifact.effective_to,
+                warnings=warnings,
+                non_claims=NON_CLAIMS_REFUSED,
+            ),
+        )
+
+    py = data["payment_years"].get(str(params.payment_year))
+    if py is None:
+        # Reachable when the vendored tables are overridden or regenerated
+        # without a year the parameter model still accepts. Reported as a miss,
+        # never as a score computed from another year's factors.
+        warnings.append(
+            f"payment year {params.payment_year} has no vendored factor set: the "
+            f"vendored data carries Rate Announcement factors for payment years "
+            f"{', '.join(sorted(data['payment_years']))} only."
+        )
+        return _miss()
+
+    # Payment-year / model applicability.
+    if params.model not in py["blend"]:
+        paid = sorted(
+            year for year, entry in data["payment_years"].items()
+            if params.model in entry["blend"]
+        )
+        warnings.append(
+            f"{params.model} is not a Part C payment model for payment year "
+            f"{params.payment_year}: CMS publishes no normalization factor for it "
+            f"({py['source']}). Payment years the vendored data pairs with "
+            f"{params.model}: {', '.join(paid) if paid else 'none'}."
+        )
+        return _miss()
+
+    if py.get("staged"):
+        # The vendored data's own staged flag: factors published, cycle not
+        # closed. A fact about the payment year, true whether or not this call
+        # goes on to score, so it is stated before the gate below rather than
+        # after it -- for a staged year it is the reason the gate fires.
+        warnings.append(
+            f"payment year {params.payment_year} is staged: its Rate Announcement "
+            f"factors are published and pinned ({py['source']}), but CMS's "
+            f"midyear-final model software for that year is not vendored here."
+        )
+
+    # The hard gate, and it comes before anything that describes a score.
+    #
+    # Everything above this point is a fact about the vendored data or the
+    # payment year -- true of a refusal as much as of an answer. Everything
+    # below describes a score that was computed, so on this branch it would be
+    # describing a computation that did not happen. A receipt is the whole
+    # product here; one that narrates a scoring run and returns `data: null` is
+    # the failure this route exists to prevent, wearing our own uniform.
+    #
+    # `_select_artifact` already names the mismatch on the receipt, and that was
+    # not enough. Selecting `data["models"][model]` regardless of the payment
+    # year means the mapping, the mandatory edits, the hierarchies and every
+    # coefficient come from whichever single release is vendored for that model
+    # -- so `score(model="v28", payment_year=2024)` returned a RAF to three
+    # decimals computed from PY2026 tables, with a warning underneath it. A
+    # caller acts on the number. Warned-but-wrong is not a category this product
+    # ships, and the honest answer to "what is the PY2024 V28 score" when the
+    # PY2024 V28 release is not vendored is that we do not know.
+    #
+    # The alternative was vendoring every (model, payment year) release CMS has
+    # published. That is the right long-term fix and it is a data-acquisition
+    # job, not a code change: the pairs below widen the moment those artifacts
+    # are vendored, because this test reads the vendored data's own version
+    # strings rather than a table in this module.
+    if artifact.software_payment_year != params.payment_year:
+        held = (
+            f"the {artifact.software_version} release, which CMS published for "
+            f"PY{artifact.software_payment_year}"
+            if artifact.software_payment_year is not None
+            else f"the {artifact.software_version} release, whose payment year the "
+            "vendored data does not name"
+        )
+        pairs = _scoreable_pairs(data)
+        warnings.append(
+            f"REFUSED: no {params.model} model software for payment year "
+            f"{params.payment_year} is vendored, so there is no score to give. "
+            f"Computing one would use {held}: its mapping, its mandatory edits, its "
+            f"hierarchies and its coefficients. A RAF carried to three decimals from "
+            f"another year's tables is a confident wrong answer, and this route "
+            f"returns nothing rather than that. Pairs this build can score: "
+            f"{', '.join(pairs) if pairs else 'none'}. Use hcc.map or "
+            f"hcc.hierarchy_explain to work with the vendored revision directly."
+        )
+        return _miss()
+
+    # Past the gate: from here on a score is actually being computed, so prose
+    # about one is prose about something that happened.
+    blend_weight = py["blend"][params.model]
+    if len(py["blend"]) > 1:
+        warnings.append(
+            f"payment year {params.payment_year} is a blend year "
+            f"({py['blend']}); this call scores the {params.model} component only "
+            f"(weight {blend_weight}). The full payment risk score blends the "
+            f"normalized scores of both models per {py['source']}."
+        )
+
+    # Demographics -> segment.
+    if params.age is None:
+        aged = True
+        warnings.append(
+            "age not provided: demographic (age-sex) term excluded and the aged "
+            "community segment assumed; the RAF below is a partial, disease-led score."
+        )
+    else:
+        aged = params.age >= 65
+    segment = "C" + {"non": "N", "full": "F", "partial": "P"}[params.dual] + ("A" if aged else "D")
+    coefs: dict[str, str] = model["coefficients"][segment]
+
+    # Mapping + mandatory edits.
+    mapped, unmapped, edits_applied = _map_codes(
+        model, codes, params.age, params.sex, warnings
+    )
+    present = {cc for ccs in mapped.values() for cc in ccs}
+
+    # Pre-hierarchy patch, hierarchy, categories, interactions, counts.
+    present, prehier_applied = _apply_pre_hierarchy(model, present)
+    final_hccs, suppressed = _apply_hierarchy(model, present)
+    final_set = set(final_hccs)
+    categories = _category_flags(model, final_set)
+    interactions = _interaction_flags(model, final_set, categories)
+
+    terms: list[dict[str, Any]] = []
+
+    # Demographic cell.
+    if params.age is not None and params.sex is not None:
+        band = next(b for lo, hi, b in _AGE_BANDS if lo <= params.age <= hi)
+        cell = f"{params.sex.upper()}{band}"
+        if cell in coefs:
+            terms.append({"variable": cell, "kind": "demographic", "value": coefs[cell]})
+        else:  # defensive; segment selection keeps bands consistent
+            warnings.append(f"no {segment} coefficient for demographic cell {cell}.")
+    elif params.age is not None and params.sex is None:
+        warnings.append(
+            "sex not provided: demographic (age-sex) term excluded; the RAF below "
+            "is a partial score."
+        )
+
+    if params.orig_disabled:
+        if aged and params.sex is not None:
+            var = "OriginallyDisabled_Female" if params.sex == "f" else "OriginallyDisabled_Male"
+            if var in coefs:
+                terms.append({"variable": var, "kind": "demographic", "value": coefs[var]})
+        elif aged:
+            warnings.append(
+                "orig_disabled needs sex to select its coefficient; term excluded."
+            )
+        else:
+            warnings.append(
+                "orig_disabled does not apply to the disabled community segments "
+                "(ORIGDS is zero when DISABL=1 per AGESEXV2.TXT); term excluded."
+            )
+
+    # Disease coefficients (post-hierarchy payment HCCs).
+    for hcc in final_hccs:
+        var = f"HCC{hcc}"
+        if var in coefs:
+            terms.append(
+                {
+                    "variable": var,
+                    "kind": "hcc",
+                    "label": model["labels"].get(str(hcc), ""),
+                    "value": coefs[var],
+                }
+            )
+
+    # Interactions present in this segment's regression.
+    for name, flag in sorted(interactions.items()):
+        if flag and name in coefs:
+            terms.append({"variable": name, "kind": "interaction", "value": coefs[name]})
+
+    # Payment HCC count variable.
+    count_var = _count_variable(len(final_hccs))
+    if count_var and count_var in coefs:
+        terms.append(
+            {
+                "variable": count_var,
+                "kind": "payment_hcc_count",
+                "count": len(final_hccs),
+                "value": coefs[count_var],
+            }
+        )
+
+    raw = sum((_dec(t["value"]) for t in terms), Decimal("0.000"))
+    raw = raw.quantize(Decimal("0.001"))  # documented no-op: 3dp inputs sum exactly
+
+    factor = Decimal(py["normalization"][params.model])
+    normalized = (raw / factor).quantize(Decimal("0.001"), rounding=ROUND_HALF_UP)
+
+    payload = {
+        "scope": "CMS-HCC community continuing-enrollee segment",
+        "model": params.model,
+        "model_name": model["cms_name"],
+        "software_version": model["software_version"],
+        "payment_year": params.payment_year,
+        "segment": {"code": segment, "description": _SEGMENT_NAMES[segment]},
+        "inputs": {
+            "diagnoses": codes,
+            "age": params.age,
+            "sex": params.sex,
+            "dual": params.dual,
+            "orig_disabled": params.orig_disabled,
+        },
+        "mapping": {
+            "mapped": [{"code": c, "ccs": mapped[c]} for c in codes if c in mapped],
+            "unmapped": unmapped,
+        },
+        "edits_applied": edits_applied,
+        "pre_hierarchy_rules_applied": prehier_applied,
+        "hierarchy": {
+            "final_hccs": [_hcc_entry(model, h) for h in final_hccs],
+            "suppressed": suppressed,
+        },
+        "terms": terms,
+        "raw_score": str(raw),
+        "raw_score_state": (
+            "pre-normalization: exact sum of published 3-decimal coefficients; "
+            "CMS's PY2026 Python model software rounds this value to 3 decimals, "
+            "which is a no-op under exact decimal arithmetic"
+        ),
+        "normalization": {
+            "factor": str(factor),
+            "factor_source": py["source"],
+            "applied_as": (
+                "normalized_score = raw_score / factor -- 'we apply it by dividing "
+                "each individual risk score in the payment year by the normalization "
+                "factor' (CY2027 Advance Notice p.59)"
+            ),
+            "rounding": "3 decimals, ROUND_HALF_UP (see VERIFIED_ADDENDUM)",
+        },
+        "normalized_score": str(normalized),
+        "normalized_score_state": "post-normalization",
+        "blend": {
+            "payment_year_blend": py["blend"],
+            "requested_model_weight": blend_weight,
+        },
+        "not_applied": [
+            f"MA coding pattern difference adjustment "
+            f"({Decimal(py['coding_pattern_adjustment']) * 100:.2f} percent)",
+            "frailty adjustment (PACE/FIDE SNP)",
+            "MCE age/sex range edits (optional SEDITS lane of the CMS software)",
+            "new-enrollee, institutional, ESRD, and RxHCC models",
+        ],
+    }
+
+    return ToolResult(
+        data=payload,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="hcc.score",
+            fetch=result,
+            source_version=f"{model['software_version']} + PY{params.payment_year} factors",
+            transform_version=TRANSFORM_VERSION,
+            effective_from=artifact.effective_from,
+            effective_to=artifact.effective_to,
+            warnings=warnings,
+            non_claims=NON_CLAIMS_COMMON,
+        ),
+    )
+
+
+def _hierarchy_handler(params: HierarchyParams) -> ToolResult:
+    result, data = _load()
+    model = data["models"][params.model]
+    codes = _normalize_codes(params.diagnoses)
+    warnings: list[str] = []
+
+    mapped, unmapped, _ = _map_codes(model, codes, age=None, sex=None, warnings=warnings)
+    present = {cc for ccs in mapped.values() for cc in ccs}
+    pre = sorted(present)
+    present, prehier_applied = _apply_pre_hierarchy(model, present)
+    final_hccs, suppressed = _apply_hierarchy(model, present)
+
+    payload = {
+        "model": params.model,
+        "model_name": model["cms_name"],
+        "software_version": model["software_version"],
+        "before_hierarchy": [_hcc_entry(model, h) for h in pre],
+        "pre_hierarchy_rules_applied": prehier_applied,
+        "suppressed": [
+            {
+                "hcc": s["hcc"],
+                "label": model["labels"].get(str(s["hcc"]), ""),
+                "suppressed_by": s["suppressed_by"],
+                "suppressed_by_label": model["labels"].get(str(s["suppressed_by"]), ""),
+            }
+            for s in suppressed
+        ],
+        "final_hccs": [_hcc_entry(model, h) for h in final_hccs],
+        "semantics": (
+            "sequential ascending-parent application per the SAS hierarchy macro "
+            "file order; a parent zeroed by an earlier rule no longer suppresses "
+            "its own children"
+        ),
+        "unmapped": unmapped,
+    }
+    artifact = _select_artifact(data, params.model)
+    warnings.extend(artifact.warnings)
+    return ToolResult(
+        data=payload,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="hcc.hierarchy_explain",
+            fetch=result,
+            source_version=model["software_version"],
+            transform_version=TRANSFORM_VERSION,
+            effective_from=artifact.effective_from,
+            effective_to=artifact.effective_to,
+            warnings=warnings,
+            non_claims=NON_CLAIMS_COMMON,
+        ),
+    )
+
+
+# --------------------------------------------------------------------------
+# Canaries
+# --------------------------------------------------------------------------
+
+
+_RELEASE_DRIFT_REMEDIATION = (
+    "CMS republished or retired a pinned model-software zip (Content-Length/"
+    "Last-Modified moved). Re-download the changed zip, recompute sha256, diff "
+    "the inner-zip listing against the provenance block in the vendored data, "
+    "regenerate with `python tests/fixtures/hcc/regenerate_vendored_data.py "
+    "--source-dir <dir>` if tables changed, then re-pin with `hc-source lock "
+    "init`. If a URL returns HTTP 404, re-run discovery from the risk-adjustment "
+    "hub page -- CMS renames slugs (see the `.zip-0` trap in the route dossier)."
+)
+
+_PY2028_REMEDIATION = (
+    "PY2028 model-software artifacts appeared on cms.gov. This is a STAGED future "
+    "cycle, not breakage: fetch the 2028 model-software page from the risk-"
+    "adjustment hub, inventory the inner zips (watch for a model version other "
+    "than V28 -- a '2027 CMS-HCC model' was proposed but not finalized in the "
+    "CY2027 cycle), extract the PY2028 normalization factors from the 2028 Rate "
+    "Announcement, extend payment_years in the vendored data, and re-pin with "
+    "`hc-source lock init`."
+)
+
+
+def _artifact_identity(result: FetchResult) -> str:
+    """One model artifact's release identity, as served.
+
+    cms.gov sends no ETag for these zips, so identity is Content-Length plus
+    Last-Modified: the pair that moves when CMS republishes a zip IN PLACE at the
+    same URL. A 4xx/5xx is an identity too -- a retired slug is exactly the event
+    worth reporting.
+
+    A 2xx that carries neither a size nor a Last-Modified is refused rather than
+    reduced to a placeholder. An observation of ``?@?`` would pin cleanly and
+    stay green forever, which is the failure this identity exists to prevent.
+    """
+    if result.status is not None and result.status >= 400:
+        return f"HTTP{result.status}"
+    content_range = result.headers.get("content-range", "")
+    size = (
+        content_range.rsplit("/", 1)[-1]
+        if "/" in content_range
+        else result.headers.get("content-length")
+    )
+    last_modified = result.headers.get("last-modified")
+    if size and last_modified:
+        # 'Tue, 23 Dec 2025 20:02:15 GMT' -> '23 Dec 2025'.
+        day = (
+            " ".join(last_modified.split()[1:4])
+            if last_modified.count(" ") >= 4
+            else last_modified
+        )
+        return f"{size}@{day}"
+    if result.status is None:
+        # A locally mirrored artifact (file://) has no HTTP identity headers, so
+        # its bytes are the identity. The prefix self-describes: a pin taken
+        # against a mirror must never read as one taken against cms.gov.
+        return f"mirror-sha256:{result.sha256[:12]}"
+    raise SourceUnreachable(
+        result.url,
+        "response carries neither a size (Content-Range/Content-Length) nor a "
+        "Last-Modified, so this artifact's release identity cannot be observed "
+        "and pinning it would attest to nothing",
+        status=result.status,
+    )
+
+
+def _probe_handler(_: NoParams) -> ToolResult:
+    """Live upstream identity probe: a wider, human-readable form of what the
+    ``hcc.model_software_release`` canary pins. One 1-byte ranged GET per pinned
+    zip (cms.gov serves no ETag: identity = Content-Length + Last-Modified;
+    confirm with sha256 after any full re-download) plus the deterministic
+    PY2028 404 probe, which the canary deliberately leaves out because a future
+    cycle opening is a staged watch item, not artifact drift."""
+    data_result, _data = _load()
+    warnings: list[str] = []
+    artifacts = []
+    for name, url, pinned_size, pinned_lm in _pinned_artifacts():
+        result = fetch(url, headers={"Range": "bytes=0-0"}, raise_for_status=False)
+        observed = _artifact_identity(result)
+        pinned = f"{pinned_size}@{pinned_lm}"
+        status = "ok" if observed == pinned else "drift"
+        if status == "drift":
+            warnings.append(
+                f"{name}: observed {observed}, pinned {pinned}. {_RELEASE_DRIFT_REMEDIATION}"
+            )
+        artifacts.append(
+            {"artifact": name, "url": url, "pinned": pinned, "observed": observed,
+             "status": status}
+        )
+
+    probe = fetch(PY2028_PROBE_URL, raise_for_status=False)
+    py2028 = "absent" if probe.status == 404 else f"published(HTTP {probe.status})"
+    if py2028 != "absent":
+        warnings.append(f"PY2028 cycle opened. {_PY2028_REMEDIATION}")
+
+    payload = {
+        "artifacts": artifacts,
+        "py2028_cycle": py2028,
+        "remediation_on_drift": _RELEASE_DRIFT_REMEDIATION,
+        "remediation_on_py2028": _PY2028_REMEDIATION,
+    }
+    return ToolResult(
+        data=payload,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="hcc.release_probe",
+            fetch=data_result,
+            source_version="pinned artifact identities, verified 2026-08-01",
+            transform_version=TRANSFORM_VERSION,
+            warnings=warnings,
+            non_claims=NON_CLAIMS_COMMON
+            + [
+                "UPSTREAM_IDENTITY_ONLY: this probe compares Content-Length and "
+                "Last-Modified of the pinned CMS zips; it does not download or "
+                "re-hash their bytes -- confirm any drift with a full download "
+                "and sha256 before re-vendoring."
+            ],
+        ),
+    )
+
+
+def _observe_vendored_tables() -> CanaryObservation:
+    _, data = _load()
+    return CanaryObservation(
+        value=_canonical_hash(data)[:16],
+        schema_hash=_schema_hash(data),
+        note="canonicalized-content hash of the vendored mapping/coefficient tables",
+    )
+
+
+def _vendored_remediation(status: CanaryStatus, observed: str | None, expected: str | None) -> str:
+    if status is CanaryStatus.SCHEMA_CHANGED:
+        return (
+            "The vendored hcc tables changed SHAPE (model/payment-year key structure). "
+            "This only happens on an intentional re-vendor: review the regeneration "
+            "diff, bump TRANSFORM_VERSION in hc_source/adapters/hcc.py, and re-pin "
+            "with `hc-source lock init`."
+        )
+    if status is CanaryStatus.UNREACHABLE:
+        return (
+            "The vendored hcc tables could not be read. Unset HC_SOURCE_HCC_DATA if "
+            "it points at a missing/corrupt file, or reinstall the package; then "
+            "re-run `hc-source doctor`."
+        )
+    return (
+        "The vendored hcc tables' content hash moved without a matching lockfile "
+        "update -- either HC_SOURCE_HCC_DATA points at modified data or the package "
+        "was tampered with. Verify the regeneration provenance (tests/fixtures/hcc/"
+        "derive_report.txt), regenerate from the pinned CMS artifacts, and only "
+        "then re-pin with `hc-source lock init`."
+    )
+
+
+def _observe_coefficient_spots() -> CanaryObservation:
+    # Value kept short for the doctor table. Field order:
+    # v28 CNA_F65_69 | v24 CFA_F65_69 | 2026 v28 norm | 2024 v24 norm |
+    # v28 payment-HCC count | v24 payment-HCC count.
+    _, data = _load()
+    m28, m24 = data["models"]["v28"], data["models"]["v24"]
+    spots = [
+        str(m28["coefficients"]["CNA"].get("F65_69", "?")),
+        str(m24["coefficients"]["CFA"].get("F65_69", "?")),
+        str(data["payment_years"]["2026"]["normalization"].get("v28", "?")),
+        str(data["payment_years"]["2024"]["normalization"].get("v24", "?")),
+        str(len(m28.get("payment_hccs", []))),
+        str(len(m24.get("payment_hccs", []))),
+    ]
+    return CanaryObservation(
+        value="|".join(spots),
+        note="v28 CNA_F65_69 | v24 CFA_F65_69 | 2026/2024 normalization | payment-HCC counts",
+    )
+
+
+def _observe_model_software_release() -> CanaryObservation:
+    """LIVE upstream identity of the model-software artifacts the tables came from.
+
+    Every other hcc canary observes VENDORED bytes, so every one of them stays
+    green forever if CMS republishes the V24 or V28 zip in place at the same URL:
+    the package would simply be quietly out of date, and both source-lock.json
+    and the GitHub Action would keep saying so. This canary is the one hcc
+    observation that leaves the machine, which is why it is declared ``live`` in
+    tests/test_offline_doctor.py and surfaces as UNREACHABLE with no network.
+    """
+    identities = [
+        _artifact_identity(fetch(url, headers={"Range": "bytes=0-0"}, raise_for_status=False))
+        for _name, url, _size, _last_modified in _pinned_artifacts()
+    ]
+    return CanaryObservation(
+        value="|".join(identities),
+        note="upstream Content-Length@Last-Modified of "
+        + ", ".join(name for name, *_rest in _PINNED_ARTIFACTS)
+        + ", in that order",
+    )
+
+
+def _model_release_remediation(
+    status: CanaryStatus, observed: str | None, expected: str | None
+) -> str:
+    # ERROR as well as UNREACHABLE: a canary that failed for any reason did not
+    # observe upstream, and telling that operator CMS republished something
+    # would be a guess dressed as a finding.
+    if status in (CanaryStatus.UNREACHABLE, CanaryStatus.ERROR):
+        return (
+            "The pinned CMS model-software zips could not be read, so this run does "
+            "not know whether the vendored tables still match upstream; the other hcc "
+            "canaries covered the vendored tables only. With no network that is "
+            "expected. With network: check "
+            "https://www.cms.gov/medicare/payment/medicare-advantage-rates-statistics/"
+            "risk-adjustment for a renamed slug (CMS renames them; see the `.zip-0` "
+            f"trap in the route dossier), point {_ENV_PREFIX}SOFTWARE_2026_URL and its "
+            "SOFTWARE_2025/SOFTWARE_2026_PY siblings at the current locations if they "
+            "moved, then re-run `hc-source doctor`."
+        )
+    return _RELEASE_DRIFT_REMEDIATION
+
+
+_SPOT_REMEDIATION = (
+    "A pinned spot value moved. The authorities are: CY2024 Rate Announcement "
+    "Table VIII-1 (v28 CNA_F65_69 = 0.330), CY2020 Rate Announcement Table VI-1 "
+    "(v24 CFA_F65_69 = 0.441), CY2026 Rate Announcement p.5 (2026 v28 "
+    "normalization = 1.067), CY2024 Rate Announcement pp.5-6 (2024 v24 "
+    "normalization = 1.146), and the model software HCC counts (115/86). Compare "
+    "the vendored data against those documents, fix the regeneration, and re-pin "
+    "with `hc-source lock init` only after the values match the PDFs."
+)
+
+
+# --------------------------------------------------------------------------
+# Adapter
+# --------------------------------------------------------------------------
+
+
+class HccAdapter(SourceAdapter):
+    source_id = SOURCE_ID
+    contract = CONTRACT
+
+    # Mixed: the vendored-table canaries never touch the network, the release
+    # trains do. Retries only ever fire on a transient SourceUnreachable, so
+    # declaring them at the adapter costs the offline canaries nothing.
+    canary_retries = 2
+
+    def canaries(self) -> list[Canary]:
+        # Two tiers, both under doctor. The offline tier (vendored-content hash
+        # + coefficient invariants) proves the package was not modified. It
+        # cannot prove the package is still CURRENT: CMS republishes these zips
+        # in place at the same URL, and an adapter whose every canary reads its
+        # own vendored bytes reports green forever afterwards. The live tier --
+        # `hcc.model_software_release` -- is the one that can see that happen.
+        # It is UNREACHABLE offline, like every other live canary in the
+        # product, and the PY2028 cycle probe stays in `hcc.release_probe`
+        # because a future cycle opening is a watch item, not artifact drift.
+        return [
+            Canary(
+                canary_id="hcc.vendored_tables",
+                source_id=SOURCE_ID,
+                description=(
+                    "Canonicalized-content hash and shape of the vendored mapping/"
+                    "hierarchy/coefficient tables (offline)."
+                ),
+                observe=_observe_vendored_tables,
+                remediation=_vendored_remediation(CanaryStatus.DRIFT, None, None),
+                remediation_for=_vendored_remediation,
+            ),
+            Canary(
+                canary_id="hcc.coefficient_spots",
+                source_id=SOURCE_ID,
+                description=(
+                    "Spot coefficient and normalization values against the published "
+                    "Rate Announcement tables (offline)."
+                ),
+                observe=_observe_coefficient_spots,
+                remediation=_SPOT_REMEDIATION,
+            ),
+            Canary(
+                canary_id="hcc.model_software_release",
+                source_id=SOURCE_ID,
+                description=(
+                    "Upstream release identity of the CMS model-software zips the "
+                    "vendored tables were derived from (Content-Length + Last-Modified "
+                    "via 1-byte ranged GETs) -- the only hcc canary that can see CMS "
+                    "republish a model zip in place (live)."
+                ),
+                observe=_observe_model_software_release,
+                remediation=_RELEASE_DRIFT_REMEDIATION,
+                remediation_for=_model_release_remediation,
+            ),
+        ]
+
+    def tools(self) -> list[ToolSpec]:
+        return [
+            ToolSpec(
+                name="hcc.map",
+                description=(
+                    "Map ICD-10-CM codes to CMS-HCC payment HCCs (V24 or V28) with "
+                    "labels and per-mapping provenance to the exact CMS model-software "
+                    "file."
+                ),
+                params_model=MapParams,
+                handler=_map_handler,
+                tags=("lookup",),
+            ),
+            ToolSpec(
+                name="hcc.score",
+                description=(
+                    "Community continuing-enrollee RAF score for a diagnosis list "
+                    "under CMS-HCC V24 or V28 for a payment year: mapping, mandatory "
+                    "edits, hierarchies, interactions, HCC counts, coefficient sum, "
+                    "and pinned normalization -- raw and normalized, clearly labeled."
+                ),
+                params_model=ScoreParams,
+                handler=_score_handler,
+                tags=("score",),
+            ),
+            ToolSpec(
+                name="hcc.release_probe",
+                description=(
+                    "Live identity check of the pinned CMS model-software zips "
+                    "(Content-Length + Last-Modified via 1-byte ranged GETs) plus "
+                    "the PY2028 cycle probe -- the same identities the "
+                    "hcc.model_software_release canary pins, reported per artifact "
+                    "against the pins recorded in this module, with remediation."
+                ),
+                params_model=NoParams,
+                handler=_probe_handler,
+                tags=("watch",),
+            ),
+            ToolSpec(
+                name="hcc.hierarchy_explain",
+                description=(
+                    "Explain CMS-HCC hierarchy suppression for a diagnosis list: which "
+                    "HCCs were zeroed by which, under V24 or V28."
+                ),
+                params_model=HierarchyParams,
+                handler=_hierarchy_handler,
+                tags=("explain",),
+            ),
+        ]
+
+
+ADAPTER = HccAdapter()