Files
pplus-core/docs/library.md
T
alexm 401084bab3
Test / gate (push) Failing after 19m0s
Initial commit
2026-11-12 22:23:54 -05:00

6.2 KiB

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) 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) 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 <id> <lang> <level> 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 <id> <lang> <level> 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), 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-<level>.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.

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.