Make this repository the engines' home; the course copies from here

Whether the engines' changes went back to the course or the course took
them from here was an open question (docs/engines.md). Soundness fixes to
the prover cannot wait for a round trip through a repository with no engine
tests, so this repository now owns the engines.

- pixi run engines-export <course>/static builds and writes every engine
  module into the course's static/js/: JavaScript modules as written,
  TypeScript ones (logic, solver, vcgen) as built, without source maps.
- pixi run engines-diff now shows what the course has not taken yet,
  comparing the file the course would receive with its copy. Both scripts
  share the list of modules in scripts/engines-files.mjs.
- docs/engines.md describes the ownership, the prover's three modules and
  its number model, the soundness tests and the bugs found so far, the
  changes the course receives with the next export, and how to export.
- AGENTS.md gains a hard rule: never let the prover call something proved
  that a run breaks, with how to add a soundness regression first.
- docs/app.md's Known limits no longer sends engine fixes upstream.

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 03:33:58 +00:00
1 parent 2416d7fc8e
commit 0d313f989d
8 files changed
+151 -42

No files matched your search

+4 -2
View File
@@ -27,12 +27,13 @@ The full suite takes about two minutes. While iterating, build and run one file:
3. **Never claim Mojo compiles, runs, or prints something without the real compiler's answer.** Mojo is pinned to 1.1.0. The checker may never report an error on a program the compiler accepts, and the interpreter must print exactly what godbolt printed or decline; `tests/mojo-check.test.mjs` and `tests/mojo-run.test.mjs` hold them to that. Every Mojo construct you write into the app must pass `checkMojo`, and every standard-library name must exist in `src/mojo/generated/stdlib.ts` or `types.ts`.
4. **No new dependencies.** TypeScript is the only npm package. There is no bundler, no framework, and no runtime dependency; the corpus pipeline is Python's standard library only. CodeMirror is vendored as one built module (`src/vendor/`), rebuilt only by `scripts/vendor/codemirror.sh`.
5. **You have no network** in most sandboxes. Godbolt (`mojo-verify`, Compile & run) and GitHub (`mojo-harvest`, `mojo-fetch`) need one. Never fake their results; leave those steps to the owner and list them.
6. **Keep the workspace working while you change it.** Code panes are always the CodeMirror editor (`Editor` in `src/ui/editor.ts`, over the vendored `src/vendor/codemirror.js`), never a `<textarea>`; `tests/editor.test.mjs` checks it. Keep the workspace's parts as they are unless the task changes them: the pane tabs over one editor, the stepper docked under the editor, the side column (the inspect panel, whose first tab is the Run view), and the dock; in the Hardware area, the code on the left and the arrangeable board on the right. Restyle or rearrange them only when asked, and after any UI change open the app (`pixi run dev`) and check that the editor has line numbers and highlighting, the stepper steps, and the styles loaded.
6. **Never let the prover call something proved that a run breaks.** "Proved" in the app must be a proof. A change to `src/engines/pseudo/logic.ts`, `solver.ts` or `vcgen.ts` keeps `tests/prover-soundness.test.mjs` and `tests/engine-solver.test.mjs` green, and a fact the prover assumes must hold for every value a run can produce, or be guarded by an obligation. When you find a soundness bug, add the program that shows it to `tests/prover/` with a `// MUST-NOT-PROVE:` (or `// RUN-STOPS:`) header first, see the test fail, then fix the rule ([docs/engines.md](docs/engines.md#soundness)).
7. **Keep the workspace working while you change it.** Code panes are always the CodeMirror editor (`Editor` in `src/ui/editor.ts`, over the vendored `src/vendor/codemirror.js`), never a `<textarea>`; `tests/editor.test.mjs` checks it. Keep the workspace's parts as they are unless the task changes them: the pane tabs over one editor, the stepper docked under the editor, the side column (the inspect panel, whose first tab is the Run view), and the dock; in the Hardware area, the code on the left and the arrangeable board on the right. Restyle or rearrange them only when asked, and after any UI change open the app (`pixi run dev`) and check that the editor has line numbers and highlighting, the stepper steps, and the styles loaded.
## Conventions
- **Commands are pixi tasks.** Name them as `pixi run <task>` in docs, comments, and messages. A new command is a task in `pixi.toml` with a `description` and a row in the README's Commands table; `tests/tasks.test.mjs` fails otherwise, and also fails on any `pixi run <name>` that names no task. `package.json` keeps only `build`, `watch`, `check`, `dev`, `test` (what CI uses).
- **Docs.** The README is the front door: keep it short. Put behavior in [docs/app.md](docs/app.md), exercises in [docs/exercises.md](docs/exercises.md), Mojo of our own and the pipeline in [docs/mojo-corpus.md](docs/mojo-corpus.md), the engines in [docs/engines.md](docs/engines.md), deployment in [docs/deploy.md](docs/deploy.md), and the Quarto extension in [quarto/README.md](quarto/README.md). Update the document a change belongs in, in the same commit.
- **Docs.** The README is the front door: keep it short. Put behavior in [docs/app.md](docs/app.md), exercises in [docs/exercises.md](docs/exercises.md), Mojo of our own and the pipeline in [docs/mojo-corpus.md](docs/mojo-corpus.md), the engines and the prover's soundness in [docs/engines.md](docs/engines.md), deployment in [docs/deploy.md](docs/deploy.md), and the Quarto extension in [quarto/README.md](quarto/README.md). Update the document a change belongs in, in the same commit.
- **Tests run against `dist/` with no DOM.** Put logic in DOM-free modules (`src/core/`, `src/services/`, `src/mojo/`, `src/quarto/`) and test it there. The views in `src/ui/views/` also run outside a browser, under the small document of `src/quarto/dom.ts`, when the Quarto extension renders them: a view may use the selectors that document knows (compound selectors and the descendant combinator) and must not need layout to produce its markup. When a test needs `localStorage`, install a fake on `globalThis` and remove it in `finally`, as `tests/state.test.mjs` does. For a UI change, write a short manual check list in the commit message.
- **TypeScript.** Strict mode, ES modules, imports with the `.js` suffix (`from './state.js'`). Indent like the file you are editing (some files use two spaces, some four).
- **Stable ids.** Diagnostic ids (`matho-refused`, `reserved-name`, ...) and reference section ids are asserted by tests and linked from guides. Change one only on purpose, and update every test and link that names it.
@@ -47,6 +48,7 @@ The full suite takes about two minutes. While iterating, build and run one file:
| A question about the compiler | `pixi run new-probe <name> "<question>"` |
| Realistic Mojo for the interpreter | `pixi run new-stress <name> "<what it exercises>"`, with the output you predict in `# expect-stdout:` lines |
| A pseudo regression program | a file in `tests/corpus/` whose `// EXPECT:` lines are the output it must print |
| A prover soundness regression | a file in `tests/prover/` whose `// MUST-NOT-PROVE: <kind>@<line>` names an obligation a run breaks, or `// RUN-STOPS: <kind>@<line>` where a run must stop |
| A command | a task in `pixi.toml` and a row in the README's Commands table |
| A language | a `LanguageService` (`src/core/types.ts`) in `src/services/`, registered in `src/services/index.ts` |
| A Quarto shortcode | a function in the table `quarto/_extensions/pplus/pplus.lua` returns, a row in `SHORTCODES` (`src/quarto/shortcodes.ts`) and in `scripts/check-pages.mjs`, a sample in the gallery (`src/ui/quarto.ts`) and a use in `quarto/example/`; a rendered view is a case of `renderStatic` (`src/quarto/render.ts`); a view of the machine is a name in `HW_NAMES` (`src/quarto/machine.ts`), `HW_VIEWS` in `pplus.lua` and `HW_VIEWS` in `scripts/check-pages.mjs` |