Files
pplus-library/AGENTS.md
T
alexmandClaude df12b2a008 Start pplus-library: 16 verified routines in six modules
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
2026-10-05 11:58:22 +00:00

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

  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).
  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).
  6. Cite the method. sources names where it comes from: a paper with its DOI, a textbook and section, a manual page.
  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 comments, notes and summaries.

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.