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

+1 -1
View File
@@ -218,6 +218,6 @@ These laws are tested in `tests/sync-speco.test.mjs`, for `count-base-proved`, `
## 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 engines live in this repository ([engines.md](engines.md)). The prover is sound and incomplete: it proves only what follows on every path it examined, and `tests/prover-soundness.test.mjs` holds it to that; English is still lowered to pseudo through text, and the parser, checker and interpreter are still JavaScript without tests of their own beyond the app's.
- The assembly pane takes the course's Intel-syntax subset; directives and `[rip + label]` are not supported yet.
- Student work persists in the browser only.