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

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

  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.