Core: a small JS advisor reads the game from policy.json; engine.js is gone (#13)

Step 4b of the Python-first core.

- core/solver.js is now a 250-line advisor (was 900 lines): it reads the game (core/spec/game.yaml,
  published inside policy.json as model.game) and the count tables, and re-solves from any point in
  a run with the same interpreter as the Python model. Same API for the site and Ken's bot
  (advisor, recommendOption, solverHistory). The bot's on-screen text for each option moves to
  game.yaml (bot_text); the deadly rolls carry their risk labels there too.
- tests/core/advisor.test.js: the advisor gives exactly the Python model's values and choices for
  every colour and goal (to 1e-12, every decision on every published route), walks a run in the
  game's order, and maps advice onto the bot's screen.
- Removed core/engine.js and everything that only compared it with Python (tests/parity/run_engine,
  compare_runs, compare_results, compare_routes, compare_solver, compare_stats, analysis/stats/
  analyze.py). In their place: tests/core/test_stats.py checks the statistics against known answers,
  test_solver.py checks the route model on a synthetic world (tests/fixtures/synthetic_policy.py).
- analysis/network/build-graph.js reads the Python-coded runs; graph.json is byte-identical.
- docs/BOT_INTEGRATION.md: what changed for the bot (history keys, new choices, re-sync all three files).


Claude-Session: https://claude.ai/code/session_01UCzTd31GphpMXDhQqWrCMQ

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
ekcSchiano
2026-11-03 22:01:32 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent d04b88e7b4
commit 11b4a0398e
27 changed files with 578 additions and 2260 deletions
+10 -11
View File
@@ -10,13 +10,13 @@ Unofficial fan project. Not affiliated with Dragonkind or the Fourth Wing publis
The project has four parts, built on one shared core. Each folder has its own README.
```
core/ the shared model every part uses. spec/ holds the declarative rules (form.yaml: every question
and answer of the community form); atlas/ is the Python package that reads them (coding.py).
engine.js, graph.js and solver.js are the JavaScript the site and Ken's bot still use; they move
to Python + spec files step by step (docs/ROADMAP.md).
core/ the shared model every part uses. spec/ holds the declarative rules (form.yaml: the community
form; game.yaml: the game); atlas/ is the Python package that reads them (coding, route model).
solver.js (the route advisor) and graph.js (the bot's text) are the only JavaScript, because
they run in the browser and in Ken's bot.
collection/ getting data in: sources/ (the form sheet, the Dragon Register, the route PDF check, the daily
update job) and bot/ (the DragonKind bot importer). Reddit is not collected yet.
analysis/ making sense of it: stats/ (Python statistics, mirrored in core/engine.js), network/ (builds
analysis/ making sense of it: stats/ (measures.yaml and site_stats.py: every number on the page), network/ (builds
data/public/graph.json), reports/ (generated reports such as POLICY.md)
planner/ the route planner: builds data/public/policy.json and its report; the bot uses it for advice
and experiments (docs/BOT_INTEGRATION.md)
@@ -25,7 +25,7 @@ data/ raw/ (source exports, not committed), public/ (what the page and
(coded runs, PDF fingerprint), bot/ (anonymised bot runs), sources.json (download links)
docs/ guides that cross sections: privacy and licences, repo settings, bot data protocol, bot
integration, colours, roadmap
tests/ core/ (unit tests), parity/ (the JS and Python implementations must agree), fixtures/
tests/ core/ (rule, statistics, route model and advisor tests), parity/ (tools to compare two policies), fixtures/
```
## Run it locally
@@ -34,7 +34,7 @@ Requirements: Node 18+, Python 3.9+ (`pip install -r requirements.txt`).
```
npm run dev # builds dist/ and serves it at http://localhost:8000
npm test # JS engine + Python reference + parity checks
npm test # coding rules, statistics, route model, game spec, advisor and bot-text tests
```
## New data from the community sources
@@ -73,7 +73,7 @@ looks like prose. See `docs/BOT_DATA_PROTOCOL.md` for what the bot should log.
In the browser: open the page and use **Load a newer export** with the responses spreadsheet
(Google Sheets → File → Download → Microsoft Excel). Everything recomputes. Questions are matched by
wording; a renamed question is listed as "not found", and then `COLUMN_KEYS` in
`core/spec/form.yaml` (and, until the site stops coding rows itself, `core/engine.js`) need updating.
`core/spec/form.yaml` needs updating.
To update the bundled snapshot, put the new export in `data/raw/form/`, then:
@@ -87,8 +87,7 @@ npm test
The tables (how each question is found, what each answer means, which answers count as missing) are in
`core/spec/form.yaml`; the logic that combines them is `code_row()` in `core/atlas/coding.py`. Add a case to
`tests/core/test_coding.py` for every rule you change, then run `npm test`. Until the site switches to
precomputed statistics, `codeRow()` in `core/engine.js` must be changed the same way (the parity tests check it).
`tests/core/test_coding.py` for every rule you change, then run `npm test`.
## Statistics in one paragraph
@@ -108,7 +107,7 @@ local, how bot accounts are anonymised) are in `docs/PRIVACY.md`.
## Release checks
```
npm test # parity and unit tests
npm test # all tests
python site/qa/check_colours.py # dragon colours stay distinguishable (docs/COLOURS.md)
npm run build && python3 -m http.server 8765 -d dist &
node site/qa/crawl.js /tmp/qa # every tab on desktop and phone: text, links, buttons, errors, overflow