Test / gate (push) Canceled after 0s
The gate first ran on the server that deploys the site: a slow container with no C compiler and no ICU. Ten tests failed there on correct code, and no Mojo program could be built at all. - The workflows ask for a runner labeled heavy, not the deploy server: the gate builds and runs some 300 Mojo programs and fuzzes. docs/ci.md says how to register one. With none registered a run waits. - The pinned environment has a C compiler on Linux (gcc, with its C library pinned to glibc 2.34): mojo build links with the C compiler it finds, and conda-forge's default links against a C library too old for Mojo's runtime. mojo-local reports a program that could not be linked as that, and does not keep the answer. - The pinned Dafny runs without ICU, and dafny-fetch fails when the Dafny it fetched does not start. - A test's time limit is processor time at the machine's pace (tests/helpers/pace.mjs). - The prover's time on the clock is the caller's: provePseudo and Workspace.proofBudgetMs take it, the Prove tab's 3 seconds stay the default, and the command line, library-check and the tests use none, so their answers are the counted budgets' alone. - The library pointer moves to its workflow change (e5ae090).
122 lines
28 KiB
Markdown
122 lines
28 KiB
Markdown
# 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. The 3 seconds are the Prove tab's (`PROVE_BUDGET_MS`); a caller gives another with `provePseudo(parsed, { budgetMs })` or `Workspace.proofBudgetMs`, and the command line, `library-check` and the tests give none, so their answers do not depend on the machine ([limits.md](limits.md#proving-and-testing)).
|
||
- **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.
|