Files
pplus-core/docs/engines.md
T
alexmandClaude be0db2d74f Widen pseudo for numerical work: sized types, FLOAT32, exact built-ins, USE IEEE
Pseudo could say what a procedure computes only up to INTEGER and FLOAT,
so it could not state what a Mojo or Python program with Int32, UInt8 or
Float32 values will compute, and it had no words for rounding itself.

- lang/parse: INT8..INT64, UINT8..UINT64, FLOAT32, FLOAT64 as types
  (INTEGER or FLOAT with a width, so every "whole number" rule accepts
  them); conversions written as Mojo writes them, INT32(X), FLOAT32(X);
  1_000_000, 0xFF and 0b1010 literals; a type name as an argument
  (MAX_VALUE(INT8)); the USE line (USE IEEE now, library modules next).
- check: widths and precisions never mix silently (mixed-width,
  mixed-precision); a literal takes the type of the sized value beside
  it, as in Mojo, and one that does not fit is an error before any run
  (literal-range); typing for every new built-in.
- interp: a sized result, store, parameter, RETURN or conversion that
  does not fit stops the run (kind overflow), WRAP(X, T) wraps on
  purpose; FLOAT32 results are rounded to single precision; USE IEEE
  lets NaN and infinities flow.
- numeric.js: exact helpers: FMA rounded once, EXACT(X) with every digit
  a FLOAT holds, ULP and NEXT_AFTER for both precisions, bit operations
  in two's complement.
- Built-ins: ASIN ACOS ATAN SINH COSH TANH HYPOT POW CBRT EXPM1 LOG1P E
  TRUNC SIGN COPYSIGN CLAMP FMA IS_NAN IS_INF IS_FINITE INF NAN ULP
  NEXT_AFTER IS_CLOSE EXACT MAX_VALUE MIN_VALUE EPSILON GCD LCM BIT_AND
  BIT_OR BIT_XOR BIT_NOT SHIFT_LEFT SHIFT_RIGHT WRAP. They stay usable
  as names (a variable E, a FUNCTION GCD): the program's own wins.
- vcgen: an overflow obligation on every sized result, then the range
  as a fact (also for sized parameters and loop-cut variables); FLOAT32
  arithmetic as its own uninterpreted functions, constants rounded
  exactly, TOFLOAT32(v) otherwise; argument obligations for SQRT, the
  logarithms, ASIN/ACOS, LOG1P, CLAMP and the shifts; nothing proved
  under USE IEEE.
- testing: the fuzzer tries the edges of a sized type and generates
  FLOAT32 values.
- pseudo-to-mojo: Int8..Float32, conversions, the new built-ins through
  std.math (each name in the harvested index), a note where Mojo wraps.
- Tests: numeric.test.mjs; corpus 49-52; prover fixtures int8-overflow,
  float32-store, ieee-nan; the reference documents every new form.

Gate: 324 pass (core). New Mojo uses std.math names the interpreter has
not been verified on (listed in sync-mojo's KNOWN_GAPS); they need
pixi run mojo-verify on the network before the interpreter runs them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
2026-10-05 11:43:53 +00:00

12 KiB
Raw Blame History

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; the rest of the engines 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 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 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 and conversion: "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). 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.

The numerical built-ins (HYPOT, EXPM1, LOG1P, FMA, ULP, NEXT_AFTER, EXACT, IS_CLOSE, MAX_VALUE, the bit operations, ...) are exact or correctly rounded: src/engines/pseudo/numeric.js 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. Functions JavaScript has no exact version of (erf, gamma) are not built-ins; they belong in the library as verified pseudo. Built-ins that stop the run for some arguments (SQRT, the logarithms, ASIN and ACOS, LOG1P, CLAMP, the shifts) carry an argument obligation. The built-ins added for numerical work stay usable as names (a variable E, a FUNCTION GCD): the program's own definition wins (SOFT_BUILTINS in lang.js).

tests/numeric.test.mjs pins each rule; the corpus programs 49-sized-integers to 52-elementary show them in use.

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 tests/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.

When a soundness bug is found, add the program that shows it to tests/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

In the app, an obligation the prover marks proved that a generated input breaks at the same place is shown as broken, not proved.

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); and logic, solver and vcgen rewritten in TypeScript with the same behavior.
  • 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; 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 one step between parse and check: 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.