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
118 lines
8.7 KiB
Markdown
118 lines
8.7 KiB
Markdown
# pplus-core
|
|
|
|
pplus-core is the part of Programming+ that has to be right: the languages, the translators between them, the Mojo checker and interpreter, the prover, the fuzzer, the x86-64 machine model, and the stored answers of the real tools that everything it says rests on. It has no DOM. pplus-web (the site, the editor, the views and the Quarto extension) and the course site use it as a pinned dependency.
|
|
|
|
- **Languages:** pseudo (parser, checker, interpreter, the English reader for lingo), matho (equations in LaTeX), speco (specifications), Mojo (a checker and an interpreter held to the real compiler), x86-64 on a model machine with caches, a pipeline and an out-of-order core.
|
|
- **Translators:** pseudo to Mojo, lingo, matho and speco, with line maps and located refusals, and the hub that keeps the linked languages in step (`src/sync/`).
|
|
- **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
|
|
|
|
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
|
|
pixi run ci # the gate: every test, and no Mojo program of ours failing
|
|
pixi run cli prove tests/corpus/27-quantifiers.pseudo
|
|
pixi run dafny-fetch # once: the pinned Dafny, into .tools/
|
|
```
|
|
|
|
Without pixi, with Node 20 or later (and `python3` for the pipelines' tests):
|
|
|
|
```bash
|
|
npm install && npm test
|
|
```
|
|
|
|
## Commands
|
|
|
|
Every command is a pixi task (`pixi task list` shows them with their descriptions). `tests/tasks.test.mjs` fails if this table and `pixi.toml` disagree.
|
|
|
|
| Task | What it does |
|
|
|---|---|
|
|
| **Build and test** | |
|
|
| `install` | Install TypeScript, the only npm dependency |
|
|
| `build` | Compile `src/` to `dist/`, with type declarations for pplus-web |
|
|
| `watch` | Rebuild `dist/` on every change |
|
|
| `check` | Type-check only |
|
|
| `test` | Build, then run every test, the pipelines' Python tests included |
|
|
| `cli` | `pplus check\|run\|prove\|fuzz\|translate <file>`: core without a browser ([scripts/cli.mjs](scripts/cli.mjs)) |
|
|
| `engines-diff <static>` | Show what a course checkout has not taken yet from the engines ([docs/engines.md](docs/engines.md)) |
|
|
| `engines-export <static>` | Copy the engines into a course checkout, TypeScript modules as built ([docs/engines.md](docs/engines.md)) |
|
|
| **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)) |
|
|
| `new-stress <name> <about>` | Start `mojo/stress/<name>.mojo`: realistic Mojo that tests the interpreter |
|
|
| `play <name>` | For `mojo/local/<name>.mojo`: run, verify on godbolt, build, list the assembly, test |
|
|
| `play-watch <name>` | The same, again on every save (tests off) |
|
|
| **The Mojo corpus** ([docs/mojo-corpus.md](docs/mojo-corpus.md)) | |
|
|
| `mojo-verify` | Ask godbolt about every program with no answer yet (network) |
|
|
| `mojo-verify-item <id>` | Ask again about one item, e.g. `'probes/life-*'` (network) |
|
|
| `mojo-verify-dry` | Show what `mojo-verify` would send; send nothing |
|
|
| `mojo-verify-diagnostics` | Also check the compiler's own diagnostic tests (opt-in; network) |
|
|
| `mojo-status` | Judge every item from the stored answers, offline; writes `mojo/golden/STATUS.md` |
|
|
| `mojo-status-strict` | The same, and fail if a program we wrote fails |
|
|
| `mojo-harvest` | After editing `mojo/pin.json`: fetch Modular's sources, process, regenerate (network) |
|
|
| `mojo-harvest-local [dir]` | Harvest, with zips standing in for sources the pin leaves unresolved |
|
|
| `mojo-harvest-offline [dir]` | Harvest from zips only, no network |
|
|
| `mojo-fetch` | Re-resolve every ref in the pin and rewrite the lock (network) |
|
|
| `mojo-emit` | Regenerate `src/mojo/generated/` and `syntax/mojo.xml` from the pin and corpus, offline |
|
|
| `mojo-test` | The corpus pipeline's own tests |
|
|
| `mojo-run <file>` | Run one Mojo file on the pinned local compiler |
|
|
| `mojo-probes-local` | Run every probe on the local compiler (a quick look) |
|
|
| `mojo-update` | After editing the pin: harvest, verify, status, test |
|
|
| **Ship** | |
|
|
| `ci` | What CI runs: every test, and no program of ours failing |
|
|
| `package` | Zip what git tracks, and nothing it ignores, into `package/` for sharing |
|
|
|
|
## Where things are
|
|
|
|
```
|
|
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)
|
|
engines/shared/ text helpers, and the course's DOM helpers
|
|
services/ one adapter per language behind LanguageService; the compiler request and backend
|
|
sync/ the translators and the hub that keeps the linked languages in step
|
|
mojo/ the Mojo checker, interpreter, lifetimes, practices, AT&T-to-Intel; generated/ from the corpus
|
|
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
|
|
docs/ the documents below
|
|
```
|
|
|
|
## Read next
|
|
|
|
| Document | For |
|
|
|---|---|
|
|
| [AGENTS.md](AGENTS.md) | Rules for anyone changing core, coding agents included: the gate, what not to edit, conventions |
|
|
| [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 |
|