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

+10 -1
View File
@@ -7,13 +7,14 @@ pplus-core is the part of Programming+ that has to be right: the languages, the
- **Verification:** the prover (`src/engines/pseudo/logic.ts`, `solver.ts`, `vcgen.ts`), sound and held to it by tests; the fuzzer (`src/common/fuzz.ts`); and a pinned Dafny (`scripts/dafny.py`).
- **Stored answers:** the Mojo corpus (`mojo/`): material harvested from Modular's repositories at pinned commits, our own probes and programs, and godbolt's answers for every one of them (`mojo/golden/`).
- **A workspace:** `src/common/workspace.ts` is one piece of work and everything its sources mean. pplus-web's session extends it.
- **A library:** pplus-library, the submodule `library/`: verified routines (statistics, numerics, alignment, molecular simulation, sequences) that a program brings in with `USE`, each checked at every level ([docs/library.md](docs/library.md)).
- **A command line:** `pixi run cli check|run|prove|fuzz|translate <file>`.
Everything it says about Mojo is pinned to **Mojo 1.1.0** and checked against the real compiler on [Compiler Explorer](https://godbolt.org).
## Quick start
With [pixi](https://pixi.sh) (it brings the pinned Mojo, Node and Python):
Clone with the library submodule (`git clone --recurse-submodules`, or `git submodule update --init` in an existing clone). With [pixi](https://pixi.sh) (it brings the pinned Mojo, Node and Python):
```bash
pixi run test # build, then every test
@@ -46,6 +47,11 @@ Every command is a pixi task (`pixi task list` shows them with their description
| **Dafny, pinned** ([scripts/dafny.py](scripts/dafny.py)) | |
| `dafny-fetch` | Download the pinned Dafny into `.tools/`, checked by SHA-256 (network, once) |
| `dafny` | Run the pinned Dafny with the arguments given, e.g. `pixi run dafny verify file.dfy` |
| **The library** ([docs/library.md](docs/library.md)) | |
| `library-check` | Check every library routine at every level; writes `library/status.json` and `STATUS.md` |
| `library-emit` | Regenerate `src/library/generated.ts`, the registry `USE` reads, from `library/` |
| `library-verify-mojo` | Ask the pinned Mojo compiler about every Mojo reference of the library (network) |
| `library-harness <id> <lang> <level>` | Print the program a reference implementation is run as |
| **Write content** | |
| `new-exercise <id>` | Start an exercise whose Mojo lives in `mojo/local/<id>.mojo` ([docs/exercises.md](docs/exercises.md)) |
| `new-probe <name> <question>` | Start `mojo/probes/<name>.mojo`: one question about the compiler ([docs/mojo-corpus.md](docs/mojo-corpus.md)) |
@@ -79,6 +85,7 @@ AGENTS.md rules for changing core (read first)
src/
common/ the workspace, the problem catalog, the fuzzer, the run view's data, the language
reference, the machine presets, the shared types
library/ the registry USE reads (generated from library/), and its types
engines/pseudo/ the pseudo language and the prover (logic, solver, vcgen in TypeScript), and the course's
page widgets for it (excluded from the build; see docs/engines.md)
engines/asm86/ the x86-64 model machine, and the course's widgets that draw it (views, hwviews)
@@ -89,6 +96,7 @@ src/
exercises/ one file per catalog problem
curriculum/ a lesson corpus kept as an interpreter fixture
syntax/mojo.xml the Mojo words as a KDE syntax for Pandoc (generated; pplus-web copies it)
library/ pplus-library, a git submodule: verified routines that programs bring in with USE
tests/ node --test against dist/; corpus/ (pseudo programs), prover/ (soundness regressions)
mojo/ the Mojo corpus: the pin and lock, harvested material, our programs, godbolt's answers
scripts/ the tasks above; scripts/mojo/ is the corpus pipeline; dafny.py the Dafny pin; cli.mjs
@@ -103,6 +111,7 @@ docs/ the documents below
| [docs/engines.md](docs/engines.md) | The engines, the prover and its soundness, and how the course takes them |
| [docs/trust.md](docs/trust.md) | Every verdict core produces: which tool earns it, what it means, and what it does not mean |
| [docs/mojo-corpus.md](docs/mojo-corpus.md) | Writing Mojo of our own and moving to a new Mojo version |
| [docs/library.md](docs/library.md) | The library: USE, what each check of a routine means, and changing it |
| [docs/exercises.md](docs/exercises.md) | Adding a catalog problem |
| [docs/sync-coverage.md](docs/sync-coverage.md) | What each translator can say, written by the tests |
| [docs/asm-coverage.md](docs/asm-coverage.md) | Which instructions compiled Mojo uses, against what the machine models |