This is the reference for the app itself: the three areas, their links and embeds, and what each part of the workspace does. For commands, see the [README](../README.md).
## The areas
The app has three areas, one workspace layout each (`src/core/areas.ts`, the `AREAS` table; the names are placeholders the owner can change in one line). A problem is one saved state shared by all three, so moving from one area to another carries the work along. The area comes from the route, not the state. Each area is its own page, reached from the nav and the home page; the toolbar names the area you are in and offers a switch only to an area that would show the open pane exactly as it is (`safeSwitches` in `src/core/areas.ts`): in practice Developer and Hardware on the same Mojo, and the Bridge's Mojo tab once the student's Mojo is its translation. A learner moving between areas therefore never finds the work changed by the move itself; **Edit in Developer** and **Open in Hardware** are the deliberate moves that carry work across.
| Area | For | Panes | Inspect tabs | Dock |
|---|---|---|---|---|
| **Bridge** (`bridge`) | taking a written problem or idea into Mojo | lingo, matho, pseudo, speco, Mojo | run, flowchart, data flow, prove, tests | setup, output, problems, compiler |
| **Hardware** (`hw`) | Mojo and x86-64 with the machine in view | Mojo, x86-64 | none: two panes, the code and the board, whose cards hold the run, registers, memory, caches, pipeline, chip, setup, output, problems and compiler | none |
Each catalog problem names the area it opens in (`area` on the exercise): Hardware for `asm-*` problems, Developer for ones that are only a Mojo program, Bridge for the rest. The panes a state is shown with come from the area, so a link made in one area opens in another on that area's first choice of pane. Layout (the dividers, the dock tab, what is folded) is kept per area (`layout: { bridge, dev, hw }` in the state). **Open in Hardware** on the compiler's listing puts a function into the x86-64 pane and switches area.
### The home page
The home page (`src/ui/home.ts`) opens with why the platform exists: work is done by human and artificial agents, producing code and analyses is cheap, and someone still has to take responsibility for the output, which takes knowing what it does step by step (the hero's sign-off panel lists who might have made it above the sentence that has to be signed). Three columns follow (producing got cheap, ownership did not, the gap from novice to expert is where tools are missing), with AlphaFold as the example. Then each area gets a card with its name and tagline from `AREAS` and a sample the engines make on the spot, each in a window of the same height: the Bridge turns the mean, written as an equation, into pseudo, lingo and labeled Mojo through the same hub the panes use; Developer shows the checker's advice on a moved-out value and the first steps of `count_base`; Hardware shows the registers and the cache line of the first load in `asm-two-pointers` on the teaching machine. **Why Mojo** says why it is the one real language: it reads plainly, it is compiled with strict rules there is always a precise answer to, it spans a first program to hand-written GPU kernels, and we believe it will lead in the computational sciences. The notations section shows `count_base` in six even boxes, except matho, which cannot express it (B is a character) and says so. The problem list shows the areas each problem opens in (`areasFor` in `src/core/areas.ts`: its own area first, then the Bridge if it has lingo, matho, pseudo or speco, Developer if it has Mojo, Hardware if it has x86-64), with a link to each, and filters by area.
### The Bridge workspace
Four languages are kept in step (see [Translation between languages](#translation-between-languages)): tabs run **lingo, matho, pseudo, speco**, then **Mojo (from pseudo)** set slightly apart.
- **Link state on every tab.** ✎ the pane you are editing (the others follow it), ⇄ in step, ⚠ not in step (the reason is in the tooltip and in the banner above the editor), nothing for a pane still **as authored** (nothing has been translated yet; the first edit makes that pane the authority).
- **Typing never fights the cursor.** The pane being edited is never rewritten. The other panes are brought up to date when their tab is shown, replacing only the part of the text that changed, so the cursor and scroll position of a pane stay put. Each such update is its own undo step (the editor's `setSynced`, a `sync` user event that history does not join to typing), so Ctrl+Z in a pane steps back to what it showed before the sync, and, as with any change to a pane, that pane then becomes the authority. Loading a problem is not an undoable edit.
- **A pane that is not in step** (matho for a `WHILE`; anything while the pane you edited does not read) keeps its last text, is read-only, and says why, with an **Edit anyway** button that makes it the authority. The stepper does not step a stale lingo or matho pane; it steps the pseudo.
- **Mojo (from pseudo)** is read-only, labeled *Generated from pseudo*, and computed from the pseudo on the fly (`Session.derivedMojo()`; the state's own `sources.mojo` is untouched). It steps in the Mojo interpreter, is checked, and **Compile & run** sends it to the real compiler. **Edit in Developer** copies it into the Developer area's Mojo pane (asking first if that pane holds something else) and records `mojoOrigin: 'generated'`; the first edit there makes it `'generated-edited'`, and the Mojo pane says so.
- **Prove and Tests** work on the hub's pseudo with the speco woven in, whichever pane you edited.
Every area is an IDE-style workspace: the language panes as tabs over one editor; under it the stepper and what runs next; beside it an inspect panel (the Run view, flowchart, data flow, proof, tests) whose tabs appear only when they apply to the pane; under everything a dock for the output, the problems, the real compiler's answer, and the machine model's numbers. A catalog of worked problems comes with it.
### The Hardware area
Two panes, and nothing shown twice. On the left the code (the Mojo and x86-64 tabs over one editor) and the stepper under it. On the right the **board** (`src/ui/hw/board.ts`), a set of cards in a two-column grid (twelve tracks, a half card spanning six): the course's own x86-64 views (`src/engines/asm86/views.js` and `hwviews.js`, the widgets the course pages use, with the course's stylesheets from `styles/course/`), mounted over the x86-64 pane's run and moved by the stepper, and the app's own views as cards too: Setup, Output, Problems, the Compiler, the Run view (for the Mojo pane), the counters, and the cache lines. The area has no inspect panel and no dock (`workspace: 'board'` in `AREAS`); Compile & run and a click on a diagnostic bring their card into view, adding it if the board does not show it.
**Arranging it.** Presets along the top set out cards that make sense to see at once. **+ Add a view** opens every card by group (Program, Registers and memory, Memory system, Time, The chip); click one to put it on the board or take it off. Drag a card by its title to move it (or use ↑ ↓), ↔ widens it to the whole row or narrows it to share one, × takes it off. The arrangement is kept per area (`layout.hw.board`, a list of `{ id, wide? }`, cleaned by `normalizeBoard`), and the preset buttons show which preset it is, if any. Every change is a pure function in `src/core/hardware.ts` (`moveItem`, `addItem`, `removeItem`, `toggleWide`, `presetOf`).
The presets:
- **Registers and memory**: a card per register the program touches (amber when the last instruction wrote it, with the value before), with every narrower name (`eax`, `ax`, `al`, `ah`) for the registers the program also uses at a narrower width; the flags, with the ones the last instruction read; the effective address as base + index × scale + displacement; the memory regions byte by byte with the load (blue) or store (purple) highlighted; and the stack as eight-byte slots with `rsp` and `rbp` marked.
- **Caches**: memory below the instruction set. **Cache lines** (the board's own view, `src/ui/hw/lines.ts`) shows, for each load and store of the last instruction, the whole line it touched as a row of bytes: the bytes this access used, the ones the program used before, the ones it uses later, and the ones it never uses, with where the line was found (an L1d hit, or the level it came from) and "used 8 of this line's 64 bytes". Beside it the course's L1d cache as sets and ways (hit green, miss red, the evicted line named), the hierarchy with the path each access took and running totals, and, with virtual memory on, the page walk and the TLB.
- **Pipeline**: time. The classic five-stage pipeline cycle by cycle (stalls amber, wrong-path fetches red, the whole run's lost cycles by cause), the micro-ops the last instruction became and the ports each can run on, what bounds the whole run (the dependency chain, the busiest ports, the front end), and the out-of-order timeline of when each instruction entered, ran and retired.
- **Whole chip**: the core from branch predictor to memory with the parts the last instruction used lit up, each lit edge with an arrowhead on the end its data reached (a load's data back up from wherever it was found to the load port, a fetch that missed back into L1i, a store out through the store buffer, the result into the registers from the port that produced it); the listing with each instruction's address and bytes beside the last instruction's machine code broken into prefix, REX, opcode, ModRM, SIB, displacement and immediate; and last, inside the out-of-order core (reorder buffer, ports, rename table, with its own cycle buttons), whose table grows and shrinks with what is in flight.
**The listing and the encoding as a pair.** When the two are next to each other at half width, `board.ts` marks them as a pair: on a board at least 960px wide they share a row two to one, and on a narrower one the encoding sits under the listing. The listing then scrolls in its own box, as tall as the encoding (300px when stacked), and keeps the instruction about to run in view; only that box scrolls, never the page.
**Nothing moves while stepping.** A card never gets shorter while one run is stepped: each keeps the tallest height it has reached as its minimum. When the board is built it first draws a spread of the run's steps (all of a short run, forty of a long one, always the last) before the browser paints, so views that grow with the run (the pipeline, the timeline) start at their final size. The minimums start over with a new run, machine or arrangement, and when the board's width changes. The same rule holds the Run view's panel of followed variables, and a string or list with no value yet keeps the height of its ruler. Elsewhere the boxes that change with each step have fixed sizes: what runs next (two lines, each cut with an ellipsis, the whole text in its tooltip), the loop status (one line), the register cards' "was" line, and in `styles/course/bridge.css` the core's caption, the address arithmetic and the cache-line list.
- **Mojo and the compiler**: the Run view of the Mojo pane, the real compiler's answer and listing (with Open in Hardware), the output and the problems.
- **Counters** (a card in any arrangement): the run as totals in the style of `perf stat`, and for code sent from the Compiler view what each Mojo line cost.
**Mojo and x86-64.** The two are tabs over the one editor, never split side by side. x86-64 sent from the Compiler view ends each instruction with `; mojo line N`, godbolt's own line table (`forSimulator` in `src/mojo/att.ts`); through it, clicking a line in either pane marks the matching lines in the other tab, lit when that tab is selected (`asmMojoLines` and `relateAsmMojo` in `src/core/hardware.ts`). A short note in the pane head says so; for x86-64 written by hand, which has no such table, it says the lines are not linked. The Mojo there carries its generated label and godbolt badge, as everywhere. Compiling needs the network; without a listing the area works on hand-written x86-64 alone.
The board's **machine** switch (also in the Setup card): `teaching` (caches small enough that misses happen on small data), `realistic` (shaped like a desktop core: 64-byte lines, an L3, a next-line prefetcher), or `ideal`; and **virtual memory** turns on paging with a TLB. The state stores it as one string (`machine: 'teaching+paging'`; `parseMachine` and `machineSpec` in `src/core/hardware.ts`), and the run hands it to the hardware model through the trace, so the board's views and the counters always describe the same machine. With virtual memory on, a line is the physical one and the access keeps the address the program wrote.
What each card mounts, with what options, and the frame each view draws at each step are decided DOM-free in `src/core/hardware.ts` and tested for every problem with assembly (`tests/hardware.test.mjs`); a view that throws says so in its own card and leaves the rest working. The course files draw dark on `body.quarto-dark`, so the app keeps exactly one of `quarto-light` and `quarto-dark` on `<body>`, matching the theme it shows (`src/ui/theme.ts`).
### Mojo badges
Two independent badges sit beside any Mojo the site shows (pane head, Compiler view, Mojo embeds, Share dialog):
- **Generated from pseudo** (or **Started from generated Mojo** once edited). `mojoProvenance` (`src/core/provenance.ts`) answers for every view: the Bridge's Mojo is always generated, elsewhere `PlayState.mojoOrigin` says. Generated Mojo starts with a header comment, so copying it keeps the warning. It never shows beside "verified on Mojo" (which is only for an exercise's own program). Only the Developer area's **I've reviewed this** button clears it (`Session.clearMojoOrigin`), taking the header comment off too; compiling and editing do not.
- **Compiled on godbolt**, with the outcome (ran, exit N / did not compile / timed out), the compiler and build level in the tooltip, or **Edited since compile**. It is keyed by a hash of source, input and build level (`compiledStatus` in `src/core/compiles.ts`), so a one-character edit, another level or another input removes it. Full answers are the newest 16 in `pplus.compiles`; a summary index (`pplus.compiled`, up to 300) lets the badge outlive them. Neither is in `PlayState`, a share link or a file: a link never claims a compile that this browser did not make. The badge means the compiler answered, not that the program is right.
### Best practices (the helper)
`src/mojo/practices.ts` (DOM-free) turns the gap between the translator's literal Mojo and the Mojo a person would write into things to learn from. It is **off by default in both the Bridge and the Developer area**: each area has its own switch (the toolbar's "Best practices" button), remembered in this browser (`pplus.practices.bridge`, `pplus.practices.dev`; `src/core/prefs.ts`), never in `PlayState` or a link. While a switch is off the rules never run (a spy test holds it to that) and nothing about them is shown. The translator never imports the helper, so the Bridge's Mojo is the same literal translation either way (a grep gate and a snapshot test keep it so).
A rule is `{ id, title, why, docUrl, example, apis, detect }`. The starting rules: declare-then-assign → `var n = …`; `x = x + 1` → `x += 1`; an index loop that only reads codepoints → `for cp in t.codepoint_slices()`; `raises` on a function that cannot raise; a never-changed number that sizes a loop → `comptime`; argument conventions (`imm` written out is the default; `mut` on an argument never changed); `reserve` before a loop that appends a known number of times; `name^` for a last use handed to a `var` argument; `.copy()` for a list copy that says so. (The plan said `read`; Mojo 1.1.0 renamed it `imm`, so the helper says `imm`.)
- **Bridge:** the Best practices dock tab lists each finding with the Mojo line, the pseudo line it came from (the hub's line map), the reason, before and after, the manual link, and, where true, how to write the pseudo so the translator writes the better form. Clicking one lights both lines. The Mojo is read-only, so rewrites are shown, not applied. **Show idiomatic version** (in the Mojo tab, off until chosen) shows a copy with the safe rewrites applied, only if it passes the checker no worse than the literal one and the interpreter prints exactly what the literal one prints; it keeps the generated label ("Generated from pseudo, with N best-practice rewrites").
- **Developer:** findings are `note` diagnostics with origin "best practices" (never an error or a warning, so they never look like the compiler) in Problems and the gutter, each with a one-click fix where the rewrite is safe. A rule that cannot promise a safe rewrite (`comptime`) explains and leaves the editing to the student.
- **Tests** (`tests/practices.test.mjs`): every rule's example passes the checker, runs, and prints the same before and after, and the rule's fix turns one into the other; every method a rewrite names is in the harvested index; a false-positive gate runs the rules over Modular's own tested programs in `mojo/corpus/manual/` against a reviewed allowlist; each exercise's findings are pinned by a snapshot; applying every fix to each exercise's generated Mojo and each `mojo/local/` program keeps it checking and printing the same.
### Saved versions
A student can save the state of their work under a name and come back to any saved version from the **Versions** menu in every area's toolbar (`src/core/versions.ts`, DOM-free, storage injectable).
- **What a version holds:** every source, the link bookkeeping (`sync`), where the Mojo came from (`mojoOrigin`), the call, the input, the assembly setup and machine, and the build level, plus the area it was saved in, a name, and a time. Not the layout, the step, or the open tab: restoring a version changes the work and never where you are looking. (`EDITS`, which decides whether work differs from the problem as written, keeps leaving `sync` out; the version fingerprint adds it, so restoring brings the links back as they were.)
- **Where they live:** `localStorage`, one list per piece of work: `pplus.versions.<problemId>`, or `pplus.versions.ws.<workspaceId>` for work that began from a share link or a file (`PlayState.workspace` is added when such work is first saved, and the address is updated so a reload finds it). Every area shows the same list. At most 50 per list: when it is full the oldest automatic version makes room, and if only named ones are left the save is refused rather than delete one. The menu says when the browser's storage is nearly full.
- **Never losing work:** choosing a version, **Reset**, and **See the new version** first save work that no version holds as "Before switching (time)" or "Before reset (time)". If that save is refused, the switch does not happen.
- **A problem that changed under saved edits** shows a banner with **See the new version**: your edits become the version "My edits, before the problem changed" and the problem opens as it is now.
- **Between browsers:** Share → Download writes the state and, with a checkbox (on by default), its versions; Open… puts them in the right list and never overwrites a version that has the same id. A share link carries only the current state.
### With Quarto
`#/quarto` (`src/ui/quarto.ts`, linked from the nav, the footer, and a section of the home page that shows one shortcode beside the stepper it makes) is a gallery of the Quarto extension's shortcodes ([quarto/README.md](../quarto/README.md)). Each card shows what an author writes (the shortcode, and every program file it names, in tabs) and what the reader gets, drawn when the card scrolls into view by the same code `quarto render` runs: `renderStatic` for the rendered views and the machine, this app's own `#/embed/...` route in an iframe for the live ones. The cards can be filtered by kind (rendered with the page, the machine, live, text); one machine card has a menu of every `pplus-hw-<view>` and draws the one chosen. `#/quarto#<shortcode>` scrolls to a card, `#/quarto#setup` to the set-up steps. The page loads the extension's `pplus.css` and `pplus.js` from the site (`scripts/assemble.sh` copies the extension into `site/`), so the steppers and "make it live" behave exactly as on a Quarto page. The shortcodes, their options and the sample programs come from `src/quarto/shortcodes.ts` and `galleryFiles()`; `tests/quarto-gallery.test.mjs` renders every sample and holds each program in it to its header lines.
## Links
| URL | Opens |
|---|---|
| `/#/` | the home page: pitch, problems, reference |
| `/#/<area>/p/<problem>` | a catalog problem in an area (`bridge`, `dev` or `hw`), with the student's saved edits (localStorage) |
| `/#/<area>/s/<state>` | a shared state in an area: every pane, the call, the setup, the step — compressed into the link |
| `/#/embed/<view>/<state>` | one view, no chrome, for an `<iframe>` |
| `/#/embed/<view>/p/<problem>` | one view of a catalog problem |
| `/#/quarto` | With Quarto: the gallery of the Quarto extension's shortcodes (`#/quarto#<section>` scrolls to one) |
Nothing else is a route: `#/p/<problem>`, `#/s/<state>` and the other earlier forms open the home page. `<view>` is `playground` (the whole workspace; `?area=dev` picks the area, Bridge by default or the problem's own), `trace`, `table`, `flow`, `data`, `life`, `proof`, `tests`, `problems`, `compiler`, `asm` (the machine numbers), or a pane name (`lingo`, `pseudo`, `speco`, `mojo`, `asm`) to show just that editor with its problems under it. Query parameters on an embed: `?t=12` parks the stepper, `?ro=1` makes the editor read-only; `area`, `panel`, `lang`, `build`, `machine`, `dock`, `docktab`, `editor`, `side`, `dockheight` and `theme` arrange the example as the playground's controls do (`applyEmbedParams` in `src/core/state.ts`).
A reader's edits in an embed are saved in their browser, in that embed's own save (one per embedded example, shared by pages that embed the same one), never in the app's save for the problem. Once they have changed something, **Reset** appears beside "open in Programming+" and puts the author's version back. An embed keeps a save only while it holds edits, so a reader who has not changed an example always sees the author's current version. A read-only embed (`?ro=1`) saves nothing.
The **Share** button in the app produces the app link, a ready-to-paste `<iframe>` for any view, and the Quarto shortcode for the same state (`{{< pplus-playground state=… >}}` or `{{< pplus-embed state=… view=… >}}`). Without the extension, in a Quarto page:
loading="lazy"title="Programming+: find a pattern, stepped through"></iframe>
```
## The workspace
- **Step through**, with the tools a tutor would use at a whiteboard: the next line is called out before it runs with what it reads and writes; strings and lists draw as rulers with the position being read highlighted; every variable shows its previous value and a link to the step that changed it; click a line number for a breakpoint and run to it; jump by loop pass; **predict mode** asks what the next step will write before you take it and keeps score; play at any speed; export the trace as CSV. Keyboard: → ← Shift+→ Home End Space B P, and ? in the toolbar lists them.
- **Light and dark**: the ☾/☀ button; follows the system until you choose. Embeds take `?theme=dark`.
- **Table of values**: the table a student draws by hand, drawn by the machine: a column per step that changed something, a row per name, the new value in the cell, blank for unchanged; click a step to jump the stepper there; copy as text.
- **Flowchart**: laid out from the structure of the pseudo (so loops loop and branches branch), each box shaded by how often its line ran in the last run, each loop labeled with its passes, each arrow out of a decision with how often it was taken; a box that never ran is dashed. Click a box to reveal its line; download as SVG.
- **Data flow**: inputs on the left, `RETURN` and `OUTPUT` on the right, one arrow per assignment that reads the one and writes the other, labeled with its line, dashed when a condition only decides whether it happens.
- **matho pane**: equations as a source language, written in LaTeX (`src/services/matho.ts`). One `FUNCTION` per equation; `\sum` and `\prod` become accumulator loops, subscripts become positions (with the 1-based shift when the sum starts at 1), `\begin{cases}` becomes `IF`/`ELSEIF`, Greek letters become names, references to earlier equations become calls hoisted out of loops when their arguments do not change. Every decision is a note on the equation's line; integrals, infinity, limits and derivatives are refused with the finite procedure to write instead. The trace steps the pseudo with the marker on the equation each step came from.
- **Numerics**: `SUM_OF MEAN_OF VARIANCE_OF STDEV_OF MEDIAN_OF DOT NORM_OF FILL CHOOSE RANDN FLOOR CEIL LOG10 SIN COS TAN ATAN2 PI()`, and `PARALLEL FOR`, a loop whose passes may run at once, checked at run time: two passes touching one location stop the run with a data race that names the location and the passes.
- **Mojo for every exercise with pseudo**: each has its Mojo in `mojo/local/`, so the Developer and Hardware areas always have something to show for it; `tests/mojo.test.mjs` runs each Mojo program in the interpreter and checks it prints what the exercise expects.
- **Panes**: the area's own (see the table above), dimmed when empty (a dimmed tab opens an empty pane to write in), as tabs over one editor (CodeMirror: search and replace with Ctrl+F, go to line with Ctrl+G, bracket matching, undo and redo; Tab indents, Ctrl+/ comments). The editor is never split: in the Bridge a short note in the pane head says the other tabs update as you type (lingo and matho update the pseudo, and the pseudo the Mojo made from it), and clicking a line marks the lines it became in the next tab down; Hardware does the same between Mojo and x86-64. Drag the dividers to resize (double-click resets); the widths, the dock tab, and what is folded are remembered in the share link.
- **The side column** is the inspect panel. Its tabs are offered only when they mean something for the pane (Prove for the pseudo family) and dimmed, with the reason, when the run has nothing for them yet.
- **The Run view** (the first tab, in the Bridge and the Developer area; `src/core/runview.ts`, drawn by `src/ui/views/run.ts`) is the whole run read top to bottom, one row per step: its number, its line, what ran (indented by call depth, with what it printed), and a column for each variable you **follow**, holding its value after that step: in color where the step wrote it (with the position, `[5, 6]`, when it wrote one element), faded where it carries over, underlined where the step reads it, hatched where it is not in scope. The lifecycle of the value a variable names (Mojo: made ●, copied ⧉, moved in ⇢, moved out ⇥, destroyed ✕) is marked in the same cell; events of values no column names are noted beside the step. Above the rows, the followed variables as they stand at the stepper's position, with a ruler for a string or list and a grid for a table, the element just written and the one about to be read marked. **+ variables** opens a picker of every variable in the run, by routine; until you choose, it follows the variables of the routine that does the most work. The choice is kept per area (`layout.follow`). "Only steps that change something" hides the rest. Click a row to step there; the stepper keeps its row in view. It replaces the Variables panel, the trace table, the table of values and the Lifetimes tab, which each showed part of this.
- **The Tests tab** is a fuzzer that shows its work (`src/core/fuzz.ts`, drawn by `src/ui/views/tests.ts`). For each routine (the pseudo's, with the speco woven in; or each Mojo function other than `main`) it lists **what each input must do** (finish within the step limit; raise no runtime error, or for Mojo no abort and no uncaught raise; keep every REQUIRE, ENSURE, INVARIANT, DECREASES and ASSERT, with inputs that break a REQUIRE skipped rather than failed; give the same answer when run again), **how the inputs were made** (each parameter's generator, with the values it tries first, and each strategy with how many inputs it made: edge cases in combination, every DNA string up to three letters for a routine that reads one, seeded random values, and mutations of the inputs that reached a line nothing earlier had reached, as a coverage-guided fuzzer does), each **failure** with the case that found it and every step of shrinking it to the smallest input that still fails the same way (**Step through this input** puts that call in the call box and shows the run), the **lines reached** by how many inputs (a line no input reached is flagged), the **answers** given and how often, and **every case** run with its strategy, input, outcome, answer or error, and steps, filterable by outcome and strategy. The seed and the number of inputs (100 to 3,000) are chosen at the top; the same seed always makes the same inputs. `tests/fuzz.test.mjs` runs it on every exercise.
- **Views that follow the run**: the **Flowchart** shades by the run so far and marks the box that runs next; the **Data flow** lights up the names the next line reads and the name the last line wrote.
- **Step colors**: every step in the Run view and the "next" box is colored by what it does (writes a value, decides, loop control, enters a routine, returns, input or output, a value destroyed, raises or fails); the legend is in the inspect panel's tab row.
- **The stepper** is docked under the editor, at the editor column's width, as part of it: first, back, step, last, play and the slider; the loop-pass jumps, run to breakpoint, predict mode, only writes, speed and CSV; the loops in flight (or the machine's counts); and what runs next. It stays visible when the dock is folded.
- **The dock** under everything holds **Setup** (the call and the input lines for pseudo, lingo and matho; the build level and stdin for Mojo; the machine and the setup block for x86-64, in fixed-size boxes), Output, Problems (with the count on its tab), Compiler (Mojo) and Machine (the Hardware area's board); ▾ folds it away.
- **Hover** any word or symbol in any editor for its reference entry: keywords, built-ins, operators, English phrasings, speco symbols, instructions, registers, condition codes.
- **Language reference** at the top of the home page, rendered from `src/core/reference.ts`. Where an engine already holds a fact (keywords, built-ins, precedence, sentence forms, instruction glosses, condition codes, machine presets) the reference reads it from the engine; the tables written by hand carry examples, and `tests/reference.test.mjs` parses every example through the real parsers, so the page cannot drift from the tool.
- **Save and load**: Share → Download writes `<title>.pplus.json`; Open… loads one back (here or on another machine). A `.pplus.json` file, a share link, or a `state=` shortcode from an earlier state format opens an empty workspace, and a save in the browser from an earlier format is discarded, so the problem opens as written; Programming+ makes no promise to keep old saves and links working. The share link and the embed code carry the same state.
- **Input**: the input box in Run setup feeds `INPUT` (pseudo) and `input()` (Mojo), one value per line; the lines travel in the share link.
## Translation between languages
Pseudo is the hub: every other notation translates to or from it, so four languages need six translators (the restructure plan, section 2.3). The translators are DOM-free functions of text under `src/sync/`; `src/sync/types.ts` has their shapes and the line maps that say which input line each output line came from.
**pseudo → Mojo** (`src/sync/pseudo-to-mojo.ts`) is one way only, and its output is always labeled generated: the first line is `# Generated by Programming+ from pseudo. Not reviewed for Mojo best practices.` (`src/sync/header.ts`). It is an app-owned port of the Mojo half of the course engine's `translate.js`, and it is deliberately literal: `var n: Int` then `n = …`, `total = total + 1`, an index loop over codepoints. Idiomatic rewrites belong to the optional best-practices helper, so a student can see the difference.
-`def main()` is written from the pseudo's own lines, then from the call being run: `COUNT_BASE('A', "GATTACA")` becomes `print(count_base("A", "GATTACA"))`, with `TRUE` as `True`, a character as a one-letter `String`, and an integer given to a `FLOAT` parameter as `1.0`.
-`raises` is inferred (a dictionary read, `input()`, `atol`, a failed `ASSERT`, or a call to a routine that raises, transitively). Imports (`Set`, `sort`, the math functions) come from the harvested standard-library index, and only for names the translation uses.
- Where the notation has a built-in with no one-line Mojo spelling (`FORALL`, `EXISTS`, `SUM`, a set written by rule, `KEYS`, `SORTED`, `SPLIT`, `FILL`, `SLICE` of a String, the statistics), the translation writes a short loop just before the line that uses it. A fixed-length `ARRAY` is an append loop, as in the verified programs, because the interpreter does not run `List(length=…)`.
- It never invents Mojo. A line with no faithful spelling (a loop condition that would need such a loop, a built-in the standard library lacks) becomes `raise Error("not translated: pseudo line N")` and a `translate-gap` warning on the pseudo line; the program stops there instead of printing a plausible wrong answer. The pseudo's own mistakes (`unsupported`) are reported, not translated.
- Two behaviors differ by design, and a literal translation keeps Mojo's: dividing a `FLOAT` by zero stops the notation but gives `nan` in Mojo, and `PARALLEL FOR` runs its passes in order with no race detector. Translation notes (`translate-divide`, `translate-each-order`, and so on) say so on the line.
`tests/sync-mojo.test.mjs` holds the translation to the pseudo: for every exercise with pseudo and every program in `tests/corpus/`, the generated Mojo has no checker errors, runs in the interpreter, and prints what the pseudo prints (compared by value, not text: `TRUE` and `True`, `3` and `3.0`, a map's keys in any order). Programs it cannot hold to that are listed in the test with a reason (the interpreter declines `chr`, `ord`, random numbers and the math functions; the checker is right about the two programs that read an unset variable), and `AGREE_AT_LEAST` is a floor that can only rise. A snapshot of the generated Mojo for every exercise is in `tests/snapshots/sync-mojo/`; when a change to the translator is wanted, run the test with `UPDATE_SNAPSHOTS=1` and review the diff.
**pseudo → lingo** (`src/sync/pseudo-to-lingo.ts`) writes the English that the lingo reader (`readSteps` in the course engine's `english.js`) understands, so the lingo pane can follow the pseudo pane. The grammar belongs to the reader, and the translator is held to it: before returning, it reads its own output back and checks that the same routines come out with the same kinds of input. If English cannot say something the way the reader needs it, the result is `unsupported` with a warning on the pseudo line, and the pane keeps its last good text instead of showing English that does not read.
- Names follow the reader's slots: a single letter or a Capitalized word. A name that is neither (`CURRENT_MAX`) has no English form yet.
- Each input is first written tersely, letting the steps show what it is. If the reader would take an input as something else, the translator adds a sentence saying what each input is ("L is a list of whole numbers.") and reads again.
- A name first set inside a block is given its value before the block, because English names are scoped by block.
- Left unsupported on purpose, each with its reason on the line: steps outside a routine (every English step belongs to a routine), records, `BYREF`, `REPEAT`, `PARALLEL FOR`, `DEFINE`, `CONSTANT`, a fixed-length `ARRAY`, maps keyed by a character, and `IN` over a String.
`tests/sync-lingo.test.mjs` holds it to that for every exercise, every corpus program, and the single-construct fixtures in `tests/helpers/sync-programs.mjs`: the English reads; lowering it back to pseudo gives a program with the same output and the same kind of stop; and writing English again from that pseudo gives the same text (comments aside). `SUPPORTED_AT_LEAST` is a floor that can only rise.
**pseudo → matho** (`src/sync/pseudo-to-matho.ts`) writes the equations, in LaTeX, for the programs that are equations, and refuses the rest. It recognizes the shapes the matho reader lowers: a `FUNCTION` that returns one value; an accumulator loop (`Total <- 0` then `Total <- Total + …`, or `1` and `*`) as `\sum` or `\prod`, with the bounds the reader uses (`FOR I <- 0 TO N` is `i=0` to `n-1`; a 1-based loop is `i=1` to `n`, and `X[I - 1]` is `x_i`); `FOR EACH` over an input list as a sum over a set; an `IF`/`ELSEIF` chain whose every branch returns as `\begin{cases}`; a call of an earlier function as a reference to its equation; and `SQRT`, `ABS`, `FLOOR`, `CEIL`, `CHOOSE`, `SIN`/`COS`/`TAN`/`EXP`/`LOG`/`LOG10`/`LOG2`, `MIN`, `MAX`, `PI()`, `DOT` and `NORM_OF`. Names given to values before the `RETURN` (the reader's hoisted calls, a temporary) are substituted where they are used.
- Everything else is `unsupported` with the construct and its line: "matho has no form for a WHILE loop (line 4)". An equation has a value, so output, input, text, a yes-or-no answer, a procedure, a record, steps outside a function, and a loop that does more than add up are all refused.
- Names. The reader makes `\bar{x}` into `X_BAR` and `\sigma` into `SIGMA`, so the pseudo has lost the student's spelling. The `NameMap` hint (`hints.names`, keyed by the upper-case pseudo name) carries it back; without one, `SIGMA` is `\sigma`, `X_BAR` is `\bar{x}`, a single letter is lower case, and a longer name is `\text{...}`. A hint is checked like everything else, and one that does not lower back to the function is refused.
- It never writes an equation that reads as something else. The LaTeX is lowered again by the matho reader and held to the pseudo: the same function names, inputs of the same kind, and the same values on three sets of sample inputs (stopping the same way where the pseudo stops). A program that fails is refused.
- Comments are not carried across. The lowering writes each equation as a comment above its function, and carrying that back would put a stale copy of the equation above the new one.
`tests/sync-matho.test.mjs` holds it to three checks on every equation set in `tests/helpers/sync-programs.mjs` (the sets `tests/matho.test.mjs` works by hand): the LaTeX reads, the pseudo it lowers to behaves like the original, and writing it again from that pseudo gives the same LaTeX. Two sets are listed as gaps with their reasons (a matrix row written `y_i`, and a second factorial whose counter the reader names `K2`); `SUPPORTED_AT_LEAST` is a floor that can only rise. Programs from the exercises and the corpus are accepted or refused the same way, with a located reason.
**The hub** (`src/sync/hub.ts`, tests in `tests/sync-hub.test.mjs`) puts the translators together. It is pure: a function of the texts it is given, with no DOM and no `localStorage`. `Session.setSource` hands an edit in a linked pane (lingo, matho, pseudo, speco) to it and applies the result in one change event; Mojo and x86-64 are stored as typed.
1.**The pane you edit is the authority** (`state.sync.authority`). The edit produces a new pseudo, directly or by lowering, and the other linked panes are regenerated from it. The pane that was edited is never rewritten, so typing never fights the cursor.
2.**Contracts ride along.** Lingo and matho cannot say contracts, so an edit in either weaves the speco into the pseudo it produced, and the speco is re-derived from that pseudo (`reconcileSpec`, which keeps claims about a routine or loop that is gone). An edit in speco replaces the pseudo's contracts with its own (`weave` in replace mode), and lingo and matho, which ignore contracts, follow.
3.**An authority with errors changes nothing.** If the edited pane does not read, every other pane keeps its text and is marked stale: "lingo line 3 does not read yet".
4.**A language that cannot say the program goes stale, not blank.** When a generator returns `unsupported` (matho has no form for a `WHILE` loop), that pane keeps its last text and is marked stale with the reason, until the program is expressible again.
5.**Mojo is produced only from pseudo**, as the literal translation, memoized by the pseudo and the call (`Session.derivedMojo()`); it is not stored.
6.**Opening a problem rewrites nothing.** Panes with text are shown as written; a linked pane that is empty is generated from the pseudo for display (`Session.source`), and reaches the saved state only with the first edit. Until then `state.sync` is absent and a pane's link state is "authored".
7.**Line maps compose through the hub.**`SyncHub.relate(maps, from, line, to)` answers which lines of one pane match a line of another, going through the pseudo; `Session.lineMaps()` has the maps of the last cascade.
`state.sync` (`{ authority, stale, names }`) is part of the saved state and the share link. It is bookkeeping, not an edit: a state whose texts are the problem's own is unedited whatever `sync` says. `names` is the student's spelling of equation names (`\overline{x}`), so a trip through pseudo restores it.
**Coverage.**`tests/sync-coverage.test.mjs` runs all three translators over every exercise, corpus program and fixture and writes [sync-coverage.md](sync-coverage.md): how many each says completely, and, for every program it cannot say, what it has no form for. Each translator has a floor in the test.
## Mojo
The distinction that shapes it: [Mojo Quest](https://quest.mojolang.org) teaches you to *write* Mojo, with the compiler as the judge; Programming+ shows you what Mojo *does when it runs*: every step, the life of every value (made, copied, moved, borrowed, destroyed), and the instructions the processor executes. The + is those views.
Everything is pinned to **Mojo 1.1.0** and checked against the real compiler on [Compiler Explorer](https://godbolt.org) (`mojo_1_1_0`). Programming+ ships no compiler and never claims a program compiles without asking one.
**The Mojo pane** is edited like the pseudo: highlighting built from the compiler's own token table (docstrings across lines, the ownership words `imm`/`mut`/`out`/`deinit`/`var`/`ref`, the transfer `^`, and the words 1.1.0 removed, such as `fn`, underlined), the VS Code extension's indentation rule, Ctrl+/ for comments, and hover text for the ownership vocabulary. Before compiling, Programming+'s own checker (`src/mojo/`) reports what it is certain the compiler would: code at file scope, an empty body, an untyped parameter, a method without self, no `main`, an implicit declaration, an unknown name (with the compiler's import hint), removed syntax such as `fn`, each in the compiler's own words. `tests/mojo-check.test.mjs` scores it against godbolt: it may never report an error on a program the compiler accepts, or one the compiler did not make. Code it cannot read yet gets a note, not an error.
**Compile & run** (Ctrl+Enter on the Mojo pane) sends the program to godbolt.org in one request: the compiler's answer, the program's output (the input box feeds `input()`), and the listing. The **Compiler** view shows them. The compiler's messages land on their lines with its fix-its as one-click fixes (an implicit copy offers "transferring the value with '^'" or "copy it explicitly with '.copy()'"). The listing is grouped by function, your own first, in Intel syntax translated from godbolt's AT&T (or the original). **Send to x86-64 pane** puts one function, and the functions of yours it calls, on the model machine with its arguments' registers ready and the listing's read-only strings placed in memory; each call into the standard library becomes a stub that stops the run where the real program would enter the library, and says so. `docs/asm-coverage.md` is the census of every instruction compiled Mojo uses against what the machine models (everything but 256-bit AVX2), and `tests/asm-coverage.test.mjs` keeps it that way. Build "as written" (`-O0`, the default, which keeps every function you wrote) or "optimized" (what `mojo build` does: small functions fold into their callers). An edit after compiling marks the answer stale rather than showing it on the wrong lines. **Step through** runs the Mojo pane in Programming+'s own interpreter (`src/mojo/interp.ts`): line by line, with the variables it follows, what each line reads and writes, loop passes, breakpoints, and each value's lifetime, in the Run view. `tests/mojo-run.test.mjs` holds it to godbolt: on every program godbolt ran, it prints exactly what that run printed, or declines and says why.
**An exercise's Mojo** is a program in `mojo/local/`, named by the exercise's `mojoProgram`. `corpus.py verify` checks it on godbolt, and the pane's badge says "verified on Mojo 1.1.0" only when godbolt's answer passed the program's own expectation.
**The corpus** behind all of this (the compiler's own words, Modular's tested programs, our probes, and godbolt's stored answers) is described in [mojo-corpus.md](mojo-corpus.md).
## speco
The course's contracts (`REQUIRE`, `ENSURE`, `INVARIANT`, `DECREASES`) can only live inside pseudocode. The speco pane lets a student write them as a separate document, in math notation, and **weaves** them into the pseudocode before proving:
```
SPEC COUNT_BASE(B, T)
ENSURE result = |{ K ∈ [0, |T|) : T[K] = B }|
LOOP FOR I
INVARIANT Total = |{ K ∈ [0, I) : T[K] = B }|
```
`∀ ∃ Σ ∈ ∧ ∨ ¬ ≤ ≥ ≠ = |…|` lower to `FORALL EXISTS SUM IN AND OR NOT <= >= != == LENGTH(…)`. `LOOP FOR I`, `LOOP WHILE`, or `LOOP 2` names the loop an invariant belongs to. Contracts already in the pseudocode are shown in the pane and never duplicated. The proof view reports each obligation against the speco line it came from.
**Where speco is going.** The next stage lets the same claims live as comments on the pseudo and the Mojo a student already has (`# @requires`, `# @ensures`, `# @invariant` on the line they govern), so a specification never has to be a separate document. Checking is two-layered and honest about which layer answered: every claim is evaluated on every step of the interpreter's run and on the generated inputs (a runtime check: "held on 300 inputs", or the smallest input that broke it), and the claims the prover can read are handed to it, so an obligation shows as *proved*, *tested*, or *broken*, never conflated.
**Speco and pseudo are two views of one set of contracts** (`src/services/speco.ts`), and neither loses a claim:
-`extractSpec(pseudo)` reads the contracts out of the pseudo as a speco document.
-`weave(pseudo, spec)` inserts a speco's claims, never duplicating what is there. This is what the proof view uses. `weave(pseudo, spec, { replace: true })` is the other mode, for when the speco is the authority: for each `SPEC` unit it first removes the routine's `REQUIRE`/`ENSURE`/`DECREASES` and the `INVARIANT`/`DECREASES` of every loop the unit selects, then inserts the speco's. Routines and loops the speco does not name are left alone.
-`reconcileSpec(pseudo, previous)` is the speco that follows the pseudo when the pseudo is edited: what the pseudo says, plus every claim the previous speco made about a routine or loop the pseudo no longer has. Those stay, under a `// kept:` comment that says why, with a warning on their line; they return to the routine or loop when it comes back, even before the pseudo has written them. A contract deleted in the pseudo, from a spec that was not waiting, is deleted from the speco too.
These laws are tested in `tests/sync-speco.test.mjs`, for `count-base-proved`, `match-proved`, and every corpus program with contracts: `extract(weave(P, extract(P))) === extract(P)`; weaving twice changes nothing; a speco woven into the same pseudo with its contracts removed, then extracted, comes back (and the contracts written are the original's, up to spelling); and reconciling is a fixed point. Holding the laws found one bug, now fixed: a symbol just inside a bracket, `(∀ K …)`, was lowered to `( FORALL K …)`, so the text drifted by a space on every round trip.
## Known limits
- The engines are the course's modules as they stand, including the issues in the toolchain review (no engine tests of their own, two unsound verifier rules, English lowered through text). Fixes belong in the engines, upstream; this app will pick them up by re-vendoring. The vendored copy carries a few small changes, each listed in [engines.md](engines.md): the four text built-ins `SPLIT`, `JOIN`, `INDEX_OF`, `REPLACE` (lang, check, interp, translate, vcgen), the numerical built-ins and `PARALLEL FOR` with its race detector (lang, parse, check, interp, translate, vcgen), an indexed read `L[I]` recorded as a read of one position rather than of the whole of `L` (interp), and a single `reserved-name` error for a keyword used as a name (parse); and three earlier ones: `english.js` exports `COMPARISONS` and `IN_PHRASES` so the reference can read them; `analyze.js` tags a variable passed to a `BYREF` parameter and `coach.js` no longer reports it as "read before set" when the procedure writes the parameter before reading it (an out-parameter); and `coach.js` no longer warns "growing bound" on a `WHILE LENGTH(Q) > 0` whose body also `REMOVE`s from `Q` (a queue).
- The assembly pane takes the course's Intel-syntax subset; directives and `[rip + label]` are not supported yet.
"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 (`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 | 97 |
| of which outside the model's set | 38 | 5 (all 256-bit AVX2: `vextracti128`, `vinserti128`, `vpblendvb`, `vperm2i128`, `vpalignr`) |
| the user's own functions that assemble | 3 of 7 (`main` never did) | 7 of 7 |
| standard-library and runtime functions that assemble | — | 438 of 467 |
`main()` now steps 25–29 instructions and stops at the call into `print` 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 optimiser 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 modelled)
- 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
**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 modelled.
-`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 five instructions above exist only in that width. A `ymm` operand is refused with that sentence. Modelling 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. Seven goldens carry listings today (the `asm`/`both` probes); `pixi run mojo-verify` with `mode: asm` probes adds more, and each addition either assembles or fails `tests/asm-coverage.test.mjs` with the instruction named. The ratchet numbers in that test are the ones in the table above; raise them when the machine learns more, never lower them.
`pixi run site` tests the app and assembles `site/`; `pixi run deploy [slug] [user@host]` does that and publishes it. CI (`.gitea/workflows/deploy.yml`) does the same on every push to `main`.
The site is five things: `index.html`, `styles.css`, `styles/` (the course's widget styles, which the Hardware area's machine views use), `dist/`, and the Quarto extension (`quarto/_extensions/pplus`, without an engine copy), which the With Quarto page loads (`pplus.css`, `pplus.js`) and links to file by file. `scripts/assemble.sh` copies them into `site/` with a `VERSION` file holding the commit, and `scripts/deploy.sh <slug> [user@host]` publishes `site/` to `/srv/www/<slug>` as an atomic release:
```
/srv/www/pplus -> symlink to the live release
/srv/www/pplus.releases/ one directory per deployed commit, the five newest kept
```
The swap is one rename, so nobody sees a half-copied site, and a rollback is `ln -sfn /srv/www/pplus.releases/<sha> /srv/www/pplus`. A pre-existing plain directory at `/srv/www/<slug>` is moved to `<slug>.releases/before-releases` on the first run.
**Caddy**: [`Caddyfile`](Caddyfile) is the site block (root on the symlink, `file_server`, `no-cache` on the modules so a new deploy is picked up on the next load, 404s rewritten to the app, and `frame-ancestors` so course pages can embed views). The live shortcodes and `live="click"` put the app in an iframe, so a Quarto site on another origin needs that origin added to `frame-ancestors`; the rendered views need nothing from the host. Caddy issues the certificate itself; add the block to `/etc/caddy/Caddyfile` and `systemctl reload caddy`.
**Gitea Actions without a container image** (`.gitea/workflows/deploy.yml`): the act_runner on the droplet runs jobs on the host shell instead of in docker. Once, on the droplet:
```bash
# tools the job uses
apt install -y git rsync curl
curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && apt install -y nodejs # or any node >= 20
# a user for the runner that owns the web root
useradd -m -s /bin/bash deploy
mkdir -p /srv/www && chown deploy:deploy /srv/www
# register the runner with a host-mode label (the :host suffix is the whole trick)
# run it as a service (act_runner generate-config > config.yaml; systemd unit per the Gitea docs, User=deploy)
```
With that label, `runs-on: quarto-deploy` executes steps directly as `deploy`, with the host's node, git, and rsync; `actions/checkout` works because node is on the host, and no image is pulled. The job builds, runs the tests, checks that our Mojo programs pass (`corpus.py status --strict`, offline), assembles `site/`, and on `main` runs `scripts/deploy.sh` into `/srv/www`. `SITE_SLUG` (repository variable) names the directory and defaults to the repository name; set it to `pplus`. `SITE_URL` turns on a smoke test that fetches `/VERSION` from the live site and fails the job if it is not the deployed commit.
If the runner ever moves off the droplet, `scripts/deploy.sh pplus deploy@droplet` rsyncs over SSH instead; give that runner a key whose public half is in `deploy`'s `authorized_keys`.
By hand, on the droplet: `pixi run deploy pplus`. From elsewhere: `pixi run deploy pplus deploy@droplet`.
Programming+ runs the course site's own language engines and draws the hardware views with the course's own stylesheets, so a program behaves the same in the app as on a course page.
| Here | From the course repository | What it is |
|---|---|---|
| `src/engines/pseudo/` | `static/js/pseudo/` | The pseudo language: parser, checker, interpreter, the English (lingo) reader, the prover's verification conditions, 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/core/types.ts`, adapters in `src/services/`). Modules the app does not use are excluded from the build in `tsconfig.json`. Do not edit `src/engines/` casually: a change there is a change to the course's language.
## How the copies differ from the course
`pixi run engines-diff <course>/static` compares every file, ignoring whitespace. As of the last check the stylesheets are identical; most engine modules differ only in formatting (they were reindented); and fourteen differ in content, every one of them a change made here and not yet sent back:
- **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; and `coach.js` no longer warning "growing bound" on a queue drained by `WHILE LENGTH(Q) > 0`.
- **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. If the course takes the form into its parser, this module can go.
Deciding what happens to these (send them to the course, or make this repository the engines' home and have the course copy from here) is open; until then, `engines-diff` is how to see the gap.
## Updating from the course
1.`pixi run engines-diff <course>/static` and read the list.
2. For a file that differs only in whitespace, or that changed only on the course side, copy the course's file over the one here.
3. For a file that differs in content on both sides, merge by hand, keeping the changes listed above.
4.`pixi run test`. The engines have no tests of their own in the course repository; the tests here (`tests/services.test.mjs`, `tests/corpus.test.mjs`, the curriculum and reference tests, `tests/asm-coverage.test.mjs`) are what catch a regression.
5. For the stylesheets, follow [styles/course/README.md](../styles/course/README.md).
An exercise 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 # 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 `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.1.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 `blank`, the demo 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 `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.
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.
## 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 | `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 | `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 | `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 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
# 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.
### 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` 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 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.
## Reading the status
`pixi run mojo-status` judges every item from the stored answers, offline, and writes `mojo/golden/STATUS.md` (a table per corpus, every failure with its reason, and every probe's question and verdict) and `status.json` (`git 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 |
|---|---|---|
| `mojo/pin.json` | The Mojo version, the godbolt compiler id, each source repository and the ref to use, and the dialect markers | You |
| `mojo/mojo.lock.json` | What each ref resolved to: commit, zip sha256, and the directory inside the zip | `fetch`/`harvest` |
| `mojo/corpus/` | Processed material, one directory per processor, each item with its provenance | `harvest` |
| `mojo/corpus/SOURCES.md` | Which commit and license everything came from, what each processor found, every warning | `harvest` |
| `mojo/probes/` | Our questions about the pinned compiler's behavior, one small program each | You (`new-probe`) |
| `mojo/local/` | Exercise programs, shipped in the app | You (`new-exercise`) |
| `mojo/stress/` | Realistic programs that test the interpreter, not shipped | You (`new-stress`) |
| `mojo/golden/<key>.json` | Godbolt's answer for one program, keyed by compiler, mode, arguments, stdin and source | `verify` |
| `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), `tokens.ts` (the words, removed words and the compiler's messages for them), `editor.ts` (comment and indentation rules), `programs.ts` (`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` |
| `quarto/_extensions/pplus/syntax/mojo.xml` | The same words as a KDE syntax for Pandoc listings | `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 |
| `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`.
2. Edit `mojo/pin.json`: `mojo.version`, `godbolt.compiler`, and `sources.modular.ref`. 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.)
4. `pixi run mojo-harvest`, then read `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.
5. `pixi run mojo-verify`. A new compiler id changes every key, so every item is asked again: about 440 requests, two at a time. Run it once, not in a loop; the public server is shared.
6. `pixi run mojo-status`, then read `mojo/golden/STATUS.md`. `git 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.
7. `pixi run test`, then commit the pin, the lock, the corpus, the goldens, and `src/mojo/generated/` together.
## Licenses and provenance
Every item records its repository, commit (or local zip hash), path, and license; `SOURCES.md` summarizes them. Modular's repository files carry Apache-2.0 WITH LLVM-exception headers. Mojo Quest's files carry the same headers, but the repository has no LICENSE file, 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. |
<!-- 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 `tests/corpus/` (48), and 17 one-construct fixtures (`tests/helpers/sync-programs.mjs`). 3 of the 82 have pseudo that does not read, by design (they teach the notation's error messages), and are left out below. That leaves **79 programs**.
| From pseudo to | Says it completely | Says it with a gap or a checker error | Cannot say it |
| --- | ---: | ---: | ---: |
| Mojo | 77 | 2 | 0 |
| lingo | 31 | 0 | 48 |
| matho | 3 | 0 | 76 |
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`.
Nothing.
## 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) | 46 | 01-arithmetic.pseudo, 02-temperature.pseudo, 03-compound-interest.pseudo, 04-gcd-recursion.pseudo, and 42 more |
| 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) | 42 | 01-arithmetic.pseudo, 02-temperature.pseudo, 03-compound-interest.pseudo, 04-gcd-recursion.pseudo, and 38 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 | |
Reference in new issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.