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
This commit is contained in:
alexmandClaude committed 2026-10-05 05:43:58 +00:00
1 parent f43bbfe0cf
commit 82e18f7966
1567 files changed
+3670 -981

No files matched your search

+12 -64
View File
@@ -6,19 +6,19 @@ import test from 'node:test';
import assert from 'node:assert/strict';
import { themeBodyClass } from '../dist/ui/theme.js';
import { BOARD_PRESETS, BOARD_VIEWS, BOARD_GROUPS, MACHINE_PRESETS, boardPreset, boardView, boardFrame, subRegisterWidths, normalizeBoard, presetOf, moveItem, addItem, removeItem, toggleWide, isWide, courseViews, parseMachine, machineName, machineSpec, machineLabel, lineTouches, asmMojoLines, relateAsmMojo } from '../dist/core/hardware.js';
import { stageOccupancy, STAGES } from '../dist/engines/asm86/pipeline.js';
import { coreAt } from '../dist/engines/asm86/ooo.js';
import { decompose } from '../dist/engines/asm86/uops.js';
import { stageOccupancy, STAGES } from '../core/dist/engines/asm86/pipeline.js';
import { coreAt } from '../core/dist/engines/asm86/ooo.js';
import { decompose } from '../core/dist/engines/asm86/uops.js';
import fs from 'node:fs';
import { stripHeader, buildListing } from '../scripts/mojo/listings.mjs';
import { forSimulator, simulatorSetup } from '../dist/mojo/att.js';
import { listingFunctions } from '../dist/services/godbolt.js';
import { hardwareFor, resolveMachine } from '../dist/engines/asm86/machine.js';
import { viewNames } from '../dist/engines/asm86/views.js';
import { stripHeader, buildListing } from '../core/scripts/mojo/listings.mjs';
import { forSimulator, simulatorSetup } from '../core/dist/mojo/att.js';
import { listingFunctions } from '../core/dist/services/godbolt.js';
import { hardwareFor, resolveMachine } from '../core/dist/engines/asm86/machine.js';
import { viewNames } from '../core/dist/engines/asm86/views.js';
import { PROBLEMS, stateForProblem } from '../dist/core/catalog.js';
import { Session } from '../dist/core/session.js';
import { normalize, emptyState } from '../dist/core/state.js';
import { SERVICES } from '../dist/services/index.js';
import { SERVICES } from '../core/dist/services/index.js';
globalThis.localStorage = { getItem() { return null; }, setItem() { }, removeItem() { } };
@@ -132,38 +132,6 @@ test('the arrangement is part of the area\'s layout and normalizes', () => {
assert.deepEqual(s.layout().board, [{ id: 'counters' }]);
});
test('a machine is a preset with virtual memory on or off, and the run carries it to the hardware model', () => {
assert.deepEqual(MACHINE_PRESETS.slice(0, 2), ['teaching', 'realistic']);
for (const preset of MACHINE_PRESETS) for (const paging of [false, true]) {
const name = machineName({ preset, paging });
assert.deepEqual(parseMachine(name), { preset, paging }, name);
assert.equal(resolveMachine(machineSpec(name)).paging.enabled, paging, `${name}: paging`);
assert.match(machineLabel(name), new RegExp(`^${preset}`));
}
assert.deepEqual(parseMachine(undefined), { preset: 'teaching', paging: false });
assert.deepEqual(parseMachine('warp'), { preset: 'teaching', paging: false }, 'an unknown machine is the teaching one');
const p = PROBLEMS.find((x) => x.id === 'asm-two-pointers');
const { session, tr, raw } = traceOf(p, 'realistic+paging');
assert.equal(tr.raw.machine, 'realistic+paging');
const hw = hardwareFor(raw);
assert.equal(hw.config.caches.l1d.line, 64, 'the views see the realistic machine');
assert.ok(hw.config.paging.enabled, 'and its virtual memory');
assert.ok(hw.memory().steps.some((r) => r.translations.length), 'addresses are translated');
session.setMachine('teaching');
assert.notEqual(session.trace(), tr, 'a new machine is a new run');
assert.equal(hardwareFor(session.trace().raw.trace).config.paging.enabled, false);
});
test('the hardware model runs on every problem with assembly, on both machines, with and without virtual memory', () => {
for (const p of WITH_ASM) for (const machine of ['teaching', 'realistic', 'teaching+paging', 'realistic+paging']) {
const { raw, tr } = traceOf(p, machine);
const hw = hardwareFor(raw);
assert.doesNotThrow(() => { hw.memory(); hw.pipeline(); hw.core(); }, `${p.id} on ${machine}`);
const perf = tr.raw.hardware().perf();
assert.equal(perf.instructions, raw.stats.instructions, `${p.id} on ${machine}: the counters read the same run`);
for (const t of [0, 1, Math.floor(raw.count / 2), raw.count]) assert.ok(hw.memory().stateAt(t).h, `${p.id}: caches at step ${t}`);
}
});
test('each load and store shows the line it touched and how much of the line the program uses', () => {
let touched = 0, missed = 0, partial = 0;
@@ -211,26 +179,6 @@ test('virtual memory: the line is the physical one, and the access keeps the add
assert.ok(all.some(({ x }) => x.vaddr !== x.addr), 'and at least one is translated to another physical address');
});
test('time: the pipeline, micro-op, out-of-order and encoding data the Pipeline and Whole chip presets draw', () => {
for (const p of WITH_ASM) for (const machine of ['teaching', 'realistic']) {
const { raw } = traceOf(p, machine);
const hw = hardwareFor(raw);
const pipe = hw.pipeline();
const core = hw.core();
assert.equal(pipe.rows.length >= raw.count, true, `${p.id}: a pipeline row per instruction run (and any wrong-path fetches)`);
for (const r of pipe.rows.slice(0, 200)) {
for (const st of STAGES) assert.equal(stageOccupancy(pipe, r.E[st])[st] != null, true, `${p.id}: ${st} is occupied when a row enters it`);
}
for (let c = 0; c <= core.cycles; c += Math.max(1, Math.floor(core.cycles / 50))) {
const at = coreAt(core, c);
assert.ok(at.rob.length <= hw.config.core.rob, `${p.id} cycle ${c}: the reorder buffer never holds more than it has room for`);
}
for (const ins of raw.program.instrs) { const u = decompose(ins); assert.ok(Array.isArray(u) && u.length >= 1, `${p.id}: ${ins.text} splits into micro-ops`); }
// the encoding view and the listing's bytes need the program laid out in memory
if (raw.layout?.ok) for (const ins of raw.program.instrs) assert.ok(raw.layout.len[ins.index] >= 1 && raw.layout.len[ins.index] <= 15, `${p.id}: ${ins.text} is 1 to 15 bytes`);
}
assert.ok(WITH_ASM.some((p) => traceOf(p).raw.layout?.ok), 'the problems encode');
});
test('Mojo beside x86-64: the line table the compiler left in the pane links each instruction to its Mojo line', () => {
const asm = 'add: ; add(Int, Int)\n mov rax, rdi ; mojo line 2\n add rax, rsi ; mojo line 2\n ret\n call add ; mojo line 6';
@@ -243,10 +191,10 @@ test('Mojo beside x86-64: the line table the compiler left in the pane links eac
// a real listing, as Open in Hardware makes it from godbolt's saved answer
const ROOT = new URL('..', import.meta.url).pathname;
let checked = 0;
for (const f of fs.readdirSync(ROOT + 'mojo/probes').filter((x) => x.endsWith('.mojo'))) {
const text = fs.readFileSync(ROOT + 'mojo/probes/' + f, 'utf8');
for (const f of fs.readdirSync(ROOT + 'core/mojo/probes').filter((x) => x.endsWith('.mojo'))) {
const text = fs.readFileSync(ROOT + 'core/mojo/probes/' + f, 'utf8');
if (!/^# mode: (asm|both)/m.test(text)) continue;
const r = buildListing(text, ROOT + 'mojo/golden', { forSimulator, simulatorSetup, listingFunctions });
const r = buildListing(text, ROOT + 'core/mojo/golden', { forSimulator, simulatorSetup, listingFunctions });
if (r.why) continue;
const table = asmMojoLines(r.asm);
if (!table.size) continue;