sourcelock 0.1.0__py3-none-any.whl

hc_source/adapters/codes.py

@@ -0,0 +1,1232 @@
+"""ICD-10-CM / HCPCS Level II release-train adapter.
+
+Serves date-of-service code questions from compact derived tables vendored at
+build time from the real CMS release files (see
+``hc_source/data/codes/manifest.json`` for full provenance and
+``hc_source/data/codes/regenerate.py`` for the regeneration command).
+
+The (code, date-of-service) -> release resolution rule
+------------------------------------------------------
+
+ICD-10-CM has no per-code effective dates; validity is a property of the
+release that governs the date of service. The rule implemented by
+:func:`resolve_cm_release`, verified against the live CMS release train on
+2026-08-01:
+
+1. ``FY(D) = D.year + 1 if D.month >= 10 else D.year``. The FY-labeled file
+   set takes effect on October 1 of the *prior* calendar year (FY2026 =
+   2025-10-01 .. 2026-09-30).
+2. Two candidate releases exist per fiscal year: the FY base file set
+   (``fyYYYY``) and, in years where CMS publishes one, the April 1 update
+   (``fyYYYY-april``), a full republished file set effective April 1 through
+   September 30 of that FY.
+3. ``D`` before April 1 of FY(D)  ->  the FY base release governs.
+   ``D`` on/after April 1        ->  the April release governs if it is
+   published ("posted" in the manifest's ``cm_april_status`` ledger); the FY
+   base release governs if the ledger says "absent" (a settled fact: the
+   manifest was generated on/after that April 1 with no April package
+   published); and the lookup **fails closed** if the ledger says "unknown"
+   (the manifest was generated before that April 1, so an update may yet be
+   published -- answering from the base file would be a guess).
+4. The lookup also fails closed when the governing release has no vendored
+   table (date of service outside the vendored release train).
+
+The effective interval stamped on each receipt is the sub-window the answer
+is certain for: an FY base answer is capped at March 31 unless the April
+status for that FY is a settled "absent"; an April answer covers April 1 ..
+September 30.
+
+HCPCS Level II is quarterly and *does* carry per-record dates. Verified
+against all 1,327 termed records in the July 2026 ANWEB master: the record's
+validity interval is ``[code_added, termination]``; ``action_effective`` is
+the date the most recent maintenance action took effect (for discontinued
+codes it is always ``termination + 1 day`` -- it is **not** the start of
+validity). A validity verdict is only issued when the governing quarterly for
+the date of service is vendored; otherwise the lookup fails closed.
+
+Staged releases (posted but not yet effective)
+----------------------------------------------
+
+CMS posts FY files ~4 months before they take effect (FY2027 was posted
+2026-06-05, effective 2026-10-01), so "a newer release exists upstream" must
+never alarm by itself. The canaries split the two events:
+
+* ``codes.cm_governing_release`` / ``codes.hcpcs_governing_quarter`` compare
+  the release that governs *today* against the pin -- they drift exactly when
+  the pin stops being correct for today's date (e.g. on October 1).
+* ``codes.cm_release_train`` / ``codes.hcpcs_release_train`` observe what is
+  *posted* upstream. A future-effective posting is pinned as part of the
+  observed value, so it reports ok; drift fires only when something newly
+  posts, and the remediation says explicitly that it is staged, not an
+  emergency. ``codes.latest_release`` reports the same staged state as an OK
+  answer with a warning.
+
+CPT: what is excluded, and what is not
+--------------------------------------
+
+HCPCS Level I (CPT) descriptors are AMA-licensed. Only the ANWEB fixed-width
+master file is ingested (verified to contain zero numeric-leading CPT and
+zero D#### ADA CDT records); ``proc_notes_*.txt`` and the ``.xlsx`` members
+are never read.
+
+That excludes CPT *records* and CPT *descriptors*. It does not exclude CPT
+code *numbers*. CMS writes part of its own Level II definitions as
+cross-references, so the shipped text of G0317 contains "list separately in
+addition to cpt codes 99306, 99310" and the shipped text of G0561 contains
+"0583t". Seventeen vendored records read that way; they are named in
+``CPT_CROSS_REFERENCED_CODES`` below. The non-claim key used to be
+``DOES_NOT_INCLUDE_CPT``, which asserted the opposite of the shipped bytes;
+it is now ``DOES_NOT_INCLUDE_CPT_DESCRIPTORS``, it states the
+cross-references and names every record carrying one, and
+``codes.hcpcs_lookup`` lists the cited identifiers on the record itself so a
+caller learns of them from the receipt rather than from a lawyer.
+
+No pattern match can tell a government cross-reference to a CPT number from
+an AMA-authored descriptor vendored by mistake -- that is a reading, not a
+regex. So the reviewed set is pinned here and
+``tests/test_codes_cpt_claim.py`` re-derives it from the vendored tables on
+every run: a re-vendoring that adds, drops, or moves a cross-reference fails
+the build until a person decides which kind it is.
+
+Runtime data location: ``hc_source/data/codes`` (package data, shipped in the
+wheel), overridable with the ``HC_SOURCE_CODES_DATA`` env var
+(also how the test suite simulates drift). ``HC_SOURCE_CODES_TODAY`` freezes
+"today" for deterministic canary runs and tests.
+"""
+
+from __future__ import annotations
+
+import gzip
+import hashlib
+import io
+import csv
+import os
+import re
+from dataclasses import dataclass
+import datetime as _dt
+from datetime import date, timedelta
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..http import FetchResult, SourceUnreachable, as_cache_hit, fetch
+from ..interfaces import Canary, CanaryObservation, SourceAdapter, ToolResult, ToolSpec
+from ..receipts import build_receipt
+from ..schemas import CanaryStatus, SourceContract
+
+SOURCE_ID = "codes"
+#: Bumped to "2" when codes.hcpcs_lookup started deriving cpt_cross_references
+#: from the record's description text.
+TRANSFORM_VERSION = "2"
+
+#: Environment overrides. DATA points at an alternate derived-data directory;
+#: TODAY freezes the clock (ISO date) for deterministic runs.
+DATA_ENV_VAR = "HC_SOURCE_CODES_DATA"
+TODAY_ENV_VAR = "HC_SOURCE_CODES_TODAY"
+
+CDC_LISTING_URL = "https://ftp.cdc.gov/pub/Health_Statistics/NCHS/Publications/ICD10CM/"
+CMS_LANDING_URL = "https://www.cms.gov/medicare/coding-billing/icd-10-codes"
+CMS_ZIP_BASE = "https://www.cms.gov/files/zip/"
+HCPCS_INDEX_URL = (
+    "https://www.cms.gov/medicare/coding-billing/healthcare-common-procedure-system/"
+    "quarterly-update"
+)
+
+REGENERATE = "python hc_source/data/codes/regenerate.py"
+ZIP_MAGIC = b"PK\x03\x04"
+
+_QUARTER_MONTHS = {1: "january", 2: "april", 3: "july", 4: "october"}
+
+CONTRACT = SourceContract(
+    source_id=SOURCE_ID,
+    authority_url=CMS_LANDING_URL,
+    fallback_url=CDC_LISTING_URL,
+    license_notes=(
+        "ICD-10-CM (NCHS/CDC), ICD-10-PCS and HCPCS Level II (CMS) are US government "
+        "works, public domain and freely redistributable. HCPCS Level I (CPT) and ADA "
+        "CDT descriptors are NOT: this adapter ingests only the ANWEB Level II master "
+        "file (verified free of CPT/CDT records) and never the proc_notes or xlsx "
+        "members. CMS's own Level II descriptions do cite CPT code numbers in a small, "
+        "named set of records (see the DOES_NOT_INCLUDE_CPT_DESCRIPTORS non-claim); "
+        "those citations ship as CMS published them. Redistributing a government "
+        "description that cites a CPT number is not the same as redistributing a CPT "
+        "descriptor, and neither this adapter nor these notes convey an AMA licence."
+    ),
+    cadence=(
+        "ICD-10-CM: annual (files posted ~June, effective October 1) plus an optional "
+        "April 1 mid-year update (posted ~December). HCPCS Level II: quarterly "
+        "(posted ~2-6 weeks before the quarter starts, reposted in place for "
+        "corrections)."
+    ),
+    effective_date_semantics=(
+        "effective_from/effective_to bound the dates of service the answering release "
+        "governs. ICD-10-CM: the FY base file governs October 1 - March 31, and the "
+        "April 1 update (when published) governs April 1 - September 30; a base-file "
+        "answer is capped at March 31 unless the April status for that FY is a settled "
+        "'absent'. HCPCS: the quarterly file governs its calendar quarter, and within "
+        "it a record's own [code_added, termination] interval is authoritative."
+    ),
+    invariants=[
+        "an ICD-10-CM release's valid-code table has an exact, release-specific row "
+        "count (FY2026: 74,719; FY2027: 74,879)",
+        "ICD-10-CM codes never change mid-FY except via a published April 1 update",
+        "FY files are posted months before they take effect: posted is not effective",
+        "the HCPCS ANWEB master contains only Level II codes and 2-char modifiers -- "
+        "zero CPT (numeric-leading) and zero ADA CDT (D####) records",
+        "CMS-authored Level II descriptions cite CPT code numbers in a fixed, reviewed "
+        "set of records; a change to that set is a licensing review, not a data update",
+        "every termed HCPCS record satisfies action_effective == termination + 1 day",
+        "CMS reposts artifacts in place at the same URL; URL identity never proves "
+        "content identity",
+    ],
+)
+
+# ---------------------------------------------------------------------------
+# CPT identifiers cited inside CMS-authored descriptions
+# ---------------------------------------------------------------------------
+
+#: Category I CPT identifiers are five digits.
+_CPT_CATEGORY_I_RE = re.compile(r"(?<![0-9A-Za-z])(\d{5})(?![0-9A-Za-z])")
+
+#: Category II identifiers are four digits plus ``F`` and span the whole
+#: leading-digit range. Category III (``T``) and Proprietary Laboratory
+#: Analyses (``U``) identifiers are four digits plus a letter but are entirely
+#: 0-leading, and requiring that zero is what keeps a dose abbreviation out of
+#: the scan: "Inj heparin sodium per 1000u" is a quantity, "0583t" is a code.
+_CPT_CATEGORY_II_III_RE = re.compile(
+    r"(?<![0-9A-Za-z])(\d{4}F|0\d{3}[TU])(?![0-9A-Za-z])", re.IGNORECASE
+)
+
+
+def scan_cpt_identifiers(*texts: str | None) -> tuple[str, ...]:
+    """Return the CPT-shaped identifiers cited in description text, sorted.
+
+    Deliberately over-inclusive: it reports *candidates*, because a five-digit
+    number in a CMS sentence could in principle be a quantity rather than a
+    code. Classification is a human gate, pinned in
+    :data:`CPT_CROSS_REFERENCED_CODES` and enforced by
+    ``tests/test_codes_cpt_claim.py``.
+    """
+    found: set[str] = set()
+    for text in texts:
+        if not text:
+            continue
+        found.update(_CPT_CATEGORY_I_RE.findall(text))
+        found.update(match.upper() for match in _CPT_CATEGORY_II_III_RE.findall(text))
+    return tuple(sorted(found))
+
+
+def cited_cpt_identifiers(records: list[dict[str, str]]) -> tuple[str, ...]:
+    """CPT identifiers cited by one code's records (long and short text)."""
+    texts: list[str | None] = []
+    for record in records:
+        texts.append(record.get("long_description"))
+        texts.append(record.get("short_description"))
+    return scan_cpt_identifiers(*texts)
+
+
+#: The vendored HCPCS Level II records whose CMS-authored description text
+#: cites a CPT identifier, reviewed by hand on 2026-08-01. Pinned rather than
+#: computed because the distinction that matters -- the government citing a CPT
+#: *number* as part of its own definition, versus an AMA-authored *descriptor*
+#: having been vendored by mistake -- is a reading, and the failure it prevents
+#: is shipping an AMA descriptor under a receipt that says we ship none.
+CPT_CROSS_REFERENCED_CODES = (
+    "AT",
+    "G0279",
+    "G0316",
+    "G0317",
+    "G0318",
+    "G0500",
+    "G0561",
+    "G2058",
+    "G2212",
+    "M1483",
+    "M1485",
+    "QP",
+    "S8055",
+    "S9034",
+    "S9123",
+    "V2530",
+    "V2531",
+)
+
+
+NON_CLAIMS = [
+    "DOES_NOT_INCLUDE_CPT_DESCRIPTORS: no HCPCS Level I (CPT) record and no ADA CDT "
+    "record is vendored here, and no AMA- or ADA-authored descriptor text is "
+    "reproduced. What is served is government-authored: NCHS ICD-10-CM codes and "
+    "descriptions, and CMS HCPCS Level II codes, modifiers and descriptions from the "
+    "ANWEB master file, verified to contain zero numeric-leading CPT and zero D#### "
+    f"CDT records. {len(CPT_CROSS_REFERENCED_CODES)} of those CMS descriptions cite "
+    "CPT code numbers inside the government's own definition text -- G0317 reads "
+    "\"list separately in addition to cpt codes 99306, 99310\" -- and the complete set "
+    f"is {', '.join(CPT_CROSS_REFERENCED_CODES)}. Those digits ship exactly as CMS "
+    "published them, carry no AMA descriptor with them, and are listed on the record "
+    "by codes.hcpcs_lookup. CPT is copyright the American Medical Association: "
+    "nothing here conveys a licence to it.",
+    "DOES_NOT_PROVE_COVERAGE: a code being valid for a date of service says nothing "
+    "about whether any payer covers, prices, or pays for it.",
+    "DOES_NOT_PROVE_CURRENCY: answers come from the release train vendored at build "
+    "time; CMS reposts corrections in place at the same URLs, so the vendored tables "
+    "may lag an unannounced correction. `hc-source doctor` checks the train.",
+]
+
+
+# ---------------------------------------------------------------------------
+# Clock, data directory, cached file loading
+# ---------------------------------------------------------------------------
+
+
+def _today() -> date:
+    override = os.environ.get(TODAY_ENV_VAR)
+    return date.fromisoformat(override) if override else date.today()
+
+
+def _data_dir() -> Path:
+    override = os.environ.get(DATA_ENV_VAR)
+    if override:
+        return Path(override)
+    return Path(__file__).resolve().parents[1] / "data" / "codes"
+
+
+_cache: dict[str, tuple[tuple[int, int] | None, FetchResult, Any]] = {}
+
+
+def _load_file(name: str, parser) -> tuple[FetchResult, Any]:
+    """Read a vendored file through the shared transport, with a stat-keyed cache."""
+    path = _data_dir() / name
+    try:
+        stat = path.stat()
+        signature: tuple[int, int] | None = (stat.st_mtime_ns, stat.st_size)
+    except OSError:
+        signature = None
+    key = str(path)
+    cached = _cache.get(key)
+    if cached is not None and signature is not None and cached[0] == signature:
+        # Same object, marked as the reuse it is. `retrieved_at` stays where the
+        # read put it -- that was the round-1 fix -- and `cache_hit` now agrees
+        # with it instead of claiming every answer came off a fresh read.
+        return as_cache_hit(cached[1]), cached[2]
+    result = fetch(path.as_uri())  # raises SourceUnreachable if unreadable
+    parsed = parser(result.content)
+    if signature is not None:
+        _cache[key] = (signature, result, parsed)
+    return result, parsed
+
+
+def _parse_manifest(content: bytes) -> dict[str, Any]:
+    import json
+
+    return json.loads(content)
+
+
+def _parse_cm_table(content: bytes) -> dict[str, str]:
+    text = gzip.decompress(content).decode("utf-8")
+    reader = csv.reader(io.StringIO(text))
+    next(reader)  # header
+    return {row[0]: row[1] for row in reader}
+
+
+def _parse_hcpcs_table(content: bytes) -> dict[str, list[dict[str, str]]]:
+    text = gzip.decompress(content).decode("utf-8")
+    reader = csv.DictReader(io.StringIO(text))
+    table: dict[str, list[dict[str, str]]] = {}
+    for row in reader:
+        table.setdefault(row["code"], []).append(row)
+    for records in table.values():
+        records.sort(key=lambda r: r["seq"])
+    return table
+
+
+def _load_manifest() -> tuple[FetchResult, dict[str, Any]]:
+    return _load_file("manifest.json", _parse_manifest)
+
+
+# ---------------------------------------------------------------------------
+# (code, date-of-service) -> release resolution
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class CmResolution:
+    """The ICD-10-CM release governing a date of service, and the sub-window
+    of dates the answer is certain for."""
+
+    release: str
+    effective_from: date
+    effective_to: date
+
+
+@dataclass(frozen=True)
+class CmUnresolved:
+    """Fail-closed outcome: no vendored release can be proven to govern."""
+
+    reason: str  # stable key: AMBIGUOUS_APRIL_WINDOW | RELEASE_NOT_VENDORED
+    detail: str  # one human sentence with the fix
+
+
+def resolve_cm_release(dos: date, manifest: dict[str, Any]) -> CmResolution | CmUnresolved:
+    """Apply the resolution rule documented in the module docstring."""
+    fy = dos.year + 1 if dos.month >= 10 else dos.year
+    fy_start = date(fy - 1, 10, 1)
+    march_31 = date(fy, 3, 31)
+    april_1 = date(fy, 4, 1)
+    fy_end = date(fy, 9, 30)
+    april_status = manifest.get("cm_april_status", {}).get(str(fy), "unknown")
+
+    if dos < april_1:
+        release = f"fy{fy}"
+        effective_from = fy_start
+        effective_to = fy_end if april_status == "absent" else march_31
+    elif april_status == "posted":
+        release = f"fy{fy}-april"
+        effective_from = april_1
+        effective_to = fy_end
+    elif april_status == "absent":
+        release = f"fy{fy}"
+        effective_from = fy_start
+        effective_to = fy_end
+    else:
+        return CmUnresolved(
+            "AMBIGUOUS_APRIL_WINDOW",
+            f"{dos.isoformat()} falls in the April-update window of FY{fy} "
+            f"(April 1 - September 30 {fy}), and whether an April 1 {fy} update exists "
+            f"was unknown when the vendored manifest was generated. Failing closed: "
+            f"re-vendor once the April status is settled ({REGENERATE}), then retry.",
+        )
+
+    if release not in manifest.get("cm_releases", {}):
+        vendored = ", ".join(sorted(manifest.get("cm_releases", {}))) or "none"
+        return CmUnresolved(
+            "RELEASE_NOT_VENDORED",
+            f"{dos.isoformat()} is governed by ICD-10-CM release {release}, which is "
+            f"not vendored in this build (vendored: {vendored}). Add it to "
+            f"CM_RELEASES in regenerate.py and re-run ({REGENERATE}), then retry.",
+        )
+    return CmResolution(release=release, effective_from=effective_from, effective_to=effective_to)
+
+
+def _quarter_label(d: date) -> str:
+    return f"{d.year}q{(d.month - 1) // 3 + 1}"
+
+
+def _quarter_start(label: str) -> date:
+    year, q = label.split("q")
+    return date(int(year), (int(q) - 1) * 3 + 1, 1)
+
+
+def _next_quarter(label: str) -> str:
+    year, q = int(label[:4]), int(label[-1])
+    return f"{year + 1}q1" if q == 4 else f"{year}q{q + 1}"
+
+
+def _hcpcs_quarter_url(label: str, *, plural: bool = False) -> str:
+    month = _QUARTER_MONTHS[int(label[-1])]
+    suffix = "files" if plural else "file"
+    return f"{CMS_ZIP_BASE}{month}-{label[:4]}-alpha-numeric-hcpcs-{suffix}.zip"
+
+
+# ---------------------------------------------------------------------------
+# Typed public parameters
+# ---------------------------------------------------------------------------
+
+
+class NoParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class ValidOnParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    code: str = Field(
+        pattern=r"^[A-Za-z][0-9][0-9A-Za-z]\.?[0-9A-Za-z]{0,4}$",
+        description="ICD-10-CM code, with or without the dot (E11.9 or E119).",
+    )
+    date: _dt.date = Field(description="Date of service (ISO, e.g. 2026-07-01).")
+
+
+class LookupParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    code: str = Field(
+        pattern=r"^[A-Za-z][0-9][0-9A-Za-z]\.?[0-9A-Za-z]{0,4}$",
+        description="ICD-10-CM code, with or without the dot.",
+    )
+    date: _dt.date | None = Field(
+        default=None,
+        description="Date of service selecting the governing release; defaults to today.",
+    )
+
+
+class HcpcsLookupParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    code: str = Field(
+        pattern=r"^([A-Za-z][0-9]{4}|[A-Za-z0-9]{2})$",
+        description="HCPCS Level II code (e.g. J0171) or 2-character modifier (e.g. A1).",
+    )
+    date: _dt.date | None = Field(
+        default=None,
+        description=(
+            "Date of service for a validity verdict; requires the governing quarterly "
+            "to be vendored. Omit for a description/date lookup from the pinned quarter."
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers for handlers
+# ---------------------------------------------------------------------------
+
+
+def _dotted(code_nodot: str) -> str:
+    return code_nodot if len(code_nodot) <= 3 else f"{code_nodot[:3]}.{code_nodot[3:]}"
+
+
+def _fail_closed(route: str, fetch_result: FetchResult, warning: str) -> ToolResult:
+    return ToolResult(
+        data=None,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route=route,
+            fetch=fetch_result,
+            source_version="unresolved",
+            transform_version=TRANSFORM_VERSION,
+            warnings=[warning],
+            non_claims=NON_CLAIMS,
+        ),
+    )
+
+
+def _cm_provenance(entry: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "source_url": entry["source_url"],
+        "source_zip_sha256": entry["source_zip_sha256"],
+        "source_last_modified": entry["source_last_modified"],
+        "inner_file": entry["inner_file"],
+        "inner_sha256": entry["inner_sha256"],
+        "fetched_at": entry["fetched_at"],
+        "table": entry["table"],
+        "table_canonical_sha256": entry["canonical_sha256"],
+        "content_identical_to": entry.get("content_identical_to"),
+        "regenerate": REGENERATE,
+    }
+
+
+def _iso(yyyymmdd: str) -> str | None:
+    return f"{yyyymmdd[:4]}-{yyyymmdd[4:6]}-{yyyymmdd[6:8]}" if yyyymmdd else None
+
+
+# ---------------------------------------------------------------------------
+# Handlers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_and_load_cm(
+    route: str, code: str, dos: date
+) -> tuple[ToolResult | None, dict[str, Any] | None, Any, Any, CmResolution | None]:
+    """Common resolution path. Returns (fail_result, entry, table_fetch, table, resolution)."""
+    manifest_fetch, manifest = _load_manifest()
+    resolution = resolve_cm_release(dos, manifest)
+    if isinstance(resolution, CmUnresolved):
+        return (
+            _fail_closed(route, manifest_fetch, f"{resolution.reason}: {resolution.detail}"),
+            None,
+            None,
+            None,
+            None,
+        )
+    entry = manifest["cm_releases"][resolution.release]
+    table_fetch, table = _load_file(entry["table"], _parse_cm_table)
+    return None, entry, table_fetch, table, resolution
+
+
+def _valid_on(params: ValidOnParams) -> ToolResult:
+    route = "codes.valid_on"
+    code_nodot = params.code.replace(".", "").upper()
+    failed, entry, table_fetch, table, resolution = _resolve_and_load_cm(
+        route, code_nodot, params.date
+    )
+    if failed is not None:
+        return failed
+    assert entry is not None and resolution is not None
+
+    description = table.get(code_nodot)
+    data: dict[str, Any] = {
+        "code": _dotted(code_nodot),
+        "code_nodot": code_nodot,
+        "code_system": "ICD-10-CM",
+        "date": params.date.isoformat(),
+        "valid": description is not None,
+        "description": description,
+        "release": resolution.release,
+        "release_effective_from": resolution.effective_from.isoformat(),
+        "release_effective_to": resolution.effective_to.isoformat(),
+    }
+    if description is None:
+        data["note"] = (
+            f"{_dotted(code_nodot)} is not in the valid/billable code set of release "
+            f"{resolution.release}; it may be a non-billable category header or not an "
+            "ICD-10-CM code at all."
+        )
+    return ToolResult(
+        data=data,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route=route,
+            fetch=table_fetch,
+            source_version=resolution.release,
+            transform_version=TRANSFORM_VERSION,
+            effective_from=resolution.effective_from,
+            effective_to=resolution.effective_to,
+            non_claims=NON_CLAIMS,
+        ),
+    )
+
+
+def _lookup(params: LookupParams) -> ToolResult:
+    route = "codes.lookup"
+    dos = params.date or _today()
+    code_nodot = params.code.replace(".", "").upper()
+    failed, entry, table_fetch, table, resolution = _resolve_and_load_cm(route, code_nodot, dos)
+    if failed is not None:
+        return failed
+    assert entry is not None and resolution is not None
+
+    description = table.get(code_nodot)
+    warnings: list[str] = []
+    data: dict[str, Any] | None
+    if description is None:
+        warnings.append(
+            f"Code {_dotted(code_nodot)} not found in release {resolution.release}."
+        )
+        data = None
+    else:
+        data = {
+            "code": _dotted(code_nodot),
+            "code_nodot": code_nodot,
+            "code_system": "ICD-10-CM",
+            "description": description,
+            "release": resolution.release,
+            "release_effective_from": resolution.effective_from.isoformat(),
+            "release_effective_to": resolution.effective_to.isoformat(),
+            "provenance": _cm_provenance(entry),
+        }
+    return ToolResult(
+        data=data,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route=route,
+            fetch=table_fetch,
+            source_version=resolution.release,
+            transform_version=TRANSFORM_VERSION,
+            effective_from=resolution.effective_from,
+            effective_to=resolution.effective_to,
+            warnings=warnings,
+            non_claims=NON_CLAIMS,
+        ),
+    )
+
+
+def _hcpcs_lookup(params: HcpcsLookupParams) -> ToolResult:
+    route = "codes.hcpcs_lookup"
+    manifest_fetch, manifest = _load_manifest()
+    releases: dict[str, Any] = manifest.get("hcpcs_releases", {})
+
+    if params.date is not None:
+        label = _quarter_label(params.date)
+        if label not in releases:
+            vendored = ", ".join(sorted(releases)) or "none"
+            return _fail_closed(
+                route,
+                manifest_fetch,
+                f"RELEASE_NOT_VENDORED: {params.date.isoformat()} is governed by the "
+                f"HCPCS quarterly {label}, which is not vendored in this build "
+                f"(vendored: {vendored}). Failing closed rather than answering from a "
+                f"different quarter's snapshot. Add it to HCPCS_RELEASES in "
+                f"regenerate.py and re-run ({REGENERATE}).",
+            )
+    else:
+        label = max(releases)  # the pinned (latest vendored) quarterly
+
+    entry = releases[label]
+    table_fetch, table = _load_file(entry["table"], _parse_hcpcs_table)
+    code = params.code.upper()
+    records = table.get(code)
+    warnings: list[str] = []
+
+    if records is None:
+        return ToolResult(
+            data=None,
+            receipt=build_receipt(
+                contract=CONTRACT,
+                route=route,
+                fetch=table_fetch,
+                source_version=label,
+                transform_version=TRANSFORM_VERSION,
+                effective_from=date.fromisoformat(entry["effective_from"]),
+                effective_to=date.fromisoformat(entry["effective_to"]),
+                warnings=[f"Code {code} not found in HCPCS quarterly {label}."],
+                non_claims=NON_CLAIMS,
+            ),
+        )
+
+    primary = records[0]
+    long_description = " ".join(r["long_description"] for r in records if r["long_description"])
+    data: dict[str, Any] = {
+        "code": code,
+        "code_system": "HCPCS Level II",
+        "kind": "modifier" if len(code) == 2 else "code",
+        "long_description": long_description,
+        "short_description": primary["short_description"],
+        "code_added": _iso(primary["code_added"]),
+        "termination": _iso(primary["termination"]),
+        "last_action_effective": _iso(primary["action_effective"]),
+        "action_code": primary["action_code"],
+        "record_count": len(records),
+        "release": label,
+        "release_effective_from": entry["effective_from"],
+        "release_effective_to": entry["effective_to"],
+    }
+
+    # Disclose the government's own CPT cross-references on the record that
+    # carries them. Derived from the shipped bytes rather than from a table, so
+    # it cannot go stale against a re-vendoring; the reviewed pin lives in
+    # CPT_CROSS_REFERENCED_CODES and is enforced at test time. This prevents the
+    # failure the old DOES_NOT_INCLUDE_CPT non-claim caused: a caller reading
+    # "no CPT here" off a receipt whose description text names CPT codes.
+    cpt_cited = cited_cpt_identifiers(records)
+    if cpt_cited:
+        data["cpt_cross_references"] = list(cpt_cited)
+        warnings.append(
+            "CPT_CROSS_REFERENCE: this record's CMS-authored description cites the CPT "
+            f"identifiers {', '.join(cpt_cited)} as part of the government's own "
+            "definition text. The digits are reproduced as CMS published them; no AMA "
+            "CPT descriptor is included, and this is not a CPT licence."
+        )
+
+    if params.date is not None:
+        added = primary["code_added"]
+        termination = primary["termination"]
+        if not added:
+            data["valid_on"] = {"date": params.date.isoformat(), "valid": None}
+            warnings.append(
+                f"Record for {code} carries no code-added date; validity on "
+                f"{params.date.isoformat()} is indeterminate (failing closed)."
+            )
+        else:
+            added_date = date.fromisoformat(_iso(added))  # type: ignore[arg-type]
+            term_date = date.fromisoformat(_iso(termination)) if termination else None
+            valid = added_date <= params.date and (term_date is None or params.date <= term_date)
+            data["valid_on"] = {"date": params.date.isoformat(), "valid": valid}
+
+    return ToolResult(
+        data=data,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route=route,
+            fetch=table_fetch,
+            source_version=label,
+            transform_version=TRANSFORM_VERSION,
+            effective_from=date.fromisoformat(entry["effective_from"]),
+            effective_to=date.fromisoformat(entry["effective_to"]),
+            warnings=warnings,
+            non_claims=NON_CLAIMS,
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Release-train observation (shared by codes.latest_release and canaries)
+# ---------------------------------------------------------------------------
+
+_CDC_YEAR_RE = re.compile(r"ICD10CM/(\d{4})/\"")
+_CDC_APRIL_RE = re.compile(r"ICD10CM/(\d{4})-update/\"", re.IGNORECASE)
+_CDC_APRIL_LONG_RE = re.compile(r"ICD10CM/April-1-(\d{4})-Update/\"", re.IGNORECASE)
+_CMS_YEAR_RE = re.compile(r"/files/zip/(\d{4})-code-descriptions-tabular-order")
+_CMS_APRIL_PREFIX_RE = re.compile(r"/files/zip/april-1-(\d{4})-code-descriptions")
+_CMS_APRIL_SUFFIX_RE = re.compile(r"/files/zip/(\d{4})-code-descriptions-tabular-order-april")
+
+
+def _parse_release_train(text: str) -> tuple[int, int | None]:
+    """Return (latest posted FY, latest FY with a posted April update).
+
+    Understands both the CDC IIS directory listing (authority) and the CMS
+    landing page (fallback). Raises ValueError when neither shape is present,
+    so a maintenance page can never be pinned as an observation.
+    """
+
+    def _years(matches: list[str]) -> set[int]:
+        return {int(m) for m in matches if 2000 <= int(m) <= 2100}
+
+    years = _years(_CDC_YEAR_RE.findall(text))
+    aprils = _years(_CDC_APRIL_RE.findall(text)) | _years(_CDC_APRIL_LONG_RE.findall(text))
+    if not years:
+        years = _years(_CMS_YEAR_RE.findall(text))
+        aprils = _years(_CMS_APRIL_PREFIX_RE.findall(text)) | _years(
+            _CMS_APRIL_SUFFIX_RE.findall(text)
+        )
+    if not years:
+        raise ValueError("no ICD-10-CM release-train links recognized in the listing")
+    return max(years), max(aprils) if aprils else None
+
+
+def _fetch_release_train() -> tuple[FetchResult, int, int | None]:
+    result = fetch(
+        CDC_LISTING_URL, fallback_url=CMS_LANDING_URL, fallback_name="cms-landing-page"
+    )
+    try:
+        latest_fy, latest_april = _parse_release_train(
+            result.content.decode("utf-8", errors="replace")
+        )
+    except ValueError as exc:
+        raise SourceUnreachable(result.url, str(exc), status=result.status) from exc
+    return result, latest_fy, latest_april
+
+
+def _probe_zip(label: str) -> bool:
+    """Range-probe a quarterly HCPCS zip: True posted, False absent (404 on
+    both slug variants). Anything else -- including non-ZIP bytes behind a
+    2xx -- raises SourceUnreachable, because pinning it would lie."""
+    last_status: int | None = None
+    for plural in (False, True):
+        url = _hcpcs_quarter_url(label, plural=plural)
+        result = fetch(url, headers={"Range": "bytes=0-3"}, raise_for_status=False)
+        if result.status in (200, 206):
+            if result.content[:4] == ZIP_MAGIC:
+                return True
+            raise SourceUnreachable(
+                url,
+                "expected ZIP magic bytes ('PK') but got something else -- the asset "
+                "may have been replaced by an error page; do not re-pin automatically",
+                status=result.status,
+            )
+        if result.status != 404:
+            raise SourceUnreachable(url, "unexpected status probing quarterly", status=result.status)
+        last_status = result.status
+    assert last_status == 404
+    return False
+
+
+def _latest_release(_: NoParams) -> ToolResult:
+    route = "codes.latest_release"
+    _, manifest = _load_manifest()
+    today = _today()
+    listing, latest_fy, latest_april = _fetch_release_train()
+
+    warnings: list[str] = []
+    resolution = resolve_cm_release(today, manifest)
+    if isinstance(resolution, CmUnresolved):
+        governing = None
+        effective_from = effective_to = None
+        warnings.append(f"{resolution.reason}: {resolution.detail}")
+    else:
+        governing = resolution.release
+        effective_from, effective_to = resolution.effective_from, resolution.effective_to
+
+    governing_fy = today.year + 1 if today.month >= 10 else today.year
+    staged: list[dict[str, Any]] = []
+    for fy in range(governing_fy + 1, latest_fy + 1):
+        starts = date(fy - 1, 10, 1)
+        release = f"fy{fy}"
+        staged.append(
+            {
+                "release": release,
+                "posted": True,
+                "effective_from": starts.isoformat(),
+                "vendored": release in manifest.get("cm_releases", {}),
+                "note": "posted upstream but not yet effective",
+            }
+        )
+        warnings.append(
+            f"FY{fy} ICD-10-CM files are posted upstream, effective {starts.isoformat()}; "
+            f"the pin will need updating before that date (run {REGENERATE}, then "
+            "`hc-source lock init`)."
+        )
+    if latest_april is not None and today < date(latest_april, 4, 1):
+        release = f"fy{latest_april}-april"
+        staged.append(
+            {
+                "release": release,
+                "posted": True,
+                "effective_from": date(latest_april, 4, 1).isoformat(),
+                "vendored": release in manifest.get("cm_releases", {}),
+                "note": "posted upstream but not yet effective",
+            }
+        )
+        warnings.append(
+            f"An April 1 {latest_april} ICD-10-CM update is posted upstream, effective "
+            f"{date(latest_april, 4, 1).isoformat()}; the pin will need updating before "
+            f"that date (run {REGENERATE}, then `hc-source lock init`)."
+        )
+
+    hcpcs_governing = _quarter_label(today)
+    hcpcs_next = _next_quarter(hcpcs_governing)
+    next_posted = _probe_zip(hcpcs_next)
+    if next_posted:
+        starts = _quarter_start(hcpcs_next)
+        warnings.append(
+            f"The {hcpcs_next} HCPCS Level II quarterly is posted upstream, effective "
+            f"{starts.isoformat()}; the pin will need updating before that date (run "
+            f"{REGENERATE}, then `hc-source lock init`)."
+        )
+
+    data = {
+        "as_of": today.isoformat(),
+        "icd10cm": {
+            "governing_release": governing,
+            "vendored": governing in manifest.get("cm_releases", {}) if governing else False,
+            "upstream_latest_posted_fy": latest_fy,
+            "upstream_latest_april_update_fy": latest_april,
+            "staged_releases": staged,
+        },
+        "hcpcs_level_ii": {
+            "governing_quarter": hcpcs_governing,
+            "vendored": hcpcs_governing in manifest.get("hcpcs_releases", {}),
+            "next_quarter": hcpcs_next,
+            "next_quarter_posted": next_posted,
+        },
+    }
+    return ToolResult(
+        data=data,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route=route,
+            fetch=listing,
+            source_version=governing or "unresolved",
+            transform_version=TRANSFORM_VERSION,
+            effective_from=effective_from,
+            effective_to=effective_to,
+            warnings=warnings,
+            non_claims=NON_CLAIMS,
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Canaries
+# ---------------------------------------------------------------------------
+
+
+def _observe_cm_governing() -> CanaryObservation:
+    _, manifest = _load_manifest()
+    resolution = resolve_cm_release(_today(), manifest)
+    if isinstance(resolution, CmUnresolved):
+        return CanaryObservation(
+            value=f"unresolved:{resolution.reason}",
+            note="no vendored ICD-10-CM release provably governs today's date",
+        )
+    return CanaryObservation(
+        value=resolution.release,
+        note="ICD-10-CM release governing today's date, from the vendored manifest",
+    )
+
+
+def _cm_governing_remediation(status: CanaryStatus, observed, expected) -> str:
+    if status is CanaryStatus.UNREACHABLE:
+        return (
+            "The vendored manifest could not be read. Check HC_SOURCE_CODES_DATA if set, "
+            f"otherwise restore hc_source/data/codes ({REGENERATE}), then re-run "
+            "`hc-source doctor`."
+        )
+    return (
+        f"The ICD-10-CM release governing today's date is {observed}, but source-lock.json "
+        f"pins {expected}: the pin is no longer correct for today. Update the vendored "
+        f"release train in hc_source/data/codes/regenerate.py (add the new FY or "
+        f"April release to CM_RELEASES and settle CM_APRIL_STATUS), run it "
+        f"({REGENERATE}), then re-pin with `hc-source lock init`."
+    )
+
+
+def _observe_hcpcs_governing() -> CanaryObservation:
+    _, manifest = _load_manifest()
+    label = _quarter_label(_today())
+    vendored = label in manifest.get("hcpcs_releases", {})
+    return CanaryObservation(
+        value=label if vendored else f"{label}:unvendored",
+        note="HCPCS quarterly governing today's date, from the vendored manifest",
+    )
+
+
+def _hcpcs_governing_remediation(status: CanaryStatus, observed, expected) -> str:
+    if status is CanaryStatus.UNREACHABLE:
+        return (
+            "The vendored manifest could not be read. Check HC_SOURCE_CODES_DATA if set, "
+            f"otherwise restore hc_source/data/codes ({REGENERATE}), then re-run "
+            "`hc-source doctor`."
+        )
+    return (
+        f"The HCPCS quarterly governing today's date is {observed}, but source-lock.json "
+        f"pins {expected}: the pin is no longer correct for today. Add the quarter to "
+        f"HCPCS_RELEASES in hc_source/data/codes/regenerate.py, run it "
+        f"({REGENERATE}), then re-pin with `hc-source lock init`."
+    )
+
+
+def _observe_vendored_tables() -> CanaryObservation:
+    _, manifest = _load_manifest()
+    tables = sorted(
+        {
+            entry["table"]
+            for section in ("cm_releases", "hcpcs_releases")
+            for entry in manifest.get(section, {}).values()
+        }
+    )
+    row_lines: list[str] = []
+    header_lines: list[str] = []
+    for name in tables:
+        path = _data_dir() / name
+        try:
+            raw = gzip.decompress(path.read_bytes())
+        except (OSError, gzip.BadGzipFile, EOFError) as exc:
+            raise SourceUnreachable(path.as_uri(), type(exc).__name__) from exc
+        header, _, body = raw.decode("utf-8").partition("\n")
+        row_lines.append(f"{name}:{hashlib.sha256(body.encode('utf-8')).hexdigest()}")
+        header_lines.append(f"{name}:{header}")
+    return CanaryObservation(
+        value=hashlib.sha256("\n".join(row_lines).encode("utf-8")).hexdigest(),
+        schema_hash=hashlib.sha256("\n".join(header_lines).encode("utf-8")).hexdigest(),
+        note=f"canonical content digest of {len(tables)} vendored derived tables",
+    )
+
+
+def _vendored_tables_remediation(status: CanaryStatus, observed, expected) -> str:
+    if status is CanaryStatus.SCHEMA_CHANGED:
+        return (
+            "A vendored derived table changed its column set without changing its rows. "
+            "If the derivation changed on purpose, bump TRANSFORM_VERSION in "
+            "hc_source/adapters/codes.py, review the manifest.json diff, and re-pin with "
+            "`hc-source lock init`; otherwise restore the table from git."
+        )
+    return (
+        "The vendored derived tables changed on disk without a re-pin. If you just "
+        f"regenerated them ({REGENERATE}), review the manifest.json diff (canonical "
+        "hashes and row counts) and re-pin with `hc-source lock init`; otherwise "
+        "restore hc_source/data/codes from git -- the answers no longer match "
+        "what the lockfile attests."
+    )
+
+
+def _cm_train_observation(
+    result: FetchResult, latest_fy: int, latest_april: int | None
+) -> CanaryObservation:
+    """Build the observation, carrying WHICH source answered.
+
+    The CDC directory listing is the authority; the CMS landing page is a
+    mirror. Round-1 finding H2: this canary reported `ok` while ftp.cdc.gov was
+    dark, because the observation had nowhere to record that a mirror had
+    answered. The transport tracked it correctly the whole time.
+    """
+    april = f"fy{latest_april}" if latest_april is not None else "none"
+    return CanaryObservation(
+        value=f"latest_posted=fy{latest_fy};latest_april={april}",
+        upstream_status=result.status,
+        note="latest ICD-10-CM FY and April update posted upstream (posted != effective)",
+        fallback_used=result.fallback_used,
+        fallback_name=result.fallback_name,
+    )
+
+
+def _observe_cm_train() -> CanaryObservation:
+    return _cm_train_observation(*_fetch_release_train())
+
+
+def _cm_train_remediation(status: CanaryStatus, observed, expected) -> str:
+    if status is CanaryStatus.UNREACHABLE:
+        return (
+            "Neither the CDC ICD-10-CM directory listing nor the CMS landing page could "
+            "be read or recognized. Retry in an hour; if it persists, check "
+            f"{CDC_LISTING_URL} and {CMS_LANDING_URL} in a browser before touching the "
+            "pin."
+        )
+    return (
+        f"The ICD-10-CM release train moved upstream: observed {observed}, pinned "
+        f"{expected}. A newly posted FY file set takes effect on October 1 and a newly "
+        "posted April update on April 1 -- posted is not effective, so this is staged, "
+        "not an emergency. Before the effective date: add the new release to "
+        "CM_RELEASES (and settle CM_APRIL_STATUS) in "
+        f"hc_source/data/codes/regenerate.py, run it ({REGENERATE}), then re-pin "
+        "with `hc-source lock init`."
+    )
+
+
+def _observe_hcpcs_train() -> CanaryObservation:
+    today = _today()
+    current = _quarter_label(today)
+    upcoming = _next_quarter(current)
+    current_state = "posted" if _probe_zip(current) else "absent"
+    next_state = "posted" if _probe_zip(upcoming) else "absent"
+    return CanaryObservation(
+        value=f"current={current}:{current_state};next={upcoming}:{next_state}",
+        note="HCPCS quarterly slugs posted upstream (range-probe; posted != effective)",
+    )
+
+
+def _hcpcs_train_remediation(status: CanaryStatus, observed, expected) -> str:
+    if status is CanaryStatus.UNREACHABLE:
+        return (
+            "A HCPCS quarterly probe failed or returned non-ZIP bytes. Do not re-pin "
+            f"automatically: retry in an hour, then re-verify via {HCPCS_INDEX_URL} "
+            "before re-locking."
+        )
+    posted = re.search(r"next=(\d{4}q\d):posted", observed or "")
+    staged_line = ""
+    if posted:
+        starts = _quarter_start(posted.group(1))
+        staged_line = (
+            f" The {posted.group(1)} file takes effect {starts.isoformat()} -- staged, "
+            "not an emergency; vendor it before that date."
+        )
+    return (
+        f"The HCPCS quarterly train moved: observed {observed}, pinned {expected}."
+        f"{staged_line} Add the quarter to HCPCS_RELEASES in "
+        f"hc_source/data/codes/regenerate.py, run it ({REGENERATE}), then re-pin "
+        "with `hc-source lock init`. If the current quarter went absent, CMS renamed "
+        f"the slug: re-scrape {HCPCS_INDEX_URL}."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Adapter
+# ---------------------------------------------------------------------------
+
+
+class CodesAdapter(SourceAdapter):
+    source_id = SOURCE_ID
+    contract = CONTRACT
+
+    # Mixed: the vendored-table canaries never touch the network, the release
+    # trains do. Retries only ever fire on a transient SourceUnreachable, so
+    # declaring them at the adapter costs the offline canaries nothing.
+    canary_retries = 2
+
+    def canaries(self) -> list[Canary]:
+        return [
+            Canary(
+                canary_id="codes.cm_governing_release",
+                source_id=SOURCE_ID,
+                description=(
+                    "ICD-10-CM release governing today's date (clock + vendored "
+                    "manifest; drifts exactly when the pin stops being correct for "
+                    "today, e.g. on October 1)."
+                ),
+                observe=_observe_cm_governing,
+                remediation=(
+                    "The ICD-10-CM release governing today is no longer the pinned one. "
+                    f"Re-vendor ({REGENERATE}) and re-pin with `hc-source lock init`."
+                ),
+                remediation_for=_cm_governing_remediation,
+            ),
+            Canary(
+                canary_id="codes.hcpcs_governing_quarter",
+                source_id=SOURCE_ID,
+                description=(
+                    "HCPCS Level II quarterly governing today's date (clock + vendored "
+                    "manifest)."
+                ),
+                observe=_observe_hcpcs_governing,
+                remediation=(
+                    "The HCPCS quarterly governing today is no longer the pinned one. "
+                    f"Re-vendor ({REGENERATE}) and re-pin with `hc-source lock init`."
+                ),
+                remediation_for=_hcpcs_governing_remediation,
+            ),
+            Canary(
+                canary_id="codes.vendored_tables",
+                source_id=SOURCE_ID,
+                description=(
+                    "Canonical content digest (seed hashes) of the vendored derived "
+                    "tables; schema hash covers their column sets."
+                ),
+                observe=_observe_vendored_tables,
+                remediation=(
+                    "The vendored derived tables changed on disk. Review the diff and "
+                    "re-pin with `hc-source lock init`, or restore them from git."
+                ),
+                remediation_for=_vendored_tables_remediation,
+            ),
+            Canary(
+                canary_id="codes.cm_release_train",
+                source_id=SOURCE_ID,
+                description=(
+                    "Latest ICD-10-CM FY and April update posted upstream (CDC listing, "
+                    "CMS landing-page fallback). Future-effective postings are pinned as "
+                    "observed, so a staged release never alarms by itself."
+                ),
+                observe=_observe_cm_train,
+                remediation=(
+                    "The ICD-10-CM release train moved upstream. Posted is not "
+                    f"effective: vendor the new release ({REGENERATE}) and re-pin with "
+                    "`hc-source lock init` before its effective date."
+                ),
+                remediation_for=_cm_train_remediation,
+            ),
+            Canary(
+                canary_id="codes.hcpcs_release_train",
+                source_id=SOURCE_ID,
+                description=(
+                    "HCPCS quarterly slugs posted upstream (4-byte range probes of the "
+                    "current and next quarter, both slug variants)."
+                ),
+                observe=_observe_hcpcs_train,
+                remediation=(
+                    "The HCPCS quarterly train moved upstream. Vendor the new quarter "
+                    f"({REGENERATE}) and re-pin with `hc-source lock init` before it "
+                    "takes effect."
+                ),
+                remediation_for=_hcpcs_train_remediation,
+            ),
+        ]
+
+    def tools(self) -> list[ToolSpec]:
+        return [
+            ToolSpec(
+                name="codes.valid_on",
+                description=(
+                    "Answer whether an ICD-10-CM code is valid/billable on a date of "
+                    "service, from the vendored release governing that date; fails "
+                    "closed when no vendored release provably governs it."
+                ),
+                params_model=ValidOnParams,
+                handler=_valid_on,
+                tags=("validity", "icd10cm"),
+            ),
+            ToolSpec(
+                name="codes.lookup",
+                description=(
+                    "Look up an ICD-10-CM code's description with full release "
+                    "provenance, from the release governing the given (or today's) "
+                    "date of service."
+                ),
+                params_model=LookupParams,
+                handler=_lookup,
+                tags=("lookup", "icd10cm"),
+            ),
+            ToolSpec(
+                name="codes.hcpcs_lookup",
+                description=(
+                    "Look up a HCPCS Level II code or modifier in the pinned quarterly "
+                    "file; with a date of service, adds a validity verdict from the "
+                    "record's code-added/termination interval."
+                ),
+                params_model=HcpcsLookupParams,
+                handler=_hcpcs_lookup,
+                tags=("lookup", "hcpcs"),
+            ),
+            ToolSpec(
+                name="codes.latest_release",
+                description=(
+                    "Detect the current and staged ICD-10-CM/HCPCS releases: what "
+                    "governs today (from the vendored manifest) and what is posted "
+                    "upstream (live CDC/CMS probe), with staged-release warnings."
+                ),
+                params_model=NoParams,
+                handler=_latest_release,
+                tags=("metadata", "release"),
+            ),
+        ]
+
+
+ADAPTER = CodesAdapter()