A FastAPI website that receives proof pull requests from
sig.golf-submissions and reports their
results, plus a separate worker that checks each proof against the trusted core checkout with
verifier/verify.py. The competition rules are on sig.golf/rules and,
precisely, in AGENTS.md; maintainer instructions for the site are in
AGENTS.md.
The active workflow is commit, push, then update the production host; no localhost preview or
refresh is required. Follow deployment and recovery for host checks,
exact-commit updates and rebuilding a disposable server from GitHub. Production web and worker use
SIG_PHONY=0.
cd service
uv sync --frozen
./run-local.shOpen http://localhost:8000. The default SIG_PHONY=0 shows only real submissions; the board
shows "No record yet" without a verified record. For a requested demo preview, run
SIG_PHONY=1 ./run-local.sh. Startup then refreshes the fictional demo fixtures,
preserving their IDs and dates; each row carries a demo label, and real submissions are left alone.
run-local.sh sets SIG_INSECURE_LOCAL=1, so the local worker runs the verifier without its Linux
sandbox; production refuses that flag.
For a deliberately running demo preview, SIG_PHONY=1 bash refresh-local.sh updates the fixtures.
The worker does not hot-reload: restart run-local.sh after changing worker code. The startup
script removes GitHub credentials from the worker's environment.
Demo rows. seed_demo.py --refresh updates them, plain seed_demo.py reconciles them and
--remove deletes them. The script refuses production mode and non-loopback site URLs, even with
--force, and normally accepts only the default local database. Never use fictional data in
production.
Local proof jobs. After verifier/setup_tools.sh and a warm formal/ build, queue a commit of
a submissions checkout the way the webhook would:
.venv/bin/python -m app.queue full --repo ../../sig.golf-submissionsLocal jobs never become records. Only one worker may use a data directory; lock files enforce this across processes on the same host.
- Pages. The homepage has one board: the current best score, the score ranking, the Pareto
frontier of signature bytes against verification work, and the record history.
#scoreand#paretoselect the view./rulesserves the rules page from the trusted checkout,/rules.mdthe submission specification (the rootAGENTS.mdbefore its maintainer section),/llms.txtthe agent guide and/notes.mdthe journal of checked submissions'NOTES.md. - Admission. While
admissionisclosedinchallenges.json, proof PRs receive a "not queued" comment and nothing is retained. When open, a pull request must change exactly one submission root. The service checks the repository, files and full head SHA, createsrefs/tags/sig-source/<submission-id>in the base submissions repository, and publishes a pending receipt with frozen attribution and contract identity. The worker cannot start until GitHub confirms that receipt. Its serialized metadata is capped at 48 KiB; longer prose belongs inNOTES.md. Draft PRs are not queued;ready_for_reviewadmits the current head. - Verification. The worker runs
verifier/verify.py full --source <repo> --commit <sha> --jsonwith the data directory hidden and the source archive store as the retention target, and accepts only a result whose track and commit match the queued head and whose metrics are consistent (score == sigma * hverify, both positive and withinlimits.max_metric). - Records. A verified head becomes a record when it beats the best score or extends the Pareto
frontier, decided in verification-finish order under the results lock once its verdict comment is
durable. Demo rows cannot affect records. After the verdict is durable, the bot commits the best
score's checked root and its
records.jsonentry to submissionsmain, preserving other repository files, withCo-authored-bytrailers for every Git author of the admitted PR revision. The bot never merges or closes PRs. - Reporting. The local outbox retries GitHub delivery without repeating a finished proof. A
result awaiting its comment stays
publishing; later jobs wait. Record-snapshot commits also retry through the outbox. - Code. Submission pages link directly to the submitted GitHub folder at the original checked SHA. Exact source ZIPs remain optional artifacts, independently reconstructible from the retained commit.
- Recovery. GitHub source tags and bot comments are durable state; submissions
mainandrecords.jsonprovide the current-record snapshot. SQLite and deterministic source ZIPs are rebuildable caches; original logs are disposable.python -m app.rebuildrestores metadata and queued receipts;--sourcesalso fetches exact commits. See rebuilding the server.
Whenever the contract or the admission status changes, update the metadata, charts, leaderboard, rules and documentation together, then check the rendered live pages after deployment.
| Variable | Default | Purpose |
|---|---|---|
SIG_ENV |
development |
development or production |
SIG_ROLE |
web |
web or worker |
SIG_REPO_ROOT |
checkout root | trusted contract checkout |
SIG_DATA_DIR |
service/data |
SQLite and source ZIP caches, disposable logs and process locks |
SIG_WORK_DIR |
<data>/work |
disposable verification jobs; dedicated bounded mount on Linux |
SIG_DATABASE_URL |
sqlite:///<data>/sig.db |
database connection; deployment uses SQLite |
SIG_BASE_URL |
http://localhost:8000 |
site origin, without a path |
SIG_CONTRACT_REPO |
leanEthereum/sig.golf-dev |
core repository; source and specification links |
SIG_SUBMISSIONS_REPO |
empty | proof PR repository; set to leanEthereum/sig.golf-submissions to configure intake |
GITHUB_WEBHOOK_SECRET |
empty | webhook authentication; web process only |
GITHUB_TOKEN |
empty | GitHub API access and reporting; web process only |
SIG_PHONY |
0 |
show real submissions only; 1 opts into labeled demo rows for local development |
SIG_RESYNC_ON_START |
1 |
rebuild missing submissions from GitHub when the website starts |
SIG_BOT_LOGIN |
token's login | account whose PR comments carry verdicts |
SIG_MAX_INFLIGHT_PER_USER |
2 |
admitting, pending, verifying and publishing jobs per user |
SIG_QUEUE_CAP |
20 |
in-flight jobs overall |
SIG_INSECURE_LOCAL |
0 |
development only: run the verifier without its sandbox; refused in production |
Production web startup requires HTTPS, two distinct repositories, a token and a webhook secret of at least 32 characters. Production workers refuse GitHub credentials. Run the web process and the worker under different Unix identities, sharing only the state group. See deployment for storage, isolation, GitHub recovery and launch checks, and repository setup for the submissions workspace.
uv sync --frozen
.venv/bin/python -m unittest discover -s tests -vService tests use isolated databases and mock GitHub. They import verifier/source_archive.py from
the trusted checkout for the archive format; the verifier's own host tests live in verifier/tests.