Files
pplus-core/README.md
T
alexmandClaude c5157fcad5 Move the engine core into core/, a project of its own (pplus-core)
What programs mean (the languages, translators, Mojo checker and
interpreter, prover, fuzzer, machine model, catalog problems and the Mojo
corpus with godbolt's stored answers) was mixed into the site's tree, so a
change to the prover and a change to a button went through the same gate
and the same docs. This moves all of it under core/, laid out as its own
repository, ready to be extracted with its history and pinned here as a
git submodule.

- core/: src/{engines,services,sync,mojo,exercises,curriculum,common},
  mojo/, syntax/mojo.xml, its tests (with Workspace and workForProblem in
  place of the site's Session), scripts (corpus pipeline, play, the
  exercise and probe starters, engines export/diff), and its docs
  (engines, trust, mojo-corpus, exercises, coverage). Its own pixi.toml,
  package.json, README, AGENTS.md and CI workflow.
- core/tests/boundary.test.mjs: library modules use no DOM, import no
  page widget, and import nothing outside src/.
- core/scripts/cli.mjs: pixi run cli check|run|prove|fuzz|translate.
- core/scripts/dafny.py: Dafny 4.11.0 pinned by version and SHA-256 per
  platform, fetched into .tools/ (pixi run dafny-fetch, pixi run dafny).
- The site imports core only as #core/<path>.js: an import map in
  index.html, "imports" in package.json for node, core's declarations for
  tsc. The site's TypeScript builds core first (npm run build).
- assemble.sh, the Quarto engine copy, the render cache key, check-pages,
  quarto-export and quarto-css read core/dist and core/mojo; quarto-css
  copies core's syntax/mojo.xml into the extension.
- Site tests that covered engines moved to core; the rest keep Session.
- README, AGENTS.md, docs/app.md, docs/deploy.md and the CI workflow
  describe the split (checkout with submodules; core's tests and corpus
  status run against the pinned commit).

Gate: site 110 pass; core 307 pass; corpus status --strict passes.
Manual check: the assembled site opens Bridge (count-base-proved),
Developer and Hardware (count-base) with the editor, the stepper and the
board, and no module errors.

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

109 lines
7.5 KiB
Markdown

# pplus-core
pplus-core is the part of Programming+ that has to be right: the languages, the translators between them, the Mojo checker and interpreter, the prover, the fuzzer, the x86-64 machine model, and the stored answers of the real tools that everything it says rests on. It has no DOM. pplus-web (the site, the editor, the views and the Quarto extension) and the course site use it as a pinned dependency.
- **Languages:** pseudo (parser, checker, interpreter, the English reader for lingo), matho (equations in LaTeX), speco (specifications), Mojo (a checker and an interpreter held to the real compiler), x86-64 on a model machine with caches, a pipeline and an out-of-order core.
- **Translators:** pseudo to Mojo, lingo, matho and speco, with line maps and located refusals, and the hub that keeps the linked languages in step (`src/sync/`).
- **Verification:** the prover (`src/engines/pseudo/logic.ts`, `solver.ts`, `vcgen.ts`), sound and held to it by tests; the fuzzer (`src/common/fuzz.ts`); and a pinned Dafny (`scripts/dafny.py`).
- **Stored answers:** the Mojo corpus (`mojo/`): material harvested from Modular's repositories at pinned commits, our own probes and programs, and godbolt's answers for every one of them (`mojo/golden/`).
- **A workspace:** `src/common/workspace.ts` is one piece of work and everything its sources mean. pplus-web's session extends it.
- **A command line:** `pixi run cli check|run|prove|fuzz|translate <file>`.
Everything it says about Mojo is pinned to **Mojo 1.1.0** and checked against the real compiler on [Compiler Explorer](https://godbolt.org).
## Quick start
With [pixi](https://pixi.sh) (it brings the pinned Mojo, Node and Python):
```bash
pixi run test # build, then every test
pixi run ci # the gate: every test, and no Mojo program of ours failing
pixi run cli prove tests/corpus/27-quantifiers.pseudo
pixi run dafny-fetch # once: the pinned Dafny, into .tools/
```
Without pixi, with Node 20 or later (and `python3` for the pipelines' tests):
```bash
npm install && npm test
```
## Commands
Every command is a pixi task (`pixi task list` shows them with their descriptions). `tests/tasks.test.mjs` fails if this table and `pixi.toml` disagree.
| Task | What it does |
|---|---|
| **Build and test** | |
| `install` | Install TypeScript, the only npm dependency |
| `build` | Compile `src/` to `dist/`, with type declarations for pplus-web |
| `watch` | Rebuild `dist/` on every change |
| `check` | Type-check only |
| `test` | Build, then run every test, the pipelines' Python tests included |
| `cli` | `pplus check\|run\|prove\|fuzz\|translate <file>`: core without a browser ([scripts/cli.mjs](scripts/cli.mjs)) |
| `engines-diff <static>` | Show what a course checkout has not taken yet from the engines ([docs/engines.md](docs/engines.md)) |
| `engines-export <static>` | Copy the engines into a course checkout, TypeScript modules as built ([docs/engines.md](docs/engines.md)) |
| **Dafny, pinned** ([scripts/dafny.py](scripts/dafny.py)) | |
| `dafny-fetch` | Download the pinned Dafny into `.tools/`, checked by SHA-256 (network, once) |
| `dafny` | Run the pinned Dafny with the arguments given, e.g. `pixi run dafny verify file.dfy` |
| **Write content** | |
| `new-exercise <id>` | Start an exercise whose Mojo lives in `mojo/local/<id>.mojo` ([docs/exercises.md](docs/exercises.md)) |
| `new-probe <name> <question>` | Start `mojo/probes/<name>.mojo`: one question about the compiler ([docs/mojo-corpus.md](docs/mojo-corpus.md)) |
| `new-stress <name> <about>` | Start `mojo/stress/<name>.mojo`: realistic Mojo that tests the interpreter |
| `play <name>` | For `mojo/local/<name>.mojo`: run, verify on godbolt, build, list the assembly, test |
| `play-watch <name>` | The same, again on every save (tests off) |
| **The Mojo corpus** ([docs/mojo-corpus.md](docs/mojo-corpus.md)) | |
| `mojo-verify` | Ask godbolt about every program with no answer yet (network) |
| `mojo-verify-item <id>` | Ask again about one item, e.g. `'probes/life-*'` (network) |
| `mojo-verify-dry` | Show what `mojo-verify` would send; send nothing |
| `mojo-verify-diagnostics` | Also check the compiler's own diagnostic tests (opt-in; network) |
| `mojo-status` | Judge every item from the stored answers, offline; writes `mojo/golden/STATUS.md` |
| `mojo-status-strict` | The same, and fail if a program we wrote fails |
| `mojo-harvest` | After editing `mojo/pin.json`: fetch Modular's sources, process, regenerate (network) |
| `mojo-harvest-local [dir]` | Harvest, with zips standing in for sources the pin leaves unresolved |
| `mojo-harvest-offline [dir]` | Harvest from zips only, no network |
| `mojo-fetch` | Re-resolve every ref in the pin and rewrite the lock (network) |
| `mojo-emit` | Regenerate `src/mojo/generated/` and `syntax/mojo.xml` from the pin and corpus, offline |
| `mojo-test` | The corpus pipeline's own tests |
| `mojo-run <file>` | Run one Mojo file on the pinned local compiler |
| `mojo-probes-local` | Run every probe on the local compiler (a quick look) |
| `mojo-update` | After editing the pin: harvest, verify, status, test |
| **Ship** | |
| `ci` | What CI runs: every test, and no program of ours failing |
| `package` | Zip what git tracks, and nothing it ignores, into `package/` for sharing |
## Where things are
```
AGENTS.md rules for changing core (read first)
src/
common/ the workspace, the problem catalog, the fuzzer, the run view's data, the language
reference, the machine presets, the shared types
engines/pseudo/ the pseudo language and the prover (logic, solver, vcgen in TypeScript), and the course's
page widgets for it (excluded from the build; see docs/engines.md)
engines/asm86/ the x86-64 model machine, and the course's widgets that draw it (views, hwviews)
engines/shared/ text helpers, and the course's DOM helpers
services/ one adapter per language behind LanguageService; the compiler request and backend
sync/ the translators and the hub that keeps the linked languages in step
mojo/ the Mojo checker, interpreter, lifetimes, practices, AT&T-to-Intel; generated/ from the corpus
exercises/ one file per catalog problem
curriculum/ a lesson corpus kept as an interpreter fixture
syntax/mojo.xml the Mojo words as a KDE syntax for Pandoc (generated; pplus-web copies it)
tests/ node --test against dist/; corpus/ (pseudo programs), prover/ (soundness regressions)
mojo/ the Mojo corpus: the pin and lock, harvested material, our programs, godbolt's answers
scripts/ the tasks above; scripts/mojo/ is the corpus pipeline; dafny.py the Dafny pin; cli.mjs
docs/ the documents below
```
## Read next
| Document | For |
|---|---|
| [AGENTS.md](AGENTS.md) | Rules for anyone changing core, coding agents included: the gate, what not to edit, conventions |
| [docs/engines.md](docs/engines.md) | The engines, the prover and its soundness, and how the course takes them |
| [docs/trust.md](docs/trust.md) | Every verdict core produces: which tool earns it, what it means, and what it does not mean |
| [docs/mojo-corpus.md](docs/mojo-corpus.md) | Writing Mojo of our own and moving to a new Mojo version |
| [docs/exercises.md](docs/exercises.md) | Adding a catalog problem |
| [docs/sync-coverage.md](docs/sync-coverage.md) | What each translator can say, written by the tests |
| [docs/asm-coverage.md](docs/asm-coverage.md) | Which instructions compiled Mojo uses, against what the machine models |