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
This commit is contained in:
alexmandClaude committed 2026-10-05 05:43:58 +00:00
1 parent 961a59054d
commit c5157fcad5
56 files changed
+3386 -66

No files matched your search

+3 -4
View File
@@ -1,15 +1,14 @@
# The engines
Programming+ runs the language engines that the course site also runs, and draws the hardware views with the course's stylesheets, so a program behaves the same in the app as on a course page. **This repository owns the engines.** Changes are made and tested here, and the course copies them from here (`pixi run engines-export`). The engines started as a copy of the course's modules; the course no longer sends changes the other way.
Programming+ runs the language engines that the course site also runs, so a program behaves the same in the app as on a course page. The course's widget stylesheets live in pplus-web (`styles/course/`), which compares them with the course's. **This repository owns the engines.** Changes are made and tested here, and the course copies them from here (`pixi run engines-export`). The engines started as a copy of the course's modules; the course no longer sends changes the other way.
| Here | The course receives it as | What it is |
|---|---|---|
| `src/engines/pseudo/` | `static/js/pseudo/` | The pseudo language: parser, checker, interpreter, the English (lingo) reader, the prover (`logic.ts`, `solver.ts`, `vcgen.ts`), translation |
| `src/engines/asm86/` | `static/js/asm86/` | The x86-64 model machine, its caches, pipeline and out-of-order core, and the widgets that draw them |
| `src/engines/shared/` | `static/js/shared/` | DOM helpers, URL state, text distance, charts |
| `styles/course/` | `static/css/base/`, `static/css/widgets/` | The widget stylesheets ([styles/course/README.md](../styles/course/README.md)) |
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`. A change in `src/engines/` is a change to the course's language, so it needs a test here and goes to the course by export.
The engines are wrapped behind one `LanguageService` interface (`src/common/types.ts`, adapters in `src/services/`). The course's page widgets (the pseudo views, the asm86 `views`/`hwviews`, the shared DOM helpers) sit beside the engines so the course and pplus-web take them from one place; the pseudo ones and a few others are excluded from core's build in `tsconfig.json`, and `tests/boundary.test.mjs` keeps core's library modules from importing any of them. A change in `src/engines/` is a change to the course's language, so it needs a test here and goes to the course by export.
## The prover
@@ -54,6 +53,6 @@ One addition to the pseudo language lives outside the engine, in app code: `DECL
1. `pixi run engines-diff <course>/static` shows what the course has not taken yet: for each module, the file the course would receive (`src/engines/` as written, `dist/engines/` for a TypeScript module) against the course's copy, whitespace ignored, and the files only one side has.
2. `pixi run engines-export <course>/static` builds and writes those files into the course's `static/js/`. A TypeScript module arrives as plain ES-module JavaScript, so the course's pages import it unchanged. Source maps are not copied.
3. In the course repository, review the diff and run its pages before committing.
4. For the stylesheets, follow [styles/course/README.md](../styles/course/README.md); they are still identical on both sides.
4. The course's stylesheets are pplus-web's to compare (`styles/course/README.md` there).
A change someone makes in the course's copy is not picked up from there. Bring it here as a change with a test, then export.
+1 -1
View File
@@ -81,7 +81,7 @@ The dialect markers in the pin are a cheap first look: `newer` patterns are synt
| `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` |
| `syntax/mojo.xml` | The same words as a KDE syntax for Pandoc listings (pplus-web copies it into its Quarto extension with its quarto-css task) | `harvest`/`emit` |
Commit all of it. The stored answers are what make `pixi run test` and `mojo-status` work offline.
+4 -2
View File
@@ -1,12 +1,14 @@
# What each badge and verdict means
pplus-web shows the badges; the verdicts behind them come from pplus-core (the prover, the fuzzer, the translators, the compiler's stored and live answers, the model machine). This page is kept here, beside what produces them.
Programming+ is built for checking work that someone or something else produced, so every claim it shows names what answered it, and none claims more than that. This page lists each one: who earns it, what it means, and what it does not mean. When a new badge or verdict is added, it gets a row here in the same commit.
## Where code came from
| Shown | Earned by | Means | Does not mean |
|---|---|---|---|
| **Generated from pseudo** | The Bridge's Mojo tab, always (`mojoProvenance` in `src/core/provenance.ts`); Mojo copied from it with **Edit in Developer** | The translator wrote this Mojo from the pseudo, literally, with a header comment saying so | That anyone has read it, or that it is the Mojo a person would write |
| **Generated from pseudo** | The Bridge's Mojo tab, always (`mojoProvenance` in pplus-web's `src/core/provenance.ts`); Mojo copied from it with **Edit in Developer** | The translator wrote this Mojo from the pseudo, literally, with a header comment saying so | That anyone has read it, or that it is the Mojo a person would write |
| **Started from generated Mojo** | Generated Mojo edited in the Developer area (`mojoOrigin: 'generated-edited'`) | A person has changed generated Mojo | That the person reviewed the parts they did not change |
| (badge cleared) | **I've reviewed this**, in the Developer area only | The person says they reviewed it; the header comment goes too | That anything checked the review. Compiling and editing never clear the badge |
@@ -36,7 +38,7 @@ The Prove tab reports every obligation in three statuses (`src/engines/pseudo/vc
| Shown | Earned by | Means | Does not mean |
|---|---|---|---|
| A routine's cases in the Tests tab | The fuzzer (`src/core/fuzz.ts`), with the seed and input count shown | Every input listed was run and checked against each claim and limit | That untried inputs pass. "Held on 300 inputs" is evidence, not proof |
| A routine's cases in the Tests tab | The fuzzer (`src/common/fuzz.ts`), with the seed and input count shown | Every input listed was run and checked against each claim and limit | That untried inputs pass. "Held on 300 inputs" is evidence, not proof |
| A failure's smallest input | Shrinking in the fuzzer | The smallest input it found that fails the same way | The only failing input |
## What a translation says