Initial commit
Test / gate (push) Failing after 19m0s

This commit is contained in:
alexm committed 2026-11-12 22:23:54 -05:00
commit 401084bab3
265 files changed
+69224

No files matched your search

+51
View File
@@ -0,0 +1,51 @@
# The model machine against compiled Mojo
"Open in Hardware" puts a function from the real compiler's listing on the model machine (`src/engines/asm86`), translated from godbolt's AT&T syntax by `src/mojo/att.ts`. The machine implements a teaching subset of x86-64, so the question is how much of what the Mojo compiler actually emits it can take. This is the census: every function in every listing the corpus holds (`library/mojo/golden/*.json` answered with `asm`), sent exactly as the button sends it, and what the assembler said. `node scripts/asm-census.mjs` reruns it (add `--ops` for every mnemonic); `tests/asm-coverage.test.mjs` holds the numbers as a ratchet, so a new corpus item that brings a new instruction fails the build rather than a student's session.
## Where it stands
| | before | now |
|---|---|---|
| distinct instructions in the listings | 97 | 104 |
| of which outside the model's set | 38 | 6 (all 256-bit AVX2: `vextracti128`, `vinserti128`, `vpblendvb`, `vperm2i128`, `vpalignr`, `vptest`) |
| the user's own functions that assemble | 3 of 7 (`main` never did) | 17 of 17 |
| standard-library and runtime functions that assemble | — | 698 of 733 |
The "before" column is the census of the listings the corpus held when this work began; the "now" column is today's census of today's listings, and `tests/documents.test.mjs` fails when it no longer matches `node scripts/asm-census.mjs`. Every listing is built for `--target-cpu x86-64-v3` (the pin's build arguments, [mojo-corpus.md](mojo-corpus.md#how-every-program-is-built)), so it holds AVX2 at most and never AVX-512, whichever of godbolt's machines answered; `tests/build-args.test.mjs` fails on a listing with a `zmm` or mask register. Asked again under those arguments, every listing the corpus held came back with the same instructions; `vptest` and four modeled ones (`adc`, `cmovle`, `jns`, `tzcnt`) came with `probes/godbolt-target-cpu`, String's `==` at the default optimization level.
`main()` now steps up to its first call into `print` and stops there with "stopped: std_io_io_print: standard library, not on the model machine", which is the honest answer: the model has no standard library, and says exactly where the real program would enter it.
## What was wrong, and what changed
**The translator dropped size suffixes only for the mnemonics it knew.** AT&T writes `andnq`, `mulxq`, `shlxq`, `xaddq`, `cmpxchgq`, `btsq`, `bswapq`; the Intel pane reads `andn`, `mulx`, … The BMI and atomic mnemonics were missing from the suffix table, so the machine was asked for an instruction called `andnq`, which exists nowhere. They are in the table now, and `lock` (a prefix) is passed through as a prefix rather than treated as a mnemonic with an operand called `xaddq`.
**The machine lacked the instructions the optimizer likes.** Added, each with a one-sentence gloss for the datapath view and the micro-op model told what it reads and writes:
- BMI1/BMI2: `andn`, `mulx`, `shlx`, `shrx`, `sarx`, `bzhi`, `blsr`, `blsi`, `blsmsk`, `rorx`, `bextr` (`pdep`/`pext` are named as not modeled)
- the atomics behind reference counts: `xadd`, `cmpxchg`, and the `lock` prefix, accepted on the read-modify-writes the ISA allows it on
- bit tests that write: `bts`, `btr`, `btc`; `bswap`; `cwd`, `cwde`, `cbw`
- `ud2`: the trap the compiler plants on paths that must never run; reaching it stops the run with "the processor raised an invalid-opcode fault"
- the 128-bit AVX spellings of what the subset had: `vmovdqu`, `vmovdqa`, `vmovups`, `vmovaps`, `vmovd`, `vmovq`, `vpxor`, `vxorps`, `vpor`, `vpand`, `vpandn`, `vpaddb`, `vpsubb`, `vpcmpeqb`, `vpmovmskb`, `vzeroupper`; three-operand form (`vop dst, a, b`), sources untouched
- lanes: `vpinsr{b,w,d,q}`, `vpextr{b,w,d,q}`, `vpshufb`, `vpshufd`, `vpbroadcast{b,d}`, `vpmin/max{ub,ud}`, `vpcmpeq{w,d,q}`, `vpadd{w,d}`, `vpsubd`, `vpsubusb`, `vpsll/vpsrl{w,d,q}`
**A call into the standard library refused the whole listing.** The assembler resolves every label up front, so one `call std::io::print` meant the function could not be stepped at all, even to the instruction before the call. The translator now appends a stub for every such symbol (`label:` then `ud2 ; …: standard library, not on the model machine`), so the function assembles, steps up to the call, and the stop says what it called.
**Read-only strings were unreachable.** `lea rax, [rip + static_string_…]` named a label that was data, not code, and the machine has no data directives. The translator now finds the `.asciz` behind each such label, places the bytes in memory (`memory 0x6000 "…"`, octal and hex escapes decoded, from 0x6000 up), writes the address in the instruction's place, and hands the lines to the setup block, where the student can see them.
## Scalar doubles, parity, shld (added)
- `addsd subsd mulsd divsd sqrtsd movsd cvtsi2sd ucomisd comisd` and their `v` forms: IEEE binary64, round to nearest even, default NaN `0xFFF8000000000000`, a NaN operand is quieted and the first operand wins. MXCSR exception flags are not modeled.
- `ucomisd`/`comisd` set ZF/PF/CF as hardware does (unordered sets all three; OF, SF clear).
- PF is a real flag now: set by logic, add/sub and shifts, cleared by `popcnt`, untouched by rotates. `jp jnp jpe jpo`, `cmovp…` and `setp…` follow.
- `shld`/`shrd` on 32- and 64-bit operands; count masked to 5/6 bits; count 0 changes nothing, flags included.
- Latencies: add/mul 4, div 14, sqrt 18 (unpipelined on port 0), convert 5, compare 3.
## What stays outside, and why
- **256-bit AVX2 (`ymm`)**: the model keeps sixteen 128-bit `xmm` registers and no `ymm` halves; the six instructions above are used only in that width. A `ymm` operand is refused with that sentence. Modeling it means widening every vector register and every lane helper; worth doing only when a user function needs it, and none in the corpus does.
- **Symbols the listing addresses but does not define**: `KGEN_…` runtime globals, `…@GOTPCREL` function pointers, a `.zero` constant. The assembler names the symbol in its refusal.
- **Constant-pool blocks with a symbol in them** (jump tables): not placed; the instruction that loads one is refused by name. Numeric `.LCPI…` blocks (`.quad`, `.long`, `.double`, `.zero`, …) *are* placed, 16-byte aligned from 0x6000, when the code addresses them, and `.LCPI0_0+8(%rip)` works.
## Keeping it honest
The census runs against whatever the corpus holds: every stored answer that carries a listing (the probes and exercise programs whose header asks for `mode: asm` or `mode: both`). `pixi run mojo-verify` on a new such program adds its listing, and each addition either assembles or fails `tests/asm-coverage.test.mjs` with the instruction named. That test's ratchet (`LIBRARY_AT_LEAST`) is a floor under the table's library count; raise it when the machine learns more, never lower it.
+48
View File
@@ -0,0 +1,48 @@
# CI
CI runs what a developer runs. Every workflow installs pixi, restores the environment `pixi.lock` pins (Node, Python, the Mojo compiler) with `pixi install --locked`, and runs a pixi task, so the gate on the runner and the gate on a laptop are the same command in the same environment. Five weeks once passed with `main` broken in two places and nobody told: CI then ran `npm ci && npm test` with whatever Node the host had, no pandoc, no Mojo compiler and no Dafny, and a missing tool skipped tests in silence.
| Workflow | When | Runs | Time here |
|---|---|---|---|
| `.gitea/workflows/test.yml` | every push and pull request | `pixi run ci`, then checks that nothing the gate regenerates differs from what is committed | 4 minutes here, 2.5 with `mojo-local`'s answers cached |
| `.gitea/workflows/nightly.yml` | every day at 06:17 UTC, and by hand | `pixi run nightly` | 12 minutes here |
| pplus-library's `.gitea/workflows/test.yml` | every push and pull request to the library | core's default branch with that library commit in `library/`, then `pixi run ci` (below) | as core's |
`pixi run ci` is `test` (every test), `mojo-status-strict` (no Mojo program of ours fails, from godbolt's stored answers), `library-check` (every library routine at every level, Dafny included), `mojo-local` (every Mojo program core holds or generates, built and run by the pinned compiler) and `ci-fuzz` (below). `pixi run nightly` is `mojo-status-strict` and the fuzzers for longer.
## The runner
The workflows are written for Gitea Actions on a runner in host mode (no container: steps run on the host's shell); pplus-web's `docs/deploy.md` has the setup. They use no `container:` and no `services:`, and each needs one change to run on GitHub Actions: `runs-on: ubuntu-latest` in place of the host's label.
- **pixi.** `PIXI_VERSION` at the top of each workflow is the pixi that reads the lock. The first step uses the host's pixi when it is that version; otherwise it downloads that release from GitHub into `$PPLUS_CI_CACHE/pixi-<version>/` (default `~/.cache/pplus-ci`), checks its SHA-256 (written in the workflow), and puts it on the PATH. No sudo; a host runner fetches it once. To move pixi: change `PIXI_VERSION` and both hashes in every workflow, in one commit, and check that `pixi install --locked` still accepts the lock.
- **The environment.** `pixi install --locked` fails if `pixi.toml` and `pixi.lock` disagree, so the runner never resolves anything new. pixi's package cache stays on the host, so a host runner downloads each package once.
- **`.tools/`.** The pinned Dafny (`pixi run dafny-fetch`, about 150 MB) and `mojo-local`'s answers live in `.tools/`; in CI `.tools` is a link to `$PPLUS_CI_CACHE/core-tools`, so neither is fetched or rebuilt on every push. `mojo-local` keys an answer by the compiler's version, the arguments, the input and the whole source, so a cached answer is the compiler's answer for exactly that program. Two jobs that share the cache at once could write the same answer file together; the runner takes one job at a time unless its `capacity` is raised.
- **`CI`.** Each workflow sets `CI=true` (Gitea and GitHub set it too). Under it a test that would skip for a missing tool fails instead, because a skip in CI is how a gap hides: python3 (`tests/mojo.test.mjs`, `tests/dafny.test.mjs`, `tests/library.test.mjs`), the fetched Dafny (`tests/dafny.test.mjs`), a git checkout to read the library pointer from (`tests/chain.test.mjs`), and in pplus-web pandoc for the Quarto tests.
- **What the host needs besides pixi:** git, curl, tar, `sha256sum`, bash, and Node for `actions/checkout` itself; a C compiler (`cc`) for the C references `library-check` builds. Without `cc` those checks are recorded as skipped, `library/status.json` then differs from the committed one, and the last step of `test.yml` fails and says so.
## The fuzzers' seeds
`pixi run ci-fuzz` runs `mojo-fuzz` (25 programs of expressions), `mojo-fuzz --statements` (25 whole programs) and `prove-fuzz` (300 programs) on two seeds each: seed 1, so a failure that comes back is the same failure, and a seed that moves, so every run looks somewhere new: the CI run's number (`GITHUB_RUN_NUMBER`, which Gitea sets too) or, outside CI, today's date in UTC as `YYYYMMDD`. `pixi run nightly` runs all three on four seeds, the date's number and the three numbers after it, with 100, 100 and 3,000 programs. The size matters: the statement mode's first run at 100 programs a seed found a translator fault (an argument evaluated once per pass of a loop) that many seeds of 40 had not. Every round prints its seed and the command that reproduces it:
```
== prove-fuzz seed 20261113 (reproduce: node scripts/prove-fuzz.mjs --seed 20261113 --programs 3000)
```
and the run ends with a summary, one line per round, `clean`, `FOUND` or `FAILED`.
## When CI or the nightly run fails
1. **Find the round.** The summary at the end of the log names it, with its command.
2. **Reproduce it here.** Run the same command as a pixi task, with the same seed and size: `pixi run prove-fuzz --seed 20261113 --programs 3000`, or `pixi run mojo-fuzz --seed 20261113 --programs 100`. The same seed makes the same programs on every machine. The prover has a time budget for each routine (`--budget-ms`, 1,500 ms), so a slower machine may prove less than the runner did, never more; if a prove-fuzz finding does not come back, raise the budget.
3. **A prove-fuzz finding** is a soundness bug: an obligation marked proved that a run breaks. The report names the program's number and prints the smallest program that still shows it, with the call and the run's seed. `pixi run prove-fuzz --seed S --only-program N --keep work/` writes it as a regression program with its `// CALL:` and `// MUST-NOT-PROVE:` header. Check it by hand (`pixi run cli prove <file>` says proved; running it with that call breaks it), put it in `library/pseudo/prover/`, watch `tests/prover-soundness.test.mjs` fail, then fix the rule (AGENTS.md, rule 5; [engines.md](engines.md#soundness)). `--without <feature>` switches off one construct at a time to see which one the finding needs.
4. **A mojo-fuzz finding** is printed once per shape with the smallest expression that shows it; its header (`scripts/mojo/fuzz.mjs`) says what each kind means. A translator fix is pinned in `tests/sync-mojo.test.mjs`; a finding that is the compiler's own is listed there as such, with what was observed.
5. **mojo-status-strict** failing means a program we wrote fails against godbolt's stored answers: see [mojo-corpus.md](mojo-corpus.md).
6. **Anything else** in `pixi run ci` fails the same way on a developer's machine: run `pixi run ci` and read the first failure.
A failure opens no issue and sends nothing: the run is red on the repository's Actions page, for whoever looks. Look after a push, and look at the nightly runs at least weekly.
## The pointer to the library
Core pins pplus-library as `library/` by commit. `tests/chain.test.mjs` fails when that commit is not in the library checkout, or the checkout is behind it, and says which command fixes it (`git submodule update --init`). The whole chain (web pins core, core pins library; each pointer pushed to its branch; the generated files current; Mojo pinned alike) is checked by pplus-web's `release-check` task, and moved in order by its `release-bump` task (pplus-web's `docs/deploy.md`).
pplus-library has no tests of its own: its checks are core's. Its workflow checks out core's default branch (or the ref in the repository variable `CORE_REF`), puts the library commit being tested where core's submodule goes, moves core's pointer to it in that throwaway checkout and regenerates what core derives from the library (`library-emit`, `mojo-emit`), and runs `pixi run ci`. A green run shows that core's default branch, given this library and what core regenerates from it, passes core's whole gate. It does not show that core pins this commit (that is a later commit in core), that the site works with it, or anything about a core branch other than the one tested; and a red run can be core's own, so look at core's latest run first.
+121
View File
@@ -0,0 +1,121 @@
# The engines
Programming+ runs the language engines that the course site also runs, so a program behaves the same in the app as on a course page. The course's widget stylesheets live in pplus-web (`styles/course/`), which compares them with the course's. **This repository owns the engines.** Changes are made and tested here, and the course copies them from here (`pixi run engines-export`). The engines started as a copy of the course's modules; the course no longer sends changes the other way.
| Here | The course receives it as | What it is |
|---|---|---|
| `src/engines/pseudo/` | `static/js/pseudo/` | The pseudo language: parser, checker, interpreter, the English (lingo) reader, the prover (`logic.ts`, `solver.ts`, `vcgen.ts`), translation |
| `src/engines/asm86/` | `static/js/asm86/` | The x86-64 model machine, its caches, pipeline and out-of-order core, and the widgets that draw them |
| `src/engines/shared/` | `static/js/shared/` | DOM helpers, URL state, text distance, charts |
The engines are wrapped behind one `LanguageService` interface (`src/common/types.ts`, adapters in `src/services/`). The course's page widgets (the pseudo views, the asm86 `views`/`hwviews`, the shared DOM helpers) sit beside the engines so the course and pplus-web take them from one place; the pseudo ones and a few others are excluded from core's build in `tsconfig.json`, and `tests/boundary.test.mjs` keeps core's library modules from importing any of them. A change in `src/engines/` is a change to the course's language, so it needs a test here and goes to the course by export.
## The prover
The prover is three TypeScript modules under strict mode. So are the parser, checker and interpreter it reads from: `ast.ts` states the syntax tree (discriminated unions `Expr` and `Stmt`), the checker's types (`PType`), symbols, run-time values and the trace, and `lang.ts`, `parse.ts`, `check.ts` and `interp.ts` are typed on it; `numeric.ts` (the exact arithmetic, which needs none of it) is TypeScript too. All five were ported with no change in behavior (each stage's results were compared over every pseudo text of the repository and 8,000 mutants of them). The course still receives each as `<name>.js`, built into `dist/engines/pseudo/`. The rest of the pseudo engine (the English reader, analysis, coach, tests, translation, `study`, the course's example programs in `specs` and the vague-word finder in `vague`) and the page widgets are still JavaScript.
- `logic.ts`: the term language (a discriminated union, `Term`), the smart constructors that simplify as they build, keys, substitution, linear forms and printing.
- `solver.ts`: the decision procedure, `prove(facts, goal)`. It answers `proved` or `unknown`, never "false". Equalities by union-find with congruence, linear arithmetic over whole numbers by Fourier-Motzkin with integer tightening, case splits, and FORALL used at the positions a case mentions. It is sound and incomplete: products of two unknowns, MOD by an unknown, and most facts about collections are opaque to it.
- `vcgen.ts`: the proof obligations, by symbolic execution, with loops cut at their invariants and simple invariants found by Houdini-style inference.
"Proved" is about the notation's own number model. INTEGER is a whole number of any size and a FLOAT is a finite number whose rounding the prover does not see into. A run of the interpreter stops where a value leaves that model (a whole number past 2^53 − 1, a FLOAT that is not finite, a division by zero), so every run stays inside what a proof covers. The Mojo made from a program has other limits (a 64-bit `Int` that wraps, a `Float64` that becomes `inf` or `nan`), and a unit whose proof leans on the number model carries an `int-model` or `float-model` note saying so.
### Numbers
Pseudo is meant for numerical work, so its number model is stated exactly ([the reference](../src/common/reference.ts) shows every form with a runnable example):
| Type | Holds | When a result does not fit | The prover |
|---|---|---|---|
| `INTEGER` | A whole number of any size; a run holds it exactly to 2^53 − 1 | The run stops past 2^53 − 1, also when the number comes from a FLOAT (`INT`, `ROUND`, `FLOOR`, `CEIL`), from SUM, on a FOR counter, and from INPUT or `TO_INTEGER` | Exact arithmetic of any size; an `int-model` note says the lab's and Mojo's limits are not part of the proof |
| `INT8` … `INT64`, `UINT8` … `UINT64` | Two's complement or unsigned, n bits (64-bit types held exactly to 2^53 − 1 in this lab) | The run stops (kind `overflow`); `WRAP(X, T)` wraps on purpose (up to 32 bits) | Exact arithmetic plus an `overflow` obligation on every result, store, parameter, RETURN, conversion and declared FOR counter: "fits INT8". After it, the range is a fact. A sized parameter and a sized variable cut by a loop keep their range |
| `FLOAT`, `FLOAT64` | IEEE 754 double | The run stops on infinity or NaN | `FLOAT+` and its kind are uninterpreted: the same operation on the same values gives the same result, nothing more |
| `FLOAT32` | IEEE 754 single: every result rounded to 24 bits (`Math.fround`, exact for +, −, ×, ÷ of singles) | As FLOAT | Its own uninterpreted functions (`F32+`, ...); a constant is rounded exactly; a value that becomes a FLOAT32 is `TOFLOAT32(v)`, about which nothing is assumed |
Rules the checker holds: two different sized types never mix silently (`mixed-width`, `mixed-precision`; convert with `INT32(X)`, `FLOAT32(X)`); a numeric literal takes the type of the sized value beside it, as in Mojo, and a whole-number literal that does not fit is an error before any run (`literal-range`); INTEGER may go into a sized type (checked when it happens), never a different sized type.
`USE IEEE` lets NaN and the infinities flow as IEEE 754 says (SQRT(−1.0) is NaN, 1.0 / 0.0 is infinity; whole-number division by zero still stops). Where IEEE 754 says what a built-in gives, that is what a run gives: `MIN` and `MAX` with a NaN among their values are NaN wherever it stands (754-2019 `minimum` and `maximum`), `ULP` of an infinity is infinity (as Python's `math.ulp`; 754 defines no ulp), `^` and `POW` follow 754's `pow` (1 to any power, NaN included, is 1, and so is −1 to an infinite power), and `SORTED` puts NaN last. The prover's reasoning about numbers does not hold for those values, so in such a program nothing is marked proved, and each unit carries an `ieee` note. Without it, NaN and the infinities do not enter a run from outside either: a call's argument (`run()` with `call`) that is or holds one for a FLOAT parameter stops the run before the call (kind `value`).
What is exact or correctly rounded, and what is not: `FMA`, `ULP`, `NEXT_AFTER`, `EXACT`, `SQRT`, the conversions (`FLOAT32(X)`, `INT32(X)`, a decimal literal that becomes a FLOAT32), `MAX_VALUE`, `EPSILON`, the bit operations, `GCD`, `LCM`, `CHOOSE`, `DIV` and `MOD`, and `+`, `-`, `*`, `/` are: `src/engines/pseudo/numeric.ts` computes `FMA` with one rounding by exact binary arithmetic, `EXACT(X)` gives every decimal digit a FLOAT holds, and `ULP` and `NEXT_AFTER` step through the representation. The elementary functions (`EXP`, `LOG` and its kind, `EXPM1`, `LOG1P`, `CBRT`, `HYPOT`, the trigonometric and hyperbolic ones, `POW` and `^` with a FLOAT) are the JavaScript engine's: within one unit in the last place of the correctly rounded value in almost every case (`HYPOT` within two), not always equal to it (`EXPM1(1.0)` is 1.718281828459045, where the nearest FLOAT is 1.7182818284590453). The statistics (`SUM_OF`, `MEAN_OF`, `VARIANCE_OF`, `STDEV_OF`, `MEDIAN_OF`, `DOT`, `NORM_OF`) are the plain left-to-right sums a loop would compute, with that loop's rounding and its overflow on the way: over whole numbers every product and partial sum is checked as `*` and `+` check theirs (`DOT([94906267, 1], [94906267, -9007199254740991])` stops, though the total fits), over FLOATs each is rounded in turn; `MEDIAN_OF` sorts and takes the middle value or the mean of the two middle ones (`NORM_OF` of one value past about 1.34e154 stops, since its square passes the largest FLOAT, `SUM_OF([1e16, 1.0, -1e16])` is 0.0); a lesson on compensated summation writes its own. `IS_CLOSE` evaluates its formula in FLOAT arithmetic, as Python's `math.isclose` does. `DIV` and `MOD` are floored: the remainder has the divisor's sign (`-7 DIV 2` is -4, `-7 MOD 2` is 1). The arithmetic inside `WRAP(...)` is exact only to 2^53 - 1, so a product of two 32-bit values can stop there before it is wrapped. Functions JavaScript has no exact version of (erf, gamma) are not built-ins; they belong in the library as verified pseudo. These built-ins carry an `argument` obligation that their arguments are allowed: SQRT, the logarithms, ASIN and ACOS, LOG1P, CLAMP, the shifts, `FILL` and `RANDINT`. Others that stop the run for some arguments (`MIN`, `MAX` and `MEAN_OF` of an empty collection, `^`, `CHR`, `DOT` of two lengths) carry none. The built-ins added for numerical work stay usable as names (a variable `E`, a `FUNCTION GCD`; `SOFT_BUILTINS` in `lang.ts`): a FUNCTION or PROCEDURE of the same name replaces the built-in, and a variable `E` is read as `E` while `E()` still calls the built-in.
`tests/numeric.test.mjs` pins each rule; the corpus programs `49-sized-integers` to `52-elementary` show them in use.
### Limits of a run
The reference's "Limits" and "What stops a run" tables (`src/common/reference.ts`) say the same to a student; `tests/reference.test.mjs` runs a program for every row of "What stops a run" (and fails on a row without one), and for five rows of "Limits": nesting, chains, a collection's size, steps and call depth.
- **What the parser reads.** A line inside more than 200 blocks, or brackets, calls, unary operators or types nested more than 200 deep, is one `too-deep` error (`MAX_NESTING` in `parse.ts`); so is a chain of more than 400 operands (`1 + 1 + ...`, `MAX_CHAIN`). The two are counted apart and a chain leans one level per operand, so brackets that each hold a long chain would multiply them; an expression whose tree is taller than 400 levels is therefore `too-deep` as well (`MAX_TREE`, measured where each expression is complete). No later stage (checker, analysis, translators) walks a taller tree; `tests/pseudo-robustness.test.mjs` takes the tallest through every one of them.
- **What a run holds.** One collection holds at most 2,000,000 values (an ARRAY's declared size, `FILL`, a range walked by `FOR EACH` or listed for a quantifier), and a text at most 10,000,000 characters (`MAX_VALUES`, `MAX_TEXT` in `interp.ts`); past either the run stops (kind `value`) instead of allocating.
- **How long a run goes.** The step limit (20,000 in the app's runs, `maxSteps`) stops a loop that may never end (kind `limit`). The positions FORALL, EXISTS, SUM and sets written by rule visit are counted apart, up to 100 per step allowed, so one quantifier inside another cannot run without end. Calls go 400 deep (`maxDepth`, kind `depth`); a recursion whose call sits inside many nested blocks can exhaust the engine underneath before 400 calls (with ten blocks around the call, somewhere between 200 and 300 calls, varying from run to run), which is the same stop, at the line the run was on.
- **The Prove tab's budget.** The verifier's work is counted, not timed (`work` in `logic.ts`): one obligation's proof, one subroutine's paths and invariants, its proofs, and the whole program each have a budget, the same on every machine, and past one the answer is open ("too large to prove here") or the subroutine partial, never proved ([limits.md](limits.md#proving-and-testing)). A wall-clock budget stays behind them as a last resort: `provePseudo` gives the verifier 3 seconds per unit, then tries generated inputs on each routine within a counted budget of steps and also for up to 3 seconds (`checkProperties` with `maxWork` and `budgetMs`): a slow routine is tried on fewer inputs, not waited for.
- **Recording.** A recorded run (the stepper, the table of values) keeps a picture of the variables after every step, and a picture copies each variable the step changed. A large collection that changes at many steps is copied at each of them, so once the copies of a run come to more than 10,000,000 values (about 80 MB of numbers; `maxRecorded` in `interp.ts`), the trace ends with a step of kind `unrecorded` that says so, and the run goes on without recording: its output, result, stop and line counts are the whole run's. No program of the corpus, the exercises or the lessons comes near it (the largest copies about 42,000). `tests/pseudo-robustness.test.mjs` holds the cut with a small budget.
- **Checker errors and stops added in the 2026-11 audits** (each in `tests/pseudo-robustness.test.mjs`, `tests/numeric.test.mjs` or `tests/reference.test.mjs`): `too-deep` (the limits above), `literal-range` for a whole-number literal past 2^53 − 1 and a FLOAT or FLOAT32 literal past its largest value, `recursive-type`, `array-of-array`, `array-length` (an ARRAY given a LIST or ARRAY of another length, when both are written as numbers), `bad-member` (a SET of anything but single values). Stops: the collection and text caps, the quantifier positions, an ARRAY given a value of another length at a store, a call or a RETURN, a FOR counter declared with a sized type leaving its type, a partial sum or product of `SUM_OF` or `DOT` past 2^53 − 1, `CHR` of a surrogate half, `TO_FLOAT` or `INPUT` of text that is not a decimal number, and NaN or an infinity passed to a FLOAT parameter from outside without `USE IEEE`.
### Soundness
A "proved" must be a proof. Two test files hold the prover to that, and a change to `logic.ts`, `solver.ts` or `vcgen.ts` must keep both green:
- `tests/prover-soundness.test.mjs`: every regression program in `library/pseudo/prover/` names, in a `// MUST-NOT-PROVE: <kind>@<line>` header, an obligation that a run breaks and that an unsound rule once proved; it may never be proved again, and the program must still break it. A program whose fix was to the language names where its run now stops, `// RUN-STOPS: <kind>@<line>`. Across every exercise, corpus program, lesson solution and example, nothing marked proved may be broken by the fuzzer or by running the program, and `ASSERT 1 == 2` appended to a program that runs to its end may never be proved.
- `tests/engine-solver.test.mjs`: a table of goals the solver must prove and goals it must leave unknown, 400 random linear integer formulas checked against every small assignment, and obligations from small programs.
Those hold what someone wrote down. `pixi run prove-fuzz` ([scripts/prove-fuzz.mjs](../scripts/prove-fuzz.mjs)) writes programs nobody did: procedures with contracts, loops with INVARIANTs (FOR, WHILE, FOR EACH, REPEAT), STEPs that are expressions, CASE, FLOAT, FLOAT32 and sized types, calls on the right of AND and OR, and FUNCTIONs that draw a random number or read INPUT. Each is proved, then run on random arguments; a proved obligation a run breaks is a finding, printed as the smallest program that still shows it (`--keep DIR` writes it with its `// MUST-NOT-PROVE:` header, ready for `library/pseudo/prover/`). CI runs it on every push and longer every night ([ci.md](ci.md)).
When a soundness bug is found, add the program that shows it to `library/pseudo/prover/` first, watch the test fail, then fix the rule. The bugs found so far, each with its program:
| Program | Rule | Fix |
|---|---|---|
| `houdini-cap.pseudo` | Invariant inference stopped after four rounds and assumed the candidates left, even when the last round still dropped some | Keep inferred invariants only at a fixed point |
| `rand-zero.pseudo`, `rand-negative.pseudo` | `RAND(X)` assumed `0 <= R < X` for every X, false for X ≤ 0, so the checker held a contradiction and proved anything | A fact that covers all three signs of X |
| `fill-negative.pseudo`, `randint-empty.pseudo` | `FILL` and `RANDINT` assumed facts about arguments the interpreter checks by stopping, without asking whether they hold | An `argument` obligation, and guarded facts |
| `float-overflow.pseudo` | The prover treats FLOAT as numbers (`Y == Y`), while a run went on with infinity and NaN | The interpreter stops on a FLOAT that is not finite |
| `foreach-empty.pseudo` | The way out of `FOR EACH` kept "X is in the collection", false after zero passes over an empty list | The fact holds only inside a pass |
| `int8-overflow.pseudo` | (a guard written with the sized types) Sized arithmetic treated as exact with no range would prove `X + 1` fits INT8 | Every sized result has an `overflow` obligation |
| `float32-store.pseudo` | (a guard) A whole number stored in a FLOAT32 keeping its exact value would prove `X == N` for N = 16777217 | A value becoming a FLOAT32 is rounded (constants) or `TOFLOAT32(v)` |
| `ieee-nan.pseudo` | (a guard) `X == X` for every number fails for NaN | Nothing is proved in a program that says `USE IEEE` |
| `havoc-float-sort.pseudo` | At the top of a loop a changed variable became an unknown of the sort its value had, so a FLOAT that started at `1` was a whole number on every pass | The unknown has the sort of the variable's declared type |
| `havoc-array-length.pseudo` | "An ARRAY keeps its dimensions through a loop" was assumed even when the body replaces the array whole (`A <- B`) | Assumed only when the body never assigns, declares or passes BYREF the bare name; and an ARRAY keeps its declared length: a store, an argument (BYREF too), a RETURN or a value APPENDed to a LIST OF ARRAY of another length is a checker error (`array-length`) when both lengths are plain numbers, and otherwise stops the run, where the prover asks for it (an `argument` obligation) and knows it afterwards; an ARRAY parameter's lengths are known inside the routine |
| `shortcircuit-range.pseudo`, `shortcircuit-ensure.pseudo`, `case-label-ensure.pseudo` | A fact learned while translating an expression (a sized result's range, a callee's ENSURE) was kept even where a short-circuit `AND`/`OR` or an earlier CASE label means the run never evaluates it | Such a fact is guarded by the conditions under which the expression is evaluated (`learn`) |
| `quantifier-ensure.pseudo` | The ENSURE of a call inside a quantifier's body was kept as a fact about the quantifier's own name, one free name shared by every quantifier | No ENSURE is stated for a call inside a quantifier's body |
| `impure-function.pseudo`, `input-function.pseudo`, `randn-twice.pseudo` | Every FUNCTION call, and `RANDN()`, was a function of its arguments, so two calls were equal | A function that reads INPUT or draws a random number (itself or through a call) gives a fresh unknown each call, with its ENSUREs; so does `RANDN()` |
| `rand-in-set-builder.pseudo` | A random draw in a quantifier's or set builder's body was one unknown for every value of its name | A body that draws makes the whole quantifier an unknown |
| `foreach-invariant-exit.pseudo`, `foreach-invariant-next.pseudo` | FOR EACH assumed its INVARIANT on the way out, where no run checked it, and proved "kept" for the value just visited while the run checked with the next | An INVARIANT that does not name the loop's variable is checked by the run once more when the loop ends (also for an empty collection) and is known afterwards; one that names it is proved for the value about to be visited and is not known afterwards |
| `repeat-invariant-exit.pseudo` | The run checks a REPEAT loop's INVARIANT after the last pass; "kept" covered only passes that repeat | The keep obligation covers the pass that ends the loop too |
| `step-not-literal.pseudo` | A FOR whose STEP is not a plain number was advanced by 1 | Its counter is an unknown after each pass, and inference offers nothing about it |
| `decreases-recursion.pseudo` | A recursive call's measure was compared with the parameters as they are at the call, not as they were on entry (what the run compares with) | Compared with the values on entry |
| `decreases-entry.pseudo` | The run checks `DECREASES >= 0` on every call; nothing asked for it | A `decreases-bound` obligation at the DECREASES line, from the REQUIREs |
| `sum-float-rounding.pseudo` | SUM over one more position was the exact sum, for FLOAT too | A FLOAT SUM grows by the uninterpreted `FLOAT+` |
| `sum-past-exact.pseudo`, `sum-not-finite.pseudo` | (a run that went on) SUM was not checked as `+` is: a whole number past 2^53 - 1 or an infinity went on, and two infinities made NaN | Every partial sum is checked; the run stops |
| `linear-doubles.pseudo`, `constant-doubles.pseudo`, `for-bound-doubles.pseudo` | Constants and coefficients were added and multiplied as doubles, so `9007199254740991 + 2 - 9007199254740991` was 1 | `linear()` works in exact rationals (`Q`, now in `logic.ts`), and constants fold only when both and the result are whole numbers a double holds exactly |
| `input-past-exact.pseudo` | (a run that went on) INPUT, `TO_INTEGER` and a FOR counter let a whole number past 2^53 - 1 into a run, where DIV and MOD are no longer exact | The run stops, as it does for `+` |
| `index-of-empty.pseudo` | `INDEX_OF` assumed a result below the length; an empty piece is found at 0 in an empty text | The fact allows 0 |
| `chr-surrogate.pseudo` | (a run that went on) `CHR` gave the halves of a surrogate pair, two CHARs that joined into one character | `CHR` stops for 0xD800 to 0xDFFF |
| `float-in-range.pseudo` | `X IN [lo, hi)` and membership of a set written by rule were `lo <= X < hi` for a FLOAT too; in a run only a whole number is in a range | Left open (an opaque term) unless X is a whole number |
| `set-literal-mixed.pseudo` | `{1, 2.5}` was a SET OF INTEGER holding 2.5 | A set literal widens to FLOAT, as a list literal does (`check.ts`) |
| `max-float32.pseudo`, `append-float32.pseudo` | A FLOAT32-typed value that was never rounded (MAX of a FLOAT32 and an INTEGER; APPEND of an INTEGER into a LIST OF FLOAT32) was taken for a FLOAT32 | MIN, MAX and CLAMP round a FLOAT32 answer, APPEND and INSERT store a value as the list's own type (and check a sized whole number), on both sides |
| `set-of-lists.pseudo` (removed) | A run's SET finds a LIST by identity; the prover compared contents | Membership of a collection in a SET was left open; then a SET's members were limited to the single values a HASHMAP key may be (checker error `bad-member`), so the program no longer checks and `tests/pseudo-robustness.test.mjs` holds the error instead |
| `sorted-2d.pseudo` | `SORTED` of a two-dimensional ARRAY has rows times columns values; the prover gave it the first length | Nothing is said about its length |
| `for-sized-counter.pseudo` | The run checks at the top of each pass that a FOR counter declared with a sized type (`DECLARE I : INT8`) still fits it, and stops there; no obligation asked, so a unit with everything proved still stopped | An `overflow` obligation at the FOR line, under the loop's guard, after which the range is a fact |
Fixes with no program of their own, because the program that showed them is now rejected or no longer breaks (each has a test in `tests/numeric.test.mjs`): `CLAMP(I, 0.5, 2.5)` was typed INTEGER and is now the widest of its three types; `UPPER`/`LOWER` of a CHAR whose other case is two characters (`'ß'`) leaves it as it is, so a CHAR is always one character; `RAND(X)` no longer returns X itself for the smallest FLOATs; an ARRAY or HASHMAP given as an argument from outside is checked value by value; INPUT into a FLOAT takes a finite number only (unless `USE IEEE`).
The harness reads a regression program's `// INPUT: <line>` headers (one per line of input) and `// CALL: <call>`. A program may carry both a `MUST-NOT-PROVE` and a `RUN-STOPS` header when the run reports the failure on another line than the obligation's (a recursive DECREASES is reported at the DECREASES line, its obligation sits at the call).
In the app, an obligation the prover marks proved that a generated input breaks at the same place is shown as broken, not proved. A failure that says which half of a contract it broke (an INVARIANT before the first pass or after one, a DECREASES below 0 or not smaller) counts against that obligation only.
## What this repository changed
Changes made here since the engines left the course, which the course receives with the next export:
- **pseudo:** the text built-ins `SPLIT`, `JOIN`, `INDEX_OF`, `REPLACE` and the numerical built-ins (`FLOOR`, `CEIL`, `LOG10`, `SIN`, `COS`, `TAN`, `ATAN2`, `PI`, the statistics) in `lang`, `parse`, `check`, `interp`, `translate`, `vcgen`; `PARALLEL FOR` with its race detector; an indexed read `L[I]` recorded as a read of one position, not all of `L` (`interp`); one `reserved-name` error for a keyword used as a name (`parse`); `english.js` exporting `COMPARISONS` and `IN_PHRASES` so the reference can read them; `analyze.js` and `coach.js` treating a variable passed `BYREF` to a procedure that writes it first as an out-parameter, not a read; `coach.js` no longer warning "growing bound" on a queue drained by `WHILE LENGTH(Q) > 0`; the soundness fixes above, with the new `argument` obligation kind (`vcgen`, and `views-analysis.js` for the course's pages); a run that stops on a FLOAT that is not finite (`interp`); the sized types, FLOAT32, `USE IEEE` and the exact numerical built-ins (`numeric`, new, and `lang`, `parse`, `check`, `interp`, `vcgen`); `USE` of the library's routines by name (`parse`, `check`, `interp`); the limits of what the parser reads and a run holds, the recording cut, and the checker errors and stops of the 2026-11 audits (above); the prover's counted budgets (`work` in `logic`); a FUNCTION in an IF, WHILE or UNTIL condition run once per test (`interp`); and `logic`, `solver`, `vcgen`, `lang`, `numeric`, `parse`, `check` and `interp` rewritten in TypeScript with the same behavior, on the types in `ast.ts`.
- **asm86:** what compiled Mojo uses beyond the course's subset (`interp.js`, about 630 lines): the BMI bit instructions, atomic read-modify-writes with `lock`, bit tests that write, `bswap`, `ud2`, the 128-bit AVX spellings, scalar double precision, and the double-width shifts; a limit on the memory a setup names (a region of at most 1 MiB) and on what a run's writes copy (128 MiB), in `interp.js`; the parity flag (`interp`, `uops`, `views`); the floating-point units and their latencies (`uops`); a small change in `sandbox.js`; and in `hwviews.js` the whole core's arrows (`machineView`): only a lit edge carries an arrowhead, in its own color and on the end its data reached, each view has its own marker ids, and the result's edge into the registers starts at the port that produced it.
One addition to the pseudo language lives outside the engine, in app code: `DECLARE <name> : <type> <- <value>`, a declaration with its starting value on one line (Mojo's `var total: Int = 0`). `src/services/pseudo-study.ts` reads it by doing what the engine's `study()` does (parse, check, analyze, coach) with steps of its own: before the parse it stops reading past 2,000 lines or 100,000 characters (`too-long`), and between parse and check it puts in the starting values and brings in the routines a `USE` line names. For the starting value, the `<- value` is blanked out of the line, columns kept, so the engine parses a plain DECLARE, and the value is parsed on its own and put in as an ordinary assignment on the same line. Every app reader of pseudo (`studyOf`, and the lingo, matho and Mojo translators) goes through it; pseudo-to-mojo writes the pair as one `var` line. The two-line form reads as before. It can move into the engine's parser now that the engine lives here.
## Giving the course the engines
1. `pixi run engines-diff <course>/static` shows what the course has not taken yet: for each module, the file the course would receive (`src/engines/` as written, `dist/engines/` for a TypeScript module) against the course's copy, whitespace ignored, and the files only one side has.
2. `pixi run engines-export <course>/static` builds and writes those files into the course's `static/js/`. A TypeScript module arrives as plain ES-module JavaScript, so the course's pages import it unchanged. Source maps are not copied.
3. In the course repository, review the diff and run its pages before committing.
4. The course's stylesheets are pplus-web's to compare (`styles/course/README.md` there).
A change someone makes in the course's copy is not picked up from there. Bring it here as a change with a test, then export.
+38
View File
@@ -0,0 +1,38 @@
# Adding an exercise
Programming+ takes a procedure from an idea to Mojo to the machine. An exercise is one procedure on that road, written in any of its notations: lingo (steps in plain English), matho (equations written in LaTeX), pseudo (pseudocode precise enough to run, prove and translate), speco (a specification to prove against), Mojo (Modular's programming language, pinned to version 1.2.0) and x86-64. It is a catalog problem: one file in `src/exercises/`, listed in `src/exercises/index.ts`. The home page, the problem menu, share links, embeds, and the tests pick it up from there. `pixi run test` checks every exercise: its pseudo parses, its call runs, its answer matches `expect`, and its Mojo program (if it names one) exists and prints what it should.
There are two ways to start one.
## An exercise around a Mojo program
```bash
pixi run new-exercise rolling-sum # library/mojo/local/rolling-sum.mojo, src/exercises/rolling-sum.ts, registered
pixi run play rolling-sum # after each edit: run, verify on godbolt, build, list the assembly, test
```
For a title or a home-page section other than the defaults, run the script directly: `node scripts/new-exercise.mjs rolling-sum --title "Rolling sum" --group "Loop forms"`. If `library/mojo/local/rolling-sum.mojo` already exists, it is kept as written and only the exercise is made.
The exercise names its program (`mojoProgram: 'rolling-sum'`) instead of carrying the source. The Mojo pane shows the file without its header comments, and badges it "verified on Mojo 1.2.0" only when godbolt's answer for that exact source passed the file's own `# expect-stdout:` lines. Editing the file changes its key, so it reads as unverified until `play` (or `mojo-verify`) asks again. The header keys are in [mojo-corpus.md](mojo-corpus.md#mojo-of-our-own).
With `# mode: both` and `# args: -O0 --debug-level=line-tables` in the header, godbolt also returns the listing, and `play` turns it into the exercise's x86-64 pane (see "The assembly" in [mojo-corpus.md](mojo-corpus.md#the-assembly)).
## An exercise in lingo, pseudo, matho or speco
Copy `src/exercises/_template.ts` to `<id>.ts`, fill it in, import it in `src/exercises/index.ts`, and add it to the list (before `demo`, the playground, which stays last). Then `pixi run test`.
## The fields
| Field | Means |
|---|---|
| `id` | The URL (`#/<area>/p/<id>`): lowercase words joined by hyphens |
| `title`, `group`, `blurb` | The name, the home-page section it files under (a new name makes a new section), and one or two sentences on what the student does |
| `meta` | Optional: `lecture`, `level` (`intro`, `core`, `advanced`), `tags`, `concepts`, `minutes`, `page` (where it is taught) |
| `sources` | Any of `lingo`, `pseudo`, `matho`, `speco`, `asm`. Pseudo is derived from lingo (or matho, written in LaTeX) when absent, and speco from the pseudo's inline contracts |
| `mojoProgram` | The name of a program in `library/mojo/local/`, shown in the Mojo pane |
| `call`, `expect` | The call to run, and what it should return; the tests compare them |
| `setup`, `machine` | For assembly: the setup block (registers and memory before the run) and the machine model preset |
| `lang` | The pane that opens first |
| `area` | The area it opens in: `bridge`, `dev` or `hw`. Absent: Hardware for `asm-*` ids, Developer for a problem that is only a Mojo program, Bridge otherwise |
`src/exercises/types.ts` documents each field in full.
+43
View File
@@ -0,0 +1,43 @@
# The library
Programming+ takes a procedure from an idea to Mojo to the machine. pplus-library (the submodule `library/`) is its ground truth. Its routines, which this document is about, are written once in pseudo (pseudocode precise enough to run, prove and translate); besides them it holds the Mojo corpus (`library/mojo/`, see [mojo-corpus.md](mojo-corpus.md)) and the pseudo regression and soundness programs (`library/pseudo/`). Each routine is checked by every tool `pixi run library-check` has (the table below), so a program can use them by name instead of rewriting and re-verifying them, and a learner can open any of them to see exactly what it does. Core reads it through a generated registry (`src/library/generated.ts`, `pixi run library-emit`), so the site needs no files at run time.
## Using a routine
```
USE md // every routine of the module
USE align.MatchScore // one routine
```
USE lines go at the top of a program. From then on a routine is called like the program's own:
- **The checker** types each call against the routine's parameters. A program may not define a routine of the same name (`library-clash`); an unknown module or routine is an error at the USE line, with the names that exist (`unknown-library`, `unknown-routine`).
- **A run** steps over a routine: one step where it is called, one where it hands back, and none of its own lines (they belong to another file). Its contracts are still checked; a broken REQUIRE is reported at the call, naming the routine. To step through a routine, open it from the site's library page, which opens it in the Bridge.
- **The prover** uses the routine's REQUIRE as an obligation at each call and its ENSURE as a fact afterwards, the way it treats the program's own routines. It does not prove the routine again: the library did.
- **The Mojo translator** writes each routine the program uses once, before the program's own code, dependencies first, labeled as coming from the library.
A routine file (`routine.pseudo`) holds USE lines and exactly one FUNCTION or PROCEDURE. A routine that calls another brings it in with USE, so every function in the library is checked on its own.
## What "verified" means for a routine
`pixi run library-check` runs every check and records what it found in `library/status.json` and `library/STATUS.md`:
| Check | Passes when | Recorded as |
|---|---|---|
| structure | `routine.pseudo` defines exactly the routine `routine.json` names, and nothing else | pass, fail |
| pseudo | every case runs; its result is recorded and is what the references are held to | pass, fail |
| prover | every obligation of the routine is proved | pass; open (some not proved, none broken: the routine's comment says which and why, and `tests/documents.test.mjs` fails when it does not mention it); fail (one broken) |
| fuzz | every input the fuzzer generates for the routine breaks no contract and stops no run (`STATUS.md` gives how many it generated) | pass, fail, skipped (the fuzzer cannot generate inputs for it) |
| mojo | the Mojo generated from the pseudo checks, and prints what the pseudo prints both in core's interpreter and built by the pinned compiler on this machine (to the last digits or nearly: [trust.md](trust.md#what-a-translation-says)) | pass (by both, or by the one that could run it), fail, skipped (the interpreter declines the construct and there is no pinned compiler here) |
| a reference, per runner | `cpython`, `cc -O0`, `cc -O2`, core's Mojo `interpreter`, the pinned Mojo `compiler` on this machine, or the pinned compiler on `godbolt` prints the pseudo's results on every case, exactly or within the tolerance `routine.json` states; a C or Mojo reference is given its cases at run time (below) | pass, fail, skipped (the tool is missing, or the `mojo` on the PATH is not the pinned version), unverified (no stored compiler answer for this exact program, input and build arguments) |
| proof | the pinned Dafny verifies the proof file, or its stored verdict matches this exact text | pass, fail, unverified |
A reference implementation is the function alone; the tool writes the program it runs as (the function plus a main that prints each case), and `pixi run library-harness <id> <lang> <level>` prints it. A Python reference's program calls it on each case's arguments. A Mojo or C reference's program holds no case: its main reads every case's arguments from one line of stdin, which `pixi run library-harness-input <id> <lang> <level>` prints, so the compiler cannot work a call out while it builds (a call on literal arguments it would, with arithmetic and a math library of its own; built with contraction on, as Mojo is by default, with other rounding than the code it makes: `library/mojo/probes/float-contract-runtime`), and every runner is given the same program and the same line. Every Mojo program is built with the pin's arguments (`build.args` in `library/mojo/pin.json`: `--target-cpu x86-64-v3 --fp-mode contract=off`, [mojo-corpus.md](mojo-corpus.md#how-every-program-is-built)), on godbolt and on this machine, so a Mojo reference rounds each Float64 operation on its own, as the pseudo does. The line is the number of cases, each case's arguments, then `end`; a FLOAT is sent as two whole numbers m and e with the value m * 2^e, exactly, a STRING with `%`, space and line breaks escaped, a LIST as its length and then its items. `tests/library-harness.test.mjs` fails if a case's arguments are ever written into the program again. A Mojo reference's answer from the compiler is stored in the routine's `golden/mojo-<level>.json`, keyed by the SHA-256 of that program, the stdin it was given and the build arguments, by `pixi run library-verify-mojo` (network). A Dafny verdict is stored in `golden/dafny.json`, keyed by the proof's text and the Dafny version.
What each check does not say is in [trust.md](trust.md#library-routines).
## Changing the library
1. Change pplus-library under its [AGENTS.md](../library/AGENTS.md): one routine per file, cases, references with their notes and tolerances, a Dafny proof where one says something.
2. In core: `pixi run library-check` (no check may fail), then `pixi run library-emit`.
3. Commit pplus-library; commit core with the new `library` pointer and the regenerated registry. `tests/library.test.mjs` fails while the registry is out of date with the checkout.
+84
View File
@@ -0,0 +1,84 @@
# Limits
A program can arrive in a share link, so every reader and every run in core has to answer any text with diagnostics, an output, a stop or a refusal: never with an exception from the JavaScript engine underneath, a run without end, or an allocation the size of the text's mistake. This page lists each limit that makes that so: where it is, its value, and what the student sees past it. Each is far beyond what a program written to be read or stepped through needs, and each is proven just past its value by a test.
## Reading
| What | Where | Value | Past it |
|---|---|---|---|
| Mojo nesting: brackets, call and index arguments, blocks, prefix operators, `**`, `if`/`else`, `:=`, lambdas | `MAX_NESTING`, `src/mojo/parse.ts` | 200 levels | The statement is not read: one note, "nested more than 200 levels deep; Programming+ cannot read this yet, and Compile & run asks the real compiler", where the limit is passed. The checks stay quiet and a run is declined, as for any code the parser cannot read |
| Mojo tree height: each operand of a chain such as `a + b + c`, each `elif` arm, each level above | `MAX_TREE`, `src/mojo/parse.ts` | 1,000 levels | The statement (the innermost one that is too tall) is not read: one note, "more than 1000 levels deep once read" |
| Mojo liveness and moved-value analyses (a loop's body is walked twice or more per enclosing loop) | `MAX_VISITS`, `src/mojo/lifetimes.ts`, `src/mojo/flow.ts` | 200,000 statements per function | The function is not analyzed: the interpreter declines to say when a value with a visible lifecycle dies, and the moved-value check says nothing more about it |
| Generated inputs for Mojo functions (`mojoProperties`) | `MAX_PARAMS`, `MAX_FUNCTIONS`, `src/mojo/properties.ts` | 64 parameters, the first 100 functions | The report says the function has too many parameters, or is past the first 100 |
| Pseudo nesting, one chain of an operator, and the tree both make together | `MAX_NESTING`, `MAX_CHAIN`, `MAX_TREE`, `src/engines/pseudo/parse.ts` | 200 levels, 400 operands, and an expression's tree 400 levels tall (brackets that each hold a long chain) | One `too-deep` error |
| One pseudocode program (the pseudo pane, and the pseudocode any other pane becomes) | `MAX_PSEUDO_LINES`, `MAX_PSEUDO_CHARS`, `src/services/pseudo-study.ts` | 2,000 lines, 100,000 characters | One `too-long` error on the line that passes it: "This program is more than 2,000 lines long" (or "longer than 100,000 characters"), "which is more than this tool reads: the lines from here on are not read, and the program is not run or proved." Blank lines past it do not count |
| lingo nesting: brackets, "not", "minus", quantifiers, steps inside steps | `MAX_NESTING`, `src/engines/pseudo/english.js` | 200 levels | One `too-deep` error: "This is nested more than 200 levels deep, which is more than this tool reads" |
| One lingo sentence | `MAX_SENTENCE`, `src/engines/pseudo/english.js` | 1,000 words and symbols | One `too-long` error; the rest of the sentence is not read |
| lingo routines and defined phrases (every value is tried against each one's first line) | `MAX_HEADS`, `src/engines/pseudo/english.js` | 200 | One `too-long` error; the ones past it are not read |
| One lingo program | `MAX_PSEUDO_LINES`, `src/engines/pseudo/english.js` | 2,000 lines | One `too-long` error; the lines past it are not read |
| The pseudocode lingo steps become | `MAX_PSEUDO_LINES`, `src/engines/pseudo/english.js` | 2,000 lines | One `too-long` error; it is not checked or run |
| matho nesting: brackets, groups, `\frac`, `\sqrt`, powers and subscripts in braces, functions of functions, signs | `MAX_NESTING`, `src/services/matho.ts` | 200 levels | `matho-too-deep` on that equation |
| One matho equation | `MAX_TOKENS`, `src/services/matho.ts` | 2,000 symbols | `matho-too-long` on that equation; it is not read |
| Equations in one matho pane | `MAX_EQUATIONS`, `src/services/matho.ts` | 500 | `matho-too-long`; none is read |
| The pseudocode matho equations become | `MAX_PSEUDO_LINES`, `src/services/matho.ts` | 2,000 lines | `matho-too-long`; it is not checked or run |
| `LENGTH(X)` written back as `\|X\|` when the speco is made from the pseudocode | `MAX_BARS`, `src/services/speco.ts` | 200 per claim | The rest stay `LENGTH(X)` |
| A reader, translator or the prover that throws anyway | `src/common/workspace.ts`, `src/sync/hub.ts` | | One `engine-stop` error on the pane ("Programming+ could not read this pane (...)"); in the hub, every other pane keeps its text, marked stale with the reason |
## Running Mojo
Past any of these the run stops as it does at its step limit: the trace ends with a stop at the line, and the result is `limited` (exit code -1), because how the compiled program would have ended is not known (`RUN_LIMITS`, `src/mojo/interp.ts`; a run may ask for lower limits, never higher).
| What | Value | The stop says |
|---|---|---|
| Steps | 20,000 (the caller's `maxSteps`) | "Stopped after 20,000 steps." |
| Calls inside calls | 200 | "Stopped at 200 calls deep" |
| Characters in one String | 10,000,000 | "Stopped: this makes a String of N characters, more than Programming+ holds (10,000,000)." |
| Values in one List, Dict or Set | 2,000,000 | "Stopped: this makes a List of N values, more than Programming+ holds (2,000,000)." |
| Characters printed | 10,000,000 | "Stopped after printing 10,000,000 characters." |
| Values made or copied into collections, over the run (what it can come to hold) | 5,000,000 | "Stopped after making or copying 5,000,000 values in Lists, Dicts and Sets" |
| Characters and values built, copied or searched through, over the run (how long it can take; the whole length of a concatenation counts, because the trace keeps every step's String) | 100,000,000 | "Stopped after building, copying and searching through 100,000,000 characters and values" |
| Variables' values the trace records, one per variable per step | 1,000,000 | "Stopped after recording 1,000,000 values of variables" |
| Passes of one call of std.math's `gcd` or `comb` (`MATH_STEPS`), which the interpreter runs as Mojo 1.2.0's own loops: its `gcd` of an even number and a much larger odd one subtracts about 10^15 times, and the built program does not come back | 1,000,000 | "Stopped: gcd(6, 4503599627370597) takes more than 1,000,000 steps in Mojo's std.math ..., more than Programming+ follows in one call." |
| The engine's own stack or size limit, past all of the above | | "Stopped: the run went deeper ... than Programming+ can follow." or "Stopped: a value grew larger than Programming+ can hold." |
A `for` loop lists only the items it can reach before the step limit. The trace shows a String past 1,000 characters and a collection past 20 items cut short; `print` writes them whole. What the engine underneath cannot compute is declined, as anything the interpreter does not model is ("Programming+ cannot run this yet: ..."): a shift by more than 64 bits, converting `inf` or `nan` to an integer, a float literal with more than 10,000 digits or an exponent past 10,000, and any other exception, which is a fault in Programming+ rather than an answer.
## The model machine
| What | Where | Value | Past it |
|---|---|---|---|
| Steps | `maxSteps`, `src/engines/asm86/interp.js` | 20,000 | The run is truncated |
| One memory region a setup maps | `MAX_REGION` | 1 MiB | The run does not start: "this machine maps regions of 0 to 1,048,576 bytes (1 MiB)" |
| Memory copied while writing (each step that writes a region keeps a copy for stepping back) | `MAX_COPIED` | 128 MiB | The run stops: "the steps so far wrote to memory regions totaling 128 MiB" |
| The stack | `stackSize` | 512 bytes | A page fault, explained as a stack overflow |
## Proving and testing
The prover's work is counted, not timed: each term it builds or visits, each case of a case split, each pair of constraints it combines, each fact it copies is a unit (`work` in `src/engines/pseudo/logic.ts`). A budget therefore runs out at the same point on every machine and in every test, and because the units are counted where memory is allocated, memory stays in proportion. Past a budget the answer is never "proved": an obligation is open with the reason "too large to prove here", or the subroutine is partial and says so (in the Prove tab a partial subroutine has nothing marked proved). Every program of the corpus takes far less than each budget, and proves the same as before they were added (`tests/prover-limits.test.mjs` proves each budget past its value).
| What | Where | Value | Past it |
|---|---|---|---|
| Proving one obligation | `PROVE_WORK`, `src/engines/pseudo/solver.ts` | 2,000,000 units | The obligation is open: "too large to prove here" |
| Following one subroutine's paths and finding its loops' invariants | `UNIT_WORK`, `src/engines/pseudo/vcgen.ts` | 40,000,000 units | The subroutine is partial, with the note "This subroutine is too large to prove here: the checker stopped before the end of it, so nothing in it is marked proved. Every run still checks it." |
| Proving one subroutine's obligations | `PROOF_WORK`, `src/engines/pseudo/vcgen.ts` | 20,000,000 units | Each obligation not yet proved is open: "too large to prove here" |
| Everything above, for a whole program | `PROGRAM_WORK`, `src/engines/pseudo/vcgen.ts` | 60,000,000 units | The subroutines after it are partial, with the same note |
| How deep a value the checker follows is (`T <- T + A[T] + ...` line after line builds one operation inside another) | `MAX_DEPTH`, `src/engines/pseudo/vcgen.ts` | 500 operations (the corpus's deepest: 18) | The value becomes one the checker knows nothing about, with the note "The value on line N is built from more than 500 operations one inside another, more than the checker follows: from there on it treats such a value as one it knows nothing about, so what depends on it stays open." The engine's own stack or size limit, past everything, is the same as running out of work: the unit is partial, or the obligation open, too large to prove here |
| A term's key, which finds equal terms (a term that shares its parts, such as nested `ABS`, is far longer written out) | `MAX_KEY`, `src/engines/pseudo/logic.ts` | 2,000 characters | The term is equal only to itself: the prover concludes less about it, never more |
| A fact or goal written out with an obligation | `SHOW_PARTS`, `src/engines/pseudo/logic.ts` | 1,000 parts | The rest is written "…" |
| The facts and goals one subroutine's report writes out | `SHOWN_CHARS`, `src/engines/pseudo/vcgen.ts` | 1,000,000 characters | Each further obligation shows its goal alone, cut at 400 characters |
| The hypotheses looked through for the facts shown with an obligation | `SHOWN_FROM`, `src/engines/pseudo/vcgen.ts` | the nearest 400 | The facts shown come from those |
| The generated inputs that cross-check a proof (`checkProperties`), counted in steps and positions visited by FORALL, EXISTS, SUM and sets written by rule | `CROSS_CHECK_ROUTINE`, `CROSS_CHECK_PROGRAM`, `src/services/pseudo.ts` | 600,000 for one routine, 1,200,000 for a program | No more inputs are tried (the routines after it, none): an obligation they would have shown broken stays open. A run cut short by the budget is not a failure |
| The sample runs that check the equations a matho pane is given give the pseudo's values | `READ_BACK_VISITS`, `src/sync/pseudo-to-matho.ts` | 100,000 quantifier positions a run | The run stops there, on both sides alike, and the check compares where they stopped |
| The fuzzer's inputs for one routine (the Tests view, `Workspace.fuzz`), counted the same way | `WORK_PER_INPUT`, `src/common/fuzz.ts` | 3,000 for each input the budget asks for: 900,000 at the default 300 | No more inputs are run, and the report's `problem` says "Stopped after N steps of work, all one routine's inputs may take here (M): the inputs listed were run, and no more." A failure found before is kept, shrunk as far as the work allowed |
| The routines of one program the fuzzer tests | `FUZZ_ROUTINES`, `src/common/workspace.ts` | the first 100 | A report with no cases: "Not tested: generated inputs cover the first 100 routines of a program, and this is routine N." |
| The fuzzer's work for a whole program | `FUZZ_PROGRAM_INPUTS`, `src/common/workspace.ts` | 600 inputs' worth: 1,800,000 at the default budget | A report with no cases: "Not tested: the routines before this one took all the work the tests of one program may take (1,800,000 steps)." |
The wall-clock budget the Prove tab gives each subroutine (3 seconds) stays behind these as a last resort. Measured on the machine this was written on: 20 nested `ABS` (or a matho pane `f(x) = ||||...x...||||` of 20 bars) took a 1 GB heap down before, and now ends in 0.1 seconds in a 128 MB heap; a subroutine at `UNIT_WORK` takes 0.7 to 2 seconds, one at `PROOF_WORK` about 1 second, and a program at `PROGRAM_WORK` about 4 seconds, each in a 128 MB heap. The most any program of the corpus takes is 234,000 units for one obligation, 145,000 for one subroutine's paths, 783,000 for its proofs and 886,000 for the whole program. `prove-fuzz` makes larger programs than anyone writes: the most in seeds 9137 and 22051 (800 programs each) are 768,000, 35,000,000 (a subroutine its 1.5-second wall-clock budget had already cut short), 5,100,000 and 38,000,000, and the proved obligations of both seeds are the same with the budgets as without. The cross-check is counted the same way: one input of a routine whose ENSURE nests 8 quantifiers visited 5,000,000 positions (7 seconds) before, and the whole cross-check of a routine now takes at most about 2 seconds; the most any routine of the corpus takes is 347,000 (`match-off-by-one`). The fuzzer runs a routine's inputs within its budget in about a second, a program's in about 2 (a program of 2,000 small routines, the first 100 fuzzed: 2 seconds); the most the corpus takes is 400,000 for one routine (kmers' `kmer_counts` in Mojo), 1,300 for one input, and every corpus program's report is the same as before.
## What the compiler does
The checker may never report an error on a program the compiler accepts, so the Mojo limits are a refusal to read, not an error. Asked through `mojo build` at the pin (Mojo 1.2.0), the compiler accepts 5,000 nested parentheses, 5,000 nested calls, 1,000 nested blocks, 5,000 `elif` arms and a 10,000-term sum, and crashes (exit 139, a stack overflow in the compiler) on 30,000 nested parentheses, a 30,000-term sum, or 30,000 minus signs. There is no depth it refuses with an error message.
## The tests
`tests/mojo-robustness.test.mjs` proves the Mojo limits and `tests/reader-limits.test.mjs` the others, each just past its value with inputs small enough to keep the test quick, and each shape just under it still reading and running. `tests/pseudo-robustness.test.mjs` has the pseudocode's.
+179
View File
@@ -0,0 +1,179 @@
# The Mojo corpus
Programming+ teaches what Mojo does when it runs, so everything it says about Mojo has to be true of a real compiler at a known version. The corpus is how: material harvested from Modular's own repositories at pinned commits, plus small programs of our own, every one of them checked on the real compiler through Compiler Explorer (godbolt). The pipeline is Python, standard library only, in `scripts/mojo/` (`corpus.py` is its command line); Node is needed for one processor (Mojo Quest keeps its tickets in TypeScript).
Every command below is a pixi task; the [README](../README.md#commands) lists them all.
The corpus itself (the pin, the harvested material, our programs and godbolt's answers) lives in pplus-library, the submodule `library/`, under `library/mojo/`; the pipeline that builds and checks it (`scripts/mojo/`) and what it generates for the app (`src/mojo/generated/`) live here. A task that changes the corpus leaves changes in both repositories: commit and push `library/` first, then commit core with the new pointer (`git add library`) and the regenerated files.
## Mojo of our own
There are three kinds of Mojo program we write, and each has a folder, a task to start one, and a job:
| Kind | Folder | Start one | Its job | Shipped in the app |
|---|---|---|---|---|
| probe | `library/mojo/probes/` | `pixi run new-probe <name> "<question>"` | Ask the pinned compiler one question (what does `//` do on a negative Int?). Godbolt's answer is the point; it is recorded, not judged. | no, but the checker and interpreter are held to the answers |
| exercise program | `library/mojo/local/` | `pixi run new-exercise <id>` | The Mojo of a catalog problem. It must pass its own `# expect-stdout:` lines. | yes, in `src/mojo/generated/programs.ts`, badged verified when it passed |
| stress program | `library/mojo/stress/` | `pixi run new-stress <name> "<what it exercises>"` | Realistic Mojo that stresses the interpreter. Its `# expect-stdout:` lines are the interpreter's prediction; godbolt confirms or refutes it. | no |
The loop is the same for all three:
```bash
pixi run new-probe int-floordiv-negative "does // floor toward negative infinity on Int?"
# edit library/mojo/probes/int-floordiv-negative.mojo
pixi run mojo-verify-item 'probes/int-floordiv-negative' # ask godbolt (network)
pixi run test # the checker and interpreter scoreboards read the new answer
```
For an exercise program, `pixi run play <id>` does the whole loop in one pass (below).
### The header
A program starts with comment lines that `corpus.py verify` reads. Only these keys are header lines; the program starts at the first other line, and the Mojo pane hides the header.
```mojo
# probe: what does // do on negative Int? the question, or what the program shows (one line)
# stdin: 3\n4\n what input() reads, with \n escapes
# mode: run run | asm | both (asm and both also return the listing)
# args: -O0 compiler arguments, after the pin's build arguments (below)
# expect-stdout: -4 a line the program must print (repeatable); implies expect: pass
# expect: compile-error pass | fail | compile-error | observe (the default without expect-stdout)
# origin: where the program came from free text, for people
# status: a note on its state free text, for people
```
**A stored answer belongs to the exact text.** Godbolt's answer is keyed by the compiler, mode, arguments, stdin and the whole source, header included. Any edit, even to a comment, makes the program unverified until it is asked again. That is deliberate: a stale answer is never shown against new code.
### How every program is built
Mojo is built one stated way everywhere core builds a program or asks godbolt to: `corpus.py verify`, `library-verify-mojo`, the Compile button (`BUILD_ARGS` in `src/services/godbolt.ts`: the pin's arguments, then the level's), `library-check`, `mojo-local`, `mojo-fuzz`, `mojo-run` and `play`. The arguments are `build.args` in `library/mojo/pin.json`, each with its reason under `build.why`:
- `--target-cpu x86-64-v3`. Without it `mojo build` targets the processor it runs on, and godbolt's machines differ: on 2026-11-12 every stored listing was AVX2 (`ymm`), and at 12:55 EST the same request for `local/demo` came back with AVX-512 (`zmm`, `kmovq`, `vpternlogd`), instructions the model machine does not know. x86-64-v3 is AVX2, FMA, BMI1 and BMI2, with no AVX-512, so a listing is the same whichever machine answers (`probes/godbolt-target-cpu`). A machine that is not x86-64 (an Apple silicon Mac) cannot build for it, so there the local tools leave it out.
- `--fp-mode contract=off`. Mojo's default, `contract=fast`, fuses a multiply with an add or subtract into one rounding wherever the operands arrive at run time: `probes/float-contract-runtime` (built with `contract=fast` on purpose) prints -0.22222222222222224 for `x * x - x` when `x` comes from stdin and -0.2222222222222222 when it is a literal the compiler works out while building. With contraction off every Float64 operation is rounded on its own, as IEEE 754 says and as the pseudo interpreter and core's Mojo interpreter compute (`probes/float-contract-runtime-off` prints -0.2222222222222222 twice).
A program's own `# args:` come after these, and an option it names replaces the pin's (the contraction probes name `--fp-mode` themselves). Every stored answer records the arguments it was built with (`args`) and is keyed by them, so a change to `build.args` leaves every answer unverified until `pixi run mojo-verify` and `library-verify-mojo` ask again. `tests/build-args.test.mjs` fails when a builder writes a code-generation flag of its own or the Python and TypeScript halves combine the arguments differently.
`mojo build` or `mojo run` on your own machine, without these arguments, targets your processor and fuses: its last digits and its listing can differ from what Programming+ shows. `pixi run mojo-run <file>` builds the way everything else does.
### The fast loop for an exercise program
```bash
pixi run play rolling-sum # one pass
pixi run play-watch rolling-sum # again on every save (tests off)
```
One pass is: run the file on the local `mojo` (pixi provides it); `corpus.py verify --item local/<name>` (godbolt, network); `corpus.py status` (offline, rewrites `programs.ts`); `tsc`; `scripts/mojo/listings.mjs`; the tests. A step that cannot run (no local compiler, godbolt unreachable) is reported as skipped and the pass goes on, so offline you still get the build and the tests, with the program shown as unverified rather than guessed at. `node scripts/play.mjs <name> --no-verify` or `--no-test` skips a step.
### The assembly
A program whose header says `# mode: both` (or `asm`) and `# args: -O0 --debug-level=line-tables` (after the pin's build arguments) makes godbolt return the compiler's listing with its answer. `scripts/mojo/listings.mjs` picks the first `def` that is not `main`, translates it and the user functions it calls to the x86-64 pane's syntax exactly as the **Send to x86-64 pane** button does (`src/mojo/att.ts`, `simulatorSetup` for the argument registers), tags each instruction `; mojo line N` with the line of the program the pane shows, and writes `src/mojo/generated/listings.ts`. An exercise that names the program in `mojoProgram` and leaves `sources.asm` empty gets that listing and its setup. No answer for the exact source, mode and arguments (the pin's and the program's) means no listing; a stale answer is never reused, because the key includes the source. Without `-O0` the optimizer may inline every function and the listing holds none of yours; the script says so.
Header lines (`# probe:`, `# mode:`, …) are for `verify`; only those keys are stripped from what the Mojo pane shows. The first line after the header block is the program.
## The compiler on your machine
Godbolt's stored answers cover the programs someone wrote down, and they need the network. pixi also installs the pinned compiler, and two tasks hold core to it directly, offline:
```bash
pixi run mojo-local # every Mojo program core holds or generates
pixi run mojo-fuzz --seed 7 --programs 50 # programs nobody wrote
pixi run mojo-fuzz --statements --seed 7 # whole programs of statements nobody wrote
```
`mojo-local` (`scripts/mojo/local.mjs`) builds and runs the probes, exercise programs and stress programs as written, the Mojo the translator writes for every exercise, every pseudo regression program and every library routine on its cases, and every Mojo reference of the library. For each it asks: does the checker stay silent on what the compiler accepts; does the interpreter print what the built program prints and end the same way, or decline; does the compiler accept generated Mojo, and does it print what the pseudo prints; does this compiler agree with godbolt's stored answer for the same text, arguments and stdin. Every "no" is printed, and the task fails. The differences that are right are listed in `EXPECTED` at the top of the script, each with its reason; a listed one that stops differing fails the pass too, so the list only shrinks. Answers are cached in `.tools/mojo-local/` by compiler version, arguments, stdin and source.
`mojo-fuzz` (`scripts/mojo/fuzz.mjs`) writes typed pseudo expressions at random from the notation's operators and built-ins, one per OUTPUT line, drops the lines the pseudo itself stops on or refuses, translates the rest, builds them, and holds each printed line to the pseudo's. It reports a line the compiler rejects, a line where the built program stops, a line that prints another value, a line where the interpreter prints something else than the built program, and a checker error on an accepted program, once per shape with the smallest expression that shows it. The same seed gives the same programs. Run it with a few seeds after changing `src/sync/pseudo-to-mojo.ts` or `src/mojo/`; when it finds something, fix the rule and pin the spelling in `tests/sync-mojo.test.mjs`.
With `--statements` it writes whole programs instead (20 to 60 lines, 100 per seed by default; the generator is `scripts/mojo/fuzz-programs.mjs`): records, constants, FUNCTIONs and PROCEDUREs with by-value and BYREF parameters of scalars and collections, some recursive with a bound, then the main lines, built from DECLARE of every scalar, sized, collection and record type, assignment to names, elements, fields and map entries, IF and CASE, FOR with positive and negative steps, FOR EACH over lists, arrays, text, ranges, maps and sets, WHILE, REPEAT, BREAK and CONTINUE, the collection built-ins, copies changed after they are made, and a tagged OUTPUT at many points, so the first line that differs says where. The generator is typed, so most programs check as written; the pseudo's checker and a run are the filter, and a line the checker refuses, a run stops on, or the translator says it has no Mojo for is left out and the rest tried again. A program whose output changes when SET members and map keys are visited in another order is dropped, since the notation never promised an order. The report says how many programs settled, which constructs they held, every finding once per shape with its smallest program, shrunk by leaving out statements one at a time while the built program still shows the same finding (`--shrink N` builds at most, 80 by default), and the pseudo engine's own faults apart. `--progress` prints each finding as it is found; `--dry` only generates and settles, to measure the generator.
Two kinds of difference are counted and not reported as failures, because the compiler decides them ([trust.md](trust.md#what-a-translation-says)): numbers that differ only in their last digits (the compiled program's `std.math` is its own; its arithmetic is the pseudo's, since every program is built with contraction off), and, for lines that use `**`, `exp` or `log2`, what those lose in Mojo 1.2.0 (they are good to 9 to 13 digits). What the compiler does wrong on its own is listed in `UPSTREAM` in the fuzzer, with the probe that records it; read that list on every version bump.
Neither task needs or replaces godbolt. A built program that traps is run with its core-dump limit set to 1, so a deliberate crash does not reach the desktop's crash handler. CI runs both in the pinned environment, which brings the compiler: `pixi run ci` runs `mojo-local` and a short `mojo-fuzz`, and the nightly run fuzzes longer ([ci.md](ci.md)). Run both yourself after changing the translator, the checker or the interpreter, and after a version bump.
## Reading the status
`pixi run mojo-status` judges every item from the stored answers, offline, and writes `library/mojo/golden/STATUS.md` (a table per corpus, every failure with its reason, and every probe's question and verdict) and `status.json` (`git -C library diff mojo/golden/status.json` shows exactly what changed).
Each item says what the pinned compiler should do with it: `pass` (compiles, runs, exits 0, and prints what it should or contains the idiom it should), `fail` (that check must not hold: a starter), `compile-error` (must be rejected, with each expected error at its line), `observe` (a probe: the answer is the point), or `skip` (with a reason: newer syntax than the pin, no `main`, not reproducible on public godbolt). Verdicts are `pass`, `fail`, `observed`, `skipped`, and `unverified` (no golden yet).
The dialect markers in the pin are a cheap first look: `newer` patterns are syntax that arrived after the pinned version (a manual sample using one is skipped), `older` patterns are syntax the pinned version rejects. They only set expectations; verify decides.
**What has to pass.** `pixi run mojo-status-strict` (and CI) fails only when a program we wrote fails: a probe, an exercise program, or a stress program. Harvested items can fail for reasons that are facts about upstream (a manual sample written for a newer compiler, a test file with no `main`); they are listed in `STATUS.md` to read, not to fix here. `corpus.py status --strict --strict-corpus all` holds every corpus to it.
## What lives where
| Path | What it is | Who writes it |
|---|---|---|
| `library/mojo/pin.json` | The Mojo version, the godbolt compiler id, the arguments every program is built with (`build`), each source repository and the ref to use, and the dialect markers | You |
| `library/mojo/mojo.lock.json` | What each ref resolved to: commit, zip sha256, and the directory inside the zip | `fetch`/`harvest` |
| `library/mojo/corpus/` | Processed material, one directory per processor, each item with its provenance | `harvest` |
| `library/mojo/corpus/SOURCES.md` | Which commit and license everything came from, what each processor found, every warning | `harvest` |
| `library/mojo/licenses/` | Each source's license file, copied from the commit the pin's `licenseCheck` names | You |
| `library/THIRD_PARTY.md` | Every harvested file with its source and the license header it carries, and what each license check found | `emit` (and `harvest`, `verify`) |
| `library/mojo/probes/` | Our questions about the pinned compiler's behavior, one small program each | You (`new-probe`) |
| `library/mojo/local/` | Exercise programs, shipped in the app | You (`new-exercise`) |
| `library/mojo/stress/` | Realistic programs that test the interpreter, not shipped | You (`new-stress`) |
| `library/mojo/golden/<key>.json` | Godbolt's answer for one program, keyed by compiler, mode, arguments (the pin's, then the program's), stdin and source | `verify`; `prune` removes the ones nothing reads |
| `library/mojo/golden/STATUS.md` | Every item's verdict against the goldens | `status` (also `harvest`, `verify`) |
| `src/mojo/generated/` | What the app reads at run time: `pin.ts` (version, compiler, build arguments), `tokens.ts` (the words, removed words and the compiler's messages for them), `editor.ts` (comment and indentation rules), `programs.ts` (`library/mojo/local/` programs with their verdicts), `stdlib.ts` and `types.ts` (which package exports each name, which types are copyable), and `listings.ts` (exercise listings, written by `scripts/mojo/listings.mjs` during `play`) | `harvest`/`emit`; `verify` and `status` refresh `programs.ts` |
| `library/syntax/mojo.xml` | The same words as a KDE syntax for Pandoc listings (pplus-web copies it into its Quarto extension with its quarto-css task) | `harvest`/`emit` |
Commit all of it. The stored answers are what make `pixi run test` and `mojo-status` work offline.
## Commands in detail
The tasks wrap `corpus.py`, which takes more options than the tasks pass:
- `harvest --local NAME=ZIP` uses a zip on disk for one source. `--local-dir DIR` matches every zip in a directory to a source by its marker files, but only for sources whose ref is still `UNRESOLVED`; add `--offline` to let zips stand in for pinned refs too (the lock then says `standsInFor`, and the next online run fetches the real ref).
- `harvest --processors quest,tokens` reruns some processors; `--keep` or `--workdir DIR` keeps the extracted sources for inspection.
- `verify --item 'probes/life-*' --force` asks again about some items (`pixi run mojo-verify-item` does this); `--dry-run` shows the request and the count and sends nothing; `--corpus diagnostics` adds the compiler's own tests (opt-in: about 140 files); `--limit N` asks about at most N.
- `status --strict` exits 1 if a program we wrote fails; `--strict-corpus` picks other corpora.
- `GITHUB_TOKEN` (any token with public read access) avoids GitHub's anonymous rate limit when resolving refs.
## The processors
| Processor | From | Produces |
|---|---|---|
| `quest` | mojo-quest | Each ticket's solution (must pass Mojo Quest's own check) and starter (must not) |
| `manual` | modular | The manual's tested code samples (must run and exit 0) and every `mojo` block that is a whole program followed by an `output` block (must print it) |
| `diagnostics` | modular | The compiler's `expected-error/warning/note` tests, each annotation resolved to its line and tagged with the pass that reports it (`parser`, `lifetimes`) |
| `tokens` | modular | Keywords (`TokenKinds.def`), soft keywords and removed words (the parser), decorators (the reference), prelude names (the stdlib) |
| `messages` | modular | The parser's and borrow checker's diagnostic wording and fix-its, read from their C++ |
| `release` | modular | The pinned release notes, section by section, and whether the snapshot is the pin, newer, or older |
| `syntax` | mojo-syntax | The TextMate grammar's tests as plain highlighting cases |
| `editor` | vscode-mojo | Comments, brackets, auto-closing pairs and indentation rules |
| `skill` | skills | Modular's table of removed syntax and its replacements |
| `stdindex` | modular | Which std package exports each public name (`sqrt` in `std.math`), for the compiler's import hint; a name exported from two places is left out; and which prelude functions raise (`input`, `atol`) |
| `stdtypes` | modular | Each std struct's declared traits (so which are implicitly copyable) and each trait's default methods (Copyable's `copy`, Equatable's `__eq__`), for the type checks |
A processor whose input files are missing at the pinned ref is skipped with a warning, and its previous output is kept.
## Moving to a new Mojo version
1. Find the release. Mojo releases are tagged `mojo/vX.Y.Z` in `modular/modular` (the platform's own tags are `modular/vX.Y`). Find godbolt's compiler id for it, `mojo_X_Y_Z`, in `https://godbolt.org/api/compilers/mojo`, and check that pixi's channel has it (`pixi search -c https://conda.modular.com/max/ mojo`).
2. Edit `library/mojo/pin.json`: `mojo.version`, `godbolt.compiler`, and `sources.modular.ref`; and `mojo = "==X.Y.Z"` in `pixi.toml` (pplus-web's too), then `pixi install`. A test holds the three names in the pin to one release, and `pixi.toml` and the documents to the pin. Move the other refs to the commits that match: Mojo Quest's commit whose `src/lib/compile.ts` names the new compiler id; the vscode-mojo, mojo-syntax and skills commits released alongside it.
3. Review the dialect markers against the new release notes. Anything in the notes' **Removed** or **Language changes** sections belongs in `older`; anything in `newer` that this release now includes comes out. (`newer` matters only when harvesting a snapshot past a release; at a release tag it is empty, and a test says so.)
4. `pixi run mojo-harvest`, then read `library/mojo/corpus/SOURCES.md`: every warning is something to look at, and a `release` line saying `snapshot newer` means the ref is not the release tag. A release can be tagged before its notes leave the nightly changelog (1.2.0 was: there is no `v1.2.0.md` at `mojo/v1.2.0`); the `release` processor then reads the changelog as the release's notes and says `notesFrom nightly-changelog`.
5. `pixi run mojo-verify`. A new compiler id changes every key, so every item is asked again, one request each and two at a time (`pixi run mojo-verify-dry` prints how many). Run it once, not in a loop; the public server is shared.
6. `pixi run mojo-status`, then read `library/mojo/golden/STATUS.md`. `git -C library diff mojo/golden/status.json` shows exactly which verdicts and probe answers changed between versions. A changed probe answer is a change Programming+'s Mojo engine has to make; a failing Mojo Quest solution or manual sample usually means a language change the markers should know about. The compiler's wording changes too: the checker quotes it, and `tests/mojo-check.test.mjs` fails where a quoted message moved (1.2.0 names a `TString` by where its values live, not by their types).
7. Check each moved source's license at its new commit: read the repository's license files and the headers of what was harvested, copy the license file into `library/mojo/licenses/`, and update that source's `licenseCheck` in the pin (commit, date, file, sha256, what it says). `pixi run mojo-emit` rewrites `library/THIRD_PARTY.md`; `tests/third-party.test.mjs` fails until every source was checked at the commit the lock holds.
8. `pixi run mojo-local`, then `pixi run mojo-fuzz` with two or three seeds: the new compiler on every program core holds or generates. Then `pixi run library-verify-mojo` and `pixi run library-check` for the library's Mojo references.
9. `pixi run mojo-prune`: the old pin's answers are keyed by its compiler id, so nothing reads them any more (git keeps them).
10. `pixi run test`, then commit the pin, the lock, the corpus, the goldens and the library's records in pplus-library, and the new pointer, `pixi.toml`, `pixi.lock`, `src/mojo/generated/` and `src/library/generated.ts` here.
## Licenses and provenance
Every item records its repository, commit (or local zip hash), path, and license; `SOURCES.md` summarizes them, and `library/THIRD_PARTY.md` counts every harvested file by the license header it carries and lists the ones with none (the manual's snippets, cut from pages with no header, and Mojo Quest's starters). Modular's repository files carry Apache-2.0 WITH LLVM-exception headers, and the repository's own LICENSE covers the rest, the docs included. Mojo Quest's solutions carry the same headers, but the repository has no LICENSE file, and its starters come from a module with no header, so its programs are used as test fixtures here; confirm with Modular before showing them to students as exercises. mojo-syntax is MIT, vscode-mojo is Apache-2.0. Manual prose is not copied into the app; hover text and quick fixes will be written in our own words and link to mojolang.org.
## When something goes wrong
| Message | Meaning |
|---|---|
| `a network proxy refused api.github.com` | No route to GitHub from here. Use `--local-dir DIR --offline`, or run elsewhere. |
| `GitHub refused the request (403)` | Usually the anonymous rate limit. Set `GITHUB_TOKEN`. |
| `GitHub has no ref ...` | The tag or commit in the pin does not exist. |
| `the lock was made from a local zip` | The pin has not moved since a local harvest. Pass the same zip with `--local`, or set a ref. |
| `GitHub's zip ... hashes to ...` | The archive for a locked commit changed. Rare; accept it with `--allow-hash-change` after a look. |
| `no directory in the zip holds all of [...]` | The repository's layout changed. Update that source's `markers` in the pin. |
| `<processor>: skipped, ... has no ...` | That input is missing at this ref; the previous output is kept. |
| `the quest processor needs Node 22.6+` | Node strips the TypeScript types from Mojo Quest's ticket file. |
+117
View File
@@ -0,0 +1,117 @@
# Translation coverage
<!-- Written by tests/sync-coverage.test.mjs. Do not edit; rerun `npm test` to refresh. -->
Each translator in `src/sync/` is run over every exercise with pseudo (17), every program in `library/pseudo/programs/` (55), and 17 one-construct fixtures (`tests/helpers/sync-programs.mjs`). 3 of the 89 have pseudo that does not read, by design (they teach the notation's error messages), and are left out below. That leaves **86 programs**.
| From pseudo to | Says it completely | Says it with a gap or a checker error | Cannot say it |
| --- | ---: | ---: | ---: |
| Mojo | 83 | 3 | 0 |
| lingo | 31 | 0 | 55 |
| matho | 3 | 0 | 83 |
Mojo is a program-for-program translation that always produces something: a line with no faithful spelling becomes a visible `raise Error("not translated: pseudo line N")` and a warning. Lingo and matho must read back as the same program, so what they cannot say exactly they refuse, with the construct and its line, and the pane keeps its last good text.
## Mojo: lines that become a visible gap
These programs translate, with the listed lines left as a `raise Error`.
| What it has no form for | Programs | Which |
| --- | ---: | --- |
| Programming+ could not translate this line into Mojo (the built-in EXACT, which Mojo's standard library has no function for). The generated code stops here with an error instead of guessing. | 1 | 50-float32.pseudo |
## Mojo: programs the translator refuses
Pseudo the course itself rejects is not translated.
Nothing.
## lingo: what English has no sentence for
English is read by `readSteps`, whose grammar has no sentence for these.
| What it has no form for | Programs | Which |
| --- | ---: | --- |
| steps outside a routine (every English step belongs to a routine) | 53 | 01-arithmetic.pseudo, 02-temperature.pseudo, 03-compound-interest.pseudo, 04-gcd-recursion.pseudo, and 49 more |
| a BYREF parameter | 4 | 06-fibonacci-memo.pseudo, 10-insertion-sort.pseudo, 26-swap-byref.pseudo, 55-statements.pseudo |
| a fixed-length ARRAY | 4 | ex:edit-distance, 05-primes-sieve.pseudo, 11-matrix-multiply.pseudo, 15-game-of-life.pseudo |
| a HASHMAP whose values are not counts | 3 | ex:translate-codons, 13-stack-brackets.pseudo, 39-constants-codons.pseudo |
| a change to this part of a value | 2 | ex:edit-distance, 16-running-stats.pseudo |
| a DEFINE set | 2 | ex:translate-codons, 21-sets.pseudo |
| a loop step that is not a whole number written out | 2 | 05-primes-sieve.pseudo, 39-constants-codons.pseudo |
| a record | 2 | 12-records.pseudo, 16-running-stats.pseudo |
| a record type | 2 | 12-records.pseudo, 16-running-stats.pseudo |
| REMOVE(...) | 2 | 13-stack-brackets.pseudo, 14-queue-bfs.pseudo |
| the built-in ROWS | 2 | 11-matrix-multiply.pseudo, 15-game-of-life.pseudo |
| this kind of position | 2 | ex:edit-distance, 15-game-of-life.pseudo |
| a CONSTANT | 1 | 39-constants-codons.pseudo |
| a Field value | 1 | 12-records.pseudo |
| PARALLEL FOR | 1 | 43-parallel-map.pseudo |
| REPEAT ... UNTIL, which English reads as a loop that tests first | 1 | 46-projectile.pseudo |
| the built-in CHOOSE | 1 | 47-binomial-and-ph.pseudo |
| the built-in CHR | 1 | 08-caesar.pseudo |
| the built-in COS | 1 | 46-projectile.pseudo |
| the built-in FILL | 1 | 43-parallel-map.pseudo |
| the built-in LOG10 | 1 | 47-binomial-and-ph.pseudo |
| the built-in SIN | 1 | 46-projectile.pseudo |
| the built-in SPLIT | 1 | 40-text-builtins.pseudo |
| the built-in TO_INTEGER | 1 | 22-binary-to-decimal.pseudo |
| the built-in TO_STRING | 1 | 22-binary-to-decimal.pseudo |
## matho: what is not an equation
An equation lowers to one `FUNCTION` that returns a value; a program with output, text, a loop that does more than add up, or steps outside a function is not one.
| What it has no form for | Programs | Which |
| --- | ---: | --- |
| steps outside a function (an equation is a function) | 49 | 01-arithmetic.pseudo, 02-temperature.pseudo, 03-compound-interest.pseudo, 04-gcd-recursion.pseudo, and 45 more |
| a function that answers LIST (equations answer numbers) | 5 | ex:match, ex:match-proved, ex:match-off-by-one, ex:match-reset, and 1 more |
| a function that answers STRING (equations answer numbers) | 5 | ex:revcomp, fixture:string-build, fixture:slice, fixture:case, and 1 more |
| a function that answers BOOL (equations answer numbers) | 3 | ex:binary-search, fixture:early-return, fixture:forall |
| a loop that is not adding up or multiplying one value (FOR) | 3 | ex:best-position, fixture:loop-down, fixture:break-continue |
| the input T, which is not a number or a list of numbers | 3 | ex:first-unknown, ex:gc-fraction, fixture:set |
| a DEFINE set | 2 | ex:translate-codons, 21-sets.pseudo |
| a function that answers HASHMAP (equations answer numbers) | 2 | ex:tally, ex:kmers |
| a record type | 2 | 12-records.pseudo, 16-running-stats.pseudo |
| the input A, which is not a number or a list of numbers | 2 | ex:hamming, ex:edit-distance |
| the input B, which is not a number or a list of numbers | 2 | ex:count-base, ex:count-base-proved |
| a CONSTANT | 1 | 39-constants-codons.pseudo |
| a loop with a STEP | 1 | fixture:loop-step |
| a position that is not a loop counter plus or minus a number | 1 | fixture:min-max |
| a PROCEDURE | 1 | fixture:procedure |
| a WHILE loop | 1 | fixture:div-mod |
## matho: the equation sets
Each set in `tests/matho.test.mjs` is lowered to pseudo by the matho reader, written back as equations by `pseudoToMatho`, and checked: 26 of 28 round-trip.
| Equation set | Round-trips | Why not |
| --- | :---: | --- |
| mean-and-variance | yes | |
| mean | yes | |
| sum-from-one | yes | |
| sum-no-bounds | yes | |
| binomial | yes | |
| height | yes | |
| kinetic | yes | |
| gravity | yes | |
| omega | yes | |
| normal-density | yes | |
| ph | yes | |
| log2 | yes | |
| ln-and-log | yes | |
| factorial | yes | |
| choose | no | the loop counter K2 (matho writes it as a single letter) |
| cosine | yes | |
| distance | yes | |
| matrix-row | no | a two-dimensional position that is not two loop counters |
| nested-sums | yes | |
| relu | yes | |
| piecewise | yes | |
| calls-an-earlier-equation | yes | |
| sum-over-a-set | yes | |
| floor | yes | |
| ceiling | yes | |
| absolute | yes | |
| max-min | yes | |
| mod | yes | |
+79
View File
@@ -0,0 +1,79 @@
# What each badge and verdict means
Programming+ takes a procedure from an idea to Mojo to the machine. The idea is written in lingo (steps in plain English), matho (equations written in LaTeX), pseudo (pseudocode precise enough to run, prove and translate) or speco (a specification to prove against); then comes Mojo (Modular's programming language, pinned to version 1.2.0), then x86-64 on a model machine. pplus-web shows the badges; the verdicts behind them come from pplus-core (the prover, the fuzzer, the translators, the compiler's stored and live answers, the model machine). This page is kept here, beside what produces them.
Programming+ is built for checking work that someone or something else produced, so every claim it shows names what answered it, and none claims more than that. This page lists each one: who earns it, what it means, and what it does not mean. When a new badge or verdict is added, it gets a row here in the same commit. The texts below are pplus-web's (`src/ui/shell.ts`, `src/ui/provenance.ts`, `src/ui/home.ts`, `src/ui/library.ts`, `src/ui/views/`); pplus-web's `tests/trust.test.mjs` fails when a badge the site draws has no row here.
## Where code came from
| Shown | Earned by | Means | Does not mean |
|---|---|---|---|
| **Generated from pseudo** | The Bridge's Mojo tab, always (`mojoProvenance` in pplus-web's `src/core/provenance.ts`); Mojo copied from it with **Edit in Developer** | The translator wrote this Mojo from the pseudo, literally, with a header comment saying so | That anyone has read it, or that it is the Mojo a person would write |
| **Generated from pseudo, with N best-practice rewrites** | The Best practices tab's rewrite of generated Mojo | The best-practice rules rewrote N places of the generated Mojo | That the rewrite was compiled. Copy it into the Developer area and Compile & run to ask |
| **Started from generated Mojo** | Generated Mojo edited in the Developer area (`mojoOrigin: 'generated-edited'`) | A person has changed generated Mojo | That the person reviewed the parts they did not change |
| (badge cleared) | **I've reviewed this**, in the Developer area only | The person says they reviewed it; the header comment goes too | That anything checked the review. Compiling and editing never clear the badge |
## What a compiler said
| Shown | Earned by | Means | Does not mean |
|---|---|---|---|
| **Compiled on godbolt** (ran, exit N / compiled, did not run / did not compile / timed out) | An answer from the compile backend (`src/services/compile-backend.ts`, godbolt.org with Mojo 1.2.0 by default) for this exact source, input and build level, made in this browser | The real compiler answered as shown | That the program is right. The badge is keyed by a hash, so any edit, other input or other level removes it, and a share link never carries it |
| **Edited since compile** | An edit after a compile | The compiler's answer is for an earlier text | Anything about the current text |
| The Compile & run tab's own badge: **compiling**, **ran, exit 0**, **exited with N**, **compiled, did not run**, **did not compile**, **timed out**, **no answer** | The last request from this browser to the compile backend, and whether it is still waiting | What the backend answered for the source it was sent, built the one way Programming+ builds Mojo (`--target-cpu x86-64-v3 --fp-mode contract=off`, then `-O0` and line tables at the default level: [mojo-corpus.md](mojo-corpus.md#how-every-program-is-built)), so the listing is the same whichever of godbolt's machines answers; when the pane has changed since, the tab says so | That the current pane compiles, or anything when there was no answer (a network failure, for one). That `mojo build` on your own machine gives the same listing or the same last digits: with no arguments it targets your processor and fuses `a * b + c` into one rounding |
| **verified on Mojo 1.2.0** | An exercise's own program in `library/mojo/local/`, shown unchanged, when godbolt's stored answer for that exact source passed the file's own expectation: its `# expect-stdout:` lines, or `# expect: fail` for a starter whose bug the student is to find (`pixi run mojo-verify`) | The program did what its file says it should, on the real compiler | That the program is right on other inputs, or that a starter is right at all |
| **not verified** | An exercise's own program, shown unchanged, with no passing stored answer for that exact source | Not yet asked, or the answer did not pass; the badge's tooltip says which | That it fails |
| **your edits** | An exercise's own program after the student changed it | The text is no longer the one that was verified | Anything about the new text; Compile & run asks about it |
| **Mojo 1.2.0** (no other word) | A Mojo pane whose text is neither an exercise's own program nor generated | The pinned version the checker, the interpreter and Compile & run use | Anything about this program |
| The home page's **verified** chip on a problem | The problem's own Mojo program has the **verified on Mojo 1.2.0** badge | As that badge | As that badge |
| The home page's **your edits saved** chip | A saved version of the problem in this browser | Opening it brings back the saved text | Anything about that text |
| A Mojo checker error, warning or note | Programming+'s own checker (`src/mojo/`) | The compiler would report this. The checker may never report an error on a program the compiler accepts: `tests/mojo-check.test.mjs` holds it to that on every program the corpus holds with a stored answer, and `pixi run mojo-local` and `mojo-fuzz` on the programs they build | That a program without checker errors compiles. Only the compiler says that |
| A **best practices** note | The optional helper (`src/mojo/practices.ts`), off by default | A more idiomatic way to write a line, whose rewrite keeps the output the same where it offers one | An error. Notes never look like the compiler |
| Mojo output in the Run view and stepper | Programming+'s Mojo interpreter (`src/mojo/interp.ts`) | For a program the compiler builds, what it prints, or the interpreter declines and says why. One listed exception: `probes/struct-field-loop-copy`, which Mojo 1.2.0 builds into a program that crashes (it frees a struct's List field twice); the interpreter runs it as written, and the test holds that difference by name. `tests/mojo-run.test.mjs` holds it to that on every program godbolt ran, from the stored answers; `pixi run mojo-local` and `mojo-fuzz` hold it to the pinned compiler on a developer's machine | That the program compiles. The interpreter can run a program the compiler rejects (`print(Int(3.9))` prints `3` here; Mojo 1.2.0 refuses to build it), so Compile & run is the word on whether it compiles. On a program outside the corpus, agreement is the rule the tests hold it to, not a proof. Its FLOAT arithmetic is the compiler's as Programming+ builds it: every build passes `--fp-mode contract=off` (`library/mojo/pin.json`), so `a * b + c` is rounded twice, as the interpreter rounds it (`probes/float-contract-runtime-off`). Three things it does not promise. The last digits of a program built another way: with Mojo's default, `--fp-mode contract=fast`, the built program fuses a multiply with an add or subtract into one rounding where the operands arrive at run time (`probes/float-contract-runtime` is built that way on purpose, and `pixi run mojo-local` lists it as the interpreter's one difference of this kind), so `mojo build` on your own machine can differ in a last digit. A float raised to a power that is not a whole number, and std.math's transcendental functions (`sin`, `cos`, `exp`, `log`, `cbrt` and the others), which Mojo computes with routines of its own or the C library's, so the interpreter declines them (a whole power it computes as Mojo does, by squaring; `fma`, `hypot`, `nextafter`, `ulp`, `copysign`, `sqrt`, `gcd`, `lcm` and `comb` it computes exactly as Mojo does, each held to a probe), as it declines random numbers, whose values come from Mojo's own generator. And input: the interpreter hands `input()` one line per call, as a terminal does; in Mojo 1.1.0 and 1.2.0 each `input()` opens its own buffered reader, so when the input is a pipe (Compile & run, a script) the first call takes every line and the second raises `EOF` |
## What a proof says
The Prove tab reports every obligation in three statuses (`src/engines/pseudo/vcgen.ts`, `src/services/pseudo.ts`).
| Shown | Earned by | Means | Does not mean |
|---|---|---|---|
| **Proved** | The built-in prover (`solver.ts`), on every path it examined, in a unit it examined completely | The claim follows from what is known, in the notation's number model: INTEGER as whole numbers of any size, the sized types (INT8 … UINT64) exactly, with an `overflow` obligation wherever a value could leave its range, FLOAT and FLOAT32 as finite numbers whose rounding is not seen into. The prover is meant to be sound: `tests/prover-soundness.test.mjs` holds it to every known hole (the regression programs in `library/pseudo/prover/`), to a canary, and to every corpus program run and fuzzed; an audit in November 2026 closed 18 rules that proved what a run breaks. In a program that says `USE IEEE` nothing is marked proved | That the Mojo made from the program has the same property. A 64-bit `Int` wraps and a `Float64` becomes `inf` or `nan`; the `int-model` and `float-model` notes say when a proof leans on the number model. That the prover has no hole left: a "proved" that a run breaks is a soundness bug ([engines.md](engines.md#soundness)) |
| **Broken** | A generated input (the fuzzer, seeded) or a run that breaks the claim at that place | There is an input for which the claim is false, and **Step through** shows it | Anything about other claims. A run outranks the prover: a proved obligation that an input breaks is shown as broken (and would be a soundness bug) |
| **Open** | Neither of the above | The checker could not finish the argument, usually because a loop needs an INVARIANT | That the claim is false |
| **partial: not every path was examined**, on a unit | The prover left some paths of the unit unexamined (more paths than its limit, or past its time limit) | Nothing in the unit is marked proved: what it would have proved shows as open | That anything in it is wrong |
| An invariant "the checker found on its own" | Inference in `vcgen.ts`, kept only at a fixed point | It holds on entry and survives every pass, and the proof used it | That it is the invariant a reader needs |
## What testing says
| Shown | Earned by | Means | Does not mean |
|---|---|---|---|
| A routine's cases in the Tests tab, under **no failures**, **N ways of failing** or **not tested** | The fuzzer (`src/common/fuzz.ts`), with the seed and input count shown; **not tested** when it cannot generate inputs for the routine, with the reason | Every input listed was run and checked against each claim and limit | That untried inputs pass. "Held on 300 inputs" is evidence, not proof |
| A failure's shrunk input | Shrinking in the fuzzer | The smallest input it found that fails the same way | The smallest input that fails, or the only one |
## What a translation says
| Shown | Earned by | Means | Does not mean |
|---|---|---|---|
| ⇄ in step (lingo, matho, speco) | The translator, which reads its own output back and holds it to the pseudo (`tests/sync-lingo.test.mjs`, `sync-matho.test.mjs`, `sync-speco.test.mjs`) | The two panes describe the same program, as far as the round trip checks | A proof that they are equivalent on every input |
| ⚠ not in step | A language that cannot say the program, or a pane that does not read | The pane keeps its last text and says why | That the pane is wrong |
| Generated Mojo agreeing with the pseudo | `tests/sync-mojo.test.mjs`, over every exercise and corpus program, in core's interpreter; and `pixi run mojo-local` and `mojo-fuzz`, on the pinned compiler itself, over those programs, the library's routines, and generated ones | On those programs, the Mojo compiles and prints what the pseudo prints: in the tests by core's interpreter, and by the compiler only on a machine with the pinned Mojo (`mojo-local` and `mojo-fuzz`) | That the translator is verified. Where a line has no faithful Mojo, the translation stops with `not translated` rather than guess. Numbers agree to their last digits or nearly: the compiler's `std.math` is its own (in Mojo 1.2.0, `**` to a fractional power is good to about 13 digits and to a whole power, done by repeated multiplication, to the last digit or two; `exp` and `cosh` are good to about 13 digits near 1 and about 10 at 100 (`probes/float-cosh-accuracy`); `log2` to about 9; a whole exponent near 1e10 stops the built program, and `gcd` of an even number and a much larger odd one does not come back), while its arithmetic is the pseudo's, each FLOAT operation rounded on its own, since every program is built with contraction off; the translation carries a note where it writes `**` or `log2`. Mojo writes some FLOATs as other text (6.02e+23 for 6.02e23), so a FLOAT made into text is translated where it is printed and is `not translated` where the program uses the text itself |
## What the machine says
| Shown | Earned by | Means | Does not mean |
|---|---|---|---|
| Registers, caches, pipeline and counters in the Hardware area | The model machine (`src/engines/asm86/`), on the preset machine named in Setup | What that model does with these instructions | A measurement of a real processor. Cycle counts are a teaching model; compare a run with itself across edits |
| "stopped: … standard library, not on the model machine" | A call into a function the model does not have | The real program would enter the library here | That the library call does anything in particular |
## Library routines
A routine of pplus-library (`USE md`) carries the record of `pixi run library-check` ([library.md](library.md)).
| Shown | Earned by | Means | Does not mean |
|---|---|---|---|
| **Cases pass** | Running the pseudo on the cases in `routine.json` | The routine gives those results; they are what every reference is held to | That the results are right for other inputs |
| **Prover: pass** | Every obligation of the routine proved, as for any pseudo | Its contracts hold for every input that meets its REQUIRE, in the notation's number model | Anything about the value of FLOAT arithmetic beyond what the contracts say |
| **Prover: open** | Some obligation not proved, none broken | The routine's comment says which and why (usually FLOAT rounding, which is opaque to the prover; `tests/documents.test.mjs` fails when the comment does not mention it) | That it is wrong |
| **A reference agrees** | Python, C at -O0 and -O2, core's Mojo interpreter, the pinned Mojo compiler on the machine that ran the check (`compiler`), or the pinned compiler on godbolt, run on the cases. A C or Mojo reference's program holds no case: it reads every case's arguments from stdin at run time, each FLOAT bit for bit (`tests/library-harness.test.mjs`), so the compiler cannot work them out while it builds | That implementation, at that level, prints the pseudo's results exactly, or within the stated tolerance, computed by the code the compiler made for inputs it did not know. A Mojo reference is built with the pin's arguments, contraction off among them, so that code rounds each FLOAT operation on its own, as the pseudo does; Mojo's own math library (`exp`, `log2`, `cosh`, `**`) is not the pseudo's, and a reference that calls it states a tolerance and why | That it agrees on other inputs, or built with other flags: with Mojo's defaults the code fuses a multiply and an add into one rounding where it can (`probes/float-contract-runtime`), and a last digit can differ |
| **Mojo: unverified** | No stored answer from the pinned compiler for that exact program and input | Not yet asked (`pixi run library-verify-mojo`) | That it fails |
| **Proof: pass** | The pinned Dafny verified the proof file (or its stored verdict for this exact text) | The method is correct over exact numbers, as the proof states it | That the FLOAT version computes the same digits: rounding is outside the proof |