sourcelock 0.1.0__tar.gz → 0.2.0__tar.gz

{sourcelock-0.1.0 → sourcelock-0.2.0}/ADAPTER_GUIDE.md

@@ -161,7 +161,14 @@ Rules:
 * Handlers are synchronous and receive the **validated** model.
 * Never call `handler` directly. `ToolSpec.invoke()` is where the zero-PHI guard
   runs; the CLI and the MCP server both go through it.
-* A miss is not an error. Return `data=None` with a warning on the receipt.
+* A miss is an answer, not an error. Return structured non-null data such as
+  `{"found": false}` or `{"matches": [], "match_count": 0}` with an
+  `answered` receipt and a warning. The framework rejects an answered
+  `ToolResult` whose data is null.
+* A deliberate fail-closed refusal is different: return `data=None` and build
+  the receipt with `status=ReceiptStatus.REFUSED` plus a stable uppercase
+  `refusal_code`. CLI route calls exit 3 and MCP marks the structured result as
+  an error. The framework rejects a refused result whose data is non-null.
   Raise only when the source itself failed.
 
 ### Receipts
@@ -395,7 +402,9 @@ to duplicate it. Write tests for the things only you know:
 
 * a successful call, asserting on `data` **and** on the receipt's
   `source_version` and `effective_from`;
-* a miss, asserting `data is None` and a warning rather than an exception;
+* a miss, asserting structured negative data and a warning rather than an exception;
+* a deliberate refusal, asserting `data is None`, `receipt.status == "refused"`,
+  and the exact stable `receipt.refusal_code`;
 * fallback: authority down, mirror up, `receipt.fallback_used is True`;
 * both sources down: `SourceUnreachable`;
 * each canary's happy path, and its drift path from a mutated fixture;

{sourcelock-0.1.0 → sourcelock-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcelock
-Version: 0.1.0
+Version: 0.2.0
 Summary: Zero-PHI source-assurance CLI for healthcare's public data inputs
 Author: SourceLock
 License: MIT License
@@ -53,14 +53,31 @@ underneath you.
 ## Install
 
 ```
-git clone https://github.com/writtenonwater99/sourcelock
-cd sourcelock
-pipx install .
+pipx install sourcelock
 ```
 
-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.
+Python 3.11 or newer. `pip install sourcelock` works too, inside a virtualenv.
+Either way you get one executable: `hc-source`.
+
+## Vendored date-of-service coverage
+
+- **ICD-10-CM: 2023-10-01 through 2027-03-31.** Vendored releases are
+  `fy2024`, `fy2024-april`, `fy2025`, `fy2025-april`, `fy2026`,
+  `fy2026-april`, and `fy2027`. FY2027 is supported only through March 31,
+  2027 because the April 2027 publication status is not yet settled.
+- **HCPCS Level II: 2023-01-01 through 2026-09-30.** Every quarterly public-use
+  file from `2023q1` through `2026q3` is vendored.
+
+CMS's [ICD-10 publication record](https://www.cms.gov/medicare/coding-billing/icd-10-codes)
+defines a distinct FY2025 base window (October 1, 2024 through March 31, 2025)
+and April-update window (April 1 through September 30, 2025). The CDC archive
+retains both upstream ZIPs. Their code-description members are byte-identical,
+so the manifest keeps two release/provenance entries while deduplicating the
+derived table; FY2024's published April update is handled the same way.
+
+Dates outside the windows above fail closed at exit `3` with
+`RELEASE_NOT_VENDORED` (or `AMBIGUOUS_WINDOW` when an April update is not yet
+settled). SourceLock never substitutes a different release's snapshot.
 
 ## See it work, offline, right now
 
@@ -157,6 +174,44 @@ hc-source mcp                                           # serve it all to an age
 `call` reaches every route, including ones provided by adapters you installed;
 the named commands are shorthand for the four questions people arrive with.
 
+## Machine contract for tool calls
+
+This is a breaking CLI contract change for the next release. `hc-source call`
+and the four route shortcuts use these exit codes:
+
+| exit | meaning | trigger |
+| --- | --- | --- |
+| `0` | answer | A positive or negative answer was produced. Negative answers are structured (`found: false`, an empty result list, or LEIE `screen_result: "clear"`); `data` is never null. |
+| `1` | invalid input | The tool name, parameter syntax, PHI guard, or typed parameter validation rejected the call. |
+| `2` | source or adapter failure | The authority could not be read, or the adapter failed unexpectedly or returned an invalid response before it could produce evidenced data. |
+| `3` | deliberate refusal | The route failed closed because the requested release/window/model year cannot be answered from the vendored evidence, or because every HCC diagnosis failed the validity gate without an explicit bypass. `data` is null; `receipt.status` is `"refused"`; `receipt.refusal_code` is stable (for example `AMBIGUOUS_WINDOW`, `RELEASE_NOT_VENDORED`, `REFUSED_MODEL_YEAR`, or `NO_VALID_DIAGNOSES`). |
+
+With `--json`, every one of those paths emits the same top-level shape:
+
+```json
+{
+  "data": {},
+  "receipt": {"status": "answered", "refusal_code": null},
+  "error": null
+}
+```
+
+Exactly one outcome channel is populated: answers carry non-null `data` and an
+`answered` receipt; refusals carry `data: null` and a `refused` receipt;
+validation/source/adapter failures carry `data: null`, `receipt: null`, and a
+structured `error` (`INVALID_INPUT`, `SOURCE_UNREACHABLE`, or
+`ADAPTER_FAILURE`). MCP returns that same envelope as `structuredContent` and
+marks failures and deliberate refusals as MCP errors.
+
+`hcc.score` has no diagnosis/date-of-service parameter, so it uses one explicit
+validity anchor for every payment year: the vendored ICD-10-CM `fy2026-april`
+release, effective 2026-04-01 through 2026-09-30. The answer payload and receipt
+name that release and its hash. A mixed list still scores from its valid codes;
+a valid-but-unmapped code keeps the existing named-unmapped behavior. If every
+code is invalid, the route refuses with `NO_VALID_DIAGNOSES`. Use
+`--allow-demographic-only` (or MCP/call parameter
+`allow_demographic_only=true`) only to opt into a demographic-only partial RAF.
+
 ## Pin your sources and fail the build when they move
 
 ```
@@ -172,7 +227,7 @@ 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,
+Doctor has a separate, unchanged 0–4 verdict 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
@@ -216,7 +271,9 @@ a stack trace — the moment upstream moves.
 `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.
+that sees a short `tools/list` reads it as the whole product. Every MCP result,
+including validation failures, source failures, and deliberate refusals, carries
+the machine envelope documented above in `structuredContent`.
 
 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

{sourcelock-0.1.0 → sourcelock-0.2.0}/README.md

@@ -13,14 +13,31 @@ underneath you.
 ## Install
 
 ```
-git clone https://github.com/writtenonwater99/sourcelock
-cd sourcelock
-pipx install .
+pipx install sourcelock
 ```
 
-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.
+Python 3.11 or newer. `pip install sourcelock` works too, inside a virtualenv.
+Either way you get one executable: `hc-source`.
+
+## Vendored date-of-service coverage
+
+- **ICD-10-CM: 2023-10-01 through 2027-03-31.** Vendored releases are
+  `fy2024`, `fy2024-april`, `fy2025`, `fy2025-april`, `fy2026`,
+  `fy2026-april`, and `fy2027`. FY2027 is supported only through March 31,
+  2027 because the April 2027 publication status is not yet settled.
+- **HCPCS Level II: 2023-01-01 through 2026-09-30.** Every quarterly public-use
+  file from `2023q1` through `2026q3` is vendored.
+
+CMS's [ICD-10 publication record](https://www.cms.gov/medicare/coding-billing/icd-10-codes)
+defines a distinct FY2025 base window (October 1, 2024 through March 31, 2025)
+and April-update window (April 1 through September 30, 2025). The CDC archive
+retains both upstream ZIPs. Their code-description members are byte-identical,
+so the manifest keeps two release/provenance entries while deduplicating the
+derived table; FY2024's published April update is handled the same way.
+
+Dates outside the windows above fail closed at exit `3` with
+`RELEASE_NOT_VENDORED` (or `AMBIGUOUS_WINDOW` when an April update is not yet
+settled). SourceLock never substitutes a different release's snapshot.
 
 ## See it work, offline, right now
 
@@ -117,6 +134,44 @@ hc-source mcp                                           # serve it all to an age
 `call` reaches every route, including ones provided by adapters you installed;
 the named commands are shorthand for the four questions people arrive with.
 
+## Machine contract for tool calls
+
+This is a breaking CLI contract change for the next release. `hc-source call`
+and the four route shortcuts use these exit codes:
+
+| exit | meaning | trigger |
+| --- | --- | --- |
+| `0` | answer | A positive or negative answer was produced. Negative answers are structured (`found: false`, an empty result list, or LEIE `screen_result: "clear"`); `data` is never null. |
+| `1` | invalid input | The tool name, parameter syntax, PHI guard, or typed parameter validation rejected the call. |
+| `2` | source or adapter failure | The authority could not be read, or the adapter failed unexpectedly or returned an invalid response before it could produce evidenced data. |
+| `3` | deliberate refusal | The route failed closed because the requested release/window/model year cannot be answered from the vendored evidence, or because every HCC diagnosis failed the validity gate without an explicit bypass. `data` is null; `receipt.status` is `"refused"`; `receipt.refusal_code` is stable (for example `AMBIGUOUS_WINDOW`, `RELEASE_NOT_VENDORED`, `REFUSED_MODEL_YEAR`, or `NO_VALID_DIAGNOSES`). |
+
+With `--json`, every one of those paths emits the same top-level shape:
+
+```json
+{
+  "data": {},
+  "receipt": {"status": "answered", "refusal_code": null},
+  "error": null
+}
+```
+
+Exactly one outcome channel is populated: answers carry non-null `data` and an
+`answered` receipt; refusals carry `data: null` and a `refused` receipt;
+validation/source/adapter failures carry `data: null`, `receipt: null`, and a
+structured `error` (`INVALID_INPUT`, `SOURCE_UNREACHABLE`, or
+`ADAPTER_FAILURE`). MCP returns that same envelope as `structuredContent` and
+marks failures and deliberate refusals as MCP errors.
+
+`hcc.score` has no diagnosis/date-of-service parameter, so it uses one explicit
+validity anchor for every payment year: the vendored ICD-10-CM `fy2026-april`
+release, effective 2026-04-01 through 2026-09-30. The answer payload and receipt
+name that release and its hash. A mixed list still scores from its valid codes;
+a valid-but-unmapped code keeps the existing named-unmapped behavior. If every
+code is invalid, the route refuses with `NO_VALID_DIAGNOSES`. Use
+`--allow-demographic-only` (or MCP/call parameter
+`allow_demographic_only=true`) only to opt into a demographic-only partial RAF.
+
 ## Pin your sources and fail the build when they move
 
 ```
@@ -132,7 +187,7 @@ 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,
+Doctor has a separate, unchanged 0–4 verdict 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
@@ -176,7 +231,9 @@ a stack trace — the moment upstream moves.
 `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.
+that sees a short `tools/list` reads it as the whole product. Every MCP result,
+including validation failures, source failures, and deliberate refusals, carries
+the machine envelope documented above in `structuredContent`.
 
 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

{sourcelock-0.1.0 → sourcelock-0.2.0}/RELEASING.md

@@ -99,6 +99,16 @@ The third command must print an answer and a receipt without touching the
 network. If it does not, the wheel is missing `hc_source/data/` and the release
 should be yanked rather than patched over.
 
+## Next-version breaking contract note
+
+The next release after `0.1.1` must call out the tool-call contract break:
+deliberate fail-closed outcomes move from exit 0 to exit 3 and carry
+`receipt.status="refused"` plus `receipt.refusal_code`; negative answers carry
+structured non-null data; and `--json`/MCP use one `{data, receipt, error}`
+envelope for answers, refusals, invalid input, and source failures. Doctor's
+existing 0–4 verdict meanings do not change. Do not publish the next version
+without putting that migration note in its release notes.
+
 For the GitHub Release artifacts instead of PyPI:
 
 ```bash

{sourcelock-0.1.0 → sourcelock-0.2.0}/action/action.yml

@@ -9,6 +9,8 @@
 # The job fails (with error annotations carrying each canary's remediation
 # verbatim) whenever doctor reports drift, a schema change, or an unreachable
 # source. See docs/ci.md for the full workflow example.
+# This action consumes doctor's 0-4 verdict contract only. Tool-call exit 3 is
+# a deliberate refusal; doctor exit 3 remains observed-but-unpinned.
 name: "SourceLock Doctor"
 description: >-
   Fail the build when a pinned public healthcare data source drifts, changes

{sourcelock-0.1.0 → sourcelock-0.2.0}/action/run_doctor.py

@@ -22,6 +22,10 @@ Behaviour contract:
 * refuses to report green on a report that contradicts itself -- see
   :func:`reconcile_exit_code`.
 
+These are doctor-specific meanings. Route calls have a separate 0-3 contract
+where exit 3 is a deliberate refusal; this script never invokes a route call and
+must not reinterpret doctor's exit 3 as one.
+
 Local dry-run (no GitHub, no install step)::
 
     python action/run_doctor.py --from-json report.json

{sourcelock-0.1.0 → sourcelock-0.2.0}/docs/ci.md

@@ -7,6 +7,12 @@ source. Every failing canary becomes a GitHub error annotation carrying that
 canary's remediation text verbatim, so the person reading the red build sees
 the fix, not a stack trace.
 
+The action runs **doctor only**, so its exit `3` remains doctor's
+"observed but unpinned" verdict. It does not consume route-call exit codes;
+`hc-source call` and the route shortcuts now use exit `3` for a deliberate
+fail-closed refusal. The two contracts are intentionally namespaced by command
+and are both tabulated in the README.
+
 ## Scaffold it
 
 ```
@@ -117,7 +123,7 @@ action version you pin is exactly the scanner version you run.
 
 ## What failure looks like
 
-Exit codes are doctor's contract: `0` everything matches the lockfile, `1`
+Exit codes here are doctor's unchanged contract: `0` everything matches the lockfile, `1`
 drift or schema change, `2` unreachable source, adapter load failure, or an
 internal adapter error, `3` a canary was observed but nothing pinned it, `4`
 every canary matched but at least one reported that what it read is out of

{sourcelock-0.1.0 → sourcelock-0.2.0}/examples/sourcelock-example-adapter/README.md

@@ -50,6 +50,10 @@ The same things it enforces on itself. There is no privileged path.
 * **Receipts.** `build_receipt` requires at least one domain non-claim and takes
   provenance from the fetch, so you cannot stamp a retrieval time you did not
   perform.
+* **Answer nullability.** An ordinary miss is structured data such as
+  `{"found": false}`. Only a deliberate fail-closed refusal may use
+  `data=None`, and its receipt must say `status="refused"` with a stable
+  `refusal_code`.
 
 ## What a broken plugin looks like
 

{sourcelock-0.1.0 → sourcelock-0.2.0}/examples/sourcelock-example-adapter/sourcelock_example_adapter.py

@@ -45,7 +45,7 @@ from hc_source.schemas import SourceContract
 # name, and every tool you declare must be prefixed with this id.
 SOURCE_ID = "example_formulary"
 
-TRANSFORM_VERSION = "example-formulary-transform/1"
+TRANSFORM_VERSION = "example-formulary-transform/2"
 
 RELEASE_ID = "2026-07"
 _RELEASE_FROM = date(2026, 7, 1)
@@ -136,7 +136,7 @@ def _lookup(params: LookupParams) -> ToolResult:
         )
 
     return ToolResult(
-        data=None if entry is None else {"code": params.code, **entry},
+        data={"found": False} if entry is None else {"code": params.code, **entry},
         receipt=build_receipt(
             contract=CONTRACT,
             route=f"{SOURCE_ID}.lookup",
@@ -200,4 +200,4 @@ class ExampleFormularyAdapter(SourceAdapter):
 
 
 #: The module-level name discovery looks for. Everything above is yours.
-ADAPTER = ExampleFormularyAdapter()
+ADAPTER = ExampleFormularyAdapter()

{sourcelock-0.1.0 → sourcelock-0.2.0}/hc_source/__init__.py

@@ -1,5 +1,5 @@
 """SourceLock: deterministic, provenance-tracked access to public healthcare data sources."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 __all__ = ["__version__"]

{sourcelock-0.1.0 → sourcelock-0.2.0}/hc_source/adapters/_demo.py

@@ -28,7 +28,7 @@ from ..receipts import build_receipt
 from ..schemas import SourceContract
 
 SOURCE_ID = "demo"
-TRANSFORM_VERSION = "1"
+TRANSFORM_VERSION = "2"
 
 #: Environment override, used by the test suite to simulate upstream drift.
 FIXTURE_ENV_VAR = "HC_SOURCE_DEMO_FIXTURE"
@@ -145,7 +145,7 @@ def _lookup_code(params: LookupCodeParams) -> ToolResult:
         )
 
     return ToolResult(
-        data=match,
+        data=match if match is not None else {"found": False},
         receipt=build_receipt(
             contract=CONTRACT,
             route="demo.lookup_code",