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
This commit is contained in:
alexmandClaude committed 2026-10-05 12:06:41 +00:00
1 parent be0db2d74f
commit 7ddc628597
21 files changed
+2654 -20

No files matched your search

+43
View File
@@ -0,0 +1,43 @@
# 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](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.
+6 -6
View File
@@ -2,13 +2,13 @@
<!-- Written by tests/sync-coverage.test.mjs. Do not edit; rerun `npm test` to refresh. -->
Each translator in `src/sync/` is run over every exercise with pseudo (17), every program in `tests/corpus/` (52), and 17 one-construct fixtures (`tests/helpers/sync-programs.mjs`). 3 of the 86 have pseudo that does not read, by design (they teach the notation's error messages), and are left out below. That leaves **83 programs**.
Each translator in `src/sync/` is run over every exercise with pseudo (17), every program in `tests/corpus/` (53), and 17 one-construct fixtures (`tests/helpers/sync-programs.mjs`). 3 of the 87 have pseudo that does not read, by design (they teach the notation's error messages), and are left out below. That leaves **84 programs**.
| From pseudo to | Says it completely | Says it with a gap or a checker error | Cannot say it |
| --- | ---: | ---: | ---: |
| Mojo | 80 | 3 | 0 |
| lingo | 31 | 0 | 52 |
| matho | 3 | 0 | 80 |
| Mojo | 81 | 3 | 0 |
| lingo | 31 | 0 | 53 |
| matho | 3 | 0 | 81 |
Mojo is a program-for-program translation that always produces something: a line with no faithful spelling becomes a visible `raise Error("not translated: pseudo line N")` and a warning. Lingo and matho must read back as the same program, so what they cannot say exactly they refuse, with the construct and its line, and the pane keeps its last good text.
@@ -32,7 +32,7 @@ English is read by `readSteps`, whose grammar has no sentence for these.
| What it has no form for | Programs | Which |
| --- | ---: | --- |
| steps outside a routine (every English step belongs to a routine) | 50 | 01-arithmetic.pseudo, 02-temperature.pseudo, 03-compound-interest.pseudo, 04-gcd-recursion.pseudo, and 46 more |
| steps outside a routine (every English step belongs to a routine) | 51 | 01-arithmetic.pseudo, 02-temperature.pseudo, 03-compound-interest.pseudo, 04-gcd-recursion.pseudo, and 47 more |
| a fixed-length ARRAY | 4 | ex:edit-distance, 05-primes-sieve.pseudo, 11-matrix-multiply.pseudo, 15-game-of-life.pseudo |
| a BYREF parameter | 3 | 06-fibonacci-memo.pseudo, 10-insertion-sort.pseudo, 26-swap-byref.pseudo |
| a HASHMAP whose values are not counts | 3 | ex:translate-codons, 13-stack-brackets.pseudo, 39-constants-codons.pseudo |
@@ -64,7 +64,7 @@ An equation lowers to one `FUNCTION` that returns a value; a program with output
| What it has no form for | Programs | Which |
| --- | ---: | --- |
| steps outside a function (an equation is a function) | 46 | 01-arithmetic.pseudo, 02-temperature.pseudo, 03-compound-interest.pseudo, 04-gcd-recursion.pseudo, and 42 more |
| steps outside a function (an equation is a function) | 47 | 01-arithmetic.pseudo, 02-temperature.pseudo, 03-compound-interest.pseudo, 04-gcd-recursion.pseudo, and 43 more |
| a function that answers LIST (equations answer numbers) | 5 | ex:match, ex:match-proved, ex:match-off-by-one, ex:match-reset, and 1 more |
| a function that answers STRING (equations answer numbers) | 5 | ex:revcomp, fixture:string-build, fixture:slice, fixture:case, and 1 more |
| a function that answers BOOL (equations answer numbers) | 3 | ex:binary-search, fixture:early-return, fixture:forall |
+14
View File
@@ -55,3 +55,17 @@ The Prove tab reports every obligation in three statuses (`src/engines/pseudo/vc
|---|---|---|---|
| Registers, caches, pipeline and counters in the Hardware area | The model machine (`src/engines/asm86/`), on the preset machine named in Setup | What that model does with these instructions | A measurement of a real processor. Cycle counts are a teaching model; compare a run with itself across edits |
| "stopped: … standard library, not on the model machine" | A call into a function the model does not have | The real program would enter the library here | That the library call does anything in particular |
## Library routines
A routine of pplus-library (`USE md`) carries the record of `pixi run library-check` ([library.md](library.md)).
| Shown | Earned by | Means | Does not mean |
|---|---|---|---|
| **Cases pass** | Running the pseudo on the cases in `routine.json` | The routine gives those results; they are what every reference is held to | That the results are right for other inputs |
| **Prover: pass** | Every obligation of the routine proved, as for any pseudo | Its contracts hold for every input that meets its REQUIRE, in the notation's number model | Anything about the value of FLOAT arithmetic beyond what the contracts say |
| **Prover: open** | Some obligation not proved, none broken | The routine's comment says which and why (usually FLOAT rounding, which is opaque to the prover) | That it is wrong |
| **A reference agrees** | Python, C at -O0 and -O2, core's Mojo interpreter, or the pinned compiler, run on the cases | That implementation, at that level, prints the pseudo's results exactly, or within the stated tolerance | That it agrees on other inputs, or at other optimization flags |
| **Mojo: unverified** | No stored answer from the pinned compiler for that exact program | Not yet asked (`pixi run library-verify-mojo`) | That it fails |
| **Proof: pass** | The pinned Dafny verified the proof file (or its stored verdict for this exact text) | The method is correct over exact numbers, as the proof states it | That the FLOAT version computes the same digits: rounding is outside the proof |