# 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](CHANGELOG.md)). It works from a clone today: the command line runs and the tests pass. - **Try it:** [Quick start](#quick-start). **Run its checks:** `pixi run ci`, or the commands under Quick start without pixi. - **Report a problem:** [SECURITY.md](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](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 in `library/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](docs/engines.md#soundness)); the fuzzer (`src/common/fuzz.ts`); and a pinned Dafny (`scripts/dafny.py`). - **A workspace:** `src/common/workspace.ts` is 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 tool `pixi run library-check` has ([docs/library.md](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](docs/mojo-corpus.md)); - pseudo regression programs and the prover's soundness regressions (`library/pseudo/`). - **A command line:** `pixi run cli check|run|prove|fuzz|translate ` (`translate` takes `--to mojo`, `lingo`, `matho` or `speco`; `prove` has no time limit unless `--budget-ms` gives one, so it says the same on every machine). 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](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](https://pixi.sh) (it brings the pinned Mojo, Node and Python): ```bash 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](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: ```bash 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 `: core without a browser ([scripts/cli.mjs](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](docs/engines.md#soundness)) | | `engines-diff ` | Show what a course checkout has not taken yet from the engines ([docs/engines.md](docs/engines.md)) | | `engines-export ` | 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 ` | Print the program a reference implementation is run as | | `library-harness-input ` | Print the line of stdin a C or Mojo reference's program reads (its cases arrive at run time) | | **Write content** | | | `new-exercise ` | Start an exercise whose Mojo lives in `library/mojo/local/.mojo` ([docs/exercises.md](docs/exercises.md)) | | `new-probe ` | Start `library/mojo/probes/.mojo`: one question about the compiler ([docs/mojo-corpus.md](docs/mojo-corpus.md)) | | `new-stress ` | Start `library/mojo/stress/.mojo`: realistic Mojo that tests the interpreter | | `play ` | For `library/mojo/local/.mojo`: run, verify on godbolt, build, list the assembly, test | | `play-watch ` | 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 ` | 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 ` | 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](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](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 a course's site 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/limits.md](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](docs/ci.md) | What CI and the nightly run do, and what to do when they fail | | [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 | ## License Copyright 2026 Scientific Computing Studio, LLC, under the Apache License 2.0 ([LICENSE.md](LICENSE.md)); [NOTICE.md](NOTICE.md) has the notices and a disclaimer of affiliation with Modular, and [THIRD_PARTY.md](THIRD_PARTY.md) lists what is not ours and its licenses.