Routines written once in pseudo and checked at every level, so programs can use them by name instead of rewriting and re-verifying them: - stats: Mean, Variance (two-pass) - numerics: KahanSum, LinearInterp, Trapezoid - align: LinearGapPenalty, AffineGapPenalty, MatchScore, NeedlemanWunschScore - md: LennardJones, LennardJonesForce, MinimumImage, PairDistance - seq: GCContent, HammingDistance - special: ErfApprox (Abramowitz and Stegun 7.1.26) Each has contracts, cases, reference implementations in Python, Mojo and (for the numerical ones) C at more than one level, and nine have a Dafny proof over exact numbers. status.json and STATUS.md are written by pplus-core's library-check: every check passes or is open/unverified as listed there. The Mojo references still need the pinned compiler's answers (library-verify-mojo, network). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
3.1 KiB
3.1 KiB
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/.
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 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
- 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). - 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). - Cite the method.
sourcesnames where it comes from: a paper with its DOI, a textbook and section, a manual page. - 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 comments, notes and summaries.
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.