Files
pplus-web/core
alexmandClaude 82e18f7966 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
..

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.

Quick start

With pixi (it brings the pinned Mojo, Node and Python):

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):

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)
engines-diff <static> Show what a course checkout has not taken yet from the engines (docs/engines.md)
engines-export <static> Copy the engines into a course checkout, TypeScript modules as built (docs/engines.md)
Dafny, pinned (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)
new-probe <name> <question> Start mojo/probes/<name>.mojo: one question about the compiler (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)
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
Document For
AGENTS.md Rules for anyone changing core, coding agents included: the gate, what not to edit, conventions
docs/engines.md The engines, the prover and its soundness, and how the course takes them
docs/trust.md Every verdict core produces: which tool earns it, what it means, and what it does not mean
docs/mojo-corpus.md Writing Mojo of our own and moving to a new Mojo version
docs/exercises.md Adding a catalog problem
docs/sync-coverage.md What each translator can say, written by the tests
docs/asm-coverage.md Which instructions compiled Mojo uses, against what the machine models