Files
pplus-core/AGENTS.md
T
alexmandClaude 7ddc628597 Add USE and pin pplus-library: routines verified once, used by name
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
2026-10-05 12:06:41 +00:00

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

  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). 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. 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 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.