pplus-core
Programming+ takes a procedure from an idea to Mojo to the machine. pplus-core is the part of it that decides what a program means: the notations and the translators between them, the Mojo checker and interpreter, the prover, the fuzzer, the x86-64 machine model, and the tools that hold all of them to the ground truth in pplus-library. It has no DOM and runs in Node as well as in a browser. pplus-web, the site, uses it as a pinned dependency, and pixi run engines-export copies the engines into a course's own site.
- Who it is for: people who want to change or reuse the engines behind Programming+, or run them without a browser. The site, pplus-web, is where most people meet them.
- Status: in development, with no tagged release yet (CHANGELOG.md). It works from a clone today: the command line runs and the tests pass.
- Try it: Quick start. Run its checks:
pixi run ci, or the commands under Quick start without pixi. - Report a problem: SECURITY.md says where to send a report and what counts as a security problem (a "proved" that a run breaks is one); CONTRIBUTING.md says what makes a good bug report.
Programming+ works in five notations:
- lingo: steps in plain English that a reader can run.
- matho: equations written in LaTeX.
- pseudo: pseudocode precise enough to run, prove and translate; every translation goes through it.
- speco: a specification to prove against: what a routine requires and ensures, and what each loop keeps.
- Mojo: Modular's programming language, pinned to version 1.2.0. Programming+ writes Mojo from pseudo, steps through it, and asks the real compiler about it.
What core holds:
- Languages: pseudo (parser, checker, interpreter, and the English reader for lingo), matho, speco, Mojo (a checker and an interpreter held to the real compiler's stored answers), 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 notations in step (
src/sync/). - Verification: the prover (
src/engines/pseudo/logic.ts,solver.ts,vcgen.ts), meant to be sound and held to it by the soundness regressions inlibrary/pseudo/prover/(an audit in November 2026 closed 18 rules that proved what a run breaks), a canary, and a run of every corpus program (docs/engines.md); the fuzzer (src/common/fuzz.ts); and a pinned Dafny (scripts/dafny.py). - A workspace:
src/common/workspace.tsis one piece of work and everything its sources mean. pplus-web's session extends it. - The ground truth: pplus-library, the submodule
library/, holds what the engines are held to; core also builds its library registry and the exercises' Mojo from it:- verified routines (statistics, numerics, alignment, molecular simulation, sequences, special functions) that a program brings in with
USE, each checked by every toolpixi run library-checkhas (docs/library.md); - the Mojo corpus (
library/mojo/): the pin, material harvested from Modular's repositories at pinned commits, our own probes and programs, and godbolt's stored answer for every program we wrote and every harvested program that runs (the compiler's own diagnostic tests are asked only on request) (docs/mojo-corpus.md); - pseudo regression programs and the prover's soundness regressions (
library/pseudo/).
- verified routines (statistics, numerics, alignment, molecular simulation, sequences, special functions) that a program brings in with
- A command line:
pixi run cli check|run|prove|fuzz|translate <file>(translatetakes--to mojo,lingo,mathoorspeco).
What core says about Mojo is pinned to Mojo 1.2.0. The checker and the interpreter are held to the real compiler's answers on the corpus: to godbolt's stored answers in the tests, and to the pinned compiler on a developer's machine with pixi run mojo-local and mojo-fuzz, which also build the Mojo the translator writes. On a program outside the corpus the interpreter can still run something the compiler rejects; docs/trust.md says what each verdict means and what it does not.
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 dafny-fetch # once: the pinned Dafny, into .tools/ (network; until then the one test that runs it is skipped)
pixi run test # build, then every test
pixi run ci # the gate: every test, no Mojo program we wrote failing by godbolt's stored answers, library-check, mojo-local and a short fuzz
pixi run cli prove library/pseudo/programs/19-max-subarray.pseudo # each obligation and its status; the last line is "6 proved, 0 broken, 0 open"
The tests that need a tool that is missing (the fetched Dafny, python3, a C compiler cc for the library's C references) are skipped and say so; under CI they fail instead (docs/ci.md).
Without pixi, with Node (package.json asks for 20 or later; the tests run on Node 26.10, which pixi pins) and python3 for the pipelines' tests:
npm install && npm test
python3 scripts/mojo/corpus.py status --strict
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) |
prove-fuzz |
Fuzz the prover: random procedures with contracts are proved, then run; fail on a proved obligation a run breaks (docs/engines.md) |
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 |
library-harness-input <id> <lang> <level> |
Print the line of stdin a C or Mojo reference's program reads (its cases arrive at run time) |
| Write content | |
new-exercise <id> |
Start an exercise whose Mojo lives in library/mojo/local/<id>.mojo (docs/exercises.md) |
new-probe <name> <question> |
Start library/mojo/probes/<name>.mojo: one question about the compiler (docs/mojo-corpus.md) |
new-stress <name> <about> |
Start library/mojo/stress/<name>.mojo: realistic Mojo that tests the interpreter |
play <name> |
For library/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 library/mojo/golden/STATUS.md |
mojo-status-strict |
The same, and fail if a program we wrote fails |
mojo-prune |
Remove stored answers nothing reads any more: another compiler's, and those of edited or removed programs |
mojo-harvest |
After editing library/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 library/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, built with the pin's build arguments and then its own |
mojo-local |
Build every Mojo program core holds or generates on the pinned local compiler; hold the checker, interpreter and translator to it |
mojo-fuzz |
Fuzz the translator, the checker and the interpreter against the pinned local compiler with generated programs |
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 |
ci-fuzz |
The fuzzers' share of ci: mojo-fuzz and prove-fuzz on seed 1 and on a seed that moves, each printed (docs/ci.md) |
nightly |
What the scheduled CI runs: mojo-status-strict, and the fuzzers longer on four seeds that move with the date |
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 a course's
page widgets for it (excluded from the build; see docs/engines.md)
engines/asm86/ the x86-64 model machine, and a course's widgets that draw it (views, hwviews)
engines/shared/ text helpers, and a 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
library/ pplus-library, a git submodule: the ground truth
modules/ verified routines that programs bring in with USE
mojo/ the Mojo corpus: the pin and lock, harvested material, our programs, godbolt's answers
pseudo/ programs/ (pseudo regression programs), prover/ (soundness regressions)
syntax/mojo.xml the Mojo words as a KDE syntax for Pandoc (generated; pplus-web copies it)
tests/ node --test against dist/, over the programs in library/ and the cases in each test
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 | 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 a course's site takes them |
| docs/trust.md | Every verdict core produces: which tool earns it, what it means, and what it does not mean |
| docs/limits.md | Where each reader and each run stops on text from a share link, and what the student sees then |
| docs/ci.md | What CI and the nightly run do, and what to do when they fail |
| 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 |
License
Copyright 2026 Scientific Computing Studio, LLC, under the Apache License 2.0 (LICENSE.md); NOTICE.md has the notices and a disclaimer of affiliation with Modular, and THIRD_PARTY.md lists what is not ours and its licenses.