Routines that many programs need (a mean, a gap penalty, the Lennard-Jones potential, the minimum image convention) were rewritten and re-verified each time, and there was no way to open one and see exactly what it does. They now live in pplus-library, pinned here as the submodule library/, and a program brings them in with USE. - USE module / USE module.Routine (pseudo-study resolveUses): each routine is studied once in its own file (its own USE lines resolved the same way, cycles refused) and handed to the checker as a library routine; unknown-library, unknown-routine, library-clash, use-place. - A run steps over a library routine (one step at the call, one at the return, none of its lines); a broken contract is reported at the call, naming the routine. The prover uses its REQUIRE and ENSURE at the call and does not prove it again; it is not a unit of the program. - pseudo-to-mojo writes each library routine the program calls once, dependencies first, labeled as coming from the library. - src/library: the registry USE reads, generated from library/ (scripts/library.mjs emit), so the site needs no files at run time. - scripts/library.mjs check: every routine at every level: structure, cases, prover, fuzzer, generated Mojo, each reference implementation (CPython; cc at -O0 and -O2; core's Mojo interpreter; the pinned compiler's stored answer) held to the pseudo's results, and the Dafny proof with the pinned Dafny. Writes library/status.json and STATUS.md. scripts/library_godbolt.py stores the compiler's answers (network). - pixi tasks library-check, library-emit, library-verify-mojo, library-harness; CI checks out the submodule and runs library-check. - Tests: tests/library.test.mjs, corpus 53-library; docs/library.md and a library section in trust.md. Gate: 332 pass; library-check: no failing check (16 routines; the Mojo references are unverified until library-verify-mojo runs on the network). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
3.9 KiB
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 <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.