pytest-gpu-proof 0.2.0__tar.gz → 0.4.0__tar.gz

pytest_gpu_proof-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev extras
+        run: pip install -e ".[dev]"
+
+      - name: Run test suite (CPU-only)
+        run: python -m pytest tests/ -q
+
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install package with dev extras
+        run: pip install -e ".[dev]"
+      - name: Enforce 100% line and branch coverage
+        run: |
+          coverage run -m pytest tests/ -q
+          coverage report --fail-under=100
+          coverage xml
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: coverage.xml
+
+  docs-and-package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install package with dev extras
+        run: pip install -e ".[dev]"
+      - name: Build documentation strictly
+        run: mkdocs build --strict
+      - name: Build and inspect distributions
+        run: |
+          python -m build
+          python -m twine check --strict dist/*
+      - name: Smoke-test the wheel
+        run: |
+          python -m venv /tmp/wheeltest
+          /tmp/wheeltest/bin/pip install -q dist/*.whl
+          /tmp/wheeltest/bin/gpu-proof --help
+          /tmp/wheeltest/bin/python -m pytest -p pytest_gpu_proof --version

pytest_gpu_proof-0.4.0/AGENTS.md

@@ -0,0 +1,29 @@
+# Agent guide
+
+This repository is a security-sensitive pytest plugin. Preserve fail-closed
+behavior and treat receipt, fingerprint, signature, Git, merge, and policy code
+as trust boundaries.
+
+Before changing behavior, read:
+
+- `README.md`
+- `docs/architecture.md`
+- `docs/security_model.md`
+- `docs/policy.md`
+- `CONTRIBUTING.md`
+
+Implementation rules:
+
+- New receipts are schema 3; keep explicit legacy verification isolated.
+- Signer metadata belongs inside the signed payload.
+- Default fingerprint scope is the full tracked repository; generated inputs
+  require explicit extra paths.
+- Never turn receipt-emission failures into success unless the caller selected
+  `best_effort`.
+- Never accept unknown policy fields or malformed receipt structure.
+- Keep tests hermetic: mock GitHub key lookup and local identity.
+- Maintain 100% line and branch coverage. Add adversarial cases for new trust
+  branches.
+- Do not edit generated `site/` or release artifacts in `dist/`.
+
+Run the complete check list from `CONTRIBUTING.md` before proposing a PR.

pytest_gpu_proof-0.4.0/CHANGELOG.md

@@ -0,0 +1,129 @@
+# Changelog
+
+All notable changes to pytest-gpu-proof are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/); versions follow
+[SemVer](https://semver.org/) (pre-1.0: minor bumps may break).
+
+## [0.4.0] — 2026-08-17
+
+### Added
+
+- Schema `"3"`: signer username, key fingerprint, key algorithm, exact test
+  collection, session outcome, pytest arguments, and per-shard environment/time
+  are included in the signed payload.
+- Open contributor and restricted signer policies. Restricted mode supports
+  username and exact SSH-key-fingerprint allowlists.
+- Policy pinning for mode, global tracked/extra fingerprint scope, exact test
+  manifest, shard names, and per-shard tracked/extra scope.
+- Explicit fingerprint paths for ignored/generated inputs and manifest support
+  for symlinks and submodule gitlinks.
+- Explicit receipt-artifact exclusions avoid self-referential whole-tree
+  fingerprints and can be pinned by verification policy.
+- `--gpu-proof-best-effort` as an explicit development escape hatch.
+- `min_schema` policy field to refuse legacy schema-1/2 receipts.
+- Python 3.13 CI, strict docs/package jobs, and enforced 100% line and branch
+  coverage.
+
+### Changed
+
+- The default fingerprint scope is the entire Git-tracked repository instead
+  of `src,tests`.
+- Receipt creation now fails pytest on Git, fingerprint, key, serialization, or
+  write errors; it also removes stale output at session start.
+- Schema-3 verification rejects dirty recording and verification trees by
+  default and accepts receipt commits only at the current commit or an ancestor.
+- Setup/teardown failures, missing terminal reports, comparison exceptions,
+  skipped tests, and overall session failure are represented and verified.
+- GPU metadata records all devices reported by `nvidia-smi`.
+- Array comparison is shape-safe, uses tolerance only for float/complex data,
+  and uses exact equality for other dtypes.
+- Receipt writes are atomic and strict JSON forbids NaN/non-JSON values.
+- Receipt generation rejects xdist workers; use separate shard processes.
+- Legacy schema-1/2 verification derives the policy-checked key fingerprint
+  from the key that actually verified the signature; an asserted
+  `signature.key_fingerprint` that disagrees is rejected.
+- `signer_mode: restricted` policies reject unsigned receipts even with
+  `--allow-unsigned`, and `--github-user` must match the signed schema-3
+  identity.
+- The receipt under verification is excluded from the verification-tree dirty
+  check, so an untracked just-generated receipt verifies without gitignoring.
+- Passphrase-protected SSH keys prompt correctly on current cryptography
+  releases (`ValueError` as well as `TypeError`) and fail closed with an
+  actionable message when no terminal is available.
+- Uninitialized submodule checkouts fingerprint their index gitlink commit
+  instead of accidentally recording the parent repository's HEAD.
+- Receipt/shard age limits are enforced to the exact day boundary.
+- GitHub usernames are validated before key fetches and key responses are
+  size-capped.
+- A stale receipt that cannot be cleared at session start raises a pytest
+  usage error (an exit-status write that early would be silently overwritten).
+- Merging receipts without session timestamps is refused with a clear error.
+
+### Fixed
+
+- Carry-forward now recomputes the stored fingerprint algorithm and preserves
+  explicit generated/ignored shard inputs.
+- Signed identity and algorithm substitution are rejected.
+- Empty source scope, unmerged index entries, malformed policies, incomplete
+  collections, and stale success artifacts fail closed.
+
+## [0.3.0] — 2026-08-08
+
+### Added
+- Schema `"2"` sharded receipts: `--gpu-proof-shard NAME` +
+  `--gpu-proof-shard-fingerprint-paths` emit a per-shard narrow fingerprint;
+  `gpu-proof merge` unions schema-2 shards (unique names enforced).
+- Verifiable carry-forward: `gpu-proof merge --carry-from OLD` grafts shards
+  absent from the fresh inputs iff the old commit is an ancestor AND the
+  shard's narrow fingerprint recomputes clean; grafted shards are marked
+  `carried` and the verifier rejects them unless the policy sets
+  `allow_carried: true` (bounded by `carried_max_age_days`, default 30).
+- Verifier: schema-2 checks (per-shard fingerprint recompute, membership
+  partition of `tests[]`, carried-shard policy gate). Schema-1 receipts are
+  unchanged and a schema-1 receipt carrying a `shards` block is rejected.
+
+## [0.2.0] — 2026-08-07
+
+### Added
+- `gpu-proof merge`: union N shard receipts from one commit into a single
+  re-signed receipt (per-module crash isolation / machine sharding). Refuses
+  shards that disagree on schema, commit SHA, fingerprint, mode, or
+  environment; duplicate node IDs across shards are a hard error. Records
+  per-shard provenance under `session.shards` (additive — the verifier is
+  unchanged). `repo.dirty` is OR-ed; `gpu_info` survives CPU-only shards.
+  Docs: `docs/sharding.md`.
+
+### Fixed
+- Explicit CLI values equal to their built-in defaults are no longer silently
+  ignored in favor of `[tool.gpu_proof]` (value-taking options now register a
+  `None` sentinel; `--gpu-proof-fail-on-skip` ORs with the toml value since a
+  store_true flag can only turn it on).
+
+## [0.1.0] — 2026-07-07
+
+First public release.
+
+### Added
+- pytest plugin (`-p` auto-loaded via the `pytest11` entry point): captures
+  per-test outcomes and skips, git SHA, a SHA-256 source fingerprint over
+  configured paths, and self-reported GPU info; emits a signed JSON receipt at
+  session end (`--gpu-proof-enable`).
+- Ed25519 SSH-key signing; signature covers the canonical (compact,
+  sorted-key) JSON without the signature block. `none` backend for unsigned
+  receipts.
+- CPU-only verifier `gpu-proof verify`: signature against the signer's public
+  `github.com/<user>.keys`, fingerprint match, commit SHA, outcome + skip
+  policy, `--require-gpu`, freshness (`--max-age-days`, `0` = today only),
+  dirty policy.
+- Skip policies: `--allow-skipped` (any) or `--expected-skips FILE` (exact-set
+  baseline — unexpected AND stale entries both fail); mutually exclusive.
+  Also `[tool.gpu_proof] expected_skips`.
+- Signer resolution: explicit flag/config → `gh` CLI login (keyholder) →
+  origin-remote owner with a printed warning (org remotes have no SSH keys).
+- `is_dirty` ignores untracked content inside submodules (pin moves and
+  tracked edits still count).
+- Receipt diffing (`compare.py`), `[tool.gpu_proof]` pyproject configuration,
+  docs site (mkdocs), honest trust-model statement in
+  `docs/security_model.md`.
+
+[0.1.0]: https://github.com/A2R-Lab/pytest-gpu-proof/releases/tag/v0.1.0

pytest_gpu_proof-0.4.0/CLAUDE.md

@@ -0,0 +1,14 @@
+# Claude orientation
+
+Use [AGENTS.md](AGENTS.md) as the canonical agent guide. In particular:
+
+- a receipt is signer attestation, not proof of GPU execution;
+- receipt, fingerprint, signature, Git, merge, and policy code fail closed;
+- new recordings use schema 3 and bind signer metadata inside the signature;
+- the default manifest covers the full tracked repository;
+- tests are hermetic and maintain 100% line and branch coverage;
+- generated `site/`, `dist/`, coverage output, real keys, and local receipts are
+  not source changes.
+
+Before implementation work, read `docs/architecture.md`,
+`docs/security_model.md`, `docs/policy.md`, and `CONTRIBUTING.md`.

pytest_gpu_proof-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing
+
+## Development setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+```
+
+## Required checks
+
+```bash
+python -m pytest tests -q
+coverage run -m pytest tests -q
+coverage report --fail-under=100
+mkdocs build --strict
+python -m build
+python -m twine check --strict dist/*
+```
+
+CI runs the test suite on Python 3.11, 3.12, and 3.13, independently enforces
+100% line and branch coverage, builds docs strictly, and smoke-tests the wheel.
+
+## Change expectations
+
+- Add adversarial tests for trust-boundary changes, not only happy paths.
+- Keep receipt generation and verification fail-closed by default.
+- Treat schema and policy changes as compatibility decisions; document them in
+  `CHANGELOG.md` and the relevant guide.
+- Keep Git and network tests hermetic. Never depend on a developer's actual
+  GitHub login, SSH keys, GPU, or global Git configuration.
+- Use separate pytest processes for shards. Receipt generation does not support
+  xdist workers.
+- Do not commit generated `site/`, coverage files, caches, or local receipts.
+
+## Pull requests
+
+Describe the trust claim before and after the change, migration implications,
+and the exact checks run. Small, reviewable commits are preferred. Security
+reports should follow [SECURITY.md](SECURITY.md), not a public issue.

pytest_gpu_proof-0.4.0/PKG-INFO

@@ -0,0 +1,331 @@
+Metadata-Version: 2.4
+Name: pytest-gpu-proof
+Version: 0.4.0
+Summary: pytest plugin for GPU equivalence testing with signed receipts verified via GitHub SSH keys
+Project-URL: Homepage, https://github.com/A2R-Lab/pytest-gpu-proof
+Project-URL: Documentation, https://a2r-lab.github.io/pytest-gpu-proof/
+Project-URL: Repository, https://github.com/A2R-Lab/pytest-gpu-proof
+Project-URL: Issues, https://github.com/A2R-Lab/pytest-gpu-proof/issues
+Project-URL: Changelog, https://github.com/A2R-Lab/pytest-gpu-proof/blob/main/CHANGELOG.md
+License: MIT
+License-File: LICENSE
+Keywords: attestation,cuda,gpu,pytest,signing,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=41.0
+Requires-Dist: pytest>=7.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: coverage[toml]>=7.6; extra == 'dev'
+Requires-Dist: hatchling>=1.25; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
+Requires-Dist: numpy>=1.26; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# pytest-gpu-proof
+
+[![CI](https://github.com/A2R-Lab/pytest-gpu-proof/actions/workflows/ci.yml/badge.svg)](https://github.com/A2R-Lab/pytest-gpu-proof/actions/workflows/ci.yml)
+[![Docs](https://github.com/A2R-Lab/pytest-gpu-proof/actions/workflows/docs.yml/badge.svg)](https://a2r-lab.github.io/pytest-gpu-proof/)
+[![PyPI](https://img.shields.io/pypi/v/pytest-gpu-proof.svg)](https://pypi.org/project/pytest-gpu-proof/)
+[![Python](https://img.shields.io/pypi/pyversions/pytest-gpu-proof.svg)](https://pypi.org/project/pytest-gpu-proof/)
+[![Coverage: 100%](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/A2R-Lab/pytest-gpu-proof/actions/workflows/ci.yml)
+
+Signed pytest receipts for local GPU runs, verified in CPU-only CI.
+
+`pytest-gpu-proof` records which marked tests ran, their outcomes, the Git
+commit and source fingerprint, the environment, and the run time. It signs
+that payload with an existing SSH key. A normal CPU runner can then verify the
+receipt against the signer's public keys on GitHub without rerunning CUDA.
+
+This is a practical bridge for projects with local or lab GPUs but no
+always-on GPU CI. It is signer attestation—not hardware attestation. See the
+[security model](docs/security_model.md) before making stronger claims.
+
+## The workflow
+
+```text
+GPU machine                              CPU-only CI
+──────────────────────────────────       ───────────────────────────────
+pytest --gpu-proof-enable                gpu-proof verify --receipt ...
+  run marked tests                         validate schema and signature
+  capture setup/call/teardown outcomes     fetch current GitHub SSH keys
+  fingerprint the checked-out tree         recompute source fingerprint
+  sign one schema-3 receipt                 enforce repository policy
+```
+
+The default signer policy is **open**: a valid receipt from any GitHub user is
+accepted. This supports contributor-signed pull requests. Repositories that
+only trust maintainers or dedicated CI keys can use **restricted** mode with
+username and/or key-fingerprint allowlists.
+
+## Install
+
+```bash
+python -m pip install pytest-gpu-proof
+```
+
+For development:
+
+```bash
+git clone https://github.com/A2R-Lab/pytest-gpu-proof.git
+cd pytest-gpu-proof
+python -m pip install -e ".[dev]"
+```
+
+Requirements: Python 3.11+, pytest 7+, and `cryptography` 41+.
+
+## Quick start
+
+Mark a test, or use the comparison fixture:
+
+```python
+import pytest
+
+
+@pytest.mark.gpu_proof
+def test_rnea(gpu_proof_check):
+    gpu_proof_check(
+        name="rnea",
+        reference=python_rnea,
+        candidate=cuda_rnea,
+        args=(model, q, qd, qdd),
+        metadata={"robot": "go2"},
+    )
+```
+
+Run from the root of the project being attested:
+
+```bash
+pytest tests/gpu --gpu-proof-enable --gpu-proof-github-user YOUR_USER
+gpu-proof verify --receipt gpu-proof.json --repo .
+```
+
+Commit `gpu-proof.json` with the code, then add a CPU-only CI step:
+
+```yaml
+- name: Verify local GPU test receipt
+  run: gpu-proof verify --receipt gpu-proof.json --repo .
+```
+
+Receipt creation is fail-closed. A missing key, invalid Git state, empty
+fingerprint scope, no selected tests, or write failure makes pytest fail and
+leaves no stale receipt behind. `--gpu-proof-best-effort` is an explicit
+development-only opt-out.
+
+## Four interfaces
+
+The project exposes four small interfaces:
+
+1. **Markers** select receipt tests.
+2. **`gpu_proof_check`** compares a reference callable with a candidate.
+3. **`gpu-proof verify`** validates a receipt and repository policy.
+4. **`gpu-proof merge`** combines separately executed shards and optionally
+   carries unchanged shards forward.
+
+### Markers
+
+| Marker | Meaning |
+|---|---|
+| `@pytest.mark.gpu_proof` | Include the test in the receipt |
+| `@pytest.mark.gpu_equivalence` | Alias for `gpu_proof` |
+| `@pytest.mark.gpu_required` | Skip when neither `nvidia-smi` nor PyTorch reports a GPU |
+
+Skipped tests are recorded. Verification rejects them by default. Prefer an
+exact `--expected-skips` baseline over the broad `--allow-skipped` escape
+hatch.
+
+### Comparison fixture
+
+```python
+gpu_proof_check(
+    name="operation",
+    reference=reference_fn,
+    candidate=gpu_fn,
+    args=(arg1, arg2),
+    kwargs={"option": value},
+    compare=custom_compare,
+    metadata={"case": "small"},
+)
+```
+
+The default comparator is shape-safe: float/complex NumPy-compatible arrays
+use `numpy.allclose(..., equal_nan=True)` and other arrays use exact equality.
+Provide a comparator for GPU tensors, domain-specific tolerances, or structured
+outputs. A comparator should return normally on success and raise
+`AssertionError` on mismatch.
+
+## Recording options
+
+| Option | Default | Purpose |
+|---|---:|---|
+| `--gpu-proof-enable` | off | Enable receipt generation |
+| `--gpu-proof-mode` | `local` | Record `local` or `ci-gpu` provenance |
+| `--gpu-proof-out` | `gpu-proof.json` | Output artifact |
+| `--gpu-proof-key` | discovered | SSH private-key file |
+| `--gpu-proof-github-user` | discovered | GitHub account that owns the public key |
+| `--gpu-proof-signing-backend` | `ed25519` | SSH signing, or explicit `none` |
+| `--gpu-proof-required-marker` | `gpu_proof` | Custom receipt marker |
+| `--gpu-proof-fail-on-skip` | off | Fail and suppress the receipt on selected skips |
+| `--gpu-proof-fingerprint-paths` | `.` | Comma-separated Git-tracked scope |
+| `--gpu-proof-fingerprint-extra-paths` | empty | Explicit ignored/generated inputs |
+| `--gpu-proof-fingerprint-excluded-paths` | `gpu-proof.json` | Receipt artifacts omitted to avoid self-reference |
+| `--gpu-proof-best-effort` | off | Warn instead of failing if emission fails |
+
+Most defaults can live in the consumer's `pyproject.toml`:
+
+```toml
+[tool.gpu_proof]
+mode = "local"
+output = "gpu-proof.json"
+fingerprint_paths = ["."]
+fingerprint_extra_paths = ["generated/kernel_table.cuh"]
+fingerprint_excluded_paths = ["gpu-proof.json"]
+required_marker = "gpu_proof"
+max_age_days = 30
+require_gpu = true
+```
+
+By default, the fingerprint covers every tracked file in the repository,
+including symlink targets and submodule gitlinks. Ignored/generated artifacts
+are excluded unless explicitly named as extra paths. An empty or unreadable
+scope is an error. The receipt artifact itself is excluded because a signed
+file cannot hash its own final contents; set the exclusion explicitly if your
+committed receipt uses a different path.
+
+## Verification and policy
+
+```bash
+gpu-proof verify \
+  --receipt gpu-proof.json \
+  --repo . \
+  --policy gpu-proof-policy.yaml
+```
+
+Schema-3 verification checks:
+
+- strict receipt structure, complete test collection, and session outcome;
+- signature, signed username, key fingerprint, and key algorithm;
+- the signer's current public SSH keys at `github.com/<user>.keys`;
+- tracked and explicit-extra source fingerprints;
+- current/ancestor Git commit and clean recording/verification trees;
+- test and comparison outcomes, exact skip policy, and optional test manifest;
+- optional shard membership, shard fingerprints, and carry-forward policy;
+- mode, GPU-information requirement, and freshness.
+
+Open policy, suitable for contributor-signed PRs:
+
+```yaml
+signer_mode: open
+max_age_days: 30
+require_mode: local
+required_fingerprint_paths: ["."]
+required_fingerprint_excluded_paths: [gpu-proof.json]
+required_test_manifest: gpu-proof-tests.txt
+```
+
+Restricted policy, suitable for a maintainer or CI allowlist:
+
+```yaml
+signer_mode: restricted
+allowed_signers: [alice, release-bot]
+allowed_key_fingerprints:
+  - "SHA256:..."
+max_age_days: 14
+require_mode: ci-gpu
+required_fingerprint_paths: ["."]
+required_fingerprint_extra_paths: [generated/kernel_table.cuh]
+required_fingerprint_excluded_paths: [gpu-proof.json]
+allow_dirty: false
+allow_carried: false
+```
+
+If both restricted allowlists are present, both must match. Unknown policy
+fields fail verification so misspellings cannot silently weaken policy.
+YAML support is available through `pytest-gpu-proof[yaml]`; JSON policy files
+need no optional dependency.
+
+`--allow-unsigned` accepts `"signature": null` with a loud warning. It removes
+signer authentication and should not be used as a merge gate.
+
+## Signing identity
+
+The GitHub username is resolved in this order:
+
+1. `--gpu-proof-github-user` or `github_username` configuration;
+2. the authenticated `gh` CLI user;
+3. the origin owner, with a warning because organization owners normally do
+   not own an individual's SSH key.
+
+The private-key file is resolved in this order:
+
+1. `--gpu-proof-key`;
+2. `git config user.signingKey`;
+3. `~/.ssh/id_ed25519`, `id_ecdsa`, then `id_rsa`.
+
+Ed25519, ECDSA, and RSA-PSS keys are supported. Agent-only and
+hardware-backed keys are not yet supported because signing currently requires
+a readable private-key file.
+
+## Shards
+
+Run shards as separate pytest processes; xdist workers are intentionally
+rejected for receipt generation.
+
+```bash
+pytest tests/gpu/a --gpu-proof-enable \
+  --gpu-proof-shard=a \
+  --gpu-proof-shard-fingerprint-paths=src/a,tests/gpu/a \
+  --gpu-proof-out=receipts/a.json
+
+pytest tests/gpu/b --gpu-proof-enable \
+  --gpu-proof-shard=b \
+  --gpu-proof-shard-fingerprint-paths=src/b,tests/gpu/b \
+  --gpu-proof-out=receipts/b.json
+
+gpu-proof merge receipts/a.json receipts/b.json --out gpu-proof.json
+```
+
+The merger refuses mixed commits, schemas, global fingerprints, modes,
+runtime environments, duplicate tests, and duplicate shard names. It records
+input provenance but does not verify each input signature; the merger signs
+for the union. See [sharding and carry-forward](docs/sharding.md).
+
+## Receipt schema
+
+New receipts use schema `"3"`. Signer identity is inside the signed payload,
+test node IDs exactly match the recorded collection, setup and teardown
+failures are terminal outcomes, and writes are atomic. The verifier retains
+schema-1/2 compatibility, but their legacy defaults are less strict.
+
+## Development
+
+```bash
+python -m pytest tests -q
+coverage run -m pytest tests -q
+coverage report --fail-under=100
+mkdocs build --strict
+python -m build
+python -m twine check --strict dist/*
+```
+
+CI tests Python 3.11–3.13 and enforces 100% line and branch coverage. See
+[CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and
+[RELEASING.md](RELEASING.md).
+
+## License
+
+MIT.