sourcelock 0.1.0__py3-none-any.whl

hc_source/adapters/coverage.py

@@ -0,0 +1,1569 @@
+"""CMS Medicare coverage-policy route: Coverage API + MCD bulk exports.
+
+Upstream is the keyless CMS Coverage API (``api.coverage.cms.gov``) with the
+Medicare Coverage Database bulk export ZIPs (``downloads.cms.gov``) as the
+documented fallback. Document families: NCDs (national, binding in all
+states), LCDs (per-MAC-jurisdiction), and Articles (billing/coding guidance
+attached to LCDs -- since the 2019 MCD restructuring, CPT/HCPCS/ICD-10 codes
+live in Articles, not LCDs, except some DME LCDs).
+
+License posture (deliberate, load-bearing):
+
+* Part of the API sits behind an AMA/ADA/AHA license-agreement Bearer token.
+  Fetching that token from ``/v1/metadata/license-agreement/`` legally
+  constitutes accepting the AMA CPT personal-use license. **This adapter never
+  calls that endpoint.** Automated paths use only keyless surfaces.
+* If the operator has minted a token themselves (their own acceptance act),
+  they may export it as ``HC_SOURCE_COVERAGE_LICENSE_TOKEN``; the adapter will
+  then use the token-gated ``related-documents`` endpoint (whose payload is
+  bare ID tuples, free of licensed descriptor text) instead of downloading the
+  bulk export. Endpoints whose responses contain CPT/CDT/NUBC descriptor
+  content (``hcpc-code``, ``bill-codes``, ``revenue-code``, LCD/Article
+  narrative) are not exposed as tools at all.
+* NCD narrative is redacted whenever the record flags AMA content
+  (``ama_statement`` non-empty -- or missing, which is the same thing minus the
+  ability to check).
+* Everything that reaches ``data`` passes a structural ALLOWLIST of field names
+  per endpoint (``NCD_DETAIL_FIELDS`` and friends). A field CMS adds or renames
+  is quarantined: dropped, with only its NAME in a receipt warning. A denylist
+  of the known narrative keys cannot see the next licensed field coming.
+
+The LCD <-> companion-Article linkage (the route's core query) was verified
+live 2026-08-01 on both surfaces: API ``/v1/data/lcd/related-documents``
+(token-gated; L33818 -> A57660) and the keyless bulk crosswalk
+``lcd_related_documents.csv`` inside ``current_lcd.zip`` (identical column
+set; 967 of 969 current final LCDs carry at least one companion link). See
+the route dossier's VERIFIED ADDENDUM.
+"""
+
+from __future__ import annotations
+
+import csv
+import dataclasses
+import hashlib
+import io
+import json
+import os
+import re
+import zipfile
+from datetime import date, datetime, timedelta
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from ..http import FetchResult, SourceUnreachable, as_cache_hit, fetch, fetch_json
+from ..interfaces import Canary, CanaryObservation, SourceAdapter, ToolResult, ToolSpec
+from ..receipts import build_receipt
+from ..schemas import CanaryStatus, SourceContract
+
+SOURCE_ID = "coverage"
+TRANSFORM_VERSION = "1"
+
+API = "https://api.coverage.cms.gov"
+SCHEDULE_URL = f"{API}/v1/metadata/local-data-schedule/"
+STATES_URL = f"{API}/v1/metadata/states/"
+CONTRACT_TYPES_URL = f"{API}/v1/metadata/contract-type/"
+NCD_REPORT_URL = f"{API}/v1/reports/national-coverage-ncd/"
+NCD_DETAIL_URL = f"{API}/v1/data/ncd/"
+FINAL_LCDS_URL = f"{API}/v1/reports/local-coverage-final-lcds/"
+ARTICLES_REPORT_URL = f"{API}/v1/reports/local-coverage-articles/"
+WHATS_NEW_LOCAL_URL = f"{API}/v1/reports/whats-new/local/"
+WHATS_NEW_NATIONAL_URL = f"{API}/v1/reports/whats-new/national/"
+LCD_RELATED_URL = f"{API}/v1/data/lcd/related-documents"
+LCD_DETAIL_URL = f"{API}/v1/data/lcd/"
+SPEC_URL = f"{API}/docs/v1/coverage-api.json"
+
+BULK_BASE = "https://downloads.cms.gov/medicare-coverage-database/downloads/exports"
+BULK_LCD_ZIP_URL = f"{BULK_BASE}/current_lcd.zip"
+NCD_ZIP_URL = f"{BULK_BASE}/ncd.zip"
+
+#: Operator-minted AMA/ADA/AHA license token. The adapter NEVER mints one.
+LICENSE_TOKEN_ENV = "HC_SOURCE_COVERAGE_LICENSE_TOKEN"
+
+#: Spec paths this adapter (or its canaries) actually calls. The api_contract
+#: canary alarms only when one of these disappears; additions upstream are
+#: informational (additive-path-growth policy).
+REQUIRED_PATHS = (
+    "/v1/data/lcd/",
+    "/v1/data/lcd/related-documents",
+    "/v1/data/ncd/",
+    "/v1/metadata/contract-type/",
+    "/v1/metadata/local-data-schedule/",
+    "/v1/metadata/states/",
+    "/v1/reports/local-coverage-articles/",
+    "/v1/reports/local-coverage-final-lcds/",
+    "/v1/reports/national-coverage-ncd/",
+    "/v1/reports/whats-new/local/",
+    "/v1/reports/whats-new/national/",
+)
+
+#: NCD narrative fields withheld when the record flags licensed AMA content.
+NCD_NARRATIVE_FIELDS = (
+    "item_service_description",
+    "indications_limitations",
+    "cross_reference",
+    "revision_history",
+    "other_text",
+    "reasons_for_denial",
+)
+
+#: Fields each Coverage API surface is allowed to emit, endpoint by endpoint.
+#: These are ALLOWLISTS on purpose. The six narrative keys above are a denylist,
+#: and a denylist over an upstream that can add or rename a column passes the
+#: seventh licensed field straight through into `data` -- AMA CPT, ADA CDT, or
+#: AHA/NUBC content SourceLock is not licensed to redistribute, published under
+#: a receipt saying it is redistribution-clean. Anything not named here is
+#: quarantined: dropped from `data`, with only its NAME recorded in a receipt
+#: warning so the omission is visible and auditable. Extending a list is a
+#: deliberate act that belongs with a contamination review, not a shrug.
+#: Recorded live 2026-08-01 from each endpoint's ``meta.fields``, in upstream
+#: column order so the two can be diffed by eye.
+NCD_DETAIL_FIELDS = (
+    "document_id",
+    "document_version",
+    "document_display_id",
+    "title",
+    "publication_number",
+    "effective_date",
+    "effective_end_date",
+    "implementation_date",
+    "qr_modifier_date",
+    "benefit_category",
+    "item_service_description",
+    "indications_limitations",
+    "cross_reference",
+    "transmittal_number",
+    "transmittal_url",
+    "revision_history",
+    "other_text",
+    "ama_statement",
+    "reasons_for_denial",
+)
+
+#: The three local-document report surfaces (final LCDs, Articles, whats-new
+#: local) share one column set upstream and therefore one allowlist here.
+LOCAL_REPORT_FIELDS = (
+    "document_id",
+    "document_version",
+    "document_display_id",
+    "document_type",
+    "note",
+    "title",
+    "contractor_name_type",
+    "updated_on",
+    "updated_on_sort",
+    "effective_date",
+    "retirement_date",
+    "url",
+)
+
+NCD_REPORT_FIELDS = (
+    "document_id",
+    "document_version",
+    "document_display_id",
+    "last_updated",
+    "last_updated_sort",
+    "document_type",
+    "title",
+    "chapter",
+    "is_lab",
+    "url",
+)
+
+WHATS_NEW_NATIONAL_FIELDS = (
+    "document_id",
+    "document_version",
+    "document_display_id",
+    "document_status",
+    "last_updated",
+    "last_updated_sort",
+    "document_type",
+    "title",
+    "whats_new_description",
+    "url",
+)
+
+#: Upstream statuses that mean "CMS had a bad minute", not "CMS changed
+#: something". Every route here that passes raise_for_status=False and reads the
+#: status itself must convert these into SourceUnreachable: doctor grades an
+#: unreadable source UNREACHABLE and a changed value DRIFT, and the two get
+#: different fixes. A 503 on the license-gate probe used to read as drift, and
+#: that canary's drift remediation tells a human to STOP and open a CPT
+#: contamination review -- over one bad minute at CMS. A 200 carrying changed
+#: content is still drift; only these statuses (and the connect/read timeouts
+#: `fetch` already converts, whatever raise_for_status says) are transient.
+TRANSIENT_STATUSES = frozenset({429, 500, 502, 503, 504})
+
+#: Bulk ZIP size band for ncd.zip (was 1,276,829 B on 2026-08-01).
+NCD_ZIP_SIZE_BAND = (900_000, 2_500_000)
+
+#: MCD-internal state ids are alphabetical-order integers, NOT FIPS; resolve
+#: through /v1/metadata/states/ descriptions. This table only maps postal
+#: abbreviations to the names those descriptions start with (public-domain).
+STATE_NAMES = {
+    "AL": "Alabama", "AK": "Alaska", "AS": "American Samoa", "AZ": "Arizona",
+    "AR": "Arkansas", "CA": "California", "CO": "Colorado", "CT": "Connecticut",
+    "DE": "Delaware", "DC": "District of Columbia", "FL": "Florida",
+    "GA": "Georgia", "GU": "Guam", "HI": "Hawaii", "ID": "Idaho",
+    "IL": "Illinois", "IN": "Indiana", "IA": "Iowa", "KS": "Kansas",
+    "KY": "Kentucky", "LA": "Louisiana", "ME": "Maine", "MD": "Maryland",
+    "MA": "Massachusetts", "MI": "Michigan", "MN": "Minnesota",
+    "MS": "Mississippi", "MO": "Missouri", "MT": "Montana", "NE": "Nebraska",
+    "NV": "Nevada", "NH": "New Hampshire", "NJ": "New Jersey",
+    "NM": "New Mexico", "NY": "New York", "NC": "North Carolina",
+    "ND": "North Dakota", "MP": "Northern Mariana Islands", "OH": "Ohio",
+    "OK": "Oklahoma", "OR": "Oregon", "PA": "Pennsylvania",
+    "PR": "Puerto Rico", "RI": "Rhode Island", "SC": "South Carolina",
+    "SD": "South Dakota", "TN": "Tennessee", "TX": "Texas", "UT": "Utah",
+    "VT": "Vermont", "VA": "Virginia", "VI": "Virgin Islands",
+    "WA": "Washington", "WV": "West Virginia", "WI": "Wisconsin",
+    "WY": "Wyoming",
+}
+
+CONTRACT = SourceContract(
+    source_id=SOURCE_ID,
+    authority_url=API,
+    fallback_url=f"{BULK_BASE}/",
+    license_notes=(
+        "The coverage documents themselves are US Government works. However, parts of the "
+        "Coverage API and the bulk exports embed licensed third-party code sets: CPT "
+        "(AMA, personal-use-only license), CDT (ADA), and UB-04 bill/revenue codes "
+        "(AHA/NUBC). This adapter never accepts those licenses programmatically, never "
+        "calls the license-agreement token endpoint, and never returns licensed "
+        "descriptor content; ID tuples, titles, dates, and jurisdiction data returned "
+        "here are redistribution-clean. Operators who need descriptor surfaces must "
+        "accept the license and mint a token themselves (see "
+        "HC_SOURCE_COVERAGE_LICENSE_TOKEN)."
+    ),
+    cadence=(
+        "local coverage (LCD/Article): weekly snapshot, captured Sundays 11:59pm ET, "
+        "published Thursdays ~02:00 GMT; national documents (NCD/NCA/CAL): event-driven"
+    ),
+    effective_date_semantics=(
+        "For NCDs, effective_from/effective_to are the NCD's own effective and "
+        "end dates (implementation_date, when claims processing starts, may differ). "
+        "For LCDs/Articles, effective_from is the document's effective date within the "
+        "weekly MCD snapshot named in source_version; the latest version of a document "
+        "may be future-effective or retired. Documents retired over a year leave the "
+        "API and bulk exports entirely for the MCD Archive."
+    ),
+    invariants=[
+        "the weekly local-data-schedule reports exactly one row, with "
+        "data_captured_through (a Sunday) strictly before refreshed_on_date",
+        "the OpenAPI spec keeps serving every path this adapter calls",
+        "internal document ids are stable: ncdid=11 is NCD 30.3 'Acupuncture' (pub 100-3)",
+        "the bulk export ZIPs stay reachable at their documented URLs and ncd.zip stays "
+        "within its size band",
+        "LCD/Article data endpoints stay behind the AMA/ADA/AHA license gate (HTTP 401 "
+        "without a token)",
+        "the MCD-internal state and contract-type keyspaces are stable (state 6 is "
+        "'California - Entire State'; contract types are exactly ids 8-13)",
+    ],
+)
+
+NON_CLAIMS = [
+    "DOES_NOT_PROVE_COVERAGE: an NCD/LCD/Article match does not prove Medicare will "
+    "cover or pay any particular claim; coverage turns on medical necessity, "
+    "jurisdiction, claim context, and edits outside these documents.",
+    "CODING_LIVES_IN_ARTICLES: LCDs generally carry no CPT/HCPCS/ICD-10 codes; billing "
+    "and coding specifics live in the companion Billing-and-Coding Article (some DME "
+    "LCDs excepted).",
+    "VERSIONS_ARE_NOT_ALWAYS_IN_EFFECT: the latest version of a document may be "
+    "future-effective or retired, and documents retired over a year move to the MCD "
+    "Archive; check status and effective dates before relying on a match.",
+    "NO_LICENSED_CODE_CONTENT: CPT (AMA), CDT (ADA), and UB-04/NUBC (AHA) descriptor "
+    "content is licensed and never returned by this adapter; consult those surfaces "
+    "under your own license.",
+    "DOES_NOT_PROVE_CURRENCY: local coverage answers come from the weekly MCD snapshot "
+    "(captured Sundays, published Thursdays) and may lag the MACs by up to a week.",
+]
+
+#: In-process cache of the parsed bulk crosswalk, bound to the weekly MCD
+#: snapshot the rows were downloaded under:
+#: {"snapshot_version": str, "fetch": FetchResult, "rows": list[dict]}.
+#: The binding is the load-bearing part -- see _load_bulk_crosswalk. Tests
+#: clear it.
+_BULK_CACHE: dict[str, Any] = {}
+
+_DISPLAY_DATE_RE = re.compile(r"^(\d{2})/(\d{2})/(\d{4})$")
+_YYYYMMDD_RE = re.compile(r"^\d{8}$")
+
+
+# --------------------------------------------------------------------------
+# small helpers
+# --------------------------------------------------------------------------
+
+
+def _rows(payload: Any) -> list[dict[str, Any]]:
+    if isinstance(payload, dict) and isinstance(payload.get("data"), list):
+        return payload["data"]
+    return []
+
+
+def _fields(payload: Any) -> list[str]:
+    if isinstance(payload, dict):
+        meta = payload.get("meta") or {}
+        fields = meta.get("fields")
+        if isinstance(fields, list):
+            return [str(f) for f in fields]
+    return []
+
+
+def _canonical_hash(obj: Any) -> str:
+    return hashlib.sha256(
+        json.dumps(obj, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+
+
+def _parse_display_date(value: Any) -> date | None:
+    """MM/DD/YYYY display strings; 'N/A' and empty are None."""
+    if not isinstance(value, str):
+        return None
+    m = _DISPLAY_DATE_RE.match(value.strip())
+    if not m:
+        return None
+    return date(int(m.group(3)), int(m.group(1)), int(m.group(2)))
+
+
+def _parse_yyyymmdd(value: Any) -> date | None:
+    if isinstance(value, str) and _YYYYMMDD_RE.match(value):
+        return date(int(value[:4]), int(value[4:6]), int(value[6:8]))
+    return None
+
+
+def _clean_crlf(value: Any) -> Any:
+    return value.replace("\r\n", " ").replace("\r", " ") if isinstance(value, str) else value
+
+
+def _quarantine(
+    row: dict[str, Any], allowed: tuple[str, ...]
+) -> tuple[dict[str, Any], list[str]]:
+    """Project one upstream row onto its endpoint's allowlist.
+
+    Returns the kept fields (CRLF-normalized) and the NAMES of the fields that
+    were dropped. The VALUE of a dropped field is never returned, never logged,
+    and never put in a warning -- the reason it was dropped is precisely that
+    nobody has established what it contains.
+    """
+    kept = {k: _clean_crlf(v) for k, v in row.items() if k in allowed}
+    return kept, [k for k in row if k not in allowed]
+
+
+def _quarantine_warning(endpoint: str, names: list[str]) -> str:
+    return (
+        f"{len(names)} field(s) returned by {endpoint} are not on this adapter's "
+        f"allowlist and were dropped from the answer: {', '.join(names)}. Names "
+        "only: an unrecognised field may carry AMA CPT, ADA CDT, or AHA/NUBC "
+        "licensed content, so its value is never emitted. Read it on the MCD "
+        "website under your own license, or extend the allowlist in "
+        "hc_source/adapters/coverage.py after a contamination review."
+    )
+
+
+def _quarantine_rows(
+    rows: list[dict[str, Any]],
+    allowed: tuple[str, ...],
+    endpoint: str,
+    warnings: list[str],
+) -> list[dict[str, Any]]:
+    """Project a list of rows and append one warning naming every dropped field."""
+    projected: list[dict[str, Any]] = []
+    dropped: set[str] = set()
+    for row in rows:
+        kept, names = _quarantine(row, allowed)
+        projected.append(kept)
+        dropped.update(names)
+    if dropped:
+        warnings.append(_quarantine_warning(endpoint, sorted(dropped)))
+    return projected
+
+
+def _raise_if_transient(result: FetchResult, url: str) -> None:
+    """Turn a transient upstream status into an unreachable source.
+
+    Called by every route that inspects a status itself. Without it a 429 or a
+    5xx becomes an observation value, which doctor then reports as drift -- a
+    false claim that CMS changed something, carrying a remediation that sends a
+    human to re-pin or to open a contamination review over an outage.
+    """
+    if result.status in TRANSIENT_STATUSES:
+        raise SourceUnreachable(
+            url,
+            "transient upstream failure; the source was not read this run",
+            status=result.status,
+        )
+
+
+def _snapshot_version() -> tuple[FetchResult, str, str]:
+    """The canonical weekly-dataset version string for local coverage data."""
+    result, payload = fetch_json(SCHEDULE_URL)
+    rows = _rows(payload)
+    if len(rows) != 1:
+        raise SourceUnreachable(SCHEDULE_URL, "local-data-schedule returned unexpected shape")
+    refreshed = str(rows[0].get("refreshed_on_date", ""))
+    captured = str(rows[0].get("data_captured_through", ""))
+    if not (_YYYYMMDD_RE.match(refreshed) and _YYYYMMDD_RE.match(captured)):
+        raise SourceUnreachable(SCHEDULE_URL, "local-data-schedule dates were not YYYYMMDD")
+    return result, refreshed, captured
+
+
+def _resolve_state_id(state: str) -> tuple[int | None, list[str]]:
+    """Resolve a postal abbreviation to the MCD-internal state_id (NOT FIPS)."""
+    warnings: list[str] = []
+    name = STATE_NAMES.get(state.upper())
+    if name is None:
+        return None, [f"Unknown state abbreviation {state!r}."]
+    _, payload = fetch_json(STATES_URL)
+    matches = [
+        row
+        for row in _rows(payload)
+        if isinstance(row.get("description"), str)
+        and (row["description"] == name or row["description"].startswith(name + " "))
+    ]
+    if not matches:
+        return None, [f"State {name!r} not present in /v1/metadata/states/."]
+    matches.sort(key=lambda r: int(r["state_id"]))
+    if len(matches) > 1:
+        warnings.append(
+            f"State {name!r} matched {len(matches)} MCD state entries; using "
+            f"state_id={matches[0]['state_id']} ({matches[0]['description']!r})."
+        )
+    return int(matches[0]["state_id"]), warnings
+
+
+def _license_token() -> str | None:
+    token = os.environ.get(LICENSE_TOKEN_ENV, "").strip()
+    return token or None
+
+
+# --------------------------------------------------------------------------
+# typed public parameters
+# --------------------------------------------------------------------------
+
+
+class NoParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class LookupNcdParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    section: str = Field(
+        pattern=r"^\d{1,3}(\.\d{1,3}){0,2}$",
+        description="NCD manual section number, e.g. '30.3' (Publication 100-3 numbering).",
+    )
+    version: int | None = Field(
+        default=None, ge=1, description="NCD version; omit for the latest."
+    )
+
+
+class LookupLcdParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    lcd_id: int = Field(ge=1, description="LCD number without the 'L' prefix, e.g. 33818.")
+    state: str | None = Field(
+        default=None,
+        pattern=r"^[A-Za-z]{2}$",
+        description="Two-letter state/territory abbreviation to scope the jurisdiction.",
+    )
+
+
+class CompanionArticlesParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    lcd_id: int = Field(ge=1, description="LCD number without the 'L' prefix, e.g. 33818.")
+    version: int | None = Field(
+        default=None, ge=1, description="LCD version; omit for the latest in the crosswalk."
+    )
+
+
+class SearchDocumentsParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    keyword: str = Field(
+        min_length=2,
+        max_length=80,
+        pattern=r"^[A-Za-z0-9][A-Za-z0-9 &,()\-./']{1,79}$",
+        description="Case-insensitive title keyword, e.g. 'malignant'.",
+    )
+    document_type: Literal["lcd", "article", "ncd"] = Field(
+        description="Which document family to search."
+    )
+    state: str | None = Field(
+        default=None,
+        pattern=r"^[A-Za-z]{2}$",
+        description="Two-letter state abbreviation (local documents only).",
+    )
+    contractor_id: int | None = Field(
+        default=None, ge=1, description="MAC contractor id (local documents only)."
+    )
+    status: Literal["A", "R", "F"] | None = Field(
+        default=None,
+        description="A=Active, R=Retired, F=Future Effective (local documents only).",
+    )
+
+    @model_validator(mode="after")
+    def _local_filters_only_for_local(self) -> SearchDocumentsParams:
+        if self.document_type == "ncd" and (self.state or self.contractor_id or self.status):
+            raise ValueError(
+                "state, contractor_id, and status apply to local documents only; "
+                "NCDs are national"
+            )
+        return self
+
+
+class WhatsChangedParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    scope: Literal["local", "national"] = Field(
+        description="local = LCD/Article whats-new feed; national = NCD/NCA/CAL feed."
+    )
+    days_back: int = Field(
+        default=7, ge=1, le=120, description="Look-back window in days (max 120)."
+    )
+    document_type: Literal["NCD", "NCA", "CAL", "MEDCAC", "TA", "MCD"] | None = Field(
+        default=None, description="National feed only: restrict to one document type."
+    )
+    contractor_id: int | None = Field(
+        default=None, ge=1, description="Local feed only: restrict to one MAC contractor."
+    )
+
+    @model_validator(mode="after")
+    def _filters_match_scope(self) -> WhatsChangedParams:
+        if self.scope == "local" and self.document_type:
+            raise ValueError("document_type applies to scope='national' only")
+        if self.scope == "national" and self.contractor_id:
+            raise ValueError("contractor_id applies to scope='local' only")
+        return self
+
+
+# --------------------------------------------------------------------------
+# handlers
+# --------------------------------------------------------------------------
+
+
+def _snapshot(_: NoParams) -> ToolResult:
+    result, refreshed, captured = _snapshot_version()
+    refreshed_date = _parse_yyyymmdd(refreshed)
+    captured_date = _parse_yyyymmdd(captured)
+    data = {
+        "data_captured_through": captured,
+        "refreshed_on_date": refreshed,
+        "captured_through_date": captured_date.isoformat() if captured_date else None,
+        "refreshed_on": refreshed_date.isoformat() if refreshed_date else None,
+    }
+    return ToolResult(
+        data=data,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="coverage.snapshot",
+            fetch=result,
+            source_version=f"mcd-weekly-{refreshed}",
+            transform_version=TRANSFORM_VERSION,
+            effective_from=refreshed_date,
+            non_claims=NON_CLAIMS,
+        ),
+    )
+
+
+def _lookup_ncd(params: LookupNcdParams) -> ToolResult:
+    warnings: list[str] = []
+
+    report_fetch, report = fetch_json(NCD_REPORT_URL)
+    anchor = next(
+        (r for r in _rows(report) if str(r.get("document_display_id")) == params.section),
+        None,
+    )
+    if anchor is None:
+        warnings.append(
+            "The requested NCD section was not found in the national-coverage-ncd report; "
+            "it may never have existed or may have been removed."
+        )
+        return ToolResult(
+            data=None,
+            receipt=build_receipt(
+                contract=CONTRACT,
+                route="coverage.lookup_ncd",
+                fetch=report_fetch,
+                source_version="national-coverage-ncd report",
+                transform_version=TRANSFORM_VERSION,
+                warnings=warnings,
+                non_claims=NON_CLAIMS,
+            ),
+        )
+
+    query: dict[str, Any] = {"ncdid": int(anchor["document_id"])}
+    if params.version is not None:
+        query["ncdver"] = params.version
+    detail_fetch = fetch(NCD_DETAIL_URL, params=query, raise_for_status=False)
+    # A 5xx is not "no such NCD". Reporting it as a miss would tell a caller the
+    # section does not exist on the strength of an outage.
+    _raise_if_transient(detail_fetch, NCD_DETAIL_URL)
+    record: dict[str, Any] | None = None
+    if detail_fetch.status == 200:
+        detail_rows = _rows(detail_fetch.json())
+        record = dict(detail_rows[0]) if detail_rows else None
+    if record is None:
+        warnings.append(
+            f"The requested NCD (ncdid={query['ncdid']}"
+            + (f", version {params.version}" if params.version is not None else "")
+            + f") returned no record (HTTP {detail_fetch.status})."
+        )
+        return ToolResult(
+            data=None,
+            receipt=build_receipt(
+                contract=CONTRACT,
+                route="coverage.lookup_ncd",
+                fetch=detail_fetch,
+                source_version=f"ncd {params.section} (not found)",
+                transform_version=TRANSFORM_VERSION,
+                warnings=warnings,
+                non_claims=NON_CLAIMS,
+            ),
+        )
+
+    record, dropped = _quarantine(record, NCD_DETAIL_FIELDS)
+    if dropped:
+        warnings.append(_quarantine_warning("/v1/data/ncd/", dropped))
+
+    # Withheld unless the record positively asserts an EMPTY ama_statement. A
+    # missing key is treated as flagged, not as clean: if CMS renames the flag,
+    # the failure mode of the old test (`record.get("ama_statement")` -> None ->
+    # falsy -> publish) was to redistribute licensed narrative. Failing towards
+    # withholding costs a caller some public-domain prose; failing the other way
+    # costs an AMA license SourceLock does not hold.
+    ama_statement = record.get("ama_statement")
+    if "ama_statement" not in record or str(ama_statement or "").strip():
+        for field_name in NCD_NARRATIVE_FIELDS:
+            if field_name in record:
+                record[field_name] = None
+        warnings.append(
+            "Narrative fields withheld: this NCD flags licensed AMA CPT content "
+            "(ama_statement present, or absent from a record whose narrative "
+            "cannot then be cleared). Read the narrative on the MCD website under "
+            "your own CPT license."
+        )
+
+    return ToolResult(
+        data=record,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="coverage.lookup_ncd",
+            fetch=detail_fetch,
+            source_version=f"ncd {params.section} v{record.get('document_version')}",
+            transform_version=TRANSFORM_VERSION,
+            effective_from=_parse_display_date(record.get("effective_date")),
+            effective_to=_parse_display_date(record.get("effective_end_date")),
+            warnings=warnings,
+            non_claims=NON_CLAIMS,
+        ),
+    )
+
+
+def _parse_contractors(name_type: Any) -> list[dict[str, str]]:
+    """Split 'Name\r\n(Types)\r\nName2\r\n(Types2)' into structured entries."""
+    contractors: list[dict[str, str]] = []
+    if not isinstance(name_type, str):
+        return contractors
+    for part in (p.strip() for p in name_type.split("\r\n") if p.strip()):
+        if part.startswith("(") and contractors:
+            contractors[-1]["contract_types"] = part.strip("()")
+        else:
+            contractors.append({"name": part, "contract_types": ""})
+    return contractors
+
+
+def _lookup_lcd(params: LookupLcdParams) -> ToolResult:
+    warnings: list[str] = []
+    _, refreshed, _captured = _snapshot_version()
+
+    query: dict[str, Any] = {}
+    scope_note = ""
+    if params.state:
+        state_id, state_warnings = _resolve_state_id(params.state)
+        warnings.extend(state_warnings)
+        if state_id is None:
+            return ToolResult(
+                data=None,
+                receipt=build_receipt(
+                    contract=CONTRACT,
+                    route="coverage.lookup_lcd",
+                    fetch=fetch(SCHEDULE_URL),
+                    source_version=f"mcd-weekly-{refreshed}",
+                    transform_version=TRANSFORM_VERSION,
+                    warnings=warnings,
+                    non_claims=NON_CLAIMS,
+                ),
+            )
+        query["state_id"] = state_id
+        scope_note = f" for state {params.state.upper()}"
+
+    report_fetch, report = fetch_json(FINAL_LCDS_URL, params=query or None)
+    matches = [r for r in _rows(report) if r.get("document_id") == params.lcd_id]
+    if not matches:
+        warnings.append(
+            f"L{params.lcd_id} not found in the current final-LCDs report{scope_note}. "
+            "It may be proposed-only, outside the selected jurisdiction, or retired "
+            "over a year (in which case it lives in the MCD Archive, which has no API)."
+        )
+        return ToolResult(
+            data=None,
+            receipt=build_receipt(
+                contract=CONTRACT,
+                route="coverage.lookup_lcd",
+                fetch=report_fetch,
+                source_version=f"mcd-weekly-{refreshed}",
+                transform_version=TRANSFORM_VERSION,
+                warnings=warnings,
+                non_claims=NON_CLAIMS,
+            ),
+        )
+
+    # No _quarantine call here: this route names every field it emits, which is
+    # an allowlist by construction. A new upstream column cannot reach `data`.
+    first = matches[0]
+    contractors: list[dict[str, str]] = []
+    for row in matches:
+        contractors.extend(_parse_contractors(row.get("contractor_name_type")))
+    data = {
+        "lcd_id": params.lcd_id,
+        "display_id": first.get("document_display_id"),
+        "version": first.get("document_version"),
+        "title": first.get("title"),
+        "status_note": first.get("note") or "",
+        "effective_date": first.get("effective_date"),
+        "retirement_date": (
+            None if first.get("retirement_date") in (None, "N/A") else first.get("retirement_date")
+        ),
+        "contractors": contractors,
+        "url": first.get("url"),
+    }
+    if data["status_note"] == "Future":
+        warnings.append(
+            f"L{params.lcd_id} is future-effective (effective {data['effective_date']}); "
+            "it is not in force yet."
+        )
+
+    return ToolResult(
+        data=data,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="coverage.lookup_lcd",
+            fetch=report_fetch,
+            source_version=f"mcd-weekly-{refreshed}",
+            transform_version=TRANSFORM_VERSION,
+            effective_from=_parse_display_date(first.get("effective_date")),
+            effective_to=_parse_display_date(first.get("retirement_date")),
+            warnings=warnings,
+            non_claims=NON_CLAIMS,
+        ),
+    )
+
+
+#: current_lcd.zip measured 31.8 MB on 2026-08-01 -- the largest real full-body
+#: fetch in the product. 128 MiB is 4x that, and the timeout of 300s below is
+#: the other half of the same acknowledgement that this one is big.
+BULK_ZIP_MAX_BYTES = 128 * 1024 * 1024
+
+
+def _load_bulk_crosswalk(
+    snapshot_version: str,
+) -> tuple[FetchResult, list[dict[str, str]], bool]:
+    """Fetch and parse lcd_related_documents.csv from the keyless bulk export.
+
+    Returns ``(fetch_result, rows, served_from_cache)``. The parsed crosswalk is
+    cached in-process -- the export only changes on the weekly Thursday refresh
+    -- but the entry is bound to ``snapshot_version``, the weekly MCD release
+    observed when those rows were downloaded, and a different release refetches.
+
+    The cache used to be keyed by nothing at all (one entry, one constant URL)
+    while every answer was stamped with a freshly-fetched schedule version. A
+    process that stayed up across a Thursday refresh then served week-N rows
+    under a receipt claiming week N+1: rows from one release paired with the
+    version identifier of another, which is the one thing a receipt must never
+    do. Refetching beats serving the old rows under the old version plus a
+    staleness warning: the release moves once a week, so a long-lived process
+    pays one extra download per refresh, and what it then returns is the
+    crosswalk the caller actually asked for rather than a correctly-labelled
+    stale one.
+    """
+    if _BULK_CACHE.get("snapshot_version") == snapshot_version:
+        return _BULK_CACHE["fetch"], _BULK_CACHE["rows"], True
+    result = fetch(BULK_LCD_ZIP_URL, timeout=300.0, max_bytes=BULK_ZIP_MAX_BYTES)
+    try:
+        with zipfile.ZipFile(io.BytesIO(result.content)) as outer:
+            inner_name = next(n for n in outer.namelist() if n.endswith("_csv.zip"))
+            with zipfile.ZipFile(io.BytesIO(outer.read(inner_name))) as inner:
+                text = inner.read("lcd_related_documents.csv").decode("utf-8-sig")
+    except (zipfile.BadZipFile, KeyError, StopIteration) as exc:
+        raise SourceUnreachable(
+            BULK_LCD_ZIP_URL,
+            f"bulk export did not contain lcd_related_documents.csv ({type(exc).__name__})",
+        ) from exc
+    rows = list(csv.DictReader(io.StringIO(text)))
+    # The FetchResult object itself is cached, never rebuilt: it carries the
+    # retrieved_at stamped when these bytes were read, and a rebuilt one would
+    # make the receipt claim a read that did not happen.
+    _BULK_CACHE["snapshot_version"] = snapshot_version
+    _BULK_CACHE["fetch"] = result
+    _BULK_CACHE["rows"] = rows
+    return result, rows, False
+
+
+def _relation_entries(rows: list[dict[str, Any]]) -> tuple[list[dict], list[dict]]:
+    """Normalize crosswalk rows (API or bulk CSV) into articles + related LCDs."""
+    articles: list[dict[str, Any]] = []
+    related_lcds: list[dict[str, Any]] = []
+    for row in rows:
+        article_id = row.get("r_article_id")
+        lcd_id = row.get("r_lcd_id")
+        if article_id not in (None, ""):
+            articles.append(
+                {
+                    "article_id": int(article_id),
+                    "display_id": f"A{int(article_id)}",
+                    "article_version": (
+                        int(row["r_article_version"])
+                        if row.get("r_article_version") not in (None, "")
+                        else None
+                    ),
+                    "contractor_id": (
+                        int(row["r_contractor_id"])
+                        if row.get("r_contractor_id") not in (None, "")
+                        else None
+                    ),
+                }
+            )
+        elif lcd_id not in (None, ""):
+            related_lcds.append(
+                {
+                    "lcd_id": int(lcd_id),
+                    "display_id": f"L{int(lcd_id)}",
+                    "lcd_version": (
+                        int(row["r_lcd_version"])
+                        if row.get("r_lcd_version") not in (None, "")
+                        else None
+                    ),
+                }
+            )
+    articles.sort(key=lambda a: a["article_id"])
+    related_lcds.sort(key=lambda entry: entry["lcd_id"])
+    return articles, related_lcds
+
+
+def _companion_articles(params: CompanionArticlesParams) -> ToolResult:
+    warnings: list[str] = []
+    _, refreshed, _captured = _snapshot_version()
+
+    relation_rows: list[dict[str, Any]] | None = None
+    result: FetchResult | None = None
+    resolved_version: int | None = params.version
+
+    token = _license_token()
+    if token is not None:
+        query: dict[str, Any] = {"lcdid": params.lcd_id}
+        if params.version is not None:
+            query["ver"] = params.version
+        try:
+            api_fetch = fetch(
+                LCD_RELATED_URL,
+                params=query,
+                headers={"Authorization": f"Bearer {token}"},
+                raise_for_status=False,
+            )
+        except SourceUnreachable as exc:
+            warnings.append(
+                f"Token-gated related-documents endpoint unreachable ({exc.reason}); "
+                "falling back to the keyless bulk export."
+            )
+        else:
+            if api_fetch.status == 200:
+                relation_rows = _rows(api_fetch.json())
+                result = api_fetch
+                warnings.append(
+                    "Fetched via the operator-supplied license token "
+                    f"({LICENSE_TOKEN_ENV}). Minting that token was the operator's own "
+                    "AMA/ADA/AHA license acceptance; SourceLock never accepts it for you."
+                )
+                if relation_rows and resolved_version is None:
+                    resolved_version = relation_rows[0].get("lcd_version")
+            elif api_fetch.status in TRANSIENT_STATUSES:
+                # Not a token problem. Telling an operator their token expired
+                # over a 503 sends them to re-mint a token that was fine.
+                warnings.append(
+                    f"Token-gated related-documents endpoint returned a transient "
+                    f"upstream failure (HTTP {api_fetch.status}); that is a CMS-side "
+                    "outage, and it says nothing about the token. Falling back to the "
+                    "keyless bulk export."
+                )
+            else:
+                warnings.append(
+                    f"Operator-supplied license token was rejected (HTTP {api_fetch.status}); "
+                    "it expires one hour after minting. Falling back to the keyless bulk "
+                    "export."
+                )
+
+    if relation_rows is None:
+        bulk_fetch, all_rows, cached = _load_bulk_crosswalk(refreshed)
+        lcd_rows = [r for r in all_rows if r.get("lcd_id") == str(params.lcd_id)]
+        if params.version is None:
+            versions = [int(r["lcd_version"]) for r in lcd_rows if r.get("lcd_version")]
+            resolved_version = max(versions) if versions else None
+        if resolved_version is not None:
+            lcd_rows = [
+                r for r in lcd_rows if r.get("lcd_version") == str(resolved_version)
+            ]
+        relation_rows = lcd_rows
+        result = dataclasses.replace(
+            bulk_fetch, fallback_used=True, fallback_name="mcd-bulk-current-lcd-zip"
+        )
+        if cached:
+            # The prose warning below said "served from the in-process cache"
+            # while the structured field said cache_hit: false. A machine
+            # reading the receipt believes the field. retrieved_at and
+            # revalidated_at stay where the download put them -- reuse inside
+            # one weekly snapshot contacted nobody.
+            result = as_cache_hit(result)
+        # Reason-neutral wording: this branch is also reached when a token WAS
+        # supplied and the endpoint failed, and the warning above says why.
+        warnings.append(
+            "Used the keyless MCD bulk export crosswalk (current_lcd.zip / "
+            "lcd_related_documents.csv) rather than the token-gated related-documents "
+            f"endpoint. Set {LICENSE_TOKEN_ENV} to use the live endpoint under your own "
+            "license acceptance."
+        )
+        if cached:
+            warnings.append(
+                "Crosswalk served from the in-process cache of a bulk export downloaded "
+                f"earlier in this run under this same weekly snapshot (mcd-weekly-"
+                f"{refreshed}); receipt provenance and retrieved_at cover that download, "
+                "and cache_hit says so."
+            )
+
+    articles, related_lcds = _relation_entries(relation_rows)
+    if not articles:
+        warnings.append(
+            f"No companion Article found for L{params.lcd_id}"
+            + (f" v{resolved_version}" if resolved_version is not None else "")
+            + ". Genuine for a few LCDs (notably DME), otherwise check the LCD id."
+        )
+
+    assert result is not None  # both branches set it or raised
+    return ToolResult(
+        data={
+            "lcd_id": params.lcd_id,
+            "display_id": f"L{params.lcd_id}",
+            "lcd_version": resolved_version,
+            "companion_articles": articles,
+            "related_lcds": related_lcds,
+        },
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="coverage.companion_articles",
+            fetch=result,
+            source_version=f"mcd-weekly-{refreshed}",
+            transform_version=TRANSFORM_VERSION,
+            warnings=warnings,
+            non_claims=NON_CLAIMS,
+        ),
+    )
+
+
+_SEARCH_MATCH_CAP = 50
+
+
+def _search_documents(params: SearchDocumentsParams) -> ToolResult:
+    warnings: list[str] = []
+
+    if params.document_type == "ncd":
+        url = NCD_REPORT_URL
+        allowed = NCD_REPORT_FIELDS
+        endpoint = "/v1/reports/national-coverage-ncd/"
+        query: dict[str, Any] = {}
+        source_version = "national-coverage-ncd report"
+    else:
+        url = FINAL_LCDS_URL if params.document_type == "lcd" else ARTICLES_REPORT_URL
+        allowed = LOCAL_REPORT_FIELDS
+        endpoint = (
+            "/v1/reports/local-coverage-final-lcds/"
+            if params.document_type == "lcd"
+            else "/v1/reports/local-coverage-articles/"
+        )
+        _, refreshed, _captured = _snapshot_version()
+        source_version = f"mcd-weekly-{refreshed}"
+        query = {}
+        if params.state:
+            state_id, state_warnings = _resolve_state_id(params.state)
+            warnings.extend(state_warnings)
+            if state_id is None:
+                return ToolResult(
+                    data=None,
+                    receipt=build_receipt(
+                        contract=CONTRACT,
+                        route="coverage.search_documents",
+                        fetch=fetch(SCHEDULE_URL),
+                        source_version=source_version,
+                        transform_version=TRANSFORM_VERSION,
+                        warnings=warnings,
+                        non_claims=NON_CLAIMS,
+                    ),
+                )
+            query["state_id"] = state_id
+        if params.contractor_id:
+            query["contractor_id"] = params.contractor_id
+        if params.status:
+            query["status"] = params.status
+
+    report_fetch, report = fetch_json(url, params=query or None)
+    rows = _rows(report)
+    needle = params.keyword.lower()
+    matches = [r for r in rows if needle in str(r.get("title", "")).lower()]
+    if len(matches) > _SEARCH_MATCH_CAP:
+        warnings.append(
+            f"{len(matches)} titles matched; returning the first {_SEARCH_MATCH_CAP}. "
+            "Narrow the keyword or add filters."
+        )
+        matches = matches[:_SEARCH_MATCH_CAP]
+    # After the cap: only fields that would actually have been emitted are
+    # reported as quarantined.
+    matches = _quarantine_rows(matches, allowed, endpoint, warnings)
+    if not matches:
+        # The keyword is NOT echoed. This warning is persisted into the evidence
+        # receipt, which is the one artifact the product tells users to keep --
+        # round-1 finding C2 made it a PHI sink. Length is enough for an
+        # operator to recognise which call this was without quoting anything.
+        warnings.append(
+            f"No {params.document_type} titles matched the supplied keyword "
+            f"({len(params.keyword)} characters). Title search only: the MCD full-text "
+            "search surface is not part of this adapter."
+        )
+
+    return ToolResult(
+        data={
+            "matches": matches,
+            "match_count": len(matches),
+            "documents_searched": len(rows),
+        },
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="coverage.search_documents",
+            fetch=report_fetch,
+            source_version=source_version,
+            transform_version=TRANSFORM_VERSION,
+            warnings=warnings,
+            non_claims=NON_CLAIMS,
+        ),
+    )
+
+
+def _whats_changed(params: WhatsChangedParams) -> ToolResult:
+    warnings: list[str] = []
+    today = date.today()
+    window_start = today - timedelta(days=params.days_back - 1)
+    window_end = today + timedelta(days=1)  # [start, end) semantics upstream
+
+    if params.scope == "national":
+        query: dict[str, Any] = {"timeframe": params.days_back}
+        if params.document_type:
+            query["document_type"] = params.document_type
+        result, payload = fetch_json(WHATS_NEW_NATIONAL_URL, params=query)
+        raw_changes = _rows(payload)
+        allowed = WHATS_NEW_NATIONAL_FIELDS
+        endpoint = "/v1/reports/whats-new/national/"
+        source_version = "whats-new national feed (event-driven)"
+    else:
+        allowed = LOCAL_REPORT_FIELDS
+        endpoint = "/v1/reports/whats-new/local/"
+        _, refreshed, _captured = _snapshot_version()
+        source_version = f"mcd-weekly-{refreshed}"
+        raw_changes = []
+        seen: set[tuple] = set()
+        result = None
+        cursor = window_start
+        window_count = 0
+        while cursor < window_end:
+            chunk_end = min(cursor + timedelta(days=7), window_end)
+            query = {
+                "start_date": cursor.strftime("%Y%m%d"),
+                "end_date": chunk_end.strftime("%Y%m%d"),
+            }
+            if params.contractor_id:
+                query["contractor_id"] = params.contractor_id
+            result, payload = fetch_json(WHATS_NEW_LOCAL_URL, params=query)
+            window_count += 1
+            for row in _rows(payload):
+                key = (
+                    row.get("document_id"),
+                    row.get("document_version"),
+                    row.get("document_type"),
+                    row.get("updated_on_sort"),
+                )
+                if key not in seen:
+                    seen.add(key)
+                    raw_changes.append(row)
+            cursor = chunk_end
+        if window_count > 1:
+            warnings.append(
+                f"Aggregated {window_count} weekly windows (the upstream feed caps each "
+                "request at one week); receipt provenance covers the final window's fetch."
+            )
+
+    assert result is not None
+    changes = _quarantine_rows(raw_changes, allowed, endpoint, warnings)
+    return ToolResult(
+        data={
+            "scope": params.scope,
+            "window_start": window_start.isoformat(),
+            "window_end": today.isoformat(),
+            "changes": changes,
+            "change_count": len(changes),
+        },
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="coverage.whats_changed",
+            fetch=result,
+            source_version=source_version,
+            transform_version=TRANSFORM_VERSION,
+            effective_from=window_start,
+            effective_to=today,
+            warnings=warnings,
+            non_claims=NON_CLAIMS,
+        ),
+    )
+
+
+# --------------------------------------------------------------------------
+# canaries
+# --------------------------------------------------------------------------
+
+
+def _observe_weekly_snapshot() -> CanaryObservation:
+    result, payload = fetch_json(SCHEDULE_URL)
+    rows = _rows(payload)
+    if len(rows) != 1:
+        raise SourceUnreachable(SCHEDULE_URL, "local-data-schedule returned unexpected shape")
+    refreshed = str(rows[0].get("refreshed_on_date", ""))
+    captured = str(rows[0].get("data_captured_through", ""))
+    refreshed_date = _parse_yyyymmdd(refreshed)
+    captured_date = _parse_yyyymmdd(captured)
+    if refreshed_date is None or captured_date is None or not captured_date < refreshed_date:
+        raise SourceUnreachable(
+            SCHEDULE_URL, "local-data-schedule dates malformed or out of order"
+        )
+    note = f"captured through {captured}"
+    age = (date.today() - refreshed_date).days
+    # Nine days is one weekly cycle plus two days of slack for a skipped
+    # Thursday. Past that, "the refresh id still matches the pin" stops meaning
+    # "nothing changed upstream" and starts meaning "the thing we watch has
+    # stopped moving" -- which is not evidence of anything, so doctor grades it
+    # STALE rather than OK.
+    stale = age > 9
+    if stale:
+        note += f" (STALE: refresh is {age} days old; CMS occasionally skips a Thursday)"
+    return CanaryObservation(
+        value=refreshed,
+        schema_hash=_canonical_hash(_fields(payload)),
+        upstream_status=result.status,
+        note=note,
+        stale=stale,
+    )
+
+
+def _weekly_snapshot_remediation(status: CanaryStatus, observed, expected) -> str:
+    if status is CanaryStatus.UNREACHABLE:
+        return (
+            "The MCD local-data-schedule endpoint could not be read or returned a "
+            "malformed body. Check https://www.cms.gov/medicare-coverage-database/ for "
+            "outage banners, then re-run `hc-source doctor`."
+        )
+    return (
+        f"CMS published a new weekly MCD snapshot (refreshed {observed}; source-lock.json "
+        f"pins {expected}). Local coverage data moved with it: review whats-new "
+        "(`hc-source call coverage.whats_changed --param scope=local`), then re-pin with "
+        "`hc-source lock init`."
+    )
+
+
+def _observe_api_contract() -> CanaryObservation:
+    result, payload = fetch_json(SPEC_URL)
+    paths = payload.get("paths")
+    if not isinstance(paths, dict):
+        raise SourceUnreachable(SPEC_URL, "OpenAPI spec had no paths object")
+    openapi = str(payload.get("openapi", "?"))
+    title = str((payload.get("info") or {}).get("title", "?"))
+    info_version = str((payload.get("info") or {}).get("version", "?"))
+    missing = sorted(p for p in REQUIRED_PATHS if p not in paths)
+    if missing:
+        value = f"openapi={openapi};title={title};missing={','.join(missing)}"
+    else:
+        value = f"openapi={openapi};title={title};required-paths=ok"
+    return CanaryObservation(
+        value=value,
+        schema_hash=_canonical_hash(sorted(p for p in REQUIRED_PATHS if p in paths)),
+        upstream_status=result.status,
+        note=(
+            f"spec v{info_version}, {len(paths)} total paths (policy: additions upstream "
+            "are informational; only removal of a load-bearing path alarms)"
+        ),
+    )
+
+
+def _api_contract_remediation(status: CanaryStatus, observed, expected) -> str:
+    if status is CanaryStatus.UNREACHABLE:
+        return (
+            "The Coverage API OpenAPI spec could not be read. No path was observed to "
+            "have moved -- the spec document itself was unavailable. Check "
+            "https://api.coverage.cms.gov/docs/v1/coverage-api.json by hand, then "
+            "re-run `hc-source doctor`."
+        )
+    return (
+        "The CMS Coverage API OpenAPI spec changed in a way that touches a path this "
+        f"adapter calls (observed {observed!r}, pinned {expected!r}). Read "
+        "https://api.coverage.cms.gov/docs/release_notes, re-verify the adapter's "
+        "endpoints against https://api.coverage.cms.gov/docs/v1/coverage-api.json, then "
+        "re-pin with `hc-source lock init`."
+    )
+
+
+def _observe_ncd_anchor() -> CanaryObservation:
+    result = fetch(NCD_DETAIL_URL, params={"ncdid": 11}, raise_for_status=False)
+    # A 5xx must not be pinned or graded as an id-scheme break: the remediation
+    # for that sends a human to rebuild the section->ncdid mapping.
+    _raise_if_transient(result, NCD_DETAIL_URL)
+    if result.status != 200:
+        return CanaryObservation(
+            value=f"invalid-anchor-http-{result.status}",
+            upstream_status=result.status,
+            note="ncdid=11 no longer resolves; the internal document-id scheme may have moved",
+        )
+    payload = result.json()
+    rows = _rows(payload)
+    if not rows:
+        raise SourceUnreachable(NCD_DETAIL_URL, "ncd detail returned no rows for ncdid=11")
+    row = rows[0]
+    value = (
+        f"{row.get('document_display_id')}|{row.get('title')}|{row.get('publication_number')}"
+    )
+    return CanaryObservation(
+        value=value,
+        schema_hash=_canonical_hash(_fields(payload)),
+        upstream_status=result.status,
+        note=(
+            f"document_version {row.get('document_version')} (version bumps are routine "
+            "policy updates and deliberately excluded from the pinned value)"
+        ),
+    )
+
+
+def _ncd_anchor_remediation(status: CanaryStatus, observed, expected) -> str:
+    if status is CanaryStatus.UNREACHABLE:
+        return (
+            "The NCD detail endpoint could not be read. The anchor record was not "
+            "observed this run, so nothing is known about the internal document-id "
+            "scheme: do not rebuild the mapping on the strength of this. Check "
+            "https://api.coverage.cms.gov/docs/release_notes for an outage or a "
+            "planned change, then re-run `hc-source doctor`."
+        )
+    if status is CanaryStatus.SCHEMA_CHANGED:
+        return (
+            "The NCD detail column set changed while the anchor record stayed put. Review "
+            "the new fields, bump TRANSFORM_VERSION in hc_source/adapters/coverage.py if "
+            "the mapping changed, then re-pin with `hc-source lock init`."
+        )
+    return (
+        f"NCD anchor check failed for ncdid=11 (expected NCD 30.3 'Acupuncture', pub "
+        f"100-3; observed {observed!r}). If the id no longer resolves, CMS changed its "
+        "internal document ids: rebuild the section->ncdid mapping from "
+        "/v1/reports/national-coverage-ncd/, re-record the coverage fixtures, and re-pin "
+        "with `hc-source lock init`."
+    )
+
+
+_CONTENT_RANGE_RE = re.compile(r"^bytes \d+-\d+/(\d+)$")
+
+
+def _observe_bulk_export() -> CanaryObservation:
+    result = fetch(NCD_ZIP_URL, headers={"Range": "bytes=0-0"})
+    content_type = result.headers.get("content-type", "?").split(";")[0].strip()
+    size: int | None = None
+    match = _CONTENT_RANGE_RE.match(result.headers.get("content-range", ""))
+    if match:
+        size = int(match.group(1))
+    elif result.headers.get("content-length", "").isdigit():
+        size = int(result.headers["content-length"])
+    low, high = NCD_ZIP_SIZE_BAND
+    if size is not None and low <= size <= high:
+        value = f"{content_type};size-band=ok"
+    else:
+        value = f"{content_type};size={size}"
+    return CanaryObservation(
+        value=value,
+        upstream_status=result.status,
+        note=(
+            f"{size} bytes, last-modified {result.headers.get('last-modified', '?')} "
+            f"(1-byte ranged probe; band {low}-{high})"
+        ),
+    )
+
+
+def _bulk_export_remediation(status: CanaryStatus, observed, expected) -> str:
+    if status is CanaryStatus.UNREACHABLE:
+        return (
+            "The MCD bulk export ncd.zip could not be probed. Re-derive the current "
+            "export links from "
+            "https://www.cms.gov/medicare-coverage-database/downloads/downloads.aspx and "
+            "update the URL table in hc_source/adapters/coverage.py if they moved."
+        )
+    return (
+        f"The MCD bulk export probe changed (observed {observed!r}, pinned {expected!r}). "
+        "If the size left its band, the dataset shape changed: re-download, re-verify "
+        "the CSV inventory, widen NCD_ZIP_SIZE_BAND deliberately, and re-pin with "
+        "`hc-source lock init`."
+    )
+
+
+def _observe_license_gate() -> CanaryObservation:
+    # Deliberately unauthenticated: this canary asserts the AMA/ADA/AHA gate is
+    # still up. It must NEVER fetch a token (fetching one = accepting the license).
+    result = fetch(LCD_DETAIL_URL, params={"lcdid": 33818}, raise_for_status=False)
+    # Transient statuses are unreachability, not a change of posture. Grading a
+    # 503 as drift here fires the remediation below, which tells a human to STOP
+    # and open a CPT-contamination review; the gate never moved.
+    _raise_if_transient(result, LCD_DETAIL_URL)
+    return CanaryObservation(
+        value=str(result.status),
+        upstream_status=result.status,
+        note="unauthenticated LCD detail probe; 401 means the license gate is intact",
+    )
+
+
+def _license_gate_remediation(status: CanaryStatus, observed, expected) -> str:
+    if status is CanaryStatus.UNREACHABLE:
+        # The drift text below tells a human to STOP and open a CPT-contamination
+        # review. It must never be printed for an outage: nothing was observed
+        # about the gate's posture this run.
+        return (
+            "The unauthenticated LCD detail probe could not be read (transient upstream "
+            "failure or transport error). This says nothing about the AMA/ADA/AHA "
+            "license gate and is NOT a reason to open a contamination review. Check "
+            "https://www.cms.gov/medicare-coverage-database/ for outage banners, then "
+            "re-run `hc-source doctor`."
+        )
+    return (
+        f"The Coverage API license gate changed posture (unauthenticated LCD call "
+        f"returned HTTP {observed}, pinned {expected}). If it now returns 200, CMS "
+        "dropped the AMA/ADA/AHA token gate: STOP and re-run the CPT-contamination "
+        "review in the coverage dossier (section 6) before exposing or redistributing "
+        "any newly reachable field, then re-pin with `hc-source lock init`."
+    )
+
+
+def _observe_reference_tables() -> CanaryObservation:
+    result_states, states_payload = fetch_json(STATES_URL, params={"state_id": 6})
+    state_rows = _rows(states_payload)
+    state6 = next((r for r in state_rows if r.get("state_id") == 6), None)
+    state_desc = state6.get("description") if state6 else "absent"
+    _result_types, types_payload = fetch_json(CONTRACT_TYPES_URL)
+    type_ids = sorted(
+        int(r["contract_type_id"])
+        for r in _rows(types_payload)
+        if r.get("contract_type_id") is not None
+    )
+    return CanaryObservation(
+        value=(
+            f"state6={state_desc};contract_types={','.join(str(i) for i in type_ids)}"
+        ),
+        schema_hash=_canonical_hash([_fields(states_payload), _fields(types_payload)]),
+        upstream_status=result_states.status,
+        note="MCD-internal keyspaces backing the jurisdiction joins (state_id is not FIPS)",
+    )
+
+
+def _reference_tables_remediation(status: CanaryStatus, observed, expected) -> str:
+    if status is CanaryStatus.UNREACHABLE:
+        return (
+            "The MCD reference-table endpoints could not be read, so the keyspaces were "
+            "not observed this run. Nothing moved as far as anyone knows: do not "
+            "re-record fixtures on the strength of an outage. Check "
+            "https://www.cms.gov/medicare-coverage-database/ for outage banners, then "
+            "re-run `hc-source doctor`."
+        )
+    return _REFERENCE_TABLES_REMEDIATION
+
+
+_REFERENCE_TABLES_REMEDIATION = (
+    "The MCD reference tables moved (states/contract-types). The jurisdiction-mapping "
+    "keyspace changed and stored contractor->state joins may be silently wrong: "
+    "re-record tests/fixtures/coverage/states.json and contract_types.json from "
+    "/v1/metadata/states/ and /v1/metadata/contract-type/, re-validate STATE_NAMES "
+    "resolution in hc_source/adapters/coverage.py, then re-pin with `hc-source lock init`."
+)
+
+
+class CoverageAdapter(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="coverage.weekly_snapshot",
+                source_id=SOURCE_ID,
+                description=(
+                    "Weekly MCD local-coverage snapshot identity "
+                    "(refreshed_on_date from /v1/metadata/local-data-schedule/)."
+                ),
+                observe=_observe_weekly_snapshot,
+                remediation=(
+                    "CMS published a new weekly MCD snapshot. Review the diff, then "
+                    "re-pin with `hc-source lock init`."
+                ),
+                remediation_for=_weekly_snapshot_remediation,
+            ),
+            Canary(
+                canary_id="coverage.api_contract",
+                source_id=SOURCE_ID,
+                description=(
+                    "Coverage API OpenAPI contract: every load-bearing path stays "
+                    "served (additive growth upstream is informational, never an alarm)."
+                ),
+                observe=_observe_api_contract,
+                remediation=(
+                    "The Coverage API spec dropped a path this adapter calls. Read "
+                    "https://api.coverage.cms.gov/docs/release_notes and re-verify the "
+                    "adapter, then re-pin with `hc-source lock init`."
+                ),
+                remediation_for=_api_contract_remediation,
+            ),
+            Canary(
+                canary_id="coverage.ncd_anchor",
+                source_id=SOURCE_ID,
+                description=(
+                    "NCD anchor-record integrity: ncdid=11 must still be NCD 30.3 "
+                    "'Acupuncture' (internal-id scheme stability)."
+                ),
+                observe=_observe_ncd_anchor,
+                remediation=(
+                    "The NCD anchor moved. Rebuild the section->ncdid mapping from "
+                    "/v1/reports/national-coverage-ncd/ and re-pin with "
+                    "`hc-source lock init`."
+                ),
+                remediation_for=_ncd_anchor_remediation,
+            ),
+            Canary(
+                canary_id="coverage.bulk_export",
+                source_id=SOURCE_ID,
+                description=(
+                    "MCD bulk export availability: 1-byte ranged probe of ncd.zip "
+                    "(content type + size band; no full download)."
+                ),
+                observe=_observe_bulk_export,
+                remediation=(
+                    "The MCD bulk export probe failed. Re-derive export URLs from the "
+                    "MCD downloads page and re-pin with `hc-source lock init`."
+                ),
+                remediation_for=_bulk_export_remediation,
+            ),
+            Canary(
+                canary_id="coverage.license_gate",
+                source_id=SOURCE_ID,
+                description=(
+                    "AMA/ADA/AHA license-gate posture: an unauthenticated LCD detail "
+                    "call must return HTTP 401. Never mints a token."
+                ),
+                observe=_observe_license_gate,
+                remediation=(
+                    "The Coverage API license gate changed posture. Re-run the "
+                    "CPT-contamination review before shipping any behavior change, then "
+                    "re-pin with `hc-source lock init`."
+                ),
+                remediation_for=_license_gate_remediation,
+            ),
+            Canary(
+                canary_id="coverage.reference_tables",
+                source_id=SOURCE_ID,
+                description=(
+                    "MCD-internal reference keyspaces: state 6 stays 'California - "
+                    "Entire State' and contract types stay exactly ids 8-13."
+                ),
+                observe=_observe_reference_tables,
+                remediation=_REFERENCE_TABLES_REMEDIATION,
+                remediation_for=_reference_tables_remediation,
+            ),
+        ]
+
+    def tools(self) -> list[ToolSpec]:
+        return [
+            ToolSpec(
+                name="coverage.snapshot",
+                description=(
+                    "Return the current weekly MCD local-coverage snapshot identity "
+                    "(data_captured_through / refreshed_on_date)."
+                ),
+                params_model=NoParams,
+                handler=_snapshot,
+                tags=("metadata",),
+            ),
+            ToolSpec(
+                name="coverage.lookup_ncd",
+                description=(
+                    "Look up a National Coverage Determination by manual section "
+                    "number (e.g. 30.3); narrative is withheld when the NCD flags "
+                    "licensed AMA CPT content."
+                ),
+                params_model=LookupNcdParams,
+                handler=_lookup_ncd,
+                tags=("lookup",),
+            ),
+            ToolSpec(
+                name="coverage.lookup_lcd",
+                description=(
+                    "Look up a Local Coverage Determination by L-number in the current "
+                    "weekly snapshot, jurisdiction-aware via an optional state filter."
+                ),
+                params_model=LookupLcdParams,
+                handler=_lookup_lcd,
+                tags=("lookup",),
+            ),
+            ToolSpec(
+                name="coverage.companion_articles",
+                description=(
+                    "Resolve an LCD's companion Billing-and-Coding Article(s) via the "
+                    "LCD<->Article crosswalk (keyless bulk export, or the live endpoint "
+                    "under an operator-supplied license token)."
+                ),
+                params_model=CompanionArticlesParams,
+                handler=_companion_articles,
+                tags=("lookup",),
+            ),
+            ToolSpec(
+                name="coverage.search_documents",
+                description=(
+                    "Search NCD/LCD/Article titles by keyword in the current release, "
+                    "with state/contractor/status filters for local documents."
+                ),
+                params_model=SearchDocumentsParams,
+                handler=_search_documents,
+                tags=("search",),
+            ),
+            ToolSpec(
+                name="coverage.whats_changed",
+                description=(
+                    "What changed in Medicare coverage policy over the last N days, "
+                    "from the MCD whats-new feeds (local weekly snapshot or national "
+                    "event stream)."
+                ),
+                params_model=WhatsChangedParams,
+                handler=_whats_changed,
+                tags=("changes",),
+            ),
+        ]
+
+
+ADAPTER = CoverageAdapter()