feat: record what each entry point reads, with python -m nodrill contract

.github/CODE_OF_CONDUCT.md

@@ -2,7 +2,7 @@
 
 nodrill is not a [Python Software Foundation](https://www.python.org/psf-landing/) project, but everyone interacting in its issues, pull requests and discussions is expected to follow the [PSF Code of Conduct](https://policies.python.org/python.org/code-of-conduct/).
 
-In short: be open, considerate and respectful, whatever anyone's position in the project is.
+In short, be open, considerate and respectful, whatever anyone's position in the project is.
 
 ## Enforcement
 

.github/CONTRIBUTING.md

@@ -16,23 +16,23 @@ make install
 ```
 
 `make install` syncs the locked environment and installs the pre-commit hooks.
-Everything else runs through the `Makefile`; `make help` lists the targets.
+Everything else runs through the `Makefile`, and `make help` lists the targets.
 
 ## The gate
 
 ```bash
-make          # lint, typecheck, coverage, docs, workflow audit — the same order CI runs
+make          # lint, typecheck, coverage, docs, workflow audit, in the order CI runs them
 make -k       # same, but keep going after a failure so one run reports everything
 ```
 
-Individual pieces, when you want a faster loop:
+Individual pieces, for when you want a faster loop.
 
 | Command | What it does |
 | --- | --- |
 | `make format` | ruff format plus the safe ruff fixes |
 | `make lint` | ruff format `--check` and `ruff check` |
 | `make typecheck` | mypy and pyright |
-| `make test` | pytest; `make test ARGS="-k inject -x"` to narrow it |
+| `make test` | pytest, which `make test ARGS="-k inject -x"` narrows |
 | `make testcov` | pytest under coverage with the 100 percent gate |
 | `make docs` | Sphinx with warnings as errors |
 | `make audit` | zizmor over the GitHub Actions workflows |
@@ -44,25 +44,25 @@ A pull request is expected to pass all of it.
 - **Coverage is 100 percent on branches.**
   New code arrives with the tests that cover it.
   A `# pragma: no cover` is not the fix.
-- **Two type checkers.** mypy runs strict over `src` and `tests`; pyright checks `src`.
-  Both must be clean — a few API shapes exist only because the two disagree.
+- **Two type checkers.** mypy runs strict over `src` and `tests`, and pyright checks `src` plus `tests/cycle`.
+  Both must be clean, and a few API shapes exist only because the two disagree.
 - **Ruff with `select = ["ALL"]`.**
   A new ignore goes in `pyproject.toml` with a comment saying why, rather than a bare `# noqa` at the call site.
 - **Docs build with `-W`.**
   A Sphinx warning fails the build here and on Read the Docs.
 
 ## House style
 
-Docstrings are plain PEP 257 prose: an imperative first line, no reStructuredText roles, no bullet lists.
-The reference pages carry the detailed descriptions; docstrings stay terse.
+Docstrings are plain PEP 257 prose, an imperative first line, no reStructuredText roles, no bullet lists.
+The reference pages carry the detailed descriptions, so docstrings stay terse.
 Comments explain why, not what.
 
-Prose in `.md` and `.rst` files uses semantic line breaks: a new sentence starts a new line, so rewording a paragraph shows up as a one-line diff.
-There is no column limit: a sentence stays on one line however long it runs, and nothing is re-wrapped by hand.
-`make lint-md` checks the rest of the Markdown — headings, lists, blank lines — but no tool can check the sentence rule, so that one rides on review.
+Prose in `.md` and `.rst` files uses semantic line breaks, so a new sentence starts a new line and rewording a paragraph shows up as a one-line diff.
+There is no column limit, so a sentence stays on one line however long it runs and nothing is re-wrapped by hand.
+`make lint-md` checks the rest of the Markdown, headings and lists and blank lines, but no tool can check the sentence rule, so that one rides on review.
 
-Public names are load-bearing: `provider`, `use`, `wrap`, `Executor`, `set_default` and `from_ctx` were reviewed and are fixed.
-Propose a rename in an issue; please do not perform one in a pull request.
+Public names are load-bearing, and `provider`, `use`, `wrap`, `Executor`, `set_default` and `from_ctx` were reviewed and are fixed.
+Propose a rename in an issue rather than performing one in a pull request.
 
 ## Reporting a bug
 
@@ -74,5 +74,5 @@ For a security issue, follow [SECURITY.md](SECURITY.md) instead of opening an is
 ## AI-assisted contributions
 
 Using an assistant to write a patch is fine.
-Submitting one you have not read, run and understood is not: you are the author of the pull request, and review time is the scarce resource here.
+Submitting one you have not read, run and understood is not, since you are the author of the pull request and review time is the scarce resource here.
 Say so in the description if a change was largely machine-generated, and make sure the tests genuinely exercise the behaviour rather than restating the implementation.

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,9 +4,9 @@
 
 ## Checklist
 
-<!-- Documentation-only fixes can skip most of this; say so and submit. -->
+<!-- Documentation-only fixes can skip most of this, so say so and submit. -->
 
-- [ ] `make -k` passes: lint, mypy, pyright, 100 percent branch coverage, docs, workflow audit.
+- [ ] `make -k` passes, meaning lint, mypy, pyright, 100 percent branch coverage, docs and the workflow audit.
 - [ ] There are tests for the new or changed behaviour.
 - [ ] Documentation is updated, including the reference page if the public API changed.
 - [ ] Prose uses semantic line breaks, one sentence per line.

.github/SECURITY.md

@@ -5,12 +5,14 @@
 Only the latest released version is supported.
 Fixes ship in a new release rather than as patches to older ones.
 
-nodrill has no runtime dependencies and does not parse untrusted input, so its realistic security surface is narrow: values leaking across a context boundary they should not cross — between threads, between asyncio tasks, or out of a `provider` block that has exited.
+nodrill has no runtime dependencies and does not parse untrusted input, so its realistic security surface is narrow.
+It is a value leaking across a context boundary it should not cross, between threads, between asyncio tasks, or out of a `provider` block that has exited.
 Reports in that shape are treated as security issues, not ordinary bugs.
 
 ## Reporting a vulnerability
 
-Report privately through GitHub: [open a draft security advisory](https://github.com/paqstd-dev/nodrill/security/advisories/new). Please do not open a public issue for a suspected vulnerability.
+Report privately through GitHub by [opening a draft security advisory](https://github.com/paqstd-dev/nodrill/security/advisories/new).
+Please do not open a public issue for a suspected vulnerability.
 
 Include the smallest program that reproduces the leak, the Python version, and whether threads or asyncio are involved.
 

README.md

@@ -62,6 +62,9 @@ When it goes wrong, `debug()` turns a miss into a diagnosis naming the thread, t
 `isolate()` gives a test fresh context state and rolls it back afterwards.
 Everything above is importable from the top-level package, and there is nothing else to import.
 
+Before it goes wrong, running a suite under `NODRILL_CONTRACT` records which keys each entry point actually read and which of those a fallback answered rather than a provider, and `python -m nodrill contract` renders that into a file a pull request reviews.
+It is a command rather than an import, so it adds no name to the package and no script to your PATH.
+
 ## Overhead
 
 A lookup is one dict read on a single `ContextVar`, and nothing is constructed, resolved or cached along the way.
@@ -91,7 +94,8 @@ Start with the [tutorial](https://nodrill.readthedocs.io/en/latest/content/intro
 
 ## Contributing
 
-Bug reports and small focused pull requests are welcome. See [CONTRIBUTING.md](https://github.com/paqstd-dev/nodrill/blob/main/.github/CONTRIBUTING.md).
+Bug reports and small focused pull requests are welcome.
+See [CONTRIBUTING.md](https://github.com/paqstd-dev/nodrill/blob/main/.github/CONTRIBUTING.md).
 `make install` sets up the environment, and `make` runs the same gate CI does.
 
 Security issues go through a [private advisory](https://github.com/paqstd-dev/nodrill/security/advisories/new) rather than the issue tracker.