montrepol / AGENTS.md
SNAPKITTYWEST's picture
montrepol: exact mathematics in Haskell, with proofs and a certifying solver
5316c4e verified
|
Raw History Blame Contribute Delete
5.04 kB
# AGENTS
The standing brief for anyone, human or otherwise, changing this repository.
Read `README-project.md` for the shape of it, then `VERIFICATION.md` for which gate
discharges what.
## The rules
Every violation `mp-gate` reports names the rule it breaks, so a red gate says
*which promise* failed rather than merely that something is wrong. Nothing else
in the repository defines an `R`-number.
| Rule | What it says | Enforced by |
| --- | --- | --- |
| R1 | The model is the single source. Every claim lives in `model/*.toml`; `CONFORMANCE.md` is generated from it. IDs are unique, well formed and name a real package. | `mp-gate` |
| R2 | Levels are load-bearing. An ID is `build` or `some-true`, never `open` or `proved`. `some-true` cites an authority that exists. A `proved` ledger claim names an Agda file and lemmas that exist. No `build` or `open` claim uses asserting words ("proves", "guarantees", ...). Every authority is cited. | `mp-gate` |
| R3 | Every ID is tagged on a test in its own package, and every test tag is a registered ID. | `mp-gate` |
| R4 | Nothing is deferred: no deferral markers, no stubs; in Agda, no `postulate`, holes or checker-disabling pragmas or flags. | `mp-gate` |
| R5 | Everything is total: no partial Prelude functions (`head`, `fromJust`, `maximum`, `!!`, `error`, ...), nothing unsafe, warnings are errors. Every Agda module is `--safe` and imported by `formal/Everything.agda`. | `mp-gate`, GHC `-Wall -Werror`, Agda `--safe` |
| R6 | Nothing arrives from outside GHC and this repository, except in `liquid/`, which has its own `cabal.project` and may use Hackage and Z3; the root build may not include it and no core package may depend on it. Boot packages carry both version bounds; every package directory is in `cabal.project`; no package repository is enabled; every Haskell source starts with `-- SPDX-License-Identifier: AGPL-3.0-or-later`, and every `.cabal` file has it straight after `cabal-version`. | `mp-gate`, `active-repositories: :none` |
## Adding a capability
In this order, because the order is the discipline:
1. A row in `model/ids.toml`, with its level, its claim and what it is checked
against.
2. A test tagged with the ID (`unit "XX-00" ...`, `prop "XX-00" ...`) that
fails without the implementation.
3. The implementation.
4. At least one entry in `model/mutants.toml`: a defect planted in the
implementation and the IDs that must catch it.
5. `cabal run mp-gate -- write`, then `cabal test all`, `cabal run mp-gate` and
`cabal run mp-gate -- mutants`.
## Adding a proof
1. The module under `formal/Montrepol/`, starting with the SPDX line and
`{-# OPTIONS --safe --without-K #-}`, using only what `formal/` defines.
2. An `import` of it in `formal/Everything.agda`, or the gate fails: an
unimported module is a proof nothing checks.
3. A ledger row at level `proved`, evidence `formal/Montrepol/File.agda:
lemma, ...`, stating exactly what the lemma's type says, and what is
*not* proved.
4. A mutant in `model/mutants.toml` with `package = "formal"`: a false
variant of the statement that Agda must reject, with `expect` naming the
file the error must be located in.
## Adding a refinement
1. The `{-@ f :: ... @-}` spec next to `f` in the core source. Never
`assume`, `lazy` or `ignore`: the gate refuses them.
2. The module in `liquid/mp-liquid.cabal`'s `exposed-modules`, with the core
`src/` directory in its `hs-source-dirs`, or the spec is a comment nothing
checks, and the gate says so.
3. A ledger row at level `refined`, evidence `packages/.../File.hs: f, ...`.
4. A mutant with `package = "liquid"` that Liquid Haskell must reject with an
error located in the file.
## Choosing an oracle
A test is only as good as what it compares against. Prefer, in order:
1. An independent algorithm for the same quantity (Leibniz for Bareiss, the
definition for Strassen, Floyd–Warshall for min-plus powers, brute force for
Berlekamp–Massey).
2. A theorem that does not depend on the code under test (von Staudt–Clausen,
`e^psi(x) = lcm(1..x)`, Euler's formula for `zeta(2k)`).
3. A published table, cited in `model/authorities.toml` and committed under
`oracles/` when it is data.
Never compare a function with itself, and never let a table be an input and
its own check.
## Writing a gate
A gate that cannot fail is worse than no gate, because it reads as evidence.
Before relying on one, plant the defect it exists to catch and confirm it
fires. For the rules that is `mp-gate-test` (GT-01..GT-07). For the
mathematics it is `model/mutants.toml`. A mutant that only breaks the build
does not count as caught.
A gate that reads source must survive reading its own. `MP.Gate.Scan` spells
its forbidden names in halves for that reason; exempting the file would leave a
hole exactly where a defect parked in the gate would sit.
## Comments
Explain *why*, not *what*. A comment earns its place by recording why a
decision went one way when it could plausibly have gone another.