# The library Programming+ takes a procedure from an idea to Mojo to the machine. pplus-library (the submodule `library/`) is its ground truth. Its routines, which this document is about, are written once in pseudo (pseudocode precise enough to run, prove and translate); besides them it holds the Mojo corpus (`library/mojo/`, see [mojo-corpus.md](mojo-corpus.md)) and the pseudo regression and soundness programs (`library/pseudo/`). Each routine is checked by every tool `pixi run library-check` has (the table below), 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 from the site's library page, which opens it in the Bridge. - **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: the routine's comment says which and why, and `tests/documents.test.mjs` fails when it does not mention it); fail (one broken) | | fuzz | every input the fuzzer generates for the routine breaks no contract and stops no run (`STATUS.md` gives how many it generated) | pass, fail, skipped (the fuzzer cannot generate inputs for it) | | mojo | the Mojo generated from the pseudo checks, and prints what the pseudo prints both in core's interpreter and built by the pinned compiler on this machine (to the last digits or nearly: [trust.md](trust.md#what-a-translation-says)) | pass (by both, or by the one that could run it), fail, skipped (the interpreter declines the construct and there is no pinned compiler here) | | a reference, per runner | `cpython`, `cc -O0`, `cc -O2`, core's Mojo `interpreter`, the pinned Mojo `compiler` on this machine, or the pinned compiler on `godbolt` prints the pseudo's results on every case, exactly or within the tolerance `routine.json` states; a C or Mojo reference is given its cases at run time (below) | pass, fail, skipped (the tool is missing, or the `mojo` on the PATH is not the pinned version), unverified (no stored compiler answer for this exact program, input and build arguments) | | 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 Python reference's program calls it on each case's arguments. A Mojo or C reference's program holds no case: its main reads every case's arguments from one line of stdin, which `pixi run library-harness-input ` prints, so the compiler cannot work a call out while it builds (a call on literal arguments it would, with arithmetic and a math library of its own; built with contraction on, as Mojo is by default, with other rounding than the code it makes: `library/mojo/probes/float-contract-runtime`), and every runner is given the same program and the same line. Every Mojo program is built with the pin's arguments (`build.args` in `library/mojo/pin.json`: `--target-cpu x86-64-v3 --fp-mode contract=off`, [mojo-corpus.md](mojo-corpus.md#how-every-program-is-built)), on godbolt and on this machine, so a Mojo reference rounds each Float64 operation on its own, as the pseudo does. The line is the number of cases, each case's arguments, then `end`; a FLOAT is sent as two whole numbers m and e with the value m * 2^e, exactly, a STRING with `%`, space and line breaks escaped, a LIST as its length and then its items. `tests/library-harness.test.mjs` fails if a case's arguments are ever written into the program again. 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, the stdin it was given and the build arguments, 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.