sourcelock 0.1.0__py3-none-any.whl

hc_source/adapters/leie.py

@@ -0,0 +1,1310 @@
+"""OIG LEIE (List of Excluded Individuals/Entities) route adapter.
+
+Source
+------
+The authority is the monthly full database CSV at
+``https://oig.hhs.gov/exclusions/downloadables/UPDATED.csv`` (~15.5 MB,
+~84k records, replaced in place by the 10th of each month; the data month is
+the month before the file's ``Last-Modified``). There is no API and OIG states
+there are no plans for one; file downloads are the only machine interface.
+The working table is built at call time from that file and cached in-process,
+then revalidated on the ``SNAPSHOT_REVALIDATE_AFTER`` cadence against the
+upstream ``Last-Modified``; nothing about the full file is vendored except a
+14-row sample (``_leie_sample.csv``, provenance in
+``tests/fixtures/leie/provenance.json``).
+
+Fail-closed answers
+-------------------
+An exclusion screen has one dangerous direction: reporting a person clear.
+Two conditions make a negative answer unearned, and in both the tools answer
+``screen_result: "indeterminate"`` rather than a miss, omit the field a caller
+would read as a verdict (``excluded_in_snapshot``, ``count``), and add a
+non-claim naming the gap:
+
+* any row the CSV parser could not read (``MAX_UNPARSED_ROWS``) — that row was
+  never compared, so "not found" is not a finding;
+* a matched record carrying a REINDATE. OIG removes reinstated parties from
+  the full file rather than dating them, so a populated one means the file no
+  longer means what this adapter was built against. The date is surfaced and
+  neither "excluded" nor "not excluded" is claimed; there are no reinstatement
+  semantics here to claim either with.
+
+Verified file facts (empirical, 2026-08-01; dossier addendum §10)
+-----------------------------------------------------------------
+* Pure 7-bit ASCII, no BOM, CRLF line endings — across UPDATED.csv and the
+  monthly supplements. The parser decodes ``utf-8-sig`` and falls back to
+  ``latin-1`` with a receipt warning rather than crash on a future stray byte.
+* Two CSV stylings exist: fully-quoted with ``00000000`` date-nulls
+  (UPDATED.csv, current supplements) and unquoted with bare ``0`` nulls for
+  dates AND NPIs (older supplements, e.g. 2501excl.csv). Null normalisation
+  treats ``""``/``"0"``/``"00000000"`` (dates) and ``""``/``"0"``/
+  ``"0000000000"`` (NPI) as null.
+* Drift is keyed on a canonicalised content hash (parsed rows, nulls
+  normalised, order-independent), never on raw bytes, so an in-place repost
+  or a styling change alone never cries wolf. Receipts still carry the raw
+  ``sha256`` of the exact bytes fetched.
+
+Matching contract (v1 decision)
+-------------------------------
+``leie.check_npi`` is the deterministic primary tool: NPI-exact against the
+snapshot. Only ~10.5% of LEIE records carry an NPI, so an NPI miss never
+clears a provider. ``leie.candidate_search`` is name-based and explicitly
+candidate-only: the bulk file has no SSN/EIN (Privacy Act), so identity is
+verified only by a human at ``https://exclusions.oig.hhs.gov/`` (OIG's own
+doctrine). Every tool also carries the state-exclusion-list non-claim: the
+LEIE is federal; state Medicaid exclusion lists are separate and unchecked.
+
+Zero-PHI posture
+----------------
+Exclusion records are public, but DOB and street ADDRESS are excluded from
+every tool result (identity confirmation happens at OIG's site anyway), and
+the vendored sample/fixtures contain no real-person DOB.
+
+Offline-harness floor
+---------------------
+The shared test suite runs every adapter's canaries with sockets blocked
+(the blocker raises a plain ``RuntimeError``, which is not a transport
+failure). Canaries therefore catch that one case and observe the packaged
+sample instead, with self-describing ``sample:*`` values, so an
+offline ``lock init``/``doctor`` is green and honest. Real transport
+failures surface as :class:`SourceUnreachable` and still report
+``unreachable``. Tools never take this fallback: a compliance answer must
+never come from a 14-row sample.
+
+Deviation from the dossier's canary plan: C3 (newest-supplement presence
+probe) is not shipped as a canary because it has no offline-observable
+equivalent under the shared no-network suite; its freshness question is
+answered by ``leie.refresh_status`` and the ``leie.full_file`` staleness
+check instead.
+"""
+
+from __future__ import annotations
+
+import csv
+import hashlib
+import json
+import os
+import time
+from dataclasses import dataclass, replace
+from datetime import date, datetime, timedelta, timezone
+from email.utils import parsedate_to_datetime
+from pathlib import Path
+from typing import Mapping
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from ..http import FetchResult, SourceUnreachable, as_cache_hit, fetch
+from ..interfaces import Canary, CanaryObservation, SourceAdapter, ToolResult, ToolSpec
+from ..npi import NPI_PATTERN, validate_npi
+from ..receipts import build_receipt
+from ..schemas import CanarySeverity, CanaryStatus, SourceContract
+
+SOURCE_ID = "leie"
+#: 2: answers became fail-closed. Tool results gained ``screen_result`` and
+#: ``snapshot_complete``, records gained ``reinstatement_date``, and the two
+#: cases that used to answer negatively without having screened — unparsed rows,
+#: a populated REINDATE — now answer ``indeterminate``.
+TRANSFORM_VERSION = "2"
+
+AUTHORITY_URL = "https://oig.hhs.gov/exclusions/downloadables/UPDATED.csv"
+HUB_URL = "https://oig.hhs.gov/exclusions/leie-database-supplement-downloads/"
+WAIVERS_URL = "https://oig.hhs.gov/exclusions/waivers/"
+VERIFICATION_URL = "https://exclusions.oig.hhs.gov/"
+QUICK_TIPS_URL = "https://oig.hhs.gov/exclusions/leie-quick-tips-instructions/"
+RECORD_LAYOUT_URL = "https://oig.hhs.gov/exclusions/files/leie_record_layout.pdf"
+
+#: Override the full-file location (any URL, including file://) — tests, mirrors.
+FULL_FILE_ENV_VAR = "HC_SOURCE_LEIE_FULL_FILE"
+#: Override the waivers-page location — tests.
+WAIVERS_ENV_VAR = "HC_SOURCE_LEIE_WAIVERS_URL"
+#: Freeze "today" (ISO date) so freshness checks are testable.
+TODAY_ENV_VAR = "HC_SOURCE_LEIE_TODAY"
+
+MIN_EXPECTED_RECORDS = 70_000
+MAX_EXPECTED_RECORDS = 110_000
+MIN_EXPECTED_BYTES = 8_000_000
+MAX_EXPECTED_BYTES = 40_000_000
+STALE_AFTER_DAYS = 45
+MAX_CANDIDATES = 25
+
+#: How many rows the CSV parser may fail to read before an answer stops being a
+#: screen. Zero on purpose. A row whose field count does not match the header is
+#: a row nobody compared the subject against, and the old behaviour -- count it,
+#: skip it, answer anyway -- turned an excluded party sitting in a malformed row
+#: into a clean "not found". A miss is the dangerous direction on an exclusion
+#: list, so any unparsed row makes a miss indeterminate rather than negative.
+MAX_UNPARSED_ROWS = 0
+
+EXPECTED_COLUMNS = (
+    "LASTNAME", "FIRSTNAME", "MIDNAME", "BUSNAME", "GENERAL", "SPECIALTY",
+    "UPIN", "NPI", "DOB", "ADDRESS", "CITY", "STATE", "ZIP",
+    "EXCLTYPE", "EXCLDATE", "REINDATE", "WAIVERDATE", "WVRSTATE",
+)
+#: The record-layout PDF spells the last column WAIVERSTATE; the CSV says
+#: WVRSTATE. Parse by the CSV header, accept either spelling.
+_WVRSTATE_ALIASES = {"WVRSTATE", "WAIVERSTATE"}
+
+DATE_COLUMNS = ("DOB", "EXCLDATE", "REINDATE", "WAIVERDATE")
+_NULL_DATES = {"", "0", "00000000"}
+_NULL_NPIS = {"", "0", "0000000000"}
+
+#: EXCLTYPE domain observed in the 2026-07-10 full file. Opaque tokens: mixed
+#: case and embedded spaces are real — exact-match, never regex-parse.
+KNOWN_EXCLTYPES = frozenset({
+    "1128a1", "1128a2", "1128a3", "1128a4", "1128Aa",
+    "1128b1", "1128b2", "1128b3", "1128b4", "1128b5", "1128b6", "1128b7",
+    "1128b8", "1128b11", "1128b12", "1128b14", "1128b15", "1128b16",
+    "1156", "1160", "BRCH SA", "BRCH CIA",
+})
+
+CONTRACT = SourceContract(
+    source_id=SOURCE_ID,
+    authority_url=AUTHORITY_URL,
+    fallback_url=None,
+    license_notes=(
+        "US federal public-domain data; keyless anonymous download, no license or "
+        "click-through. SSNs/EINs are deliberately excluded from the file (Privacy Act), "
+        "so a bulk-file hit is never identity-verified — verification happens at "
+        "https://exclusions.oig.hhs.gov/. Contains no AMA CPT content. Redistribution "
+        "obligation: preserve the candidate-only framing of name matches."
+    ),
+    cadence="monthly (updated by the 10th; contains exclusions through the end of the prior month)",
+    effective_date_semantics=(
+        "For record-level answers effective_from is the record's EXCLDATE — the "
+        "exclusion's legal effective date, which may postdate the file's data month. "
+        "For file-level answers effective_from is the snapshot's Last-Modified date. "
+        "effective_to is always open: an exclusion ends only by reinstatement, which "
+        "REMOVES the record from the next monthly full file."
+    ),
+    invariants=[
+        "the CSV header is exactly the locked 18 columns ending in WVRSTATE",
+        "full-file record count stays within 70,000–110,000",
+        "REINDATE is null for every record in the full file (reinstated people are removed)",
+        "NPI is a placeholder (0000000000/0/blank) on ~89.5% of records",
+        "the file is plain ASCII CSV; no SSN or EIN column exists",
+    ],
+)
+
+# ---------------------------------------------------------------------------
+# Non-claims (stable keys; reviewers read these)
+# ---------------------------------------------------------------------------
+
+NC_STATE = (
+    "DOES_NOT_COVER_STATE_EXCLUSIONS: the LEIE is the federal OIG exclusion list only; "
+    "state Medicaid exclusion and termination lists are separate and are not checked "
+    "here — an LEIE miss does not mean the provider is excluded nowhere."
+)
+NC_CURRENCY = (
+    "DOES_NOT_PROVE_CURRENCY: this answer comes from the monthly LEIE full-file "
+    "snapshot (replaced by the 10th of each month, data through the end of the prior "
+    "month) and may lag OIG actions by up to a month."
+)
+NC_HISTORY = (
+    "DOES_NOT_PROVE_NEVER_EXCLUDED: reinstated individuals are removed from the "
+    "monthly full file; absence from the current snapshot says nothing about past "
+    "exclusions."
+)
+NC_NPI_COVERAGE = (
+    "DOES_NOT_CLEAR_ON_NPI_MISS: ~89.5% of LEIE records carry no NPI, so an NPI-exact "
+    "miss does not clear a provider — run leie.candidate_search and verify identity at "
+    "the official OIG online workflow: https://exclusions.oig.hhs.gov/."
+)
+NC_CANDIDATE = (
+    "NOT_IDENTITY_VERIFICATION: candidate match is NOT identity verification — the "
+    "bulk file lacks SSN/EIN (~10.5% of records have NPI); verify at the official OIG "
+    "online workflow: https://exclusions.oig.hhs.gov/."
+)
+NC_UNPARSED = (
+    "DID_NOT_SCREEN_THE_WHOLE_LIST: part of the snapshot could not be parsed, so rows "
+    "that may name this subject were never compared. Any absence of a match here is "
+    "indeterminate, not clearance — re-run once the file parses cleanly, and verify at "
+    "https://exclusions.oig.hhs.gov/."
+)
+NC_REINSTATEMENT = (
+    "DOES_NOT_IMPLEMENT_REINSTATEMENT: a matched record carries a reinstatement date. "
+    "OIG removes reinstated parties from the monthly full file, so a record that has "
+    "one means the file no longer behaves the way this adapter was built against. "
+    "SourceLock implements no reinstatement semantics and will not call such a record "
+    "excluded or not excluded — resolve it at https://exclusions.oig.hhs.gov/."
+)
+
+CHECK_NPI_NON_CLAIMS = [NC_STATE, NC_CURRENCY, NC_HISTORY, NC_NPI_COVERAGE]
+CANDIDATE_NON_CLAIMS = [NC_CANDIDATE, NC_STATE, NC_CURRENCY, NC_HISTORY]
+REFRESH_NON_CLAIMS = [NC_STATE, NC_CURRENCY, NC_HISTORY]
+
+CADENCE_TEXT = (
+    "monthly; OIG updates all exclusion information by the 10th of every month, and "
+    "the data month is the month before the file's Last-Modified date"
+)
+RETENTION_TEXT = (
+    "OIG archives monthly supplement files for only the previous 12 months; older "
+    "supplements are not available upstream. Archive supplements yourself, or "
+    "re-baseline from UPDATED.csv when history is lost."
+)
+
+# ---------------------------------------------------------------------------
+# Snapshot loading (the runtime working table)
+# ---------------------------------------------------------------------------
+
+
+def sample_path() -> Path:
+    """The packaged 14-row sample (DOB-scrubbed; never served by tools)."""
+    return Path(__file__).with_name("_leie_sample.csv")
+
+
+def _sample_uri() -> str:
+    return sample_path().as_uri()
+
+
+def _full_file_url() -> str:
+    return os.environ.get(FULL_FILE_ENV_VAR) or AUTHORITY_URL
+
+
+def _waivers_url() -> str:
+    return os.environ.get(WAIVERS_ENV_VAR) or WAIVERS_URL
+
+
+def _today() -> date:
+    override = os.environ.get(TODAY_ENV_VAR)
+    return date.fromisoformat(override) if override else date.today()
+
+
+@dataclass(frozen=True)
+class _Snapshot:
+    fetch_meta: FetchResult          # content stripped; provenance for receipts
+    from_sample: bool
+    source_version: str
+    last_modified: datetime | None
+    data_month: str | None
+    columns: tuple[str, ...]
+    records: tuple[Mapping[str, str], ...]
+    npi_index: Mapping[str, tuple[int, ...]]
+    canonical_hash: str
+    schema_hash: str
+    reindate_populated: int
+    unknown_excltypes: tuple[str, ...]
+    parse_warnings: tuple[str, ...]
+    malformed_rows: int
+
+
+@dataclass(frozen=True)
+class _CacheEntry:
+    """One cached snapshot plus what we know about how current it is."""
+
+    snapshot: _Snapshot
+    #: Monotonic mark of the last revalidation ATTEMPT, successful or not. This
+    #: is what throttles retries, so a source that is down is probed once per
+    #: cadence instead of on every tool call.
+    checked_at: float
+    #: Monotonic mark of the last time upstream actually answered — either these
+    #: bytes were read, or a probe confirmed upstream had not moved.
+    verified_at: float
+    #: Warnings about the entry itself (a failed revalidation), as opposed to
+    #: the snapshot's own parse warnings.
+    warnings: tuple[str, ...] = ()
+    #: True when THIS hand-out came out of the in-process cache rather than off
+    #: the wire. Set on the copy that is returned, never on the stored entry:
+    #: the first hand-out of a freshly downloaded snapshot is not a cache hit,
+    #: and every one after it is.
+    reused: bool = False
+    #: Wall-clock moment upstream last confirmed these bytes are still current
+    #: -- a probe whose Last-Modified or hash matched. ``None`` means no probe
+    #: has ever confirmed them, so the fetch's own stamp stands. Never advanced
+    #: by a reuse that contacted nobody: "still current as of a moment ago" and
+    #: "still what we downloaded on Tuesday" are different claims.
+    confirmed_at: datetime | None = None
+    #: True when revalidation FAILED and this snapshot is being served anyway.
+    stale: bool = False
+
+    def fetch_meta(self) -> FetchResult:
+        """Provenance for a receipt built from this hand-out.
+
+        The receipt's ``cache_hit`` used to come straight off the original
+        FetchResult, so an answer computed from a snapshot downloaded twenty
+        minutes ago said ``cache_hit: false`` in its structured field while the
+        warning above it said it came from an in-process cache. A machine
+        reading the receipt believes the field.
+        """
+        meta = self.snapshot.fetch_meta
+        if not self.reused:
+            return meta
+        if self.confirmed_at is not None:
+            return as_cache_hit(meta, revalidated_at=self.confirmed_at)
+        return as_cache_hit(meta)
+
+
+_SNAPSHOT_CACHE: dict[str, _CacheEntry] = {}
+
+
+def clear_cache() -> None:
+    _SNAPSHOT_CACHE.clear()
+
+
+def _schema_hash(columns: list[str] | tuple[str, ...]) -> str:
+    shape = json.dumps(list(columns), separators=(",", ":"))
+    return hashlib.sha256(shape.encode("utf-8")).hexdigest()
+
+
+def _decode(content: bytes) -> tuple[str, list[str]]:
+    try:
+        return content.decode("utf-8-sig"), []
+    except UnicodeDecodeError:
+        return content.decode("latin-1"), [
+            "full file contained non-UTF-8 bytes and was decoded as latin-1; upstream "
+            "was pure ASCII when last verified (2026-08-01) — review the raw file."
+        ]
+
+
+def _canonical_row(rec: Mapping[str, str]) -> str:
+    parts = []
+    for col in EXPECTED_COLUMNS:
+        v = rec.get(col, "").strip()
+        if col in DATE_COLUMNS and v in _NULL_DATES:
+            v = ""
+        elif col == "NPI" and v in _NULL_NPIS:
+            v = ""
+        parts.append(v)
+    return "\x1f".join(parts)
+
+
+def _parse_last_modified(headers: Mapping[str, str]) -> datetime | None:
+    raw = headers.get("last-modified")
+    if not raw:
+        return None
+    try:
+        return parsedate_to_datetime(raw)
+    except (TypeError, ValueError):
+        return None
+
+
+def _data_month(lm_date: date) -> str:
+    year, month = lm_date.year, lm_date.month - 1
+    if month == 0:
+        year, month = year - 1, 12
+    return f"{year}-{month:02d}"
+
+
+def _parse_snapshot(result: FetchResult, *, expect_full: bool, from_sample: bool) -> _Snapshot:
+    text, warnings = _decode(result.content)
+    rows = list(csv.reader(text.splitlines()))
+    if not rows:
+        raise SourceUnreachable(result.url, "full file is empty")
+
+    header = [h.strip() for h in rows[0]]
+    lookup: dict[str, int] = {}
+    for idx, name in enumerate(header):
+        canonical = "WVRSTATE" if name in _WVRSTATE_ALIASES else name
+        lookup.setdefault(canonical, idx)
+    missing = [c for c in EXPECTED_COLUMNS if c not in lookup]
+    if missing:
+        raise SourceUnreachable(
+            result.url,
+            f"column layout changed: missing column(s) {missing}; fetch the current "
+            f"record layout from {RECORD_LAYOUT_URL} and update the adapter",
+        )
+    if tuple(header) != EXPECTED_COLUMNS:
+        warnings.append(f"header differs from the locked layout: {header}")
+
+    records: list[dict[str, str]] = []
+    malformed = 0
+    for row in rows[1:]:
+        if not row:
+            continue
+        if len(row) != len(header):
+            malformed += 1
+            continue
+        records.append({c: row[lookup[c]].strip() for c in EXPECTED_COLUMNS})
+    if malformed:
+        warnings.append(
+            f"{malformed} row(s) did not match the header's field count and could not "
+            "be parsed; the subjects named in them were never compared"
+        )
+
+    count = len(records)
+    if expect_full and not (MIN_EXPECTED_RECORDS <= count <= MAX_EXPECTED_RECORDS):
+        raise SourceUnreachable(
+            result.url,
+            f"record count {count} outside the sanity band "
+            f"[{MIN_EXPECTED_RECORDS}, {MAX_EXPECTED_RECORDS}] — treating the download "
+            "as truncated or corrupt; keep the prior snapshot and retry in 24h",
+        )
+
+    npi_index: dict[str, tuple[int, ...]] = {}
+    for j, rec in enumerate(records):
+        npi = rec["NPI"]
+        if npi not in _NULL_NPIS:
+            npi_index[npi] = npi_index.get(npi, ()) + (j,)
+
+    canonical = hashlib.sha256(
+        "\n".join(sorted(_canonical_row(r) for r in records)).encode("utf-8")
+    ).hexdigest()
+
+    lm = _parse_last_modified(result.headers)
+    if from_sample:
+        source_version = f"sample:{canonical[:8]}"
+    elif lm is not None:
+        source_version = lm.date().isoformat()
+    else:
+        source_version = f"canonical:{canonical[:12]}"
+
+    return _Snapshot(
+        fetch_meta=replace(result, content=b""),
+        from_sample=from_sample,
+        source_version=source_version,
+        last_modified=lm,
+        data_month=_data_month(lm.date()) if lm else None,
+        columns=tuple(header),
+        records=tuple(records),
+        npi_index=npi_index,
+        canonical_hash=canonical,
+        schema_hash=_schema_hash(header),
+        reindate_populated=sum(1 for r in records if r["REINDATE"] not in _NULL_DATES),
+        unknown_excltypes=tuple(sorted({r["EXCLTYPE"] for r in records} - KNOWN_EXCLTYPES)),
+        parse_warnings=tuple(warnings),
+        malformed_rows=malformed,
+    )
+
+
+#: The LEIE full file measured 14.8 MB on 2026-08-01 and grows monotonically as
+#: exclusions accumulate. 64 MiB is roughly 4x that: enough headroom for years
+#: of growth, tight enough that a hostile or broken mirror cannot hand this
+#: process an unbounded body. Raising it is a deliberate act, not a default.
+LEIE_MAX_BYTES = 64 * 1024 * 1024
+
+
+#: How long a cached snapshot may be served before upstream is asked whether it
+#: moved. OIG replaces UPDATED.csv by the 10th of every month, but not on a
+#: fixed day, and NC_CURRENCY promises callers a lag of at most a month. The
+#: cache used to have no expiry at all, so a long-lived process (the MCP server)
+#: pinned the first snapshot it ever read and kept printing that promise —
+#: after two publication cycles the promise was simply false. One day is the
+#: interval that keeps it true with margin: a month-long interval would let a
+#: server answer from a file two releases old and still be "within cadence",
+#: and the check costs one ~2 KB ranged GET per day per process.
+SNAPSHOT_REVALIDATE_AFTER = timedelta(days=1)
+
+
+def _monotonic() -> float:
+    """Elapsed-time clock for the cache. Monotonic, so a wall-clock jump or an
+    NTP correction can neither expire a fresh snapshot nor freeze a stale one."""
+    return time.monotonic()
+
+
+def _load_snapshot(url: str, *, from_sample: bool) -> _Snapshot:
+    """Read and parse the full file. Always goes upstream; caching is _cached_entry's job."""
+    result = fetch(url, max_bytes=LEIE_MAX_BYTES)
+    return _parse_snapshot(result, expect_full=not from_sample, from_sample=from_sample)
+
+
+def _store(url: str, snapshot: _Snapshot) -> _CacheEntry:
+    mark = _monotonic()
+    entry = _CacheEntry(snapshot=snapshot, checked_at=mark, verified_at=mark)
+    # One dict assignment, after the new snapshot is fully parsed. A reader
+    # concurrent with a revalidation sees either the whole old entry or the
+    # whole new one, never a half-swapped table.
+    _SNAPSHOT_CACHE[url] = entry
+    return entry
+
+
+def _confirm(url: str, entry: _CacheEntry) -> _CacheEntry:
+    """Upstream had not moved. Keep the bytes — and their retrieval stamp.
+
+    Nothing was re-read here, so re-stamping ``retrieved_at`` would put a read
+    that never happened on every receipt these bytes go on to support.
+    ``confirmed_at`` is the field that DOES move: upstream really did just say
+    these bytes are current, and that is the one thing this branch establishes.
+    """
+    mark = _monotonic()
+    confirmed = replace(
+        entry,
+        checked_at=mark,
+        verified_at=mark,
+        warnings=(),
+        reused=True,
+        stale=False,
+        confirmed_at=datetime.now(timezone.utc),
+    )
+    _SNAPSHOT_CACHE[url] = confirmed
+    return confirmed
+
+
+def _keep_stale(url: str, entry: _CacheEntry, reason: str) -> _CacheEntry:
+    """Revalidation failed. Serve the old snapshot and say how old it is.
+
+    Discarding a good snapshot because the network blinked would turn a
+    transient outage into no answer at all; pretending it is current would be
+    worse. The warning names the retrieval stamp so the caller can price it.
+    """
+    confirmed = entry.confirmed_at or entry.snapshot.fetch_meta.revalidated_at
+    warning = (
+        f"STALE: LEIE snapshot could not be revalidated ({reason}); still serving the "
+        f"snapshot retrieved {entry.snapshot.fetch_meta.retrieved_at.isoformat()} "
+        f"(source_version {entry.snapshot.source_version}), last confirmed current by "
+        f"upstream {confirmed.isoformat() if confirmed else 'never'}. The receipt's "
+        f"cache_hit and revalidated_at say the same thing in machine-readable form. "
+        f"This answer is that old — OIG republishes monthly, so re-check {HUB_URL} if "
+        "the outage persists."
+    )
+    stale = replace(
+        entry, checked_at=_monotonic(), warnings=(warning,), reused=True, stale=True
+    )
+    _SNAPSHOT_CACHE[url] = stale
+    return stale
+
+
+def _revalidate(url: str, entry: _CacheEntry) -> _CacheEntry:
+    try:
+        probe = _probe(url)
+        cached_lm = entry.snapshot.last_modified
+        probe_lm = _parse_last_modified(probe.headers)
+        if cached_lm is not None and probe_lm is not None and probe_lm == cached_lm:
+            return _confirm(url, entry)
+        if _content_range_total(probe.headers) is None and probe.sha256 == entry.snapshot.fetch_meta.sha256:
+            # No Content-Range means the probe body IS the whole body (a file://
+            # mirror, or a server that ignored the Range header), so its hash is
+            # comparable to the full-file hash on the receipt. Same bytes, no
+            # re-parse. Never compare a 206's hash: that is 2 KB, not the file.
+            return _confirm(url, entry)
+        snapshot = _load_snapshot(url, from_sample=False)
+    except SourceUnreachable as exc:
+        return _keep_stale(url, entry, exc.reason)
+    except RuntimeError as exc:
+        # The offline harness's socket blocker raises a plain RuntimeError. It
+        # is not a transport failure, but for a cached snapshot the handling is
+        # the same: keep what we have and say it was not rechecked.
+        return _keep_stale(url, entry, type(exc).__name__)
+    return _store(url, snapshot)
+
+
+def _cached_entry(*, from_sample: bool = False) -> _CacheEntry:
+    url = _sample_uri() if from_sample else _full_file_url()
+    entry = _SNAPSHOT_CACHE.get(url)
+    if entry is None:
+        return _store(url, _load_snapshot(url, from_sample=from_sample))
+    if from_sample:
+        # The packaged sample ships inside this process. It has no upstream to
+        # have moved, so revalidating it would only spend a fetch.
+        return replace(entry, reused=True)
+    if _monotonic() - entry.checked_at < SNAPSHOT_REVALIDATE_AFTER.total_seconds():
+        # Inside the revalidation window: reuse, and say so. Nobody was
+        # contacted, so `confirmed_at` stays where it was.
+        return replace(entry, reused=True)
+    return _revalidate(url, entry)
+
+
+def _cached_snapshot(*, from_sample: bool = False) -> _Snapshot:
+    return _cached_entry(from_sample=from_sample).snapshot
+
+
+def _probe(url: str | None = None) -> FetchResult:
+    """One cheap ranged GET of the full-file URL (headers + first ~2 KB)."""
+    return fetch(url or _full_file_url(), headers={"Range": "bytes=0-2047"})
+
+
+# ---------------------------------------------------------------------------
+# Typed public parameters
+# ---------------------------------------------------------------------------
+
+
+class NoParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class CheckNpiParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    npi: str = Field(
+        pattern=NPI_PATTERN,
+        description="10-digit NPI to check against the LEIE full-file snapshot.",
+    )
+
+    @field_validator("npi")
+    @classmethod
+    def _real_npi(cls, v: str) -> str:
+        # The placeholder check runs first because it fails the Luhn too, and
+        # "you passed the LEIE's no-NPI sentinel" is the diagnosis the caller
+        # needs; "check digit failed" would send them looking for a typo.
+        if v == "0000000000":
+            raise ValueError(
+                "0000000000 is the LEIE placeholder for 'no NPI on record', not a real NPI"
+            )
+        # Shape is not validity. Ten digits that cannot be an NPI used to reach
+        # the snapshot and come back as a confident miss on a number that does
+        # not exist, which is exactly the false clearance this adapter must not
+        # produce. hc_source.npi is the one validator; provider uses it too.
+        return validate_npi(v)
+
+
+_NAME_PATTERN = r"^[A-Za-z0-9][A-Za-z0-9 .,'&#\-]*$"
+
+
+class CandidateSearchParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    last_name: str | None = Field(
+        default=None, min_length=2, max_length=30, pattern=_NAME_PATTERN,
+        description="Individual's last name, matched exactly (case-insensitive).",
+    )
+    first_name: str | None = Field(
+        default=None, min_length=1, max_length=20, pattern=_NAME_PATTERN,
+        description="Optional first-name prefix filter; requires last_name.",
+    )
+    business_name: str | None = Field(
+        default=None, min_length=2, max_length=40, pattern=_NAME_PATTERN,
+        description="Entity name fragment, matched as a case-insensitive substring.",
+    )
+    state: str | None = Field(
+        default=None, pattern=r"^[A-Za-z]{2}$",
+        description="Two-letter address-state filter as it appears in the file.",
+    )
+
+    @field_validator("state")
+    @classmethod
+    def _upper(cls, v: str | None) -> str | None:
+        return v.upper() if v else v
+
+    @model_validator(mode="after")
+    def _exactly_one_subject(self) -> "CandidateSearchParams":
+        if bool(self.last_name) == bool(self.business_name):
+            raise ValueError(
+                "provide exactly one of last_name (individuals) or business_name (entities)"
+            )
+        if self.first_name and not self.last_name:
+            raise ValueError("first_name only narrows a last_name search")
+        return self
+
+
+# ---------------------------------------------------------------------------
+# Record projection (public fields only: no DOB, no street address)
+# ---------------------------------------------------------------------------
+
+
+def _iso_date(v: str) -> str | None:
+    if v in _NULL_DATES:
+        return None
+    if len(v) == 8 and v.isdigit():
+        try:
+            return date(int(v[:4]), int(v[4:6]), int(v[6:8])).isoformat()
+        except ValueError:
+            return v
+    return v
+
+
+def _record_effective(rec: Mapping[str, str]) -> date | None:
+    iso = _iso_date(rec["EXCLDATE"])
+    try:
+        return date.fromisoformat(iso) if iso else None
+    except ValueError:
+        return None
+
+
+def _public_record(rec: Mapping[str, str]) -> dict[str, object]:
+    waiver = None
+    if rec["WAIVERDATE"] not in _NULL_DATES:
+        waiver = {"date": _iso_date(rec["WAIVERDATE"]), "state": rec["WVRSTATE"] or None}
+    return {
+        "record_type": "entity" if rec["BUSNAME"] else "individual",
+        "last_name": rec["LASTNAME"] or None,
+        "first_name": rec["FIRSTNAME"] or None,
+        "mid_name": rec["MIDNAME"] or None,
+        "business_name": rec["BUSNAME"] or None,
+        "general": rec["GENERAL"] or None,
+        "specialty": rec["SPECIALTY"] or None,
+        "upin": rec["UPIN"] or None,
+        "npi": rec["NPI"] if rec["NPI"] not in _NULL_NPIS else None,
+        "city": rec["CITY"] or None,
+        "state": rec["STATE"] or None,
+        "zip": rec["ZIP"] or None,
+        "excltype": rec["EXCLTYPE"],
+        "exclusion_date": _iso_date(rec["EXCLDATE"]),
+        # Null on every record in a well-formed full file: OIG removes
+        # reinstated parties rather than dating them. Surfaced anyway, because
+        # the day it is not null the caller needs to see the date, not a verdict
+        # this adapter has no semantics for.
+        "reinstatement_date": _iso_date(rec["REINDATE"]),
+        "waiver": waiver,
+    }
+
+
+def _norm(value: str) -> str:
+    return " ".join(value.split()).casefold()
+
+
+# ---------------------------------------------------------------------------
+# Handlers
+# ---------------------------------------------------------------------------
+
+
+def _snapshot_date(snapshot: _Snapshot) -> date | None:
+    return snapshot.last_modified.date() if snapshot.last_modified else None
+
+
+def _check_npi(params: CheckNpiParams) -> ToolResult:
+    entry = _cached_entry()
+    snapshot = entry.snapshot
+    warnings = list(snapshot.parse_warnings) + list(entry.warnings)
+    non_claims = list(CHECK_NPI_NON_CLAIMS)
+
+    unparsed = snapshot.malformed_rows > MAX_UNPARSED_ROWS
+    if unparsed:
+        non_claims.append(NC_UNPARSED)
+
+    indices = snapshot.npi_index.get(params.npi, ())
+    records = [_public_record(snapshot.records[j]) for j in indices]
+    reinstated = [r for r in records if r["reinstatement_date"]]
+
+    # Everything a caller may read is keyed on screen_result. It is "excluded"
+    # or "indeterminate" and never a clear: a clean no-match returns data=None
+    # instead, so no shape of this payload can be read as clearance.
+    common: dict[str, object] = {
+        "npi": params.npi,
+        "data_month": snapshot.data_month,
+        "snapshot_complete": not unparsed,
+        "verification_url": VERIFICATION_URL,
+    }
+
+    if reinstated:
+        # A record with a reinstatement date contradicts the full file's own
+        # invariant, so the honest answer is neither "excluded" (the party may
+        # have been reinstated) nor "not excluded" (the record is still here).
+        # excluded_in_snapshot is OMITTED rather than set false or null: a
+        # caller that reads it gets a KeyError, not a falsy value.
+        data: dict[str, object] | None = {
+            **common,
+            "screen_result": "indeterminate",
+            "indeterminate_reason": "reinstatement_date_present",
+            "records": records,
+        }
+        non_claims.append(NC_REINSTATEMENT)
+        warnings.append(
+            f"{len(reinstated)} matched record(s) carry a reinstatement date, which the "
+            "LEIE full file is not supposed to contain. SourceLock implements no "
+            f"reinstatement semantics: this is not a verdict either way — resolve it at "
+            f"{VERIFICATION_URL}."
+        )
+        effective = _snapshot_date(snapshot)
+    elif indices:
+        data = {
+            **common,
+            "screen_result": "excluded",
+            "excluded_in_snapshot": True,
+            "match_basis": "npi-exact",
+            "records": records,
+        }
+        effective = (
+            _record_effective(snapshot.records[indices[0]])
+            if len(indices) == 1
+            else _snapshot_date(snapshot)
+        )
+        if unparsed:
+            warnings.append(
+                f"{snapshot.malformed_rows} row(s) of the snapshot could not be parsed, so "
+                "this record list may be incomplete; the match itself stands."
+            )
+    elif unparsed:
+        # No match, but the screen did not read the whole list. Fail closed.
+        data = {
+            **common,
+            "screen_result": "indeterminate",
+            "indeterminate_reason": "unparsed_rows",
+            "unparsed_rows": snapshot.malformed_rows,
+            "records": records,
+        }
+        warnings.append(
+            f"{snapshot.malformed_rows} row(s) of the LEIE snapshot "
+            f"({snapshot.source_version}) could not be parsed, so this NPI was not "
+            "compared against the whole list. Reporting indeterminate rather than "
+            f"not-found — verify at {VERIFICATION_URL}."
+        )
+        effective = _snapshot_date(snapshot)
+    else:
+        data = None
+        effective = _snapshot_date(snapshot)
+        warnings.append(
+            "The requested NPI was not found in the LEIE full-file snapshot "
+            f"({snapshot.source_version}). ~89.5% of LEIE records carry no NPI — run "
+            f"leie.candidate_search and verify identity at {VERIFICATION_URL} before "
+            "treating this as clearance."
+        )
+
+    return ToolResult(
+        data=data,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="leie.check_npi",
+            fetch=entry.fetch_meta(),
+            source_version=snapshot.source_version,
+            transform_version=TRANSFORM_VERSION,
+            effective_from=effective,
+            warnings=warnings,
+            non_claims=non_claims,
+        ),
+    )
+
+
+def _candidate_search(params: CandidateSearchParams) -> ToolResult:
+    entry = _cached_entry()
+    snapshot = entry.snapshot
+    warnings = list(snapshot.parse_warnings) + list(entry.warnings)
+    non_claims = list(CANDIDATE_NON_CLAIMS)
+    unparsed = snapshot.malformed_rows > MAX_UNPARSED_ROWS
+    if unparsed:
+        non_claims.append(NC_UNPARSED)
+
+    matches: list[int] = []
+    if params.last_name:
+        last = _norm(params.last_name)
+        first = _norm(params.first_name) if params.first_name else None
+        for j, rec in enumerate(snapshot.records):
+            if not rec["LASTNAME"] or _norm(rec["LASTNAME"]) != last:
+                continue
+            if first and not _norm(rec["FIRSTNAME"]).startswith(first):
+                continue
+            matches.append(j)
+    else:
+        fragment = _norm(params.business_name or "")
+        for j, rec in enumerate(snapshot.records):
+            if rec["BUSNAME"] and fragment in _norm(rec["BUSNAME"]):
+                matches.append(j)
+
+    if params.state:
+        matches = [j for j in matches if snapshot.records[j]["STATE"] == params.state]
+
+    matches.sort(
+        key=lambda j: (
+            snapshot.records[j]["LASTNAME"],
+            snapshot.records[j]["FIRSTNAME"],
+            snapshot.records[j]["BUSNAME"],
+            snapshot.records[j]["EXCLDATE"],
+            j,
+        )
+    )
+    truncated = len(matches) > MAX_CANDIDATES
+    picked = matches[:MAX_CANDIDATES]
+    if truncated:
+        warnings.append(
+            f"more than {MAX_CANDIDATES} candidate rows matched; returning the first "
+            f"{MAX_CANDIDATES} — narrow with first_name or state"
+        )
+
+    if picked:
+        candidates = [
+            dict(_public_record(snapshot.records[j]), match_basis="name-candidate")
+            for j in picked
+        ]
+        data: dict[str, object] | None = {
+            "screen_result": "candidates",
+            "candidates": candidates,
+            "count": len(candidates),
+            "truncated": truncated,
+            "snapshot_complete": not unparsed,
+            "data_month": snapshot.data_month,
+            "verification_url": VERIFICATION_URL,
+        }
+        reinstated = [c for c in candidates if c["reinstatement_date"]]
+        if reinstated:
+            non_claims.append(NC_REINSTATEMENT)
+            warnings.append(
+                f"{len(reinstated)} returned candidate(s) carry a reinstatement date, "
+                "which the LEIE full file is not supposed to contain. SourceLock "
+                "implements no reinstatement semantics: their exclusion status is "
+                f"undetermined here — resolve it at {VERIFICATION_URL}."
+            )
+        if unparsed:
+            warnings.append(
+                f"{snapshot.malformed_rows} row(s) of the snapshot could not be parsed, "
+                "so this candidate list may be missing matches."
+            )
+    elif unparsed:
+        # Nothing matched, but the search did not read the whole list. The
+        # candidate/count keys are OMITTED so an empty list cannot be read as
+        # "searched, found nobody".
+        data = {
+            "screen_result": "indeterminate",
+            "indeterminate_reason": "unparsed_rows",
+            "unparsed_rows": snapshot.malformed_rows,
+            "snapshot_complete": False,
+            "data_month": snapshot.data_month,
+            "verification_url": VERIFICATION_URL,
+        }
+        warnings.append(
+            f"{snapshot.malformed_rows} row(s) of the LEIE snapshot "
+            f"({snapshot.source_version}) could not be parsed, so this name was not "
+            "searched against the whole list. Reporting indeterminate rather than "
+            f"no-candidates — verify at {VERIFICATION_URL}."
+        )
+    else:
+        data = None
+        warnings.append(
+            "No candidate rows matched. Per OIG search guidance, also try maiden or "
+            "former names, each half of a hyphenated name separately, and spelling "
+            "variants — apostrophes, hyphens, ampersands and commas are significant."
+        )
+
+    return ToolResult(
+        data=data,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="leie.candidate_search",
+            fetch=entry.fetch_meta(),
+            source_version=snapshot.source_version,
+            transform_version=TRANSFORM_VERSION,
+            effective_from=_snapshot_date(snapshot),
+            warnings=warnings,
+            non_claims=non_claims,
+        ),
+    )
+
+
+def _refresh_status(_: NoParams) -> ToolResult:
+    result = _probe()
+    warnings: list[str] = []
+    lm = _parse_last_modified(result.headers)
+    today = _today()
+
+    if lm is not None:
+        lm_date = lm.date()
+        age_days: int | None = (today - lm_date).days
+        stale: bool | None = age_days > STALE_AFTER_DAYS
+        data_month = _data_month(lm_date)
+        next_year, next_month = lm_date.year, lm_date.month + 1
+        if next_month == 13:
+            next_year, next_month = next_year + 1, 1
+        next_expected: str | None = f"{next_year}-{next_month:02d}-10"
+        source_version = lm_date.isoformat()
+        effective: date | None = lm_date
+        if stale:
+            warnings.append(
+                f"snapshot is stale: last modified {lm_date.isoformat()} ({age_days} "
+                f"days ago) against OIG's monthly by-the-10th cadence — check {HUB_URL}"
+            )
+    else:
+        age_days = stale = None
+        data_month = next_expected = None
+        source_version = f"sha256:{result.sha256[:12]}"
+        effective = None
+        warnings.append(
+            "no Last-Modified header (local mirror or override); snapshot age unknown"
+        )
+
+    data = {
+        "source_url": result.url,
+        "last_modified": lm.isoformat() if lm else None,
+        "data_month": data_month,
+        "age_days": age_days,
+        "stale": stale,
+        "cadence": CADENCE_TEXT,
+        "supplement_retention": RETENTION_TEXT,
+        "next_update_expected": next_expected,
+        "verification_url": VERIFICATION_URL,
+    }
+    return ToolResult(
+        data=data,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="leie.refresh_status",
+            fetch=result,
+            source_version=source_version,
+            transform_version=TRANSFORM_VERSION,
+            effective_from=effective,
+            warnings=warnings,
+            non_claims=REFRESH_NON_CLAIMS,
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Canaries
+# ---------------------------------------------------------------------------
+
+
+def _content_range_total(headers: Mapping[str, str]) -> int | None:
+    raw = headers.get("content-range", "")
+    if "/" not in raw:
+        return None
+    total = raw.rsplit("/", 1)[1].strip()
+    return int(total) if total.isdigit() else None
+
+
+def _observe_full_file() -> CanaryObservation:
+    try:
+        result = _probe()
+    except SourceUnreachable:
+        raise
+    except RuntimeError:
+        # Offline harness (socket blocker): observe the packaged sample with a
+        # self-describing token. Real transport failures raise above.
+        snapshot = _cached_snapshot(from_sample=True)
+        return CanaryObservation(
+            value=f"sample:{snapshot.canonical_hash[:8]}",
+            schema_hash=snapshot.schema_hash,
+            note="offline: observed the packaged sample, not the live source",
+        )
+
+    content_type = result.headers.get("content-type", "")
+    if content_type and not content_type.startswith("text/csv"):
+        return CanaryObservation(
+            value=f"unexpected-content-type:{content_type.split(';')[0]}",
+            upstream_status=result.status,
+        )
+    total = _content_range_total(result.headers)
+    if total is not None and not (MIN_EXPECTED_BYTES <= total <= MAX_EXPECTED_BYTES):
+        return CanaryObservation(value=f"size-out-of-band:{total}", upstream_status=result.status)
+
+    lm = _parse_last_modified(result.headers)
+    if lm is None:
+        # Local mirror / file override: key on canonical content, never raw bytes.
+        snapshot = _cached_snapshot()
+        return CanaryObservation(
+            value=f"canonical:{snapshot.canonical_hash[:12]}",
+            schema_hash=snapshot.schema_hash,
+            note="no Last-Modified header; keyed on canonical content",
+        )
+    lm_date = lm.date()
+    if (_today() - lm_date).days > STALE_AFTER_DAYS:
+        return CanaryObservation(value=f"stale:{lm_date.isoformat()}", upstream_status=result.status)
+    return CanaryObservation(
+        value=lm_date.isoformat(),
+        upstream_status=result.status,
+        note="Last-Modified of UPDATED.csv; a new monthly release moves this forward",
+    )
+
+
+def _observe_header() -> CanaryObservation:
+    try:
+        result = _probe()
+    except SourceUnreachable:
+        raise
+    except RuntimeError:
+        result = fetch(_sample_uri())
+
+    text = result.content.decode("utf-8-sig", errors="replace")
+    if text.lstrip().startswith("<"):
+        return CanaryObservation(value="html-body", upstream_status=result.status)
+    lines = text.splitlines()
+    columns = [c.strip() for c in next(csv.reader(lines[:1]), [])] if lines else []
+    if not columns:
+        return CanaryObservation(value="empty-header", upstream_status=result.status)
+    return CanaryObservation(
+        value=str(len(columns)),
+        schema_hash=_schema_hash(columns),
+        upstream_status=result.status,
+        note="column count of the UPDATED.csv header; the hash locks the exact names",
+    )
+
+
+def _observe_content() -> CanaryObservation:
+    try:
+        snapshot = _cached_snapshot()
+    except SourceUnreachable:
+        raise
+    except RuntimeError:
+        snapshot = _cached_snapshot(from_sample=True)
+
+    if snapshot.reindate_populated:
+        return CanaryObservation(
+            value=f"reindate-populated:{snapshot.reindate_populated}",
+            schema_hash=snapshot.schema_hash,
+            note="REINDATE must be null in the full file; OIG may have changed semantics",
+        )
+    note = f"records={len(snapshot.records)}"
+    if snapshot.unknown_excltypes:
+        note += "; new EXCLTYPE tokens: " + ", ".join(snapshot.unknown_excltypes)
+    value = (
+        f"sample:{snapshot.canonical_hash[:8]}"
+        if snapshot.from_sample
+        else f"canonical:{snapshot.canonical_hash[:16]}"
+    )
+    return CanaryObservation(value=value, schema_hash=snapshot.schema_hash, note=note)
+
+
+def _observe_waivers() -> CanaryObservation:
+    """Advisory cross-check: observes, never drifts, never fails.
+
+    Its ``value`` is the constant ``"advisory"``, so it cannot drift by
+    construction -- which is the point, and also the trap. When the cross-check
+    MISMATCHES, an unchanged constant would be graded ``ok`` while the invariant
+    the canary exists to test is broken. So a mismatch sets ``stale``: doctor
+    downgrades the match to STALE (exit 4), because a comparison that succeeded
+    against something the canary says is wrong is not assurance.
+
+    A SKIP is different and deliberately not stale. The advisory being
+    unavailable -- offline, or the waivers page returning a non-2xx -- says
+    nothing about whether the exclusion data is right, and the note already
+    carries the reason.
+    """
+    stale = False
+    try:
+        page = fetch(_waivers_url(), raise_for_status=False)
+        try:
+            snapshot = _cached_snapshot()
+        except Exception:  # noqa: BLE001 - advisory must not fail on the data path either
+            snapshot = _cached_snapshot(from_sample=True)
+        names = sorted({
+            r["LASTNAME"]
+            for r in snapshot.records
+            if r["WAIVERDATE"] not in _NULL_DATES and r["LASTNAME"]
+        })
+        if page.status is not None and not (200 <= page.status < 300):
+            note = f"skipped: waivers page returned HTTP {page.status}"
+        else:
+            text = page.content.decode("utf-8", errors="replace").casefold()
+            missing = [n for n in names if n.casefold() not in text]
+            if missing:
+                stale = True
+                note = (
+                    f"mismatch: {len(missing)} of {len(names)} CSV waiver surnames not on "
+                    "the waivers page — waiver scope is defined by the letters there"
+                )
+            else:
+                note = f"ok: {len(names)}/{len(names)} CSV waiver surnames found on the waivers page"
+    except Exception as exc:  # noqa: BLE001 - advisory by design
+        note = f"skipped: {type(exc).__name__}"
+    return CanaryObservation(value="advisory", note=note, stale=stale)
+
+
+def _full_file_remediation(status: CanaryStatus, observed: str | None, expected: str | None) -> str:
+    if status is CanaryStatus.UNREACHABLE:
+        return (
+            f"UPDATED.csv could not be probed at {AUTHORITY_URL}. Check network and the "
+            f"hub page {HUB_URL} for a moved link; if the page is gone, email "
+            "exclusions@oig.hhs.gov. Keep serving the last verified snapshot, labelled "
+            "with its data month, until resolved."
+        )
+    if observed and observed.startswith("sample:"):
+        return (
+            "The canary observed the packaged sample because the live source was not "
+            "reachable at observation time. Re-run `hc-source lock init` with network "
+            "access so the lockfile pins the real upstream."
+        )
+    if observed and (observed.startswith("stale:") or observed.startswith("size-out-of-band:")
+                     or observed.startswith("unexpected-content-type:")):
+        return (
+            f"UPDATED.csv looks wrong upstream ({observed}). Open {HUB_URL}, confirm the "
+            "'Updated LEIE Database (CSV)' link, and update the adapter URL if it moved. "
+            "Keep the prior snapshot until a clean file is published."
+        )
+    return (
+        f"OIG published a new monthly LEIE file (pinned {expected}, observed {observed}). "
+        "Review the change, then re-pin with `hc-source lock init`."
+    )
+
+
+ADAPTER: SourceAdapter
+
+
+class LeieAdapter(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="leie.full_file",
+                source_id=SOURCE_ID,
+                description="Presence, type, size band, and monthly freshness of UPDATED.csv.",
+                observe=_observe_full_file,
+                remediation=(
+                    f"UPDATED.csv moved, went stale, or changed shape. Open {HUB_URL}, "
+                    "locate the 'Updated LEIE Database (CSV)' link, update the adapter "
+                    "URL if needed, then re-pin with `hc-source lock init`."
+                ),
+                remediation_for=_full_file_remediation,
+            ),
+            Canary(
+                canary_id="leie.header",
+                source_id=SOURCE_ID,
+                description="The locked 18-column CSV header of UPDATED.csv.",
+                observe=_observe_header,
+                remediation=(
+                    "LEIE column layout changed. Diff the live header against the locked "
+                    f"18 columns, fetch the current record layout from {RECORD_LAYOUT_URL} "
+                    "(follows a 301), regenerate the field map, bump TRANSFORM_VERSION in "
+                    "hc_source/adapters/leie.py, then re-pin with `hc-source lock init`. "
+                    "Do not ingest until the new header is locked."
+                ),
+            ),
+            Canary(
+                canary_id="leie.content",
+                source_id=SOURCE_ID,
+                description=(
+                    "Canonicalised content hash of the full file (styling- and "
+                    "order-independent), plus the REINDATE-null invariant."
+                ),
+                observe=_observe_content,
+                remediation=(
+                    "LEIE full-file content moved — a new monthly release or an in-place "
+                    "repost. Review the change, then re-pin with `hc-source lock init`. "
+                    "If the observed value starts with 'reindate-populated', OIG changed "
+                    f"full-file semantics: re-read {QUICK_TIPS_URL} before ingesting. If "
+                    "it starts with 'sample:', the live source was unreachable at "
+                    "observation time — re-pin with network access."
+                ),
+            ),
+            Canary(
+                canary_id="leie.waivers",
+                source_id=SOURCE_ID,
+                description=(
+                    "Advisory cross-check of CSV waiver rows against the OIG waivers "
+                    "page (WARN-only: HTML scrape, never drifts or fails a run)."
+                ),
+                observe=_observe_waivers,
+                # Declared, not merely intended. This canary scrapes an HTML
+                # page OIG restyles at will and reports a cross-check whose
+                # disagreement means "a human should read the waiver letters",
+                # never "your data is wrong". It was already described as
+                # WARN-only; now the exit code agrees with the description.
+                severity=CanarySeverity.ADVISORY,
+                remediation=(
+                    f"Advisory only: waiver rows in UPDATED.csv disagree with {WAIVERS_URL}. "
+                    "Waiver scope is defined by the letters on that page, not the CSV; "
+                    "flag affected records as 'waiver status uncertain — see the OIG "
+                    "waiver letter' until the next monthly file."
+                ),
+            ),
+        ]
+
+    def tools(self) -> list[ToolSpec]:
+        return [
+            ToolSpec(
+                name="leie.check_npi",
+                description=(
+                    "Deterministic NPI-exact check against the current monthly LEIE "
+                    "full-file snapshot; a miss never clears a provider (~89.5% of "
+                    "records carry no NPI)."
+                ),
+                params_model=CheckNpiParams,
+                handler=_check_npi,
+                tags=("lookup", "exclusions"),
+            ),
+            ToolSpec(
+                name="leie.candidate_search",
+                description=(
+                    "Name-based CANDIDATE matching in the LEIE snapshot — candidates "
+                    "only, never identity verification; verify at "
+                    "https://exclusions.oig.hhs.gov/."
+                ),
+                params_model=CandidateSearchParams,
+                handler=_candidate_search,
+                tags=("search", "exclusions"),
+            ),
+            ToolSpec(
+                name="leie.refresh_status",
+                description=(
+                    "Freshness of the LEIE snapshot versus OIG's monthly by-the-10th "
+                    "cadence, plus the 12-month supplement retention limit."
+                ),
+                params_model=NoParams,
+                handler=_refresh_status,
+                tags=("metadata",),
+            ),
+        ]
+
+
+ADAPTER = LeieAdapter()