sourcelock 0.1.0__py3-none-any.whl

hc_source/adapters/provider.py

@@ -0,0 +1,1159 @@
+"""Provider identity / enrollment route.
+
+Two authorities, one semantic ladder, deliberately kept apart:
+
+* **NPPES NPI Registry API v2.1** (`npiregistry.cms.hhs.gov`) -- does this NPI
+  exist, and what identity does NPPES hold for it? Keyless, refreshed daily,
+  errors arrive as HTTP 200 bodies with an ``Errors`` array.
+* **PECOS Public Provider Enrollment (PPEF)** on data.cms.gov -- was this
+  provider approved to bill Medicare FFS as of the quarterly snapshot's extract
+  date? Served through the stable "latest" alias UUID.
+
+The ladder these tools must never collapse (CMS says the first rung verbatim:
+"Issuance of an NPI does not ensure or validate that the Health Care Provider
+is Licensed or Credentialed."):
+
+    NPI exists  !=  Medicare-enrolled  !=  credentialed / licensed / any-payer
+
+``provider.evidence_ladder`` therefore returns the facts SEPARATELY, each with
+its own provenance, and refuses on principle to merge them into a score.
+
+A PECOS answer is never one artifact. The rows come from the Data API; the
+snapshot id and extract date that DATE those rows come from the dataset-resources
+metadata, which is a separate document. So every PECOS route reports both -- url,
+status, sha256, retrieval time, one entry per artifact -- and re-reads the
+metadata after the rows: if the "latest" alias rolled to a new quarter mid-read,
+the call fails rather than stamping rows with the wrong snapshot.
+
+Deactivation semantics (verified 2026-08-01, full parse of the real report):
+the monthly ``NPPES_Deactivated_NPI_Report_<MMDDYY>_V2.zip`` XLSX is the only
+cumulative list of currently-deactivated NPIs and carries exactly two columns
+(NPI, deactivation date, both text, MM/DD/YYYY); the main dissemination file
+strips a deactivated NPI's row to those same two fields and never populates
+the reason-code column. The Registry API does not serve deactivated NPIs at
+all -- which is why a lookup miss warns about the report instead of concluding
+the NPI never existed. Bulk-file mirroring itself is out of v1 scope; the
+canaries watch the listing, not the gigabyte zips.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from dataclasses import dataclass
+from datetime import date
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from ..http import FetchResult, SourceUnreachable, fetch, fetch_json
+from ..interfaces import Canary, CanaryObservation, SourceAdapter, ToolResult, ToolSpec
+from ..npi import NPI_PATTERN, validate_npi
+from ..receipts import build_receipt
+from ..schemas import CanaryStatus, SourceContract
+
+SOURCE_ID = "provider"
+#: 2 -- PECOS results carry per-artifact provenance and an explicit
+#: completeness flag; enrollment_count is null rather than a partial number when
+#: paging stopped early.
+TRANSFORM_VERSION = "2"
+
+# --------------------------------------------------------------------------
+# Endpoints. Environment overrides exist so drift can be rehearsed against
+# file:// fixtures (`file://` ignores query params, so the same code path
+# serves live HTTP and local rehearsal).
+# --------------------------------------------------------------------------
+
+NPI_API_URL = "https://npiregistry.cms.hhs.gov/api/"
+NPPES_FILES_URL = "https://download.cms.gov/nppes/NPI_Files.html"
+PECOS_LATEST_ALIAS_UUID = "2457ea29-fc82-48b0-86ec-3b0755de7515"
+PECOS_DATA_URL = f"https://data.cms.gov/data-api/v1/dataset/{PECOS_LATEST_ALIAS_UUID}/data"
+PECOS_STATS_URL = f"{PECOS_DATA_URL}/stats"
+PECOS_RESOURCES_URL = (
+    f"https://data.cms.gov/data-api/v1/dataset-resources/{PECOS_LATEST_ALIAS_UUID}"
+)
+
+_ENV_PREFIX = "HC_SOURCE_PROVIDER_"
+
+
+def _url(name: str, default: str) -> str:
+    return os.environ.get(f"{_ENV_PREFIX}{name}", default)
+
+
+def _npi_api_url() -> str:
+    return _url("NPI_API_URL", NPI_API_URL)
+
+
+def _nppes_files_url() -> str:
+    return _url("NPPES_FILES_URL", NPPES_FILES_URL)
+
+
+def _pecos_data_url() -> str:
+    return _url("PECOS_DATA_URL", PECOS_DATA_URL)
+
+
+def _pecos_stats_url() -> str:
+    return _url("PECOS_STATS_URL", PECOS_STATS_URL)
+
+
+def _pecos_resources_url() -> str:
+    return _url("PECOS_RESOURCES_URL", PECOS_RESOURCES_URL)
+
+
+def _today() -> date:
+    """Cadence clock. Module-level so tests can freeze it."""
+    return date.today()
+
+
+def _artifact_url(url: str) -> str:
+    """The URL of an artifact, without the query string.
+
+    Every request this route makes carries the caller's NPI in the query
+    (``number=`` on the Registry, ``filter[NPI]=`` on the Data API). Receipt
+    warnings and exception text are persisted, human-read surfaces, and the
+    no-echo rule applies to them exactly as it applies to a rejection message.
+    The sha256 still binds the exact bytes; the URL only names the artifact they
+    came from.
+    """
+    return url.split("?", 1)[0]
+
+
+def _provenance(fetch_result: FetchResult, source: str) -> dict[str, Any]:
+    """One artifact's provenance line: which source, which bytes, when, what upstream said.
+
+    An answer assembled from several artifacts gets one of these per artifact.
+    ``retrieved_at`` is the fetch's own stamp, never the clock at receipt time.
+    """
+    return {
+        "source": source,
+        "url": _artifact_url(fetch_result.url),
+        "raw_sha256": fetch_result.sha256,
+        "upstream_status": fetch_result.status,
+        "retrieved_at": fetch_result.retrieved_at.isoformat(),
+    }
+
+
+def _provenance_lines(artifacts: list[dict[str, Any]]) -> list[str]:
+    """Render artifacts as receipt warnings.
+
+    ``Receipt`` has one url, one status and one sha256, so a multi-artifact
+    answer cannot express its provenance in the typed fields. ``data`` carries
+    the structured list -- but a miss returns ``data=None``, and a miss is
+    exactly when someone asks which artifacts were read. These lines are the
+    record that survives it.
+    """
+    return [
+        "PROVENANCE_ARTIFACT: source={source} url={url} status={upstream_status} "
+        "sha256={raw_sha256} retrieved_at={retrieved_at}".format(**a)
+        for a in artifacts
+    ]
+
+
+#: A boringly stable individual NPI used as the API-contract anchor.
+ANCHOR_NPI = "1003000126"
+
+NPI_API_VERSION = "2.1"
+
+CONTRACT = SourceContract(
+    source_id=SOURCE_ID,
+    authority_url="https://npiregistry.cms.hhs.gov/api/?version=2.1",
+    fallback_url=None,
+    license_notes=(
+        "US Government works, public domain (https://www.usa.gov/government-works): NPPES "
+        "dissemination data and the PECOS Public Provider Enrollment files are freely "
+        "redistributable. One caveat: the NUCC Healthcare Provider Taxonomy DESCRIPTIONS the "
+        "Registry API returns are NUCC-licensed -- store and redistribute taxonomy CODES; "
+        "treat descriptions as display-time convenience and do not vendor the NUCC code-set "
+        "CSV. No CPT/AMA content exists on this route."
+    ),
+    cadence=(
+        "NPI Registry API: daily refresh from NPPES; NPPES bulk files: weekly incrementals + "
+        "monthly full + monthly deactivation report (V2 grammar since 2026-03-03); "
+        "PECOS PPEF: quarterly (R/P3M)"
+    ),
+    effective_date_semantics=(
+        "provider.lookup_npi: effective_from is the NPI's NPPES enumeration date and "
+        "effective_to is open while the record is active -- the API refreshes daily and has "
+        "no release stamp. provider.pecos_enrollments and provider.evidence_ladder: "
+        "effective_from is the PPEF quarterly snapshot's extract date (from the dated "
+        "filename, e.g. 2026.07.17); enrollment facts speak as of that extract date only."
+    ),
+    invariants=[
+        "NPI Registry API v2.1 answers a valid active NPI with result_count/results and no "
+        "top-level Errors key (errors always arrive as HTTP 200 bodies)",
+        "download.cms.gov/nppes lists monthly full, weekly incremental, and monthly "
+        "deactivation files in the _V2 naming grammar (V1 retired 2026-03-03)",
+        "the PECOS PPEF latest-alias dataset serves >2.5M enrollment rows and all five "
+        "relational components (Enrollment, Additional NPIs, Reassignment, Practice "
+        "Location, Secondary Specialty)",
+        "a deactivated NPI is served only by the cumulative monthly Deactivated NPI Report "
+        "(two columns: NPI, deactivation date), never by the Registry API",
+    ],
+)
+
+# --------------------------------------------------------------------------
+# Non-claims. These are the part reviewers read; each states one rung of the
+# ladder the result must never be stretched across.
+# --------------------------------------------------------------------------
+
+_NC_NPI_NOT_CREDENTIALED = (
+    "NPI_PRESENT_IS_NOT_CREDENTIALED: an NPI record proves identity registration only. CMS "
+    "states verbatim that issuance of an NPI does not ensure or validate that the provider "
+    "is licensed or credentialed; NPPES license numbers are self-reported and unvalidated."
+)
+_NC_NPI_NOT_ENROLLED = (
+    "DOES_NOT_PROVE_MEDICARE_ENROLLMENT: an NPPES record says nothing about PECOS enrollment, "
+    "Medicare billing privileges, or participation in any payer's network."
+)
+_NC_NPI_CURRENCY = (
+    "DOES_NOT_PROVE_CURRENCY: served by the NPI Registry API, which refreshes daily from "
+    "NPPES with no release stamp; deactivations land in the monthly Deactivated NPI Report "
+    "before this answer necessarily reflects them."
+)
+_NC_PECOS_NOT_ALL_PAYER = (
+    "PECOS_ACTIVE_IS_NOT_ALL_PAYER_ACTIVE: a PPEF row means approved to bill Medicare "
+    "fee-for-service (or an 855O on file) as of the quarterly extract date -- it says "
+    "nothing about Medicaid, commercial payers, network participation, or today."
+)
+_NC_PECOS_NOT_CREDENTIALED = (
+    "DOES_NOT_PROVE_CREDENTIALING: no public CMS dataset asserts credentialing, privileging, "
+    "or licensure in good standing; Medicare enrollment is not that."
+)
+_NC_PECOS_MAIN_FILE_ONLY = (
+    "MAIN_FILE_ONLY: absence from the PPEF main enrollment extract is not proof of "
+    "non-enrollment -- multi-NPI enrollments can carry an NPI only in the Additional NPIs "
+    "sub-file, which this API filter does not search."
+)
+_NC_PECOS_COUNT_INCOMPLETE = (
+    "ENROLLMENT_COUNT_IS_NOT_COMPLETE: paging stopped at this route's page bound while the "
+    "Data API was still returning full pages, so the enrollments listed are a prefix of what "
+    "this NPI has, not all of it. enrollment_count is null for exactly that reason; "
+    "enrollment_count_at_least is what was actually read."
+)
+_NC_NOT_A_SCORE = (
+    "NOT_A_SCORE: NPI_EXISTS and PECOS_ENROLLED are independent facts with independent "
+    "vintages. SourceLock reports them separately and never merges them into a combined "
+    "verdict; any downstream aggregation is the consumer's claim, not this receipt's."
+)
+
+NPI_NON_CLAIMS = [_NC_NPI_NOT_CREDENTIALED, _NC_NPI_NOT_ENROLLED, _NC_NPI_CURRENCY]
+PECOS_NON_CLAIMS = [_NC_PECOS_NOT_ALL_PAYER, _NC_PECOS_NOT_CREDENTIALED, _NC_PECOS_MAIN_FILE_ONLY]
+LADDER_NON_CLAIMS = [
+    _NC_NOT_A_SCORE,
+    _NC_NPI_NOT_CREDENTIALED,
+    _NC_PECOS_NOT_ALL_PAYER,
+    _NC_NPI_NOT_ENROLLED,
+    _NC_PECOS_MAIN_FILE_ONLY,
+]
+
+
+# --------------------------------------------------------------------------
+# Typed public parameters
+# --------------------------------------------------------------------------
+
+
+class NpiParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    npi: str = Field(
+        pattern=NPI_PATTERN,
+        description="10-digit National Provider Identifier (check digit is validated).",
+    )
+
+    @field_validator("npi")
+    @classmethod
+    def _check_digit(cls, v: str) -> str:
+        # hc_source.npi is the one validator. This route used to carry its own
+        # copy while leie accepted any ten digits, so a transposed NPI was
+        # refused here and screened confidently there.
+        return validate_npi(v)
+
+
+# --------------------------------------------------------------------------
+# NPPES NPI Registry API
+# --------------------------------------------------------------------------
+
+
+def _fetch_npi(npi: str) -> tuple[FetchResult, dict[str, Any]]:
+    result, payload = fetch_json(
+        _npi_api_url(), params={"version": NPI_API_VERSION, "number": npi}
+    )
+    if not isinstance(payload, dict):
+        raise SourceUnreachable(
+            _artifact_url(result.url), "NPI Registry response was not a JSON object"
+        )
+    errors = payload.get("Errors")
+    if errors:
+        codes = ",".join(str(e.get("number", "?")) for e in errors)
+        raise SourceUnreachable(
+            _artifact_url(result.url),
+            f"NPI Registry returned API error(s) {codes} with HTTP 200 -- the v{NPI_API_VERSION} "
+            "contract has changed (see https://npiregistry.cms.hhs.gov/api-page)",
+            status=result.status,
+        )
+    return result, payload
+
+
+def _as_date(value: Any) -> date | None:
+    if not isinstance(value, str):
+        return None
+    try:
+        return date.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+def _map_npi_record(record: dict[str, Any]) -> dict[str, Any]:
+    basic = record.get("basic", {})
+    return {
+        "npi": record.get("number"),
+        "enumeration_type": record.get("enumeration_type"),
+        "status": basic.get("status"),
+        "enumeration_date": basic.get("enumeration_date"),
+        "last_updated": basic.get("last_updated"),
+        "name": {
+            "first_name": basic.get("first_name"),
+            "last_name": basic.get("last_name"),
+            "credential": basic.get("credential"),
+            "organization_name": basic.get("organization_name"),
+        },
+        "taxonomies": [
+            {
+                "code": t.get("code"),
+                "desc": t.get("desc"),
+                "primary": t.get("primary"),
+                "state": t.get("state"),
+                "license": t.get("license"),
+            }
+            for t in record.get("taxonomies", [])
+        ],
+        "addresses": [
+            {
+                "purpose": a.get("address_purpose"),
+                "city": a.get("city"),
+                "state": a.get("state"),
+                "postal_code": a.get("postal_code"),
+            }
+            for a in record.get("addresses", [])
+        ],
+    }
+
+
+_MISS_WARNING = (
+    "The requested NPI was not found by the NPI Registry API (v2.1). The API does not serve "
+    "deactivated NPIs: before concluding this NPI never existed, check the monthly NPPES "
+    "Deactivated NPI Report (cumulative XLSX of every currently-deactivated NPI with its "
+    "deactivation date) at https://download.cms.gov/nppes/NPI_Files.html."
+)
+
+
+def _lookup_npi(params: NpiParams) -> ToolResult:
+    result, payload = _fetch_npi(params.npi)
+    warnings: list[str] = []
+    data: dict[str, Any] | None = None
+    effective_from: date | None = None
+
+    if payload.get("result_count", 0) >= 1 and payload.get("results"):
+        record = payload["results"][0]
+        data = _map_npi_record(record)
+        effective_from = _as_date(data.get("enumeration_date"))
+        if data.get("status") != "A":
+            warnings.append(
+                "The requested NPI is not in active status "
+                f"({data.get('status')!r}) in the NPI Registry."
+            )
+    else:
+        warnings.append(_MISS_WARNING)
+
+    return ToolResult(
+        data=data,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="provider.lookup_npi",
+            fetch=result,
+            source_version=f"npi-registry-api-{NPI_API_VERSION}",
+            transform_version=TRANSFORM_VERSION,
+            effective_from=effective_from,
+            warnings=warnings,
+            non_claims=NPI_NON_CLAIMS,
+        ),
+    )
+
+
+# --------------------------------------------------------------------------
+# PECOS PPEF (data.cms.gov Data API, latest-alias UUID)
+# --------------------------------------------------------------------------
+
+_PPEF_EXTRACT_RE = re.compile(r"PPEF_Enrollment_Extract_(\d{4})\.(\d{2})\.(\d{2})\.csv")
+
+#: The five relational components a healthy PPEF release publishes.
+_PPEF_COMPONENTS = {
+    "enrollment": "PPEF_Enrollment_Extract_",
+    "additional_npis": "PPEF_Additional_NPIs_",
+    "reassignment": "PPEF_Reassignment_Extract_",
+    "practice_location": "PPEF_Practice_Location_Extract_",
+    "secondary_specialty": "PPEF_Secondary_Specialty_Extract_",
+}
+
+
+def _ppef_snapshot(resources: Any) -> tuple[str, date | None, list[str]]:
+    """Extract (snapshot id, extract date, missing components) from dataset-resources."""
+    entries = resources.get("data", []) if isinstance(resources, dict) else []
+    urls = [e.get("downloadURL", "") for e in entries if isinstance(e, dict)]
+
+    snapshot, extract_date = "unknown", None
+    for u in urls:
+        m = _PPEF_EXTRACT_RE.search(u)
+        if m:
+            snapshot = ".".join(m.groups())
+            extract_date = date(int(m.group(1)), int(m.group(2)), int(m.group(3)))
+            break
+
+    missing = sorted(
+        name
+        for name, pattern in _PPEF_COMPONENTS.items()
+        if not any(pattern in u for u in urls)
+    )
+    return snapshot, extract_date, missing
+
+
+def _fetch_ppef_version() -> tuple[FetchResult, str, date | None, list[str]]:
+    result, resources = fetch_json(_pecos_resources_url())
+    snapshot, extract_date, missing = _ppef_snapshot(resources)
+    return result, snapshot, extract_date, missing
+
+
+#: Rows per Data API page. What this route has always asked for, kept well under
+#: the API's own size cap.
+_PPEF_PAGE_SIZE = 200
+
+#: Hard stop on paging: 25 pages is 5,000 rows, two orders of magnitude past the
+#: busiest real NPI. The bound is not a guess at how many enrollments a provider
+#: has -- it is the thing that stops an upstream which keeps handing back full
+#: pages from spinning this process forever. Reaching it is reported as an
+#: incomplete read, never as a count.
+_PPEF_MAX_PAGES = 25
+
+
+def _fetch_ppef_rows(npi: str) -> tuple[list[dict[str, Any]], list[FetchResult], bool]:
+    """Read every PPEF row for one NPI. Returns (rows, page fetches, complete).
+
+    This route used to request one page of 200 and present ``len(rows)`` as the
+    enrollment count. A provider with more than 200 enrollments got a wrong
+    number that read as a complete one, which is the specific failure this
+    product exists not to produce. So: page to exhaustion, and when the page
+    bound stops us first, say so instead of returning a number.
+    """
+    rows: list[dict[str, Any]] = []
+    fetches: list[FetchResult] = []
+    seen: set[str] = set()
+
+    for page in range(_PPEF_MAX_PAGES):
+        result, batch = fetch_json(
+            _pecos_data_url(),
+            params={
+                "filter[NPI]": npi,
+                "size": _PPEF_PAGE_SIZE,
+                "offset": page * _PPEF_PAGE_SIZE,
+            },
+        )
+        if not isinstance(batch, list):
+            raise SourceUnreachable(
+                _artifact_url(result.url),
+                "PECOS Data API did not return the expected bare JSON array",
+            )
+        if result.sha256 in seen:
+            # An API that ignores `offset` answers every page with page 1, and
+            # paging would then multiply one page into a confident wrong count.
+            # Identical bytes at a different offset means we cannot page this
+            # source, so we refuse rather than count.
+            raise SourceUnreachable(
+                _artifact_url(result.url),
+                "PECOS Data API returned identical bytes for two different offsets, so it "
+                "is not honouring the offset parameter and its rows cannot be paged",
+                status=result.status,
+            )
+        seen.add(result.sha256)
+        fetches.append(result)
+        rows.extend(r for r in batch if isinstance(r, dict))
+        if len(batch) < _PPEF_PAGE_SIZE:
+            return rows, fetches, True
+
+    return rows, fetches, False
+
+
+def _map_enrollment(row: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "enrollment_id": row.get("ENRLMT_ID"),
+        "pac_id": row.get("PECOS_ASCT_CNTL_ID"),
+        "provider_type_code": row.get("PROVIDER_TYPE_CD"),
+        "provider_type": row.get("PROVIDER_TYPE_DESC"),
+        "state": row.get("STATE_CD"),
+        "multiple_npi_flag": row.get("MULTIPLE_NPI_FLAG"),
+        "first_name": row.get("FIRST_NAME"),
+        "last_name": row.get("LAST_NAME"),
+        "org_name": row.get("ORG_NAME"),
+    }
+
+
+# The NPI is NOT interpolated. It is caller-supplied text, this string is
+# persisted into the evidence receipt, and the no-echo rule has no carve-out
+# for identifiers that happen to be public. The snapshot is ours to name.
+_PECOS_MISS_WARNING = (
+    "The requested NPI has no row in the PPEF main enrollment extract ({snapshot}). That "
+    "means no "
+    "approved Medicare FFS enrollment was recorded under this NPI at the extract date -- but "
+    "the NPI could still ride a multi-NPI enrollment listed only in the Additional NPIs "
+    "sub-file, and enrollment can postdate the snapshot. Absence here is not proof of "
+    "non-enrollment."
+)
+
+_PECOS_PROVENANCE_WARNING = (
+    "MULTI_ARTIFACT_PROVENANCE: {n} upstream artifact(s) produced this answer. The receipt's "
+    "raw_sha256 and upstream_status describe only the first PPEF data page; source_version "
+    "and effective_from come from the dataset-resources metadata, which is a different "
+    "document read at a different moment. Every artifact is listed below as a "
+    "PROVENANCE_ARTIFACT line, and in data.provenance when data is not null. The metadata was "
+    "re-read after the rows and still reported snapshot {snapshot}, so the rows and the "
+    "version claimed here come from one release."
+)
+
+_PECOS_TRUNCATION_WARNING = (
+    "ENROLLMENT_COUNT_TRUNCATED: the PPEF Data API was still returning full pages after "
+    "{pages} pages of {size} rows, so paging stopped at this route's bound and the enrollment "
+    "list is a prefix. enrollment_count is null; enrollment_count_at_least is {read}. Do not "
+    "read this result as a complete enrollment count."
+)
+
+_PECOS_ROLLOVER = (
+    "the PPEF latest alias reported snapshot {before} before the row read and {after} after "
+    "it, so a new quarterly snapshot landed mid-call. Refusing rather than dating rows to a "
+    "release they did not come from; re-run to read the new snapshot whole"
+)
+
+
+@dataclass(frozen=True)
+class _PpefRead:
+    """One PECOS answer plus every artifact that had to be read to produce it."""
+
+    rows: list[dict[str, Any]]
+    #: The first data page. What the receipt's single raw_sha256 attests to.
+    rows_fetch: FetchResult
+    snapshot: str
+    extract_date: date | None
+    missing: list[str]
+    #: False when the page bound stopped the read before the rows ran out.
+    complete: bool
+    artifacts: list[dict[str, Any]]
+
+
+def _read_ppef(npi: str) -> _PpefRead:
+    """Read the PPEF rows for one NPI and bind them to the snapshot that dates them.
+
+    The version and the data are two different fetches of two different
+    documents through a "latest" alias that moves quarterly. Reading the
+    metadata, then the rows, then the metadata again is what makes the receipt's
+    ``source_version`` a claim about the bytes it hashed rather than a claim
+    about whatever the alias happened to point at first.
+    """
+    before, snapshot, extract_date, missing = _fetch_ppef_version()
+    rows, page_fetches, complete = _fetch_ppef_rows(npi)
+    after, snapshot_after, _extract_after, _missing_after = _fetch_ppef_version()
+
+    if snapshot_after != snapshot:
+        # SourceUnreachable because that is the honest classification: the
+        # source was not read coherently, so this run does not know what it
+        # says. Every caller already handles it.
+        raise SourceUnreachable(
+            _artifact_url(after.url),
+            _PECOS_ROLLOVER.format(before=snapshot, after=snapshot_after),
+            status=after.status,
+        )
+
+    artifacts = [_provenance(before, f"pecos-ppef-{snapshot}:dataset-resources")]
+    artifacts += [
+        _provenance(f, f"pecos-ppef-{snapshot}:data-page-{i}")
+        for i, f in enumerate(page_fetches, start=1)
+    ]
+    artifacts.append(_provenance(after, f"pecos-ppef-{snapshot}:dataset-resources-recheck"))
+
+    return _PpefRead(
+        rows=rows,
+        rows_fetch=page_fetches[0],
+        snapshot=snapshot,
+        extract_date=extract_date,
+        missing=missing,
+        complete=complete,
+        artifacts=artifacts,
+    )
+
+
+def _enrollment_count_fields(read: _PpefRead) -> dict[str, Any]:
+    """The count, or an explicit refusal to state one.
+
+    ``enrollment_count`` is null rather than a plausible integer when the read
+    was truncated: a consumer that reads only that field gets nothing it can
+    mistake for a total, and ``enrollment_count_at_least`` says what was
+    actually seen.
+    """
+    if read.complete:
+        return {"enrollments_are_complete": True, "enrollment_count": len(read.rows)}
+    return {
+        "enrollments_are_complete": False,
+        "enrollment_count": None,
+        "enrollment_count_at_least": len(read.rows),
+    }
+
+
+def _pecos_warnings(read: _PpefRead) -> list[str]:
+    """Provenance, component inventory, and truncation -- in that order."""
+    warnings = [
+        _PECOS_PROVENANCE_WARNING.format(n=len(read.artifacts), snapshot=read.snapshot),
+        *_provenance_lines(read.artifacts),
+    ]
+    if read.missing:
+        warnings.append(
+            f"PPEF release is missing expected component(s): {', '.join(read.missing)}."
+        )
+    if not read.complete:
+        warnings.append(
+            _PECOS_TRUNCATION_WARNING.format(
+                pages=_PPEF_MAX_PAGES, size=_PPEF_PAGE_SIZE, read=len(read.rows)
+            )
+        )
+    return warnings
+
+
+def _pecos_enrollments(params: NpiParams) -> ToolResult:
+    read = _read_ppef(params.npi)
+    warnings = _pecos_warnings(read)
+    non_claims = list(PECOS_NON_CLAIMS)
+    if not read.complete:
+        non_claims.append(_NC_PECOS_COUNT_INCOMPLETE)
+
+    if read.rows:
+        data: dict[str, Any] | None = {
+            "npi": params.npi,
+            "snapshot": read.snapshot,
+            **_enrollment_count_fields(read),
+            "enrollments": [_map_enrollment(r) for r in read.rows],
+            "provenance": read.artifacts,
+        }
+    else:
+        data = None
+        warnings.append(
+            _PECOS_MISS_WARNING.format(snapshot=read.snapshot)
+        )
+
+    return ToolResult(
+        data=data,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="provider.pecos_enrollments",
+            fetch=read.rows_fetch,
+            source_version=f"pecos-ppef-{read.snapshot}",
+            transform_version=TRANSFORM_VERSION,
+            effective_from=read.extract_date,
+            warnings=warnings,
+            non_claims=non_claims,
+        ),
+    )
+
+
+# --------------------------------------------------------------------------
+# The evidence ladder: distinct facts, never a merged verdict
+# --------------------------------------------------------------------------
+
+
+def _evidence_ladder(params: NpiParams) -> ToolResult:
+    npi_fetch, npi_payload = _fetch_npi(params.npi)
+    read = _read_ppef(params.npi)
+
+    npi_exists = bool(npi_payload.get("result_count", 0) >= 1 and npi_payload.get("results"))
+    npi_detail: dict[str, Any]
+    if npi_exists:
+        basic = npi_payload["results"][0].get("basic", {})
+        npi_detail = {
+            "status": basic.get("status"),
+            "enumeration_type": npi_payload["results"][0].get("enumeration_type"),
+            "enumeration_date": basic.get("enumeration_date"),
+        }
+    else:
+        npi_detail = {
+            "note": (
+                "not served by the NPI Registry API -- never issued, or deactivated "
+                "(deactivated NPIs appear only in the monthly Deactivated NPI Report)"
+            )
+        }
+
+    pecos_enrolled = bool(read.rows)
+    pecos_detail = {
+        "snapshot": read.snapshot,
+        **_enrollment_count_fields(read),
+        "enrollment_ids": [r.get("ENRLMT_ID") for r in read.rows],
+    }
+
+    npi_artifacts = [_provenance(npi_fetch, f"npi-registry-api-{NPI_API_VERSION}")]
+
+    data = {
+        "npi": params.npi,
+        "facts": {
+            "NPI_EXISTS": {
+                "value": npi_exists,
+                "detail": npi_detail,
+                # A list even when there is one artifact: a fact's provenance is
+                # everything that produced it, and PECOS_ENROLLED genuinely takes
+                # several. One shape for both keeps a consumer from learning the
+                # single-artifact form and breaking on the other.
+                "provenance": npi_artifacts,
+            },
+            "PECOS_ENROLLED": {
+                "value": pecos_enrolled,
+                "detail": pecos_detail,
+                "provenance": read.artifacts,
+            },
+        },
+        "ladder_note": (
+            "Distinct facts, deliberately not merged: NPI existence (NPPES, daily refresh) "
+            "and Medicare FFS enrollment (PECOS PPEF, quarterly snapshot) are different "
+            "assertions with different vintages."
+        ),
+    }
+
+    warnings = [
+        "COMPOSITE_EVIDENCE: this receipt's raw_sha256/upstream_status cover the first PECOS "
+        "PPEF data page only. Every artifact behind either fact -- the NPPES response, the "
+        "PPEF dataset-resources metadata, each data page -- is listed below as a "
+        "PROVENANCE_ARTIFACT line and inside data.facts.*.provenance. The two sources have "
+        "different vintages.",
+        *_provenance_lines([*npi_artifacts, *read.artifacts]),
+    ]
+    if read.missing:
+        warnings.append(
+            f"PPEF release is missing expected component(s): {', '.join(read.missing)}."
+        )
+    non_claims = list(LADDER_NON_CLAIMS)
+    if not read.complete:
+        warnings.append(
+            _PECOS_TRUNCATION_WARNING.format(
+                pages=_PPEF_MAX_PAGES, size=_PPEF_PAGE_SIZE, read=len(read.rows)
+            )
+        )
+        non_claims.append(_NC_PECOS_COUNT_INCOMPLETE)
+
+    return ToolResult(
+        data=data,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="provider.evidence_ladder",
+            fetch=read.rows_fetch,
+            source_version=(
+                f"npi-registry-api-{NPI_API_VERSION}+pecos-ppef-{read.snapshot}"
+            ),
+            transform_version=TRANSFORM_VERSION,
+            effective_from=read.extract_date,
+            warnings=warnings,
+            non_claims=non_claims,
+        ),
+    )
+
+
+# --------------------------------------------------------------------------
+# Canary 1: NPI Registry API contract
+# --------------------------------------------------------------------------
+
+
+def _npi_schema_hash(payload: dict[str, Any]) -> str:
+    """Hash the response SHAPE only: key sets, never values."""
+    results = payload.get("results") or [{}]
+    record = results[0]
+    shape = {
+        "top": sorted(payload.keys()),
+        "result": sorted(record.keys()),
+        "basic": sorted(record.get("basic", {}).keys()),
+        "taxonomy": sorted((record.get("taxonomies") or [{}])[0].keys()),
+        "address": sorted((record.get("addresses") or [{}])[0].keys()),
+    }
+    return hashlib.sha256(
+        json.dumps(shape, sort_keys=True, separators=(",", ":")).encode()
+    ).hexdigest()
+
+
+def _observe_npi_api() -> CanaryObservation:
+    result, payload = fetch_json(
+        _npi_api_url(), params={"version": NPI_API_VERSION, "number": ANCHOR_NPI}
+    )
+    if not isinstance(payload, dict):
+        raise SourceUnreachable(result.url, "NPI Registry response was not a JSON object")
+
+    errors = payload.get("Errors")
+    if errors:
+        codes = ",".join(sorted(str(e.get("number", "?")) for e in errors))
+        return CanaryObservation(
+            value=f"api-error:{codes}",
+            upstream_status=result.status,
+            note="registry answered HTTP 200 with an Errors body",
+        )
+
+    if payload.get("result_count", 0) != 1 or not payload.get("results"):
+        return CanaryObservation(
+            value=f"v{NPI_API_VERSION}:{ANCHOR_NPI}:absent",
+            upstream_status=result.status,
+            note="anchor NPI not returned",
+        )
+
+    record = payload["results"][0]
+    basic = record.get("basic", {})
+    return CanaryObservation(
+        value=(
+            f"v{NPI_API_VERSION}:{ANCHOR_NPI}:{record.get('enumeration_type')}:"
+            f"{basic.get('status')}"
+        ),
+        schema_hash=_npi_schema_hash(payload),
+        upstream_status=result.status,
+        note="anchor NPI record and response shape",
+    )
+
+
+def _npi_api_remediation(status: CanaryStatus, observed: str | None, expected: str | None) -> str:
+    if status is CanaryStatus.SCHEMA_CHANGED:
+        return (
+            "The NPI Registry API kept answering but its response shape moved (new or renamed "
+            "keys). Diff the live response for NPI "
+            f"{ANCHOR_NPI} against tests/fixtures/provider/lookup_npi_ok.json, update "
+            "_map_npi_record, bump TRANSFORM_VERSION in hc_source/adapters/provider.py, then "
+            "re-pin with `hc-source lock init`."
+        )
+    if status is CanaryStatus.UNREACHABLE:
+        return (
+            "The NPI Registry API could not be read. Check "
+            "https://npiregistry.cms.hhs.gov/api-page for outage or relocation notices, then "
+            "run `hc-source doctor` again."
+        )
+    if observed and observed.startswith("api-error:"):
+        return (
+            "The NPI Registry answered HTTP 200 with an Errors body -- this is exactly what "
+            f"version retirement looks like (v1.0 and v2.0 died the same way; v{NPI_API_VERSION} "
+            "was current as of 2026-08). Read https://npiregistry.cms.hhs.gov/api-page for the "
+            "current version, update NPI_API_VERSION in hc_source/adapters/provider.py, verify "
+            "the response mapping, then re-pin with `hc-source lock init`."
+        )
+    if observed and observed.endswith(":absent"):
+        return (
+            f"The anchor NPI {ANCHOR_NPI} is no longer served by the Registry API (likely "
+            "deactivated -- check the monthly Deactivated NPI Report). Pick a new boringly "
+            "stable anchor NPI, update ANCHOR_NPI and the recorded fixtures, then re-pin with "
+            "`hc-source lock init`."
+        )
+    return (
+        "The NPI Registry API contract moved. Compare observed vs expected, consult "
+        "https://npiregistry.cms.hhs.gov/api-page, then re-pin with `hc-source lock init`."
+    )
+
+
+# --------------------------------------------------------------------------
+# Canary 2: NPPES bulk V2 file listing + cadence
+# --------------------------------------------------------------------------
+
+_MONTHLY_RE = re.compile(r"NPPES_Data_Dissemination_([A-Z][a-z]+)_(\d{4})(_V\d+)?\.zip")
+_WEEKLY_RE = re.compile(r"NPPES_Data_Dissemination_(\d{6})_(\d{6})_Weekly(_V\d+)?\.zip")
+_DEACT_RE = re.compile(r"NPPES_Deactivated_NPI_Report_(\d{6})(_V\d+)?\.zip")
+
+_MONTHS = {
+    name: i
+    for i, name in enumerate(
+        [
+            "January", "February", "March", "April", "May", "June",
+            "July", "August", "September", "October", "November", "December",
+        ],
+        start=1,
+    )
+}
+
+#: A monthly older than this many days means publication stalled (the file is
+#: dated mid-month and the next lands ~a month later; 62 gives one month of
+#: slack before alarming).
+_MONTHLY_STALE_DAYS = 62
+
+
+def _observe_nppes_files() -> CanaryObservation:
+    result = fetch(_nppes_files_url())
+    html = result.content.decode("utf-8", errors="replace")
+
+    monthlies: list[tuple[int, int, str]] = []
+    for m in _MONTHLY_RE.finditer(html):
+        month = _MONTHS.get(m.group(1))
+        if month:
+            monthlies.append((int(m.group(2)), month, m.group(0)))
+    weeklies = {m.group(0) for m in _WEEKLY_RE.finditer(html)}
+    deactivations = {m.group(0) for m in _DEACT_RE.finditer(html)}
+
+    if not monthlies:
+        value = "no-monthly-dissemination-file"
+    else:
+        year, month, filename = max(monthlies)
+        value = filename
+        flags: list[str] = []
+        today = _today()
+        age_days = (today - date(year, month, 1)).days
+        if age_days > _MONTHLY_STALE_DAYS + 31:  # measured from month start
+            flags.append("stale-monthly")
+        if not weeklies:
+            flags.append("no-weekly-files")
+        if not deactivations:
+            flags.append("no-deactivation-report")
+        if flags:
+            value = "|".join([value, *sorted(flags)])
+
+    return CanaryObservation(
+        value=value,
+        upstream_status=result.status,
+        note=(
+            f"{len(set(f for *_ , f in monthlies))} monthly, {len(weeklies)} weekly, "
+            f"{len(deactivations)} deactivation file(s) listed"
+        ),
+    )
+
+
+_V1_RETIREMENT_REMEDIATION = (
+    "NPPES retired the V1 bulk files on 2026-03-03; only *_V2.zip names are published now "
+    "(V2 extends the First Name and Legal Business Name field lengths). The listing this "
+    "canary just read carries a V1-style name with no _V2 suffix, which means the page has "
+    "regressed, a stale mirror is being served, or something upstream renamed the grammar "
+    "again. Fix: open https://download.cms.gov/nppes/NPI_Files.html, read the 'Important "
+    "Information' block (where CMS announced the V1 retirement), confirm the current version "
+    "suffix, make sure nothing in your pipeline still generates V1 filenames "
+    "(NPPES_Data_Dissemination_<Month>_<YYYY>.zip silently 404s), then re-pin with "
+    "`hc-source lock init`."
+)
+
+
+def _nppes_files_remediation(
+    status: CanaryStatus, observed: str | None, expected: str | None
+) -> str:
+    if status is CanaryStatus.UNREACHABLE:
+        return (
+            "download.cms.gov/nppes/NPI_Files.html could not be read or no longer lists a "
+            "monthly dissemination file. Locate the current NPPES dissemination page from "
+            "https://www.cms.gov/medicare/regulations-guidance/administrative-simplification/"
+            "data-dissemination, update NPPES_FILES_URL if it moved, then re-pin with "
+            "`hc-source lock init`."
+        )
+    head = (observed or "").split("|", 1)[0]
+    monthly = _MONTHLY_RE.fullmatch(head)
+    if monthly and not monthly.group(3):
+        return _V1_RETIREMENT_REMEDIATION
+    if monthly and monthly.group(3) and monthly.group(3) != "_V2":
+        return (
+            f"NPPES bumped the bulk-file version suffix to {monthly.group(3)[1:]} (precedent: "
+            "V1 retired 2026-03-03, V2 took over). Read the 'Important Information' block on "
+            "https://download.cms.gov/nppes/NPI_Files.html for what changed, update the "
+            "filename grammar and column map in hc_source/adapters/provider.py (bump "
+            "TRANSFORM_VERSION if the mapping moved), then re-pin with `hc-source lock init`."
+        )
+    if observed and "stale-monthly" in observed:
+        return (
+            "The newest NPPES monthly file is more than ~3 months old -- publication stalled "
+            "or the page stopped updating. Verify on "
+            "https://download.cms.gov/nppes/NPI_Files.html; if CMS paused publication, keep "
+            "the current pin and re-run doctor after the next release; otherwise re-pin with "
+            "`hc-source lock init`."
+        )
+    if observed and ("no-weekly-files" in observed or "no-deactivation-report" in observed):
+        return (
+            "The NPPES listing lost its weekly incrementals and/or the monthly Deactivated "
+            "NPI Report. Deactivation truth lives ONLY in that report (the main file strips "
+            "deactivated NPIs to two fields), so treat this as a real coverage gap: check "
+            "https://download.cms.gov/nppes/NPI_Files.html, then re-pin with "
+            "`hc-source lock init` once the listing is whole."
+        )
+    return (
+        "NPPES published a new monthly dissemination file. Review the release (column map "
+        "unchanged? deactivation report present?), then re-pin with `hc-source lock init`."
+    )
+
+
+# --------------------------------------------------------------------------
+# Canary 3: PECOS PPEF release identity + row-count + component inventory
+# --------------------------------------------------------------------------
+
+_PPEF_ROW_FLOOR = 2_500_000
+
+
+def _observe_pecos_ppef() -> CanaryObservation:
+    stats_fetch, stats = fetch_json(_pecos_stats_url())
+    total = int(stats.get("total_rows", 0)) if isinstance(stats, dict) else 0
+
+    _, snapshot, _extract_date, missing = _fetch_ppef_version()
+
+    rows_fetch, rows = fetch_json(_pecos_data_url(), params={"size": 1})
+    if not isinstance(rows, list) or not rows or not isinstance(rows[0], dict):
+        raise SourceUnreachable(
+            rows_fetch.url, "PECOS Data API did not return a non-empty JSON array"
+        )
+
+    value = f"ppef-{snapshot}:rows={total}"
+    flags: list[str] = []
+    if total < _PPEF_ROW_FLOOR:
+        flags.append("row-count-low")
+    if missing:
+        flags.append(f"missing-components={','.join(missing)}")
+    if flags:
+        value = "|".join([value, *sorted(flags)])
+
+    schema_hash = hashlib.sha256(
+        json.dumps(sorted(rows[0].keys()), separators=(",", ":")).encode()
+    ).hexdigest()
+
+    return CanaryObservation(
+        value=value,
+        schema_hash=schema_hash,
+        upstream_status=stats_fetch.status,
+        note="latest-alias snapshot id, row count, and column set",
+    )
+
+
+def _pecos_remediation(status: CanaryStatus, observed: str | None, expected: str | None) -> str:
+    if status is CanaryStatus.SCHEMA_CHANGED:
+        return (
+            "The PPEF enrollment extract kept its snapshot id but its column set moved. "
+            "Fetch one row from the latest-alias Data API, diff the keys against "
+            "tests/fixtures/provider/pecos_size1.json, update the column map and bump "
+            "TRANSFORM_VERSION in hc_source/adapters/provider.py, then re-pin with "
+            "`hc-source lock init`."
+        )
+    if status is CanaryStatus.UNREACHABLE:
+        return (
+            "The PECOS Public Provider Enrollment latest-alias dataset "
+            f"({PECOS_LATEST_ALIAS_UUID}) could not be read -- it may have been re-keyed. "
+            "Re-download https://data.cms.gov/data.json, locate the dataset titled "
+            "'Medicare Fee-For-Service  Public Provider Enrollment' (the double space is "
+            "verbatim), take the first API distribution's UUID as the new latest alias, "
+            "update PECOS_LATEST_ALIAS_UUID, then re-pin with `hc-source lock init`."
+        )
+    if observed and "row-count-low" in observed:
+        return (
+            "PPEF row count collapsed below 2.5M (2,978,925 as of 2026-08) -- likely a "
+            "partial load upstream. Do NOT re-pin onto a truncated snapshot: re-check the "
+            "row count in a day via `hc-source doctor`, and only re-pin with "
+            "`hc-source lock init` once it recovers or CMS documents the change."
+        )
+    if observed and "missing-components" in observed:
+        return (
+            "A PPEF relational component (of: Enrollment, Additional NPIs, Reassignment, "
+            "Practice Location, Secondary Specialty) vanished from dataset-resources. "
+            "Diff the file inventory at "
+            f"https://data.cms.gov/data-api/v1/dataset-resources/{PECOS_LATEST_ALIAS_UUID} "
+            "against the five PPEF_* patterns, update _PPEF_COMPONENTS if CMS renamed one, "
+            "then re-pin with `hc-source lock init`."
+        )
+    return (
+        "PECOS published a new quarterly PPEF snapshot. Review the new extract date and row "
+        "count, re-record fixtures if the shape moved, then re-pin with "
+        "`hc-source lock init`."
+    )
+
+
+# --------------------------------------------------------------------------
+# Adapter
+# --------------------------------------------------------------------------
+
+
+class ProviderAdapter(SourceAdapter):
+    source_id = SOURCE_ID
+    contract = CONTRACT
+
+    # These canaries read a live CMS service, so a single 502 is not news --
+    # it is Tuesday. Two retries with exponential backoff, applied only to
+    # transient failures (see hc_source.doctor._observe). A gate that goes red
+    # on somebody else's bad afternoon gets uninstalled.
+    canary_retries = 2
+
+    def canaries(self) -> list[Canary]:
+        return [
+            Canary(
+                canary_id="provider.npi_api_contract",
+                source_id=SOURCE_ID,
+                description=(
+                    "NPI Registry API v2.1 answers the anchor NPI with the pinned record "
+                    "identity and response shape (errors arrive as HTTP 200 bodies)."
+                ),
+                observe=_observe_npi_api,
+                remediation=(
+                    "The NPI Registry API contract moved. Check "
+                    "https://npiregistry.cms.hhs.gov/api-page, then re-pin with "
+                    "`hc-source lock init`."
+                ),
+                remediation_for=_npi_api_remediation,
+            ),
+            Canary(
+                canary_id="provider.nppes_v2_files",
+                source_id=SOURCE_ID,
+                description=(
+                    "download.cms.gov/nppes lists the V2 monthly full file (newest wins; two "
+                    "may coexist at a month boundary), weekly incrementals, and the monthly "
+                    "Deactivated NPI Report, at a live cadence."
+                ),
+                observe=_observe_nppes_files,
+                remediation=(
+                    "The NPPES bulk file listing moved (naming, cadence, or contents). Read "
+                    "https://download.cms.gov/nppes/NPI_Files.html and its 'Important "
+                    "Information' block, then re-pin with `hc-source lock init`."
+                ),
+                remediation_for=_nppes_files_remediation,
+            ),
+            Canary(
+                canary_id="provider.pecos_ppef",
+                source_id=SOURCE_ID,
+                description=(
+                    "PECOS PPEF latest alias serves the pinned quarterly snapshot: extract "
+                    "date, row count above floor, five relational components, stable columns."
+                ),
+                observe=_observe_pecos_ppef,
+                remediation=(
+                    "The PECOS Public Provider Enrollment dataset changed on data.cms.gov. "
+                    "Re-locate it in data.json (title has a verbatim double space), verify "
+                    "UUID and components, then re-pin with `hc-source lock init`."
+                ),
+                remediation_for=_pecos_remediation,
+            ),
+        ]
+
+    def tools(self) -> list[ToolSpec]:
+        return [
+            ToolSpec(
+                name="provider.lookup_npi",
+                description=(
+                    "Look up one NPI in the NPPES NPI Registry API v2.1 (daily refresh): "
+                    "identity, status, taxonomies, practice locations."
+                ),
+                params_model=NpiParams,
+                handler=_lookup_npi,
+                tags=("lookup",),
+            ),
+            ToolSpec(
+                name="provider.pecos_enrollments",
+                description=(
+                    "List a provider's Medicare FFS enrollment records from the PECOS PPEF "
+                    "quarterly snapshot (latest alias) for one NPI."
+                ),
+                params_model=NpiParams,
+                handler=_pecos_enrollments,
+                tags=("lookup",),
+            ),
+            ToolSpec(
+                name="provider.evidence_ladder",
+                description=(
+                    "Report NPI_EXISTS (NPPES) and PECOS_ENROLLED (PPEF snapshot) as "
+                    "separate facts with separate provenance -- never a merged score."
+                ),
+                params_model=NpiParams,
+                handler=_evidence_ladder,
+                tags=("evidence",),
+            ),
+        ]
+
+
+ADAPTER = ProviderAdapter()