# STARTHERE — mgf-test-web (ProofWarden)

> **Sibling package in the Magogi Foundation federation.**
> See [README.md](README.md) for what it is; [FEDERATION.md](FEDERATION.md) for
> the federation contract.

`mgf-test-web` is **ProofWarden** — the per-project **testing & CI authority**. Its
base is the **warden** single-flight broker + the `testctl` CLI + the runner
adapters (FastAPI-free, so CI installs the authority without a web stack); the
`[web]` extra adds the console. It is built on the [`mgf-fedres`](https://codeberg.org/magogi-admin/mgf-fedres)
spine and drives [`mgf-test-supervisor`](https://codeberg.org/magogi-admin/mgf-test-supervisor)
(`mtest`) as the runner.

The rule that defines the product: **a given test can never run twice at once**, no
matter how it was launched (CLI / this website / an AI agent / CI) — enforced *by
construction* by a resident warden that is the sole executor, via an atomic lease
registry (heartbeat + TTL + audited reclaim), **fail-closed** when the warden is down.

## For consumers

```bash
pip install mgf-test-web        # resolves from the self-hosted devpi index
```
```bash
testctl serve                  # run the warden (the resident authority)
testctl run tests/test_x.py::test_y   # submit a run request (fail-closed if down)
testctl status --format json   # read the lease registry (honest broker:down)
```
```python
from mgf.test_web import Warden, WardenClient, RunRequest

warden = Warden("my-project", runner)         # construct once; submit requests
outcome = warden.submit(RunRequest("run_1", "tests/test_x.py::test_y"))
print(outcome.status)                          # started | coalesced | queued
```

Importing `mgf.test_web` pulls in only the **stdlib warden core** — not `mgf-fedres`
and not FastAPI — so the authority is reusable from CI and agents.

## For contributors

See [CONTRIBUTING.md](CONTRIBUTING.md). Standards inherited from
[mgf-common](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/).

## Quick links

| Resource | Where |
|---|---|
| What it is + the layering | [README.md](README.md) |
| The end-to-end plan + spec | [`mgf-fedres/docs/planning/mgf-test-web/`](https://codeberg.org/magogi-admin/mgf-fedres/src/branch/main/docs/planning/mgf-test-web) |
| Scope policy | [SCOPE.md](SCOPE.md) |
| Deps / consumers | [DEPS.md](DEPS.md) |
| Conformance ledger | [docs/inprogress/MGF_STANDARDS_CONFORMANCE.md](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md) |
| Federation contract | [FEDERATION.md](FEDERATION.md) |
