Files
alexm 568474d52f
Test (in pplus-core) / in-core (push) Failing after 28m44s
Initial commit
2026-11-12 22:23:48 -05:00

48 lines
6.1 KiB
Markdown

# AGENTS.md
Rules for changing pplus-library, the ground truth of Programming+. Programming+ takes a procedure from an idea to Mojo to the machine. Its routines are written in pseudo (pseudocode precise enough to run, prove and translate). The checks are pplus-core's tasks: run them from a core checkout, where this repository is `library/`. A change here is committed here first, then in core with the new submodule pointer and whatever core regenerated from it.
## The gate
```bash
pixi run library-check # in pplus-core: no check may fail
pixi run library-emit # then core's registry, committed in core
```
**A change is finished when `library-check` reports no failing check and `STATUS.md` shows what you expect.** A check may be `open` (the prover could not finish an obligation), `skipped` (a tool is missing, or a tool declines: core's Mojo interpreter or translator a construct, the fuzzer the routine's inputs) or `unverified` (no stored compiler answer for this exact text yet); none of those is a failure, and each is listed in your summary.
## Hard rules for routines
1. **One routine per file.** `routine.pseudo` holds USE lines and one FUNCTION or PROCEDURE, named as `routine.json` names it, and nothing else. A helper is a routine of its own, brought in with USE. That way every function in the library is checked on its own and appears once in generated Mojo.
2. **The pseudo is the specification.** The cases' results come from running the pseudo; every reference implementation is held to them. Never change a case's expected value by hand: `status.json` records it from the run.
3. **Do not edit generated files.** `status.json`, `STATUS.md` and everything under `golden/` are written by tools. A Mojo answer comes only from `pixi run library-verify-mojo`; a Dafny verdict only from `library-check` with the pinned Dafny.
4. **Contracts the prover can hold.** REQUIRE everything the routine needs. Write an ENSURE when the prover proves it (whole numbers, comparisons, lengths); a claim about the value of FLOAT arithmetic belongs in the Dafny proof over exact numbers, because rounding is opaque to the prover. An obligation left open is explained in the routine's comment (see `special.ErfApprox`); core's `tests/documents.test.mjs` fails when a routine recorded *open* has no comment that says so.
5. **Every tolerance is explained.** A reference held to the pseudo within `rel` or `abs` says in its note why the answers differ (a different order of additions, a different method, an approximation's stated bound), and for which inputs the tolerance holds when it does not hold for all. `tests/documents.test.mjs` fails on a tolerance with no note.
6. **Cite the method.** `sources` names where it comes from: a paper with its DOI, a book with its edition and section, a manual page with its URL. `tests/documents.test.mjs` fails on a routine with no source of one of those kinds.
7. **No new dependencies.** Python references use the standard library; C references use the C standard library and `-lm`; Mojo references use the standard library of the pinned Mojo.
8. **US English**, plain sentences, in a routine's comments, notes and summaries (`tests/documents.test.mjs` fails on the British spellings it knows).
## Adding a routine
1. Make `modules/<module>/<kebab-name>/` with `routine.json` (name, summary, tags, sources, cases) and `routine.pseudo`.
2. Add references under `ref/<lang>/<level>.<ext>`: the function only, named in snake case after the routine (`LennardJones` is `lennard_jones`). A list parameter is a list in Python and Mojo, and an array and its length in C. Add each to `routine.json` with its note and any tolerance.
3. Add a Dafny proof under `proof/` when there is something worth proving over exact numbers, and name it in `routine.json`.
4. Run `pixi run library-check` and `pixi run library-emit` in core; commit this repository, then core with the new pointer and registry.
## The Mojo corpus (`mojo/`)
The gate, in core: `pixi run mojo-status-strict` (offline) and `npm test`. Read core's `docs/mojo-corpus.md` first.
1. **Never claim Mojo compiles, runs, or prints something without the real compiler's answer.** Everything under `mojo/golden/` is written by `corpus.py verify` from godbolt's answers, and `STATUS.md` and `status.json` there by `corpus.py status`. Never edit them by hand.
2. **Do not edit `mojo/corpus/` or `mojo/mojo.lock.json`.** They come from `pixi run mojo-harvest` at the refs in `mojo/pin.json`. To move to a new Mojo version, edit `mojo/pin.json` and follow core's `docs/mojo-corpus.md`.
3. **Our programs are made with core's scripts:** `pixi run new-probe`, `new-exercise`, `new-stress`. A probe asks one question. An exercise program passes its own `# expect-stdout:` lines, or says with `# expect: fail` that the check must not hold (a starter with a bug for the student to find). A stress program's `# expect-stdout:` lines are the interpreter's prediction, checked against godbolt; a few stress programs are `# expect: compile-error` cases the compiler must reject. The header keys are in core's `docs/mojo-corpus.md`.
4. **`syntax/mojo.xml` is generated** by `pixi run mojo-emit` in core, from the same words as core's `src/mojo/generated/`.
## Pseudo programs (`pseudo/`)
The gate, in core: `npm test` (`tests/corpus.test.mjs`, `tests/prover-soundness.test.mjs`, the sync tests).
1. **A regression program** is a file in `pseudo/programs/` named `<nn>-<name>.pseudo`, numbered after the last one, whose `// EXPECT:` lines are the output it must print (`// INPUT:` lines are what it reads), or whose `// STOPS: <kind>` line says how its run must stop, or whose `// ERRORS: <n>` line says how many errors the checker must report. Every translator in core is also run over it.
2. **A prover soundness regression** is a file in `pseudo/prover/` whose `// MUST-NOT-PROVE: <kind>@<line>` names an obligation a run breaks, or `// RUN-STOPS: <kind>@<line>` where a run must stop. When a soundness bug is found, add its program here first, watch core's test fail, then fix the rule in core.
3. **Never change an `// EXPECT:` line to match a new answer** without knowing why the old answer was wrong; the line is the specification.