Files
pplus-core/AGENTS.md
T
alexm cae5cff55a
Test / test (push) Failing after 1m38s
feat: move corpus to library
2026-10-06 10:27:46 -04:00

7.8 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 library/syntax/mojo.xml come from the corpus pipeline (pixi run mojo-emit, mojo-status, play). src/library/generated.ts comes from library/ (pixi run library-emit), and the library's status.json, STATUS.md and golden/ from pixi run library-check and library-verify-mojo. library/mojo/corpus/ comes from mojo-harvest. library/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 library/pseudo/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.
  9. Data lives in pplus-library, code lives here. Programs, corpora, pins, fixtures and stored answers belong in library/ (its own AGENTS.md has its rules); scripts, engines and tests that read them stay in core. A change under library/ is committed and pushed in pplus-library first, then committed here with the new submodule pointer (git add library) and whatever core regenerated from it.

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 library/pseudo/programs/ whose // EXPECT: lines are the output it must print
A prover soundness regression a file in library/pseudo/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> (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.