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

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

  1. 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.
  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.