6.1 KiB
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
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
- One routine per file.
routine.pseudoholds USE lines and one FUNCTION or PROCEDURE, named asroutine.jsonnames 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. - 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.jsonrecords it from the run. - Do not edit generated files.
status.json,STATUS.mdand everything undergolden/are written by tools. A Mojo answer comes only frompixi run library-verify-mojo; a Dafny verdict only fromlibrary-checkwith the pinned Dafny. - 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'stests/documents.test.mjsfails when a routine recorded open has no comment that says so. - Every tolerance is explained. A reference held to the pseudo within
relorabssays 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.mjsfails on a tolerance with no note. - Cite the method.
sourcesnames 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.mjsfails on a routine with no source of one of those kinds. - 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. - US English, plain sentences, in a routine's comments, notes and summaries (
tests/documents.test.mjsfails on the British spellings it knows).
Adding a routine
- Make
modules/<module>/<kebab-name>/withroutine.json(name, summary, tags, sources, cases) androutine.pseudo. - Add references under
ref/<lang>/<level>.<ext>: the function only, named in snake case after the routine (LennardJonesislennard_jones). A list parameter is a list in Python and Mojo, and an array and its length in C. Add each toroutine.jsonwith its note and any tolerance. - Add a Dafny proof under
proof/when there is something worth proving over exact numbers, and name it inroutine.json. - Run
pixi run library-checkandpixi run library-emitin 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.
- Never claim Mojo compiles, runs, or prints something without the real compiler's answer. Everything under
mojo/golden/is written bycorpus.py verifyfrom godbolt's answers, andSTATUS.mdandstatus.jsonthere bycorpus.py status. Never edit them by hand. - Do not edit
mojo/corpus/ormojo/mojo.lock.json. They come frompixi run mojo-harvestat the refs inmojo/pin.json. To move to a new Mojo version, editmojo/pin.jsonand follow core'sdocs/mojo-corpus.md. - 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: failthat 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-errorcases the compiler must reject. The header keys are in core'sdocs/mojo-corpus.md. syntax/mojo.xmlis generated bypixi run mojo-emitin core, from the same words as core'ssrc/mojo/generated/.
Pseudo programs (pseudo/)
The gate, in core: npm test (tests/corpus.test.mjs, tests/prover-soundness.test.mjs, the sync tests).
- 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. - 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. - Never change an
// EXPECT:line to match a new answer without knowing why the old answer was wrong; the line is the specification.