Files
pplus-web/core/AGENTS.md
T
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

7.0 KiB

AGENTS.md

Instructions for coding agents (and people) changing pplus-core. Read this first, then the README for what core is and where things are. When this file and a task's instructions disagree, the task wins; say so in your summary.

Build, test, and the gate

pixi run test     # build, then every test (node --test against dist/, the pipelines' Python tests included)
pixi run ci       # the gate: every test, and no Mojo program of ours failing

Without pixi (a sandbox with only Node and Python):

npx tsc -p tsconfig.json && node --test tests/*.test.mjs
python3 scripts/mojo/corpus.py status --strict

Finish every change with the gate green. The baseline passes completely; there is no known failure to work around. If a test fails, fix the cause or stop and report it. Do not skip, loosen, or delete a test to get green.

The full suite takes about two minutes. While iterating, build and run one file: npx tsc -p tsconfig.json && node --test tests/sync-hub.test.mjs.

Hard rules

  1. Core has no DOM. What a program means is decided without a browser. A library module never touches document, window, localStorage or navigator, never imports one of the course's page widgets, and never imports from outside src/; tests/boundary.test.mjs holds it to that. The widgets (listed in that test) live beside the engines only so the course and pplus-web take them from one place.
  2. Do not edit generated files by hand. src/mojo/generated/* and syntax/mojo.xml come from the corpus pipeline (pixi run mojo-emit, mojo-status, play). mojo/corpus/ comes from mojo-harvest. mojo/golden/ holds godbolt's answers and comes only from mojo-verify.
  3. Do not edit a .mojo file's text unless the task needs it. A stored godbolt answer is keyed by the whole source, header comments included, so any edit (even to a comment) makes the program unverified until it is asked again on the network. If you add or change one, say in your summary that it needs pixi run mojo-verify-item '<corpus>/<name>'.
  4. 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 core must pass checkMojo, and every standard-library name must exist in src/mojo/generated/stdlib.ts or types.ts.
  5. Never let the prover call something proved that a run breaks. "Proved" 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).
  6. No new dependencies. TypeScript is the only npm package; there is no runtime dependency. The pipelines (the Mojo corpus, the Dafny pin) are Python's standard library only. Tools that are not npm packages are pinned: Mojo, Node and Python by pixi, Dafny by scripts/dafny.py (a version and a SHA-256 per platform).
  7. You have no network in most sandboxes. Godbolt (mojo-verify), GitHub (mojo-harvest, mojo-fetch, dafny-fetch) need one. Never fake their results; leave those steps to the owner and list them.
  8. Core's exports are pplus-web's API. pplus-web imports core's built modules as #core/<path> and builds against the declarations in dist/. Renaming or removing an export, or changing what a function returns, breaks the site; when you do it, say so in the summary so web is updated in the same release.

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, test (what CI uses).
  • Docs. The README is the front door: keep it short. Put the engines, the prover and its soundness in docs/engines.md, verdicts in docs/trust.md, exercises in docs/exercises.md, and Mojo of our own and the pipeline in docs/mojo-corpus.md. Update the document a change belongs in, in the same commit.
  • Tests run against dist/ with no DOM. A test that needs a piece of work uses a Workspace (src/common/workspace.ts) with workForProblem (src/common/problems.ts), not pplus-web's session.
  • TypeScript. Strict mode, ES modules, imports with the .js suffix (from './workspace.js'). Indent like the file you are editing (some files use two spaces, some four). A JavaScript module's exported function gets JSDoc for its optional parameters, so the declaration pplus-web builds against says so.
  • Stable ids. Diagnostic ids (matho-refused, reserved-name, ...) and obligation kinds (index, argument, ...) are asserted by tests and shown by pplus-web. Change one only on purpose, and update every test and link that names it.
  • Writing. User-facing copy is US English (color, behavior, optimized, labeled). Plain sentences; say what a thing does, not how good it is.

Adding things

To add Do
A catalog problem pixi run new-exercise <id> for one built around a Mojo program, or copy src/exercises/_template.ts (docs/exercises.md)
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/common/types.ts) in src/services/, registered in src/services/index.ts

Delivering work

  • One logical change per commit, with a message that says what changed and why: the problem first, then what each part of the change does.
  • When the owner asks for patches, export them with git format-patch -o patches/ <base> (the patches/ folder is ignored by git) and do not paste whole files into chat.
  • End with a summary: what you changed, the gate's result, anything you could not verify (network steps), anything that changes core's exports, and anything you noticed but left alone.