4.2 KiB
The library
pplus-library (the submodule library/) is the ground truth of Programming+: besides the routines this document is about, it holds the Mojo corpus (library/mojo/, see mojo-corpus.md) and the pseudo regression and soundness programs (library/pseudo/). Its routines are 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 <id> <lang> <level> prints it. A Mojo reference's answer from the compiler is stored in the routine's golden/mojo-<level>.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.
Changing the library
- Change pplus-library under its AGENTS.md: one routine per file, cases, references with their notes and tolerances, a Dafny proof where one says something.
- In core:
pixi run library-check(no check may fail), thenpixi run library-emit. - Commit pplus-library; commit core with the new
librarypointer and the regenerated registry.tests/library.test.mjsfails while the registry is out of date with the checkout.