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:
21 files changed
+2654
-20
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user