sourcelock 0.1.0__py3-none-any.whl

hc_source/receipts.py

@@ -0,0 +1,74 @@
+"""Receipt construction.
+
+Adapters build receipts through :func:`build_receipt` so that provenance is
+filled in from the fetch itself rather than retyped, and so that every receipt
+carries the zero-PHI non-claim without the author remembering it.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import Sequence
+
+from .guard import PHI_NON_CLAIM
+from .http import FetchResult
+from .schemas import Receipt, SourceContract
+
+__all__ = ["build_receipt"]
+
+
+def build_receipt(
+    *,
+    contract: SourceContract,
+    route: str,
+    fetch: FetchResult,
+    source_version: str,
+    transform_version: str,
+    non_claims: Sequence[str],
+    effective_from: date | None = None,
+    effective_to: date | None = None,
+    warnings: Sequence[str] | None = None,
+) -> Receipt:
+    """Assemble a receipt from a fetch result.
+
+    ``non_claims`` is required and must be non-empty: state at least one thing
+    this result does not prove, in the language of your source. The zero-PHI
+    non-claim is prepended for you.
+
+    ``retrieved_at`` comes from ``fetch``, not from the clock. This function used
+    to stamp ``utcnow()`` here, which meant every answer served out of an adapter's
+    process cache -- the LEIE snapshot, the coverage bulk crosswalk, the vendored
+    code files -- carried a receipt claiming bytes had just been read from CMS.
+    """
+    domain_claims = [c for c in non_claims if c.strip() and c != PHI_NON_CLAIM]
+    if not domain_claims:
+        raise ValueError(
+            f"{route}: build_receipt requires at least one domain non-claim, e.g. "
+            "'DOES_NOT_PROVE_COVERAGE: an active NPI does not mean the payer covers this service.'"
+        )
+
+    return Receipt(
+        source_id=contract.source_id,
+        route=route,
+        upstream_status=fetch.status,
+        retrieved_at=fetch.retrieved_at,
+        source_version=source_version,
+        effective_from=effective_from,
+        effective_to=effective_to,
+        raw_sha256=fetch.sha256,
+        transform_version=transform_version,
+        fallback_used=fetch.fallback_used,
+        fallback_name=fetch.fallback_name,
+        # Both come from the fetch for the same reason ``retrieved_at`` does: a
+        # cache that renewed either of these would be attesting to a read that
+        # did not happen. Which means an adapter re-answering from its OWN
+        # in-process cache has to say so at the fetch object -- pass
+        # ``hc_source.http.as_cache_hit(meta)``, not the original result. Two
+        # adapters used to pass the original, so their receipts carried a prose
+        # warning saying "served from the in-process cache" beside
+        # ``cache_hit: false``, and the field is what a machine reads.
+        cache_hit=fetch.cache_hit,
+        revalidated_at=fetch.revalidated_at,
+        warnings=list(warnings or []),
+        non_claims=[PHI_NON_CLAIM, *domain_claims],
+    )

hc_source/schemas.py

@@ -0,0 +1,339 @@
+"""Core schemas for SourceLock.
+
+Three of these types are the public contract that route adapters and CI
+consumers depend on:
+
+* ``Receipt``       -- evidence attached to every tool result.
+* ``CanaryResult``  -- one canary observation, as ``hc-source doctor`` reports it.
+* ``SourceContract``-- the promises a source adapter makes about its upstream.
+* ``Lockfile``      -- the pinned state written to ``source-lock.json``.
+
+Everything here is strict: unknown fields are rejected so that a typo in an
+adapter fails loudly at construction rather than silently disappearing from a
+receipt.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import date, datetime, timezone
+from enum import Enum
+from typing import Annotated, Any
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    field_serializer,
+    field_validator,
+    model_validator,
+)
+
+__all__ = [
+    "CanaryResult",
+    "CanarySeverity",
+    "CanaryStatus",
+    "ExpectedCanary",
+    "Lockfile",
+    "LOCKFILE_VERSION",
+    "Receipt",
+    "SourceContract",
+    "SourceLockEntry",
+    "utcnow",
+]
+
+LOCKFILE_VERSION = 1
+
+_SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9_]*$")
+_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+
+Sha256 = Annotated[str, Field(pattern=r"^[0-9a-f]{64}$")]
+
+
+def utcnow() -> datetime:
+    """Current time as a timezone-aware UTC datetime."""
+    return datetime.now(timezone.utc)
+
+
+def _to_utc(value: datetime) -> datetime:
+    if value.tzinfo is None:
+        return value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc)
+
+
+class _Strict(BaseModel):
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+
+class Receipt(_Strict):
+    """Evidence for one tool call.
+
+    A receipt answers: which source, which route, what the upstream said, when,
+    which version of the source and of our transform, the hash of the raw bytes
+    we based the answer on, whether we fell back, and -- explicitly -- what the
+    result does NOT prove.
+    """
+
+    source_id: str = Field(description="Adapter source id, e.g. 'nppes'.")
+    route: str = Field(description="Fully-qualified tool/route name, e.g. 'nppes.lookup_npi'.")
+    upstream_status: int | None = Field(
+        default=None, description="HTTP status of the upstream call, or None for local sources."
+    )
+    retrieved_at: datetime = Field(description="When the upstream bytes were retrieved (UTC).")
+    source_version: str = Field(description="Upstream release/version identifier.")
+    effective_from: date | None = Field(
+        default=None, description="First date this data is in force, per the source contract."
+    )
+    effective_to: date | None = Field(
+        default=None, description="Last date this data is in force; None means open-ended."
+    )
+    raw_sha256: Sha256 = Field(description="SHA-256 of the raw upstream bytes.")
+    transform_version: str = Field(
+        description="Version of the adapter transform that produced the result."
+    )
+    fallback_used: bool = Field(default=False, description="True if the fallback source was used.")
+    fallback_name: str | None = Field(
+        default=None, description="Name of the fallback used; required when fallback_used is True."
+    )
+    cache_hit: bool = Field(
+        default=False,
+        description=(
+            "True when the bytes behind this answer came out of a cache rather "
+            "than off the wire. `retrieved_at` still reports when they were "
+            "RETRIEVED -- a cache that renewed that timestamp would be inventing "
+            "a read that did not happen."
+        ),
+    )
+    revalidated_at: datetime | None = Field(
+        default=None,
+        description=(
+            "When upstream last confirmed these bytes are current: the moment of "
+            "the 304 on a cache hit, the moment of the download otherwise. Kept "
+            "apart from retrieved_at because 'you still have the right bytes' and "
+            "'these bytes are new' are different claims."
+        ),
+    )
+    warnings: list[str] = Field(default_factory=list)
+    non_claims: list[str] = Field(
+        default_factory=list,
+        description="Explicit statements of what this result does NOT prove.",
+    )
+
+    @field_validator("revalidated_at")
+    @classmethod
+    def _utc_optional(cls, v: datetime | None) -> datetime | None:
+        return _to_utc(v) if v is not None else None
+
+    @field_serializer("revalidated_at")
+    def _ser_optional_dt(self, v: datetime | None) -> str | None:
+        return _to_utc(v).isoformat() if v is not None else None
+
+    @field_validator("source_id")
+    @classmethod
+    def _slug(cls, v: str) -> str:
+        if not _SLUG_RE.match(v):
+            raise ValueError("source_id must be a lowercase slug ([a-z0-9_], not starting with _)")
+        return v
+
+    @field_validator("retrieved_at")
+    @classmethod
+    def _utc(cls, v: datetime) -> datetime:
+        return _to_utc(v)
+
+    @field_serializer("retrieved_at")
+    def _ser_dt(self, v: datetime) -> str:
+        return _to_utc(v).isoformat()
+
+    @model_validator(mode="after")
+    def _fallback_consistency(self) -> Receipt:
+        if self.fallback_used and not (self.fallback_name or "").strip():
+            raise ValueError("fallback_used=True requires fallback_name")
+        if not self.fallback_used and self.fallback_name:
+            raise ValueError("fallback_name set but fallback_used is False")
+        if self.effective_from and self.effective_to and self.effective_to < self.effective_from:
+            raise ValueError("effective_to precedes effective_from")
+        return self
+
+
+class CanaryStatus(str, Enum):
+    OK = "ok"
+    DRIFT = "drift"
+    UNREACHABLE = "unreachable"
+    SCHEMA_CHANGED = "schema_changed"
+    #: Observed successfully but never compared, because nothing pinned it.
+    #: Deliberately not ``ok``: a summary that says "22 ok, 0 drift" when
+    #: nothing was compared is a green build that verified nothing.
+    UNPINNED = "unpinned"
+    #: Compared and matched, but the canary itself reported that what it read is
+    #: out of date -- a weekly snapshot that has not moved in a month, a
+    #: cross-check it had to skip. An `ok` computed from data the canary says is
+    #: stale is not assurance, so it does not get to be `ok`.
+    STALE = "stale"
+    #: The canary raised something that is not a transport failure. Upstream may
+    #: be perfectly healthy; SourceLock's own code is what broke. Kept apart from
+    #: `unreachable` so "CMS is down" and "our adapter has a bug" are not the
+    #: same line in a CI log -- they have completely different fixes.
+    ERROR = "error"
+
+
+class CanarySeverity(str, Enum):
+    """Whether a finding from this canary may fail somebody's build.
+
+    Status and severity are different questions, and conflating them is how a
+    check that watches an HTML page CMS restyles quarterly ends up blocking a
+    release. `drift` is `drift` either way -- it is reported, annotated, and
+    counted. Severity only decides whether it reaches the exit code.
+    """
+
+    BLOCKING = "blocking"
+    ADVISORY = "advisory"
+
+
+class CanaryResult(_Strict):
+    """The outcome of one canary, as reported by ``hc-source doctor``."""
+
+    canary_id: str
+    source_id: str
+    status: CanaryStatus
+    severity: CanarySeverity = Field(
+        default=CanarySeverity.BLOCKING,
+        description=(
+            "Whether this canary's finding counts toward the exit code. Advisory "
+            "findings are reported in full and excluded from the verdict."
+        ),
+    )
+    attempts: int = Field(
+        default=1,
+        ge=1,
+        description=(
+            "How many times the observation was attempted. Greater than one means "
+            "a transient upstream failure was retried -- worth seeing on a canary "
+            "that reports ok, because 'ok on the third try' is a different fact "
+            "about the source than 'ok'."
+        ),
+    )
+    observed: str | None = Field(default=None, description="What we saw upstream.")
+    expected: str | None = Field(default=None, description="What source-lock.json pinned.")
+    checked_at: datetime
+    remediation: str = Field(
+        default="",
+        description="Exact human-readable fix. Required for any non-ok status.",
+    )
+    warnings: list[str] = Field(default_factory=list)
+    fallback_used: bool = Field(
+        default=False,
+        description=(
+            "True when a mirror answered because the pinned authority could not be read. "
+            "An `ok` from a mirror is not the same claim as an `ok` from the authority."
+        ),
+    )
+    fallback_name: str | None = Field(
+        default=None, description="Which mirror answered, when fallback_used is True."
+    )
+
+    @field_validator("checked_at")
+    @classmethod
+    def _utc(cls, v: datetime) -> datetime:
+        return _to_utc(v)
+
+    @field_serializer("checked_at")
+    def _ser_dt(self, v: datetime) -> str:
+        return _to_utc(v).isoformat()
+
+    @model_validator(mode="after")
+    def _remediation_required(self) -> CanaryResult:
+        if self.status is not CanaryStatus.OK and not self.remediation.strip():
+            raise ValueError(f"status={self.status.value} requires non-empty remediation text")
+        return self
+
+    @property
+    def ok(self) -> bool:
+        return self.status is CanaryStatus.OK
+
+
+class SourceContract(_Strict):
+    """The unit of value: what a source promises and how to read its dates."""
+
+    source_id: str
+    authority_url: str = Field(description="The one canonical, citable upstream URL.")
+    fallback_url: str | None = Field(
+        default=None, description="Mirror used only when the authority is unreachable."
+    )
+    license_notes: str = Field(description="Redistribution/attribution terms in plain language.")
+    cadence: str = Field(description="How often upstream publishes, e.g. 'quarterly'.")
+    effective_date_semantics: str = Field(
+        description="What effective_from/effective_to mean for THIS source."
+    )
+    invariants: list[str] = Field(
+        default_factory=list,
+        description="Statements that must hold upstream; canaries should test these.",
+    )
+
+    @field_validator("source_id")
+    @classmethod
+    def _slug(cls, v: str) -> str:
+        if not _SLUG_RE.match(v):
+            raise ValueError("source_id must be a lowercase slug ([a-z0-9_], not starting with _)")
+        return v
+
+
+class ExpectedCanary(_Strict):
+    """The pinned expectation for one canary."""
+
+    value: str
+    schema_hash: str | None = None
+
+
+class SourceLockEntry(_Strict):
+    """Pinned state for one source inside ``source-lock.json``."""
+
+    source_id: str
+    pinned_version: str
+    release_id: str | None = None
+    schema_hash: str | None = None
+    checked_at: datetime
+    expected_canaries: dict[str, ExpectedCanary] = Field(default_factory=dict)
+
+    @field_validator("checked_at")
+    @classmethod
+    def _utc(cls, v: datetime) -> datetime:
+        return _to_utc(v)
+
+    @field_serializer("checked_at")
+    def _ser_dt(self, v: datetime) -> str:
+        return _to_utc(v).isoformat()
+
+
+class Lockfile(_Strict):
+    """``source-lock.json``: what CI compares today's upstream against."""
+
+    lockfile_version: int = LOCKFILE_VERSION
+    generated_at: datetime
+    sources: dict[str, SourceLockEntry] = Field(default_factory=dict)
+
+    @field_validator("generated_at")
+    @classmethod
+    def _utc(cls, v: datetime) -> datetime:
+        return _to_utc(v)
+
+    @field_serializer("generated_at")
+    def _ser_dt(self, v: datetime) -> str:
+        return _to_utc(v).isoformat()
+
+    @model_validator(mode="after")
+    def _keys_match(self) -> Lockfile:
+        for key, entry in self.sources.items():
+            if key != entry.source_id:
+                raise ValueError(f"lockfile key {key!r} does not match source_id {entry.source_id!r}")
+        return self
+
+    def expected_canary_ids(self) -> set[str]:
+        return {cid for entry in self.sources.values() for cid in entry.expected_canaries}
+
+    def expectation(self, source_id: str, canary_id: str) -> ExpectedCanary | None:
+        entry = self.sources.get(source_id)
+        return entry.expected_canaries.get(canary_id) if entry else None
+
+
+def is_sha256(value: Any) -> bool:
+    return isinstance(value, str) and bool(_SHA256_RE.match(value))

sourcelock-0.1.0.dist-info/METADATA

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: sourcelock
+Version: 0.1.0
+Summary: Zero-PHI source-assurance CLI for healthcare's public data inputs
+Author: SourceLock
+License: MIT License
+        
+        Copyright (c) 2026 SourceLock
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: mcp==2.0.0
+Requires-Dist: pydantic<3.0,>=2.7
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SourceLock
+
+**Every answer comes with a receipt, and your build fails when the source moves.**
+
+SourceLock reads the public data healthcare software runs on — CMS coverage
+policy, NPPES and PECOS, ICD-10-CM and HCPCS releases, CMS-HCC risk models, the
+OIG LEIE — and returns, with every answer, the release it came from, the SHA-256
+of the raw bytes behind it, when those bytes were retrieved, and what the answer
+does not prove. `hc-source lock init` pins those sources in a `source-lock.json`;
+`hc-source doctor` verifies that pin and fails CI the day one of them changes
+underneath you.
+
+## Install
+
+```
+git clone https://github.com/writtenonwater99/sourcelock
+cd sourcelock
+pipx install .
+```
+
+Python 3.11 or newer. There is no PyPI release yet, so `pip install sourcelock`
+does not work and this file does not pretend it does — see
+[RELEASING.md](RELEASING.md) for what publishing takes.
+
+## See it work, offline, right now
+
+```
+hc-source valid-on E11.9 2026-07-01
+```
+
+No network, no credentials, no lockfile. The release tables are vendored, so
+that command answers in under a second on a plane:
+
+```json
+{
+  "code": "E11.9",
+  "code_nodot": "E119",
+  "code_system": "ICD-10-CM",
+  "date": "2026-07-01",
+  "valid": true,
+  "description": "Type 2 diabetes mellitus without complications",
+  "release": "fy2026-april",
+  "release_effective_from": "2026-04-01",
+  "release_effective_to": "2026-09-30"
+}
+```
+
+followed by the receipt — source, route, release, effective window, retrieval
+time, upstream status, the hash of the bytes the answer was derived from, the
+transform version, and whether a mirror answered — and then the part most tools
+leave out. Four non-claims, printed in full; the first line of each:
+
+```
+does not prove:
+  - PHI_NOT_EXPECTED: this tool accepts only public typed parameters.
+  - DOES_NOT_INCLUDE_CPT_DESCRIPTORS: no HCPCS Level I (CPT) record and no ADA
+  - DOES_NOT_PROVE_COVERAGE: a code being valid for a date of service says
+  - DOES_NOT_PROVE_CURRENCY: answers come from the release train vendored at
+```
+
+The real output does not wrap and does not trail off: the CPT one runs to a
+paragraph naming all seventeen CMS descriptions that quote a CPT number, because
+that is what an AMA licence question actually needs. These four are what
+`codes.valid_on` claims it cannot tell you — every one of them, not a
+representative sample, and nothing this product does not actually print.
+
+## What it is for
+
+If you are building AI or automation over revenue-cycle data, you have run into
+some version of this:
+
+- **A model cited a code set and nobody can say which release.** Every answer
+  here carries `source_version`, `effective_from`/`effective_to`, and
+  `raw_sha256`. That is an audit trail, not a log line.
+- **A pipeline broke because CMS renamed something.** NPPES retired its V1 bulk
+  filenames on 2026-03-03; jobs that still generated them got silent 404s.
+  `hc-source lock init` pins 23 cheap checks across six sources and `hc-source
+  doctor` fails the build the day one moves — with the fix, not a stack trace.
+- **An agent will confidently answer from a stale cache.** Receipts distinguish
+  when bytes were *retrieved* from when upstream last *confirmed* them, a canary
+  that read out-of-date data is not allowed to report `ok`, and a source that
+  could not be read is never reported as unchanged.
+- **Your reference data is not all public.** Sources are plugins. Your licensed
+  AMA CPT tables can be a first-class adapter without forking anything.
+- **PHI must not end up in a tool call.** Parameters are public and typed, no
+  receipt or log carries a payload, and a guard refuses input shaped like a
+  patient record. It is a structural best-effort refusal, not a HIPAA control:
+  `hc_source/guard.py` states exactly what it detects and, just as plainly,
+  which evasion classes it does not close.
+
+## The six sources
+
+| source     | what it answers                                                             |
+|------------|-----------------------------------------------------------------------------|
+| `codes`    | ICD-10-CM / HCPCS Level II validity on a date of service, release trains    |
+| `hcc`      | CMS-HCC V24/V28 mapping, hierarchies, community continuing-enrollee scoring |
+| `provider` | NPI Registry lookups, NPPES bulk-file cadence, PECOS enrollment snapshot    |
+| `coverage` | CMS coverage policy: NCDs, LCDs and articles, MCD weekly snapshot identity  |
+| `leie`     | OIG LEIE exclusion checks by NPI, candidate search, monthly refresh status  |
+| `demo`     | packaged reference adapter used in tests and examples                       |
+
+`codes` and `hcc` answer offline from vendored release data. The rest read live
+CMS and OIG endpoints.
+
+## Everyday commands
+
+```
+hc-source valid-on E11.9 2026-07-01                     # offline
+hc-source hcc score --dx E11.9,I50.9 --model v28 --year 2026 --age 72 --sex F
+hc-source lookup-npi 1003000126                         # NPPES
+hc-source check-npi 1003000126                          # OIG LEIE screen
+hc-source tools                                         # every route, with its parameters
+hc-source call coverage.lookup_ncd --param section=30.3 # the general form
+hc-source mcp                                           # serve it all to an agent over MCP
+```
+
+`call` reaches every route, including ones provided by adapters you installed;
+the named commands are shorthand for the four questions people arrive with.
+
+## Pin your sources and fail the build when they move
+
+```
+hc-source lock init      # observe all six sources, write source-lock.json
+hc-source doctor         # re-check upstream against the lockfile
+hc-source init --ci      # scaffold the GitHub Actions workflow
+```
+
+Commit `source-lock.json` and review its diffs like any other lockfile. A green
+run ends with:
+
+```
+23 ok, 0 drift, 0 unreachable, 0 schema_changed, 0 unpinned, 0 stale, 0 error
+```
+
+Exit codes are the contract: `0` everything matched, `1` drift or schema change,
+`2` a source was unreachable or an adapter broke, `3` a canary was observed but
+nothing pinned it, `4` everything matched but something reported that what it
+read is out of date. `3` and `4` exist because a missing `source-lock.json` used
+to report `23 ok, 0 drift` at exit 0 — a build that verified nothing, reporting
+green. Full CI setup, per-canary severity, and the `on-unreachable` /
+`on-stale` policies: [docs/ci.md](docs/ci.md).
+
+## Watch it catch drift, in 90 seconds
+
+You do not have to wait for CMS to change something. NPPES really did retire its
+V1 bulk-file names on 2026-03-03. The repo carries a recording of what the
+listing page would look like if that class of change happened again:
+
+```
+hc-source lock init
+HC_SOURCE_PROVIDER_NPPES_FILES_URL="file://$PWD/tests/fixtures/provider/npi_files_v1_only.html" \
+  hc-source doctor --source provider
+```
+
+Doctor exits `1`, marks `provider.nppes_v2_files` as `drift`, and prints:
+
+```
+provider.nppes_v2_files [drift]: NPPES retired the V1 bulk files on 2026-03-03; only
+*_V2.zip names are published now (V2 extends the First Name and Legal Business Name
+field lengths). The listing this canary just read carries a V1-style name with no _V2
+suffix, which means the page has regressed, a stale mirror is being served, or
+something upstream renamed the grammar again. Fix: open
+https://download.cms.gov/nppes/NPI_Files.html, read the 'Important Information' block
+(where CMS announced the V1 retirement), confirm the current version suffix, make sure
+nothing in your pipeline still generates V1 filenames
+(NPPES_Data_Dissemination_<Month>_<YYYY>.zip silently 404s), then re-pin with
+`hc-source lock init`.
+```
+
+Run it again without the override and it goes back to green. That is the whole
+product: pin what your build depends on, and get told — with an instruction, not
+a stack trace — the moment upstream moves.
+
+## For agents
+
+`hc-source mcp` serves every discovered tool over MCP stdio: one MCP tool per
+route, the same typed parameters, the same receipts, the same PHI refusals as
+the CLI. It refuses to start if any adapter failed to import, because an agent
+that sees a short `tools/list` reads it as the whole product.
+
+Responses are cached on disk and revalidated conditionally — an entry is stored
+only if the response carried an `ETag` or a `Last-Modified`, and a hit is a
+request that came back `304`, so cached bytes are ones the source confirmed a
+moment ago. A cache hit still reports when its bytes were *retrieved*, with a
+`cache_hit` flag, rather than claiming a fresh read.
+
+**How much it helps depends entirely on whether upstream sends validators, and
+that varies a lot.** Measured here against live sources, median of five runs
+each:
+
+| command | cold | warm |
+| --- | --- | --- |
+| `hc-source call leie.check_npi --param npi=…` (15.5 MB OIG file) | 2.78s | **0.90s** |
+| `hc-source doctor` (23 canaries) | ~6s | ~6s (no reliable difference) |
+
+The LEIE file is served with a `Last-Modified`, so the warm run revalidates it
+in one round trip instead of re-downloading 15.5 MB. `doctor` gets no measurable
+benefit: its canaries are cheap by design, so the round trip already dominates
+what a cache could save. Every path under `api.coverage.cms.gov/v1/` and the
+NPPES NPI Registry API sends **neither** an `ETag` nor a `Last-Modified`, so
+they are re-fetched every time by design — storing a body with no way to
+re-confirm it is exactly the shortcut this product exists not to take.
+`hc-source cache info` lists the endpoints in that state rather than leaving you
+to wonder why the entry count is low.
+
+`hc-source cache info|clear`; `HC_SOURCE_CACHE_DIR` moves or disables it.
+
+## Adding your own source
+
+Three homes, one contract: ship it in the package, publish it as a distribution
+advertising the `sourcelock.adapters` entry point, or drop a file in
+`./.sourcelock/adapters/` and switch that directory on with
+`HC_SOURCE_LOCAL_ADAPTERS=1` (off by default: loading a file from it means
+executing it, so it is never on where a pull request could add one). A
+third-party adapter gets the same validation, the same PHI guard, and the same
+receipts — and cannot claim a built-in source id.
+
+[ADAPTER_GUIDE.md](ADAPTER_GUIDE.md) is the contract;
+[examples/sourcelock-example-adapter/](examples/sourcelock-example-adapter/) is
+a working skeleton with four marked places to change.
+
+## More
+
+- [ADAPTER_GUIDE.md](ADAPTER_GUIDE.md) — writing a source adapter
+- [docs/ci.md](docs/ci.md) — the GitHub Action, severity, and CI policy
+- [RELEASING.md](RELEASING.md) — publishing to PyPI
+- `hc_source/guard.py` — what the PHI guard detects, and what it does not
+
+## License
+
+MIT. See [LICENSE](LICENSE). Source data carries its own terms; each adapter
+records them in its `SourceContract.license_notes`.