# The library pplus-library (the submodule `library/`) holds routines written once in pseudo and checked at every level, so a program can use them by name instead of rewriting and re-verifying them, and a learner can open any of them to see exactly what it does. Core reads it through a generated registry (`src/library/generated.ts`, `pixi run library-emit`), so the site needs no files at run time. ## Using a routine ``` USE md // every routine of the module USE align.MatchScore // one routine ``` USE lines go at the top of a program. From then on a routine is called like the program's own: - **The checker** types each call against the routine's parameters. A program may not define a routine of the same name (`library-clash`); an unknown module or routine is an error at the USE line, with the names that exist (`unknown-library`, `unknown-routine`). - **A run** steps over a routine: one step where it is called, one where it hands back, and none of its own lines (they belong to another file). Its contracts are still checked; a broken REQUIRE is reported at the call, naming the routine. To step through a routine, open it in the library. - **The prover** uses the routine's REQUIRE as an obligation at each call and its ENSURE as a fact afterwards, the way it treats the program's own routines. It does not prove the routine again: the library did. - **The Mojo translator** writes each routine the program uses once, before the program's own code, dependencies first, labeled as coming from the library. A routine file (`routine.pseudo`) holds USE lines and exactly one FUNCTION or PROCEDURE. A routine that calls another brings it in with USE, so every function in the library is checked on its own. ## What "verified" means for a routine `pixi run library-check` runs every check and records what it found in `library/status.json` and `library/STATUS.md`: | Check | Passes when | Recorded as | |---|---|---| | structure | `routine.pseudo` defines exactly the routine `routine.json` names, and nothing else | pass, fail | | pseudo | every case runs; its result is recorded and is what the references are held to | pass, fail | | prover | every obligation of the routine is proved | pass; open (some not proved, none broken); fail (one broken) | | fuzz | 300 generated inputs break no contract and stop no run | pass, fail, skipped | | mojo | the Mojo generated from the pseudo checks, runs in core's interpreter and prints what the pseudo prints | pass, fail, skipped (a construct the interpreter declines) | | a reference, per runner | `cpython`, `cc -O0`, `cc -O2`, core's Mojo `interpreter`, or the pinned compiler on `godbolt` prints the pseudo's results on every case, exactly or within the tolerance `routine.json` states | pass, fail, skipped (the tool is missing), unverified (no stored compiler answer for this exact program) | | proof | the pinned Dafny verifies the proof file, or its stored verdict matches this exact text | pass, fail, unverified | A reference implementation is the function alone; the tool writes the program it runs as (the function plus a main that prints each case), and `pixi run library-harness ` prints it. A Mojo reference's answer from the compiler is stored in the routine's `golden/mojo-.json`, keyed by the SHA-256 of that program, by `pixi run library-verify-mojo` (network). A Dafny verdict is stored in `golden/dafny.json`, keyed by the proof's text and the Dafny version. What each check does not say is in [trust.md](trust.md#library-routines). ## Changing the library 1. Change pplus-library under its [AGENTS.md](../library/AGENTS.md): one routine per file, cases, references with their notes and tolerances, a Dafny proof where one says something. 2. In core: `pixi run library-check` (no check may fail), then `pixi run library-emit`. 3. Commit pplus-library; commit core with the new `library` pointer and the regenerated registry. `tests/library.test.mjs` fails while the registry is out of date with the checkout.