alexm 38e6e2cdd2
Test / gate (push) Canceled after 0s
A proof report says when the clock stopped it
The Prove tab gives each routine 3 seconds on the clock, and on a slow
or busy machine that runs out before the proof does: claims stay open
with nothing to say why. Now the prover marks a unit it ran out of time
on (timedOut, and an out-of-time note), checkProperties says when the
clock cut its inputs short, and ProofReport.clock carries the budget and
the routines it stopped, so a caller can offer more time.
2026-11-13 06:55:11 -05:00
2026-11-12 22:23:54 -05:00
2026-11-12 22:23:54 -05:00
2026-11-12 22:23:54 -05:00
2026-11-12 22:23:54 -05:00
2026-11-12 22:23:54 -05:00
2026-11-12 22:23:54 -05:00
2026-11-12 22:23:54 -05:00
2026-11-12 22:23:54 -05:00
2026-11-12 22:23:54 -05:00
2026-11-12 22:23:54 -05:00
2026-11-12 22:23:54 -05:00
2026-11-12 22:23:54 -05:00
2026-11-12 22:23:54 -05:00
2026-11-12 22:23:54 -05:00

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 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); 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);
    • 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/).
  • A command line: pixi run cli check|run|prove|fuzz|translate <file> (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 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
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.

S
Description
No description provided
Readme Cite this repository
5.2 MiB
0 Stars 1 Watchers 0 Forks
Languages
TypeScript 47.7%
JavaScript 47.1%
Python 4.9%
Mojo 0.3%