Files
pplus-core/README.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

8.7 KiB

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).
  • 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.

Quick start

Clone with the library submodule (git clone --recurse-submodules, or git submodule update --init in an existing clone). With pixi (it brings the pinned Mojo, Node and Python):

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):

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)
engines-diff <static> Show what a course checkout has not taken yet from the engines (docs/engines.md)
engines-export <static> Copy the engines into a course checkout, TypeScript modules as built (docs/engines.md)
Dafny, pinned (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)
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)
new-probe <name> <question> Start mojo/probes/<name>.mojo: one question about the compiler (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)
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
Document For
AGENTS.md Rules for anyone changing core, coding agents included: the gate, what not to edit, conventions
docs/engines.md The engines, the prover and its soundness, and how the course takes them
docs/trust.md Every verdict core produces: which tool earns it, what it means, and what it does not mean
docs/mojo-corpus.md Writing Mojo of our own and moving to a new Mojo version
docs/library.md The library: USE, what each check of a routine means, and changing it
docs/exercises.md Adding a catalog problem
docs/sync-coverage.md What each translator can say, written by the tests
docs/asm-coverage.md Which instructions compiled Mojo uses, against what the machine models