Files
pplus-core/docs/library.md
T
alexmandClaude 7ddc628597 Add USE and pin pplus-library: routines verified once, used by name
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
2026-10-05 12:06:41 +00:00

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

  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.