Architecture

One engine, three surfaces, one rule that keeps the game and the economy honest: only server-verified events count. This paper maps what lives where, what depends on what, and which boundaries are frozen.

1 · Layout, stated plainly

musefly.lol (static skin)
  index.html            home: the game, the agent prompt, the genesis mint
  play/                 the lineage game — plain ESM, no build step
    js/sim.js           pure game logic: world, traits, RNG, escape assay
    js/gf-neuron.js     pure neural layer (paper 3)
    js/scene-*.js       scenes; scene-game.js is the loop
  raise/ adopt/         the plan UI and the mint form
  muse.txt              the plain-text rulebook your agent reads
  agent-mint.mjs        the official miner
  whitepaper/           this documentation set

server (Fruit Fly World backend, shared with fruitfly.world)
  api/                  route handlers: exam replay, mint voucher, metadata
  lib/server/           db, session, rate limits, vouchers, x-proof
contracts/              ERC-721 + ERC-5192 (soul-bound) + test suite

The nginx at musefly.lol proxies /api/* to the backend; both domains serve the same engine and the same grader. The static skin is the MuseFly brand; everything under /api is the machinery.

2 · One engine, three surfaces

There is no second implementation to drift from. The browser, the server and the exam room all run the same simulation modules — the grader imports world.js from disk at runtime, the exact bytes the browser runs — which is exactly why the parity guarantee below is cheap to enforce and hard to fake.

3 · The parity guarantee

• Published model outputs (the escape assay, the wiring check) are pinned by tests — prose and numbers cannot silently diverge.
• The golden baseline (1260/1260, paper 6) is regenerated and compared on two architectures before any engine change ships.
• The one-way vendor flow (vendor.lock.json, sha256 per file, CI-checked) keeps the sim, the game and the site serving identical bytes.

4 · The game's compatibility surfaces

The game is shipped and frozen at these boundaries — changes must keep them working, and the tests and the HUD are the check:

• localStorage keys: flyline_v1 (lineage save), flyline_quests_v1 (quest evidence), flyline_bench_v1 (local exam board).
• DOM events: flyline:genstart, flyline:genend, flyline:log, flyline:lunge, flyline:quest.
• window.FlyLabAPI — getState(), setControl(), dash(), setMode(), autopilot(), importQuests().
• The gf state field names (pot, lc4, lplc2, armed, …) read by the HUD and the API.

5 · Server side

• Persistence — PostgreSQL via transactional helpers; mint vouchers and proof records are multi-step and transactional.
• Identity — wallet-signature sessions for humans; agents authenticate by wallet signature over a fixed message format.
• Mint rail — POST /api/mint/voucher returns an EIP-712 signed voucher; the signing key never leaves the server. The contract is the only supply authority.
• Abuse control — same-origin checks, per-IP rate limits on every mutating route, small body caps, and one X account per proof (UNIQUE(campaign, x_author_id)).
• Exam rail — the replay grader (paper 6) re-derives every hash before any voucher is signed.

6 · What qualifies for what

Local play can never mint anything by itself, by design. See paper 8.

7 · Testing and verification

npm run typecheck   # tsc --noEmit
npm test            # the full suite — model contracts, determinism, mint state machine
npm run build       # production build

Coverage areas: missions, mint state machine and voucher/contract hash agreement, API input validation, determinism of the vial model, the GF neural unit contract (leak, threshold, refractory, determinism, pinned experiment numbers), bench determinism, quest evidence validation.