Routines that many programs need (a mean, a gap penalty, the Lennard-Jones potential, the minimum image convention) were rewritten and re-verified each time, and there was no way to open one and see exactly what it does. They now live in pplus-library, pinned here as the submodule library/, and a program brings them in with USE. - USE module / USE module.Routine (pseudo-study resolveUses): each routine is studied once in its own file (its own USE lines resolved the same way, cycles refused) and handed to the checker as a library routine; unknown-library, unknown-routine, library-clash, use-place. - A run steps over a library routine (one step at the call, one at the return, none of its lines); a broken contract is reported at the call, naming the routine. The prover uses its REQUIRE and ENSURE at the call and does not prove it again; it is not a unit of the program. - pseudo-to-mojo writes each library routine the program calls once, dependencies first, labeled as coming from the library. - src/library: the registry USE reads, generated from library/ (scripts/library.mjs emit), so the site needs no files at run time. - scripts/library.mjs check: every routine at every level: structure, cases, prover, fuzzer, generated Mojo, each reference implementation (CPython; cc at -O0 and -O2; core's Mojo interpreter; the pinned compiler's stored answer) held to the pseudo's results, and the Dafny proof with the pinned Dafny. Writes library/status.json and STATUS.md. scripts/library_godbolt.py stores the compiler's answers (network). - pixi tasks library-check, library-emit, library-verify-mojo, library-harness; CI checks out the submodule and runs library-check. - Tests: tests/library.test.mjs, corpus 53-library; docs/library.md and a library section in trust.md. Gate: 332 pass; library-check: no failing check (16 routines; the Mojo references are unverified until library-verify-mojo runs on the network). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
7.3 KiB
7.3 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
- Core has no DOM. What a program means is decided without a browser. A library module never touches
document,window,localStorageornavigator, never imports one of the course's page widgets, and never imports from outsidesrc/;tests/boundary.test.mjsholds 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. - Do not edit generated files by hand.
src/mojo/generated/*andsyntax/mojo.xmlcome from the corpus pipeline (pixi run mojo-emit,mojo-status,play).src/library/generated.tscomes fromlibrary/(pixi run library-emit), and the library'sstatus.json,STATUS.mdandgolden/frompixi run library-checkandlibrary-verify-mojo.mojo/corpus/comes frommojo-harvest.mojo/golden/holds godbolt's answers and comes only frommojo-verify. - Do not edit a
.mojofile'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 needspixi run mojo-verify-item '<corpus>/<name>'. - 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.mjsandtests/mojo-run.test.mjshold them to that. Every Mojo construct you write into core must passcheckMojo, and every standard-library name must exist insrc/mojo/generated/stdlib.tsortypes.ts. - 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.tsorvcgen.tskeepstests/prover-soundness.test.mjsandtests/engine-solver.test.mjsgreen, 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 totests/prover/with a// MUST-NOT-PROVE:(or// RUN-STOPS:) header first, see the test fail, then fix the rule (docs/engines.md). - 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). - 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. - Core's exports are pplus-web's API. pplus-web imports core's built modules as
#core/<path>and builds against the declarations indist/. 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 inpixi.tomlwith adescriptionand a row in the README's Commands table;tests/tasks.test.mjsfails otherwise, and also fails on anypixi run <name>that names no task.package.jsonkeeps onlybuild,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 aWorkspace(src/common/workspace.ts) withworkForProblem(src/common/problems.ts), not pplus-web's session. - TypeScript. Strict mode, ES modules, imports with the
.jssuffix (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 verified routine others can USE | in pplus-library (library/), under its AGENTS.md; then pixi run library-check and library-emit here (docs/library.md) |
| 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>(thepatches/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.