feat: move corpus to library

This commit is contained in:
alexm committed 2026-10-06 09:57:04 -04:00
1 parent df12b2a008
commit 9d351b4a0f
1301 files changed
+941859 -4

No files matched your search

+19 -2
View File
@@ -1,6 +1,6 @@
# AGENTS.md
Rules for adding or changing a routine of pplus-library. The checks are pplus-core's tasks: run them from a core checkout, where this repository is `library/`.
Rules for changing pplus-library, the ground truth of Programming+. 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
@@ -11,7 +11,7 @@ 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 core's Mojo interpreter declines a construct) 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
## 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.
@@ -28,3 +28,20 @@ pixi run library-emit # then core's registry, committed in core
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; a stress program's `# expect-stdout:` lines are the interpreter's prediction, checked against godbolt.
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. 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.