Files
pplus-core/docs/library.md
T
alexm cae5cff55a
Test / test (push) Failing after 1m38s
feat: move corpus to library
2026-10-06 10:27:46 -04:00

44 lines
4.2 KiB
Markdown

# 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](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](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.