vimp-engine 0.4.0 → 0.6.0

package/bin/vimp-sim.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { readFile } from 'node:fs/promises';
 import { runScenario } from '../src/devtools/ScenarioRunner.js';
-import { loadGameForSim } from '../src/devtools/pluginLoader.js';
+import { builtinScenario } from '../src/devtools/builtinScenario.js';
+import { loadGameForSim, isFixture } from '../src/devtools/pluginLoader.js';
 import {
   checkDeterminism,
   summarize,
@@ -12,33 +13,37 @@ import { writeReport, formatMarkdown } from '../src/devtools/report.js';
 // CLI headless-прогона: правка → npm run sim → текстовый вердикт, без
 // браузера и без человека.
 
+// ошибка разбора флагов печатается без стека — см. обработчик внизу файла
+class UsageError extends Error {}
+
 const USAGE = `Usage: vimp-sim [options]
 
   --scenario <path>  scenario JSON (default: built-in smoke scenario)
   --game <path>      game package directory or dist/manifest.json
-  --core <path>      node build of the game core (overrides entries.wasmNode)
+  --core <path>      node build of the game core (overrides entries.wasmNode);
+                     only meaningful with --game — the built-in fixture has
+                     no WASM core to override
   --out <dir>        report root (default: .debug)
   --no-write         print the report to stdout instead of writing files
   --determinism      run the scenario twice and compare the frame streams
   --help
 `;
 
-// минимальный сценарий на фикстуре: один игрок заходит, едет вперёд,
-// отпускает клавишу — этого хватает, чтобы контур доказал, что он замкнут
-const DEFAULT_SCENARIO = {
-  version: 1,
-  seed: 3812,
-  participants: [{ id: 'p1', name: 'P1', model: 'm1' }],
-  timeline: [
-    { tick: 0, op: 'join', who: 'p1', team: 'team1' },
-    { tick: 10, op: 'key', who: 'p1', action: 'down', name: 'forward' },
-    { tick: 60, op: 'key', who: 'p1', action: 'up', name: 'forward' },
-  ],
-  // событийный ключ фикстуры в этом сценарии не стреляет — объявлено явно,
-  // иначе инвариант 2 честно посчитает это «сущность не спавнится»
-  unusedSnapshotKeys: ['e1'],
-  ticks: 120,
-};
+// каждая строка с префиксом: дальше в stderr уходит список падений, и
+// грепалки CI не должны путать предупреждение с ними
+const BUILTIN_NOTICE =
+  'notice: the built-in smoke scenario is running against --game. It only\n' +
+  'notice: proves the loop closes on this plugin: key coverage (invariant 2)\n' +
+  'notice: and prediction drift (invariant 9) are skipped — both need a\n' +
+  'notice: scenario written for your game. See § Scenario format in the\n' +
+  "notice: engine's docs/en/debugging.md (github.com/lgick/vimp), then run\n" +
+  'notice: vimp-sim --scenario <file>.\n\n';
+
+// типичная опечатка «--core без --game»: фикстурное ядро — обычный JS и
+// wasmUrl не смотрит, поэтому прогон был бы зелёным, не тронув ядро игры
+const STRAY_CORE_NOTICE =
+  'notice: --core without --game does nothing: the run falls back to the\n' +
+  "notice: built-in fixture, whose core is plain JS. Add --game <path>.\n\n";
 
 async function main(argv) {
   const args = parseArgs(argv);
@@ -48,17 +53,30 @@ async function main(argv) {
     return 0;
   }
 
-  const scenario = args.scenario
-    ? JSON.parse(await readFile(args.scenario, 'utf8'))
-    : DEFAULT_SCENARIO;
+  if (args.core && !args.game) {
+    process.stderr.write(STRAY_CORE_NOTICE);
+  }
 
   // плагин грузится один раз: второй прогон самопроверки детерминизма
-  // обязан идти на том же ядре, иначе он проверял бы загрузчик, а не мир
+  // обязан идти на том же ядре, иначе он проверял бы загрузчик, а не мир.
+  // Загрузка идёт до сборки сценария: встроенный берёт имена модели, команды
+  // и клавиши из gameConfig игры
   const plugin = await loadGameForSim({ game: args.game, core: args.core });
-  const report = await runScenario(scenario, { plugin });
+
+  if (!args.scenario && !isFixture(plugin)) {
+    process.stderr.write(BUILTIN_NOTICE);
+  }
+
+  const scenario = args.scenario
+    ? JSON.parse(await readFile(args.scenario, 'utf8'))
+    : builtinScenario(plugin);
+  // хеши потока кадров собираются только под --determinism: их единственный
+  // потребитель — сравнение двух прогонов, а объём линеен по длине матча
+  const captureFrames = args.determinism === true;
+  const report = await runScenario(scenario, { plugin, captureFrames });
 
   if (args.determinism) {
-    const second = await runScenario(scenario, { plugin });
+    const second = await runScenario(scenario, { plugin, captureFrames });
     const check = checkDeterminism(report, second);
 
     report.invariants = report.invariants.map(item =>
@@ -115,11 +133,20 @@ function parseArgs(argv) {
       case '--core':
       case '--out':
         i += 1;
+
+        // «--game» последним аргументом (или перед следующим флагом) тихо
+        // уводил на фикстуру: прогон зелёный, игра не тронута. Путь,
+        // начинающийся с '--', тем самым запрещён — таких не бывает, а
+        // явный отказ лучше ENOENT про каталог '--determinism'
+        if (argv[i] === undefined || argv[i].startsWith('--')) {
+          throw new UsageError(`option '${arg}' needs a value\n\n${USAGE}`);
+        }
+
         args[arg.slice(2)] = argv[i];
         break;
 
       default:
-        throw new Error(`unknown option '${arg}'\n\n${USAGE}`);
+        throw new UsageError(`unknown option '${arg}'\n\n${USAGE}`);
     }
   }
 
@@ -131,7 +158,13 @@ main(process.argv.slice(2)).then(
     process.exitCode = code;
   },
   error => {
-    process.stderr.write(`${error.stack ?? error.message}\n`);
+    // опечатка в флаге — не краш инструмента: стек тут лишний шум поверх
+    // USAGE, который пользователь и должен прочитать
+    process.stderr.write(
+      error instanceof UsageError
+        ? `${error.message}\n`
+        : `${error.stack ?? error.message}\n`,
+    );
     process.exitCode = 1;
   },
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vimp-engine",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "VIMP — движок-приложение (мастер, P2P-транспорт, Worker-хост, мета, MVC-каркас клиента)",
   "license": "MIT",
   "repository": {

package/src/config/lobby.js

@@ -57,7 +57,7 @@ export default {
     maxDelay: 30000,
   },
 
-  // приёмник выгрузок отладочного контура (этап 6 плана plan/ai-debug):
+  // приёмник выгрузок отладочного контура (этап 6 плана plan/done/ai-debug):
   // маршрут поднимается мастером только в dev, в проде вернёт 404
   debugReportUrl: '/debug/report',
 

package/src/devtools/RecordingSocketManager.js

@@ -1,99 +1,62 @@
-// Транспорт хоста, который вместо сети пишет исходящие кадры в память.
-// Обобщение FakeSocketManager из tests/host/fixtureHarness.js: одну и ту же
-// подмену используют и движковые тесты меты, и headless-runner — иначе
-// пришлось бы держать две копии перечня отправителей SocketManager.
-
-// Все отправители SocketManager, которые дёргает host-фасад.
-export const SENDER_METHODS = [
-  'sendConfig',
-  'sendAuthData',
-  'sendAuthResult',
-  'sendPing',
-  'sendClear',
-  'sendTechInform',
-  'sendMap',
-  'sendFirstShot',
-  'sendFirstVote',
-  'sendShot',
-  'sendPanel',
-  'sendStat',
-  'sendChat',
-  'sendVote',
-  'sendKeySet',
-  'sendPlayerDefaultShot',
-  'sendSpectatorDefaultShot',
-  'sendConsole',
-  'sendGameInform',
-  'sendRoundEnd',
-  'sendSoundCue',
-  'sendName',
-];
-
-class RecordingSocketManager {
+import wsports from '../config/wsports.js';
+import SocketManager from '../host/meta/SocketManager.js';
+
+// Транспорт хоста, который вместо сети пишет исходящие вызовы в память.
+// Наследует боевой SocketManager, а не копирует его отправителей: составные
+// отправители (sendFirstShot и компания), нагрузка портов и их номера
+// остаются одни на прод и на headless — ручная копия уже расходилась с
+// оригиналом и стоила прогону keySet, панели и первого снапшота мира.
+//
+// Записывается сам вызов (метод + аргументы, как их видит хост), а нагрузка
+// транспорта — тем, что настоящий код успел передать в _send/_sendBinary:
+// проверки инвариантов рассуждают о семантике («roundEnd объявил победителя»),
+// а VirtualClient — о том, что реально уехало бы в data channel.
+
+// имена отправителей берутся из прототипа: ручной список неизбежно отстаёт
+// от боевого класса, что уже случалось
+const SENDER_METHODS = Object.getOwnPropertyNames(SocketManager.prototype)
+  .filter(name => name.startsWith('send'));
+
+class RecordingSocketManager extends SocketManager {
   /**
+   * @param {Object} [ports] - Карта портов host→client; по умолчанию боевая
+   *   (движковые тесты меты создают транспорт без аргументов).
+   * @param {Object} [gameOpts] - Игровая параметризация ({ soundCues,
+   *   initialVote }) — та же, что получает боевой SocketManager.
    * @param {Object} [options]
    * @param {Function} [options.onFrame] - Вызывается на каждый исходящий кадр
-   *   ({ method, socketId, args }) — runner раздаёт их VirtualClient'ам, не
-   *   дожидаясь конца прогона.
+   *   ({ method, socketId, args, tick, sent }) — runner раздаёт их
+   *   VirtualClient'ам, не дожидаясь конца прогона.
    */
-  constructor({ onFrame = null } = {}) {
-    this.frames = []; // [{ method, socketId, args, tick }]
+  constructor(ports = wsports.server, gameOpts = {}, { onFrame = null } = {}) {
+    super(ports, gameOpts);
+
+    this.frames = []; // [{ method, socketId, args, tick, sent }]
 
     // номер тика прогона: runner двигает его перед каждым шагом, кадры
     // получают метку — без неё проверки жизненного цикла раунда не могут
     // сказать «кому именно не доехал roundEnd на этом тике»
     this.tick = 0;
     this._onFrame = onFrame;
-    this._game = null;
-    this._panel = null;
-    this._stat = null;
+
+    // кадр, чьё тело сейчас исполняется: в него уходит нагрузка _send;
+    // составные отправители вкладываются друг в друга, поэтому это стек
+    // через локальную переменную в _record
+    this._current = null;
 
     for (const method of SENDER_METHODS) {
       this[method] = (socketId, ...args) => {
-        this._record({ method, socketId, args });
+        this._record(method, socketId, args, () =>
+          SocketManager.prototype[method].call(this, socketId, ...args),
+        );
       };
     }
-
-    // Составные отправители боевого SocketManager сами дёргают панель,
-    // статистику и keySet. Плоская запись их не раскрывает — тогда клиент
-    // headless-прогона живёт с пустой панелью и без keySet, то есть предикт
-    // у него не включается никогда. Развёртка обязана повторять
-    // host/meta/SocketManager.js.
-    this.sendFirstShot = socketId => {
-      this._record({ method: 'sendFirstShot', socketId, args: [] });
-      this.sendStat(socketId, this._stat?.getFull());
-      this.sendPanel(socketId, this._panel?.getEmptyPanel());
-      this.sendKeySet(socketId, 0); // наблюдатель
-    };
-
-    this.sendPlayerDefaultShot = (socketId, gameId) => {
-      this._record({
-        method: 'sendPlayerDefaultShot',
-        socketId,
-        args: [gameId],
-      });
-      this.sendPanel(socketId, this._panel?.getFullPanel(gameId));
-      this.sendKeySet(socketId, 1); // играющий
-    };
-
-    this.sendSpectatorDefaultShot = socketId => {
-      this._record({ method: 'sendSpectatorDefaultShot', socketId, args: [] });
-      this.sendPanel(socketId, this._panel?.getEmptyPanel());
-      this.sendKeySet(socketId, 0);
-    };
-  }
-
-  injectServices(game, panel, stat) {
-    this._game = game;
-    this._panel = panel;
-    this._stat = stat;
   }
 
-  addUser() {}
-  removeUser() {}
-
   close(socketId, code, key, arr) {
-    this._record({ method: 'close', socketId, args: [code, key, arr] });
+    this._record('close', socketId, [code, key, arr], () =>
+      super.close(socketId, code, key, arr),
+    );
   }
 
   // все кадры указанного метода
@@ -101,14 +64,76 @@ class RecordingSocketManager {
     return this.frames.filter(frame => frame.method === method);
   }
 
-  clear() {
+  clearFrames() {
     this.frames.length = 0;
   }
 
-  _record(frame) {
-    frame.tick = this.tick;
+  // сети нет: всё, что боевой код отдал бы сокету, оседает в текущем кадре
+  _send(socketId, port, data, reliable = true) {
+    this._payload({ port, data, reliable });
+  }
+
+  _sendBinary(socketId, buffer, reliable) {
+    this._payload({ port: this._PORT_SHOT_DATA, data: buffer, reliable });
+  }
+
+  _close(socketId, code, data) {
+    this._payload({ port: null, data: { code, data } });
+  }
+
+  // Кадр публикуется в момент первой отправки — это и есть порядок провода:
+  // составной отправитель отдаёт свою нагрузку раньше вложенных вызовов
+  // (FIRST_SHOT_DATA → STAT → PANEL → KEYSET), и клиент прогона видит ту же
+  // последовательность, что и браузер. Публикация после invoke() отдавала бы
+  // родителя последним.
+  //
+  // Отсюда несущее допущение: у отправителя не больше ОДНОЙ собственной
+  // нагрузки (составные раскладываются во вложенные вызовы, а два _send в
+  // sendClear/sendTechInform — это ветки if/else). Нарушь его — и подписчик
+  // получит кадр, собранный наполовину, уже после решения о маршрутизации.
+  // Поэтому не молчим, а называем контракт.
+  _payload(entry) {
+    const frame = this._current;
+
+    if (!frame) {
+      return;
+    }
+
+    if (frame.sent.length) {
+      throw new Error(
+        `RecordingSocketManager: '${frame.method}' sent a second payload ` +
+          `(port ${entry.port}) — a sender may hand the socket at most one, ` +
+          'otherwise the subscriber already routed a half-built frame; ' +
+          'split it into nested senders like sendFirstShot does',
+      );
+    }
+
+    frame.sent.push(entry);
+    this._emit(frame);
+  }
+
+  _record(method, socketId, args, invoke) {
+    const frame = { method, socketId, args, tick: this.tick, sent: [] };
+    const parent = this._current;
+
     this.frames.push(frame);
+    this._current = frame;
+
+    try {
+      invoke();
+    } finally {
+      this._current = parent;
+    }
+
+    // отправитель без собственной нагрузки (составной вроде
+    // sendPlayerDefaultShot либо отфильтрованный прод-кодом незамапленный
+    // soundCue) всё равно доезжает до подписчика — но ровно один раз
+    if (!frame.sent.length) {
+      this._emit(frame);
+    }
+  }
 
+  _emit(frame) {
     if (this._onFrame) {
       this._onFrame(frame);
     }

package/src/devtools/ScenarioRunner.js

@@ -4,7 +4,11 @@ import RecordingSocketManager from './RecordingSocketManager.js';
 import VirtualClient from './VirtualClient.js';
 import { loadGameForSim } from './pluginLoader.js';
 import { resetHostSingletons } from './resetHostSingletons.js';
-import { checkInvariants, summarize } from './invariants.js';
+import {
+  checkInvariants,
+  summarize,
+  ALL_KEYS_UNAUDITED,
+} from './invariants.js';
 import { inspectCore, inspectHost } from './inspectHost.js';
 
 // Прогон сценария целиком в одном Node-процессе: авторитетный хост
@@ -58,6 +62,21 @@ export function parseScenario(raw) {
   const timeline = [...(raw.timeline ?? [])].sort(
     (a, b) => (a.tick ?? 0) - (b.tick ?? 0),
   );
+  const unusedSnapshotKeys = raw.unusedSnapshotKeys ?? [];
+
+  // строка тут легальна ровно одна: без проверки забытые скобки
+  // ("unusedSnapshotKeys": "w1") молча разложились бы в набор символов, и
+  // объявленный ключ всё равно попал бы в нарушения инварианта 2
+  if (
+    unusedSnapshotKeys !== ALL_KEYS_UNAUDITED &&
+    (!Array.isArray(unusedSnapshotKeys) ||
+      unusedSnapshotKeys.some(key => typeof key !== 'string'))
+  ) {
+    throw new Error(
+      'scenario: unusedSnapshotKeys must be an array of snapshot keys or ' +
+        `"${ALL_KEYS_UNAUDITED}"`,
+    );
+  }
 
   return {
     version: 1,
@@ -69,10 +88,11 @@ export function parseScenario(raw) {
     timeline,
     // ключи схемы, которых в этом сценарии заведомо не будет (инвариант 2):
     // «сущность не спавнится» отличается от «сценарий её не трогает» только
-    // этим объявлением
-    unusedSnapshotKeys: raw.unusedSnapshotKeys ?? [],
+    // этим объявлением. '*' — сценарий не берётся судить покрытие ключей
+    // вовсе (встроенный смоук на чужой игре), и инвариант честно пропускается
+    unusedSnapshotKeys,
     // пороги детектора рассинхрона предикта (инвариант 9); {} — дефолты
-    // ядра, null — детектор выключен
+    // ядра, null — детектор выключен, и инвариант тоже пропускается
     divergence: raw.divergence === null ? null : (raw.divergence ?? {}),
     ticks: raw.ticks ?? 600,
     dumpTicks: raw.dumpTicks ?? null,
@@ -89,6 +109,9 @@ export function parseScenario(raw) {
  *   детерминизма).
  * @param {string} [options.gamePath] - Путь к пакету игры/манифесту.
  * @param {string} [options.corePath] - Путь к node-сборке ядра.
+ * @param {boolean} [options.captureFrames] - Считать хеши потока кадров
+ *   (нужны только самопроверке детерминизма — на длинном матче это лишние
+ *   мегабайты в отчёте).
  * @returns {Promise<Object>} Отчёт прогона.
  */
 export async function runScenario(rawScenario, options = {}) {
@@ -105,13 +128,15 @@ export async function runScenario(rawScenario, options = {}) {
   const restoreClock = virtualClock.install();
 
   try {
-    return await execute(scenario, plugin, virtualClock);
+    return await execute(scenario, plugin, virtualClock, {
+      captureFrames: options.captureFrames === true,
+    });
   } finally {
     restoreClock();
   }
 }
 
-async function execute(scenario, plugin, virtualClock) {
+async function execute(scenario, plugin, virtualClock, { captureFrames }) {
   const clients = new Map(); // socketId → VirtualClient
   const byParticipant = new Map(); // id сценария → { socketId, gameId }
   const participantLog = []; // [{ who, socketId, gameId, joinTick, leaveTick }]
@@ -120,13 +145,11 @@ async function execute(scenario, plugin, virtualClock) {
 
   let currentTick = 0;
 
-  const socketManager = new RecordingSocketManager({
-    onFrame: frame => routeFrame(frame, clients, virtualClock, host),
-  });
-
   // ping/pong: без ответа хост честно кикает участника по таймауту RTT, и
-  // длинный сценарий тихо теряет игроков посреди прогона
+  // длинный сценарий тихо теряет игроков посреди прогона. Объявлено до
+  // транспорта — замыкание onFrame читает эту переменную.
   let host = null;
+  let socketManager = null;
 
   const room = {
     ...scenario.room,
@@ -143,7 +166,15 @@ async function execute(scenario, plugin, virtualClock) {
 
   const runtime = await createHostRuntime(room, {
     loadHostPlugin: () => plugin.hostPlugin,
-    createSocketManager: () => socketManager,
+    // транспорт собирается той же фабрикой, что и боевой: наследник обязан
+    // получить те же порты и ту же игровую параметризацию
+    createSocketManager: (ports, gameOpts) => {
+      socketManager = new RecordingSocketManager(ports, gameOpts, {
+        onFrame: frame => routeFrame(frame, clients, virtualClock, host),
+      });
+
+      return socketManager;
+    },
     overrideGameConfig: game => mergeConfig(game, scenario.config),
     hostOptions: {
       onMapChange: mapName =>
@@ -229,6 +260,7 @@ async function execute(scenario, plugin, virtualClock) {
     mapChanges,
     byParticipant,
     participantLog,
+    captureFrames,
   });
 }
 
@@ -253,6 +285,21 @@ function routeFrame(frame, clients, virtualClock, host) {
     return;
   }
 
+  // первый снапшот мира: в браузере он применяется сразу (applyShot), а не
+  // едет через буфер интерполяции — сущность, доехавшая только им, иначе не
+  // попадёт ни в сцену, ни в проверки
+  if (frame.method === 'sendFirstShot') {
+    client.applyFirstShot(frame.sent[0]?.data);
+    return;
+  }
+
+  // CLEAR приходит на каждый рестарт раунда и на смену карты; без него
+  // headless живёт через границу раунда в состоянии, которого в игре нет
+  if (frame.method === 'sendClear') {
+    client.clear(frame.args[0]);
+    return;
+  }
+
   if (frame.method === 'sendMap') {
     client.setMap(frame.args[0]);
     return;
@@ -286,6 +333,10 @@ async function applyOp(op, ctx) {
 
       if (entry) {
         host.removeUser(entry.gameId);
+
+        // ядро клиента живёт в WASM-памяти: без free многочасовой реплей с
+        // текучкой участников растит процесс
+        clients.get(entry.socketId)?.destroy();
         clients.delete(entry.socketId);
         byParticipant.delete(op.who);
 
@@ -409,13 +460,16 @@ function requireEntry(byParticipant, who) {
   return entry;
 }
 
-// точечное переопределение конфига игры сценарием: config.timers.* и
-// config.<ключ верхнего уровня>
+// точечное переопределение конфига игры сценарием. Таймеры — только через
+// config.timers: неявный роутинг одноимённого ключа верхнего уровня в
+// game.timers молча правил не то, что просил сценарий.
 function mergeConfig(game, overrides) {
-  for (const [key, value] of Object.entries(overrides)) {
-    if (key in game.timers) {
-      game.timers[key] = value;
-    } else if (value && typeof value === 'object' && !Array.isArray(value)) {
+  const { timers = {}, ...rest } = overrides;
+
+  Object.assign(game.timers, timers);
+
+  for (const [key, value] of Object.entries(rest)) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
       game[key] = { ...game[key], ...value };
     } else {
       game[key] = value;
@@ -439,6 +493,7 @@ function buildReport(ctx) {
     mapChanges,
     byParticipant,
     participantLog,
+    captureFrames,
   } = ctx;
 
   const frameCounts = {};
@@ -511,11 +566,14 @@ function buildReport(ctx) {
       ),
     })),
     scenes,
-    // сырой поток кадров нужен самопроверке детерминизма (этап 3) —
-    // сравнивается побайтово
-    shotBytes: socketManager
-      .framesOf('sendShot')
-      .map(frame => Buffer.from(toBytes(frame.args[0])).toString('base64')),
+    // поток кадров нужен ровно одному потребителю — самопроверке
+    // детерминизма (этап 3). Хеша на кадр для сравнения потоков достаточно,
+    // а сами байты линейно от длины матча раздували report.json
+    shotHashes: captureFrames
+      ? socketManager
+          .framesOf('sendShot')
+          .map(frame => hash32(toBytes(frame.args[0])))
+      : null,
     snapshotSchema: game.snapshot,
   };
 }
@@ -527,3 +585,16 @@ function toBytes(value) {
 
   return new Uint8Array(value);
 }
+
+// FNV-1a: сравниваются потоки одного и того же прогона, криптостойкость не
+// нужна — нужна дешевизна и отсутствие зависимостей
+function hash32(bytes) {
+  let hash = 0x811c9dc5;
+
+  for (let i = 0; i < bytes.length; i += 1) {
+    hash ^= bytes[i];
+    hash = Math.imul(hash, 0x01000193);
+  }
+
+  return hash >>> 0;
+}

package/src/devtools/VirtualClient.js

@@ -141,6 +141,48 @@ class VirtualClient {
     }
   }
 
+  /**
+   * FIRST_SHOT_DATA: первый снапшот мира. В браузере применяется немедленно
+   * (applyShot), в буфер интерполяции не попадает — сущность, доехавшая
+   * только им, иначе не появится в сцене вовсе.
+   * @param {Array} [data] - [gameSnapshot, camera, serverTime, seq].
+   */
+  applyFirstShot(data) {
+    if (!Array.isArray(data)) {
+      return;
+    }
+
+    const [game, camera] = data;
+
+    if (game) {
+      this._applyGameData(game);
+    }
+
+    if (camera && camera !== 0) {
+      this.camera = [camera[0], camera[1]];
+    }
+  }
+
+  /**
+   * CLEAR: зеркало client/main.js — снятие сущностей с «холста» и сброс ядра
+   * (буфер интерполяции + предикт). Хост шлёт его на каждый рестарт раунда
+   * и на смену карты; без него headless живёт через границу раунда в
+   * состоянии, которого в браузере не бывает.
+   * @param {Array} [setIdList] - Ключи схемы к снятию; без него — всё.
+   */
+  clear(setIdList) {
+    if (Array.isArray(setIdList)) {
+      for (const setId of setIdList) {
+        delete this.scene[setId];
+      }
+    } else {
+      this.scene = {};
+      this.camera = null;
+    }
+
+    this.core.reset?.();
+  }
+
   /**
    * MAP_DATA: мир raycast в ядре и сброс предикта — зеркало main.js.
    * @param {Object} data - Данные карты, как их шлёт хост.
@@ -242,6 +284,12 @@ class VirtualClient {
     return JSON.parse(this.core.debug_json());
   }
 
+  // Ядро живёт в памяти WASM: вышедший участник обязан её отдать, иначе
+  // длинный реплей с текучкой игроков растит процесс
+  destroy() {
+    this.core.free?.();
+  }
+
   // Записи детектора рассинхрона предикта из ядра. Агрегаты накопительные,
   // поэтому просто перезаписываются; записи — вычерпываются.
   _drainDivergence() {

package/src/devtools/builtinScenario.js

@@ -0,0 +1,95 @@
+import { ALL_KEYS_UNAUDITED } from './invariants.js';
+import { isFixture } from './pluginLoader.js';
+
+// Встроенный сценарий headless-прогона: один участник заходит, едет вперёд,
+// отпускает клавишу. Этого хватает, чтобы контур доказал, что он замкнут
+// (хост → кадр → клиентское ядро → сцена), и не хватает ни на что больше.
+//
+// Идентификаторы берутся из gameConfig самой игры: имя модели, команды и
+// клавиши — часть игры, а не движка. Захардкоженные фикстурные 'm1' /
+// 'team1' / 'forward' на чужом плагине означают падение в ядре («unknown
+// model») либо красный инвариант 8 у исправного плагина.
+
+// Ввод начинается на 40-м тике, а не сразу: кадр спавна с force_reset
+// приходит примерно на interpolation.delay (движковый дефолт — 100 мс, тут
+// ~3× запаса) позже входа и чистит удержанные клавиши предиктора
+// (docs/en/debugging.md) — встроенный сценарий не должен демонстрировать
+// ровно ту ловушку, от которой предостерегает документация
+const INPUT_DOWN_TICK = 40;
+const INPUT_UP_TICK = 100;
+const TICKS = 120;
+
+// событийный ключ фикстуры в этом сценарии не стреляет — объявлено явно,
+// иначе инвариант 2 честно посчитает это «сущность не спавнится»
+const FIXTURE_UNUSED_KEYS = ['e1'];
+
+const firstKey = dict => Object.keys(dict ?? {})[0];
+
+// Клавиша для смоука обязана быть удерживаемой: по конвенции playerKeys
+// (docs/ai/04-client-plugin.md) `type: 1` — триггер, у которого 'up'
+// игнорируется, и «нажал — отпустил» не даёт ни удержания, ни движения.
+// Порядок объявления в playerKeys контрактом не задан, поэтому берём первую
+// без type; если игра объявила одни триггеры — первую любую, смоук всё равно
+// должен запуститься. Движок сам type не интерпретирует (это дело ядра
+// игры) — здесь это эвристика выбора, а не поведение движка.
+const heldKey = playerKeys => {
+  const keys = Object.entries(playerKeys ?? {});
+
+  return (keys.find(([, spec]) => !spec?.type) ?? keys[0])?.[0];
+};
+
+/**
+ * Собирает встроенный смоук-сценарий под конкретную игру.
+ * @param {Object} plugin - Результат loadGameForSim.
+ * @returns {Object} Сценарий в формате runScenario.
+ */
+export function builtinScenario(plugin) {
+  const config = plugin.hostPlugin.gameConfig;
+  const model = firstKey(config.parts?.models);
+  const key = heldKey(config.playerKeys);
+  const team = Object.keys(config.teams ?? {}).find(
+    name => name !== config.spectatorTeam,
+  );
+
+  if (!model || !key || !team) {
+    throw new Error(
+      `game "${plugin.id}": the built-in scenario has nothing to drive ` +
+        `(model: ${model ?? '—'}, playable team: ${team ?? '—'}, ` +
+        `player key: ${key ?? '—'}) — write a scenario for this game and ` +
+        `pass --scenario <file>`,
+    );
+  }
+
+  const scenario = {
+    version: 1,
+    seed: 3812,
+    participants: [{ id: 'p1', name: 'P1', model }],
+    timeline: [
+      { tick: 0, op: 'join', who: 'p1', team },
+      {
+        tick: INPUT_DOWN_TICK,
+        op: 'key',
+        who: 'p1',
+        action: 'down',
+        name: key,
+      },
+      { tick: INPUT_UP_TICK, op: 'key', who: 'p1', action: 'up', name: key },
+    ],
+    ticks: TICKS,
+  };
+
+  if (isFixture(plugin)) {
+    return { ...scenario, unusedSnapshotKeys: FIXTURE_UNUSED_KEYS };
+  }
+
+  // На чужой игре это смоук контура, а не аудит контракта: сценарий не знает
+  // ни ключей её схемы, ни её порогов дрейфа (у каждой игры своя раскладка
+  // player-блока и свои единицы). Судить исправный плагин по фикстурным
+  // значениям значит выдавать ему красный вердикт, поэтому проверки 2 и 9
+  // честно пропускаются, а не притворяются пройденными.
+  return {
+    ...scenario,
+    unusedSnapshotKeys: ALL_KEYS_UNAUDITED,
+    divergence: null,
+  };
+}

package/src/devtools/invariants.js

@@ -15,7 +15,11 @@ export const PASS = 'pass';
 export const FAIL = 'fail';
 export const SKIP = 'skip';
 
-// список проверок в порядке plan/ai-debug/stage_3.md
+// scenario.unusedSnapshotKeys: вместо списка ключей — «этот сценарий вообще
+// не берётся судить покрытие схемы» (встроенный смоук на чужой игре)
+export const ALL_KEYS_UNAUDITED = '*';
+
+// список проверок в порядке plan/done/ai-debug/stage_3.md
 const CHECKS = [
   [1, 'finiteValues', 'no NaN/Infinity in decoded fields and hot buffer'],
   [2, 'snapshotKeysUsed', 'every snapshot key produced at least one row'],
@@ -67,14 +71,19 @@ export function checkInvariants(ctx) {
 }
 
 /**
- * Инвариант 12: два прогона одного сценария обязаны совпасть побайтово.
+ * Инвариант 12: два прогона одного сценария обязаны совпасть кадр в кадр
+ * (сравниваются хеши кадров, собранные при captureFrames).
  * @param {Object} first - Отчёт первого прогона.
  * @param {Object} second - Отчёт второго прогона.
  * @returns {Object} Результат проверки.
  */
 export function checkDeterminism(first, second) {
-  const a = first.shotBytes;
-  const b = second.shotBytes;
+  const a = first.shotHashes;
+  const b = second.shotHashes;
+
+  if (!a || !b) {
+    return result('determinism', SKIP, [], 'run with --determinism');
+  }
 
   if (a.length !== b.length) {
     return result('determinism', FAIL, [
@@ -132,6 +141,19 @@ function finiteValues({ clients }) {
 
 // 2
 function snapshotKeysUsed({ game, clients, scenario }) {
+  // сценарий, не знающий схемы этой игры (встроенный смоук на чужом плагине),
+  // не должен объявлять её ключи «не спавнящимися» — это красный вердикт
+  // исправной игре
+  if (scenario.unusedSnapshotKeys === ALL_KEYS_UNAUDITED) {
+    return result(
+      'snapshotKeysUsed',
+      SKIP,
+      [],
+      `the scenario declares unusedSnapshotKeys: "${ALL_KEYS_UNAUDITED}" — ` +
+        'key coverage is not audited',
+    );
+  }
+
   const declared = Object.keys(game.snapshot);
   const unused = new Set(scenario.unusedSnapshotKeys);
   const seen = new Set();
@@ -392,7 +414,19 @@ function keyBindings({ game, clientConfig, scenario }) {
 // player-блоком кадра. Сопоставление идёт по времени кадра, а не по seq —
 // предиктор переигрывает историю ввода от момента авторитетного состояния,
 // и «тот же seq» на клиенте и на хосте означает разные моменты.
-function predictionDrift({ clients }) {
+function predictionDrift({ clients, scenario }) {
+  // детектор выключен самим сценарием — молчит не ядро, и автор плагина не
+  // должен идти искать несуществующую проблему в take_divergence
+  if (scenario.divergence === null) {
+    return result(
+      'predictionDrift',
+      SKIP,
+      [],
+      'the scenario disables the drift detector (divergence: null) — ' +
+        'thresholds are per-game, write a scenario for yours',
+    );
+  }
+
   const violations = [];
   const tracked = clients.filter(client => client.divergenceStats);
 
@@ -442,11 +476,19 @@ function predictionDrift({ clients }) {
 }
 
 // Компоненты player-блока — игровая раскладка, движок знает только их
-// порядок, поэтому нарушение адресуется индексом.
+// порядок, поэтому нарушение адресуется индексом. Исключение — уровень 0
+// (source 'camera'): там движок сравнивает ровно мировые x/y, и называть их
+// «#0/#1» значит прятать причину (см. docs/ai/13-debugging.md).
+const CAMERA_COMPONENTS = ['x', 'y'];
+
 function formatDivergence(record) {
+  const name =
+    record.source === 'camera'
+      ? index => CAMERA_COMPONENTS[index] ?? `#${index}`
+      : index => `#${index}`;
   const parts = (record.exceeded ?? []).map(
     index =>
-      `#${index} Δ${record.delta[index]} > ${record.thresholds[index]} ` +
+      `${name(index)} Δ${record.delta[index]} > ${record.thresholds[index]} ` +
       `(predicted ${record.predicted[index]}, authoritative ${record.authoritative[index]})`,
   );
   const replayed = record.replayed

package/src/devtools/pluginLoader.js

@@ -1,7 +1,10 @@
-import { readFile } from 'node:fs/promises';
+import { access, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { assertEngineApiCompatible } from '../lib/gamePlugin.js';
+import {
+  assertEngineApiCompatible,
+  assertGameConfigShape,
+} from '../lib/gamePlugin.js';
 
 // Поиск игры для headless-прогона. В браузере плагин грузится по URL из
 // GameManifest мастера; в Node URL-ов нет, поэтому источников три, по
@@ -21,6 +24,16 @@ const FIXTURE_DIR = new URL(
   import.meta.url,
 );
 
+// значение поля source у фикстуры: по нему отличается «своя игра, схему
+// которой инструмент знает» от чужого плагина (см. builtinScenario.js)
+export const FIXTURE_SOURCE = 'fixture:miniGame';
+
+/**
+ * @param {Object} plugin - Результат loadGameForSim.
+ * @returns {boolean} Прогон идёт на встроенной фикстуре, а не на чужой игре.
+ */
+export const isFixture = plugin => plugin.source === FIXTURE_SOURCE;
+
 /**
  * @param {Object} [options]
  * @param {string} [options.game] - Путь к пакету игры или к манифесту.
@@ -30,10 +43,20 @@ const FIXTURE_DIR = new URL(
  *   source }.
  */
 export async function loadGameForSim({ game = null, core = null } = {}) {
-  if (!game) {
-    return loadFixture(core);
-  }
+  const plugin = game
+    ? await loadFromManifest(game, core)
+    : await loadFixture(core);
 
+  // контракт gameConfig проверяется здесь, а не только в createHostRuntime:
+  // встроенный сценарий собирается из gameConfig раньше, чем стартует прогон
+  // (builtinScenario.js), и плагин без конфига иначе отвечал бы сырым
+  // TypeError вместо перечисления недостающих полей
+  assertGameConfigShape(plugin.hostPlugin);
+
+  return plugin;
+}
+
+async function loadFromManifest(game, core) {
   const manifestPath = game.endsWith('.json')
     ? path.resolve(game)
     : path.resolve(game, 'dist/manifest.json');
@@ -43,8 +66,22 @@ export async function loadGameForSim({ game = null, core = null } = {}) {
 
   const baseDir = path.dirname(manifestPath);
   const { assetsBase } = manifest;
-  const hostPlugin = await importDefault(baseDir, manifest.entries.host, assetsBase);
-  const clientPlugin = await importDefault(baseDir, manifest.entries.client, assetsBase);
+  const hostPlugin = await importDefault(
+    baseDir,
+    manifest.entries.host,
+    assetsBase,
+  );
+  const clientPlugin = await importDefault(
+    baseDir,
+    manifest.entries.client,
+    assetsBase,
+  );
+
+  assertPluginMatchesManifest(manifest, {
+    host: hostPlugin,
+    client: clientPlugin,
+  });
+
   const nodeCore = core ?? manifest.entries.wasmNode ?? null;
 
   if (!nodeCore) {
@@ -54,6 +91,21 @@ export async function loadGameForSim({ game = null, core = null } = {}) {
     );
   }
 
+  const corePath = path.resolve(baseDir, nodeCore);
+
+  // манифест объявляет поле, но опубликованный пакет мог не довезти файл
+  // (ignore-правила срезают каталог внутри files) — без этой проверки отказ
+  // приходит сырым ERR_MODULE_NOT_FOUND из резолвера
+  try {
+    await access(corePath);
+  } catch {
+    throw new Error(
+      `${manifestPath}: entries.wasmNode points at '${nodeCore}', but ` +
+        `${corePath} does not exist — the game package was published ` +
+        `without its node core (npm run core:build:node) or pass --core <path>`,
+    );
+  }
+
   return {
     id: manifest.id,
     manifest,
@@ -78,10 +130,25 @@ async function loadFixture(core) {
     hostPlugin,
     clientPlugin,
     wasmUrl: core ? pathToFileURL(path.resolve(core)).href : undefined,
-    source: 'fixture:miniGame',
+    source: FIXTURE_SOURCE,
   };
 }
 
+// зеркало lib/gamePlugin.js:loadClientPlugin — манифест мог быть пересобран
+// без dist/: прогон на старом плагине даёт зелёный вердикт о том, чего в
+// сборке уже нет
+function assertPluginMatchesManifest(manifest, plugins) {
+  for (const [half, plugin] of Object.entries(plugins)) {
+    if (plugin.engineApi !== manifest.engineApi) {
+      throw new Error(
+        `game "${manifest.id}": ${half} plugin engineApi ` +
+          `v${plugin.engineApi} does not match manifest engineApi ` +
+          `v${manifest.engineApi} — stale dist/`,
+      );
+    }
+  }
+}
+
 function importDefault(baseDir, entry, assetsBase) {
   const file = path.resolve(baseDir, stripBase(entry, assetsBase));
 

package/src/devtools/report.js

@@ -18,8 +18,10 @@ export async function writeReport(report, { outDir = '.debug', stamp } = {}) {
 
   await mkdir(runDir, { recursive: true });
 
-  // срезы сцены — отдельными файлами: они самые объёмные и читаются точечно
-  const { scenes = [], ...rest } = report;
+  // срезы сцены — отдельными файлами: они самые объёмные и читаются точечно.
+  // shotHashes — служебный материал самопроверки детерминизма (длина = число
+  // кадров матча), в читаемом отчёте ему делать нечего
+  const { scenes = [], shotHashes, ...rest } = report;
 
   await Promise.all(
     scenes.map(scene =>

package/src/host/DebugRecorder.js

@@ -1,6 +1,6 @@
 import clock from '../lib/clock.js';
 
-// Рекордер живого матча (этап 6 плана plan/ai-debug): пишет то, что headless
+// Рекордер живого матча (этап 6 плана plan/done/ai-debug): пишет то, что headless
 // не воспроизводит — реальный WebRTC, PixiJS и живой ввод человека — ровно в
 // формат сценария headless-runner'а (devtools/ScenarioRunner.js). Баг,
 // пойманный человеком в браузере, догоняется потом `npm run sim:replay`
@@ -134,8 +134,11 @@ export default class DebugRecorder {
       version: 1,
       seed: this._seed,
       map: this._map,
+      // таймеры сценария живут только в config.timers: верхний уровень
+      // config — это ключи конфига игры, и раньше запись подсовывала туда
+      // таймер в расчёте на неявный роутинг
       config: this._networkSendRate
-        ? { networkSendRate: this._networkSendRate }
+        ? { timers: { networkSendRate: this._networkSendRate } }
         : {},
       participants: this._participants,
       timeline: this._timeline,

package/src/host/HostGame.js

@@ -145,7 +145,7 @@ export default class HostGame {
     this._networkSendRate = data.timers.networkSendRate;
     this._snapshotManager = new SnapshotThrottle(this._networkSendRate);
 
-    // рекордер живого матча (этап 6 плана plan/ai-debug) — только в dev-режиме;
+    // рекордер живого матча (этап 6 плана plan/done/ai-debug) — только в dev-режиме;
     // в проде null, и все точки записи ниже вырождаются в ?.
     this._recorder = this._isDevMode ? new DebugRecorder() : null;
 
@@ -511,7 +511,7 @@ export default class HostGame {
     this._mapList.push(...Object.keys(this._maps));
   }
 
-  // ***** отладочный контур (этап 6 плана plan/ai-debug) ***** //
+  // ***** отладочный контур (этап 6 плана plan/done/ai-debug) ***** //
   // Всё ниже живёт под флагом isDevMode: в проде рекордера нет, а дамп
   // отдаёт только то, что и так знает мета.
 

package/src/host/host.worker.js

@@ -407,7 +407,7 @@ self.onmessage = async event => {
       host?.setHostId(msg.hostId, msg.hostSecret);
       break;
 
-    // отладочный контур (этап 6 плана plan/ai-debug): единственный вход в
+    // отладочный контур (этап 6 плана plan/done/ai-debug): единственный вход в
     // авторитетную половину из главного потока — запрос/ответ по requestId
     case 'debug':
       onDebug(msg);

package/src/host/meta/SocketManager.js

@@ -310,7 +310,7 @@ export default class SocketManager {
 
   /**
    * Отправка отладочного лога хоста в консоль клиента (порт CONSOLE,
-   * этап 6 плана plan/ai-debug). Worker изолирован от DevTools вкладки —
+   * этап 6 плана plan/done/ai-debug). Worker изолирован от DevTools вкладки —
    * без этого канала его события в браузере не видны вовсе.
    * @param {string} socketId
    * @param {*} data

package/src/lib/AbstractTimer.js

@@ -49,9 +49,14 @@ class AbstractTimer {
   _stopTimer(key) {
     if (this._timers.has(key)) {
       const { timerId, isInterval } = this._timers.get(key);
-      const handler = isInterval ? clock.clearInterval : clock.clearTimeout;
 
-      handler(timerId);
+      // вызов через clock, а не отрыв метода от объекта: сейчас это
+      // замыкания, но привязка к модулю не должна зависеть от этого
+      if (isInterval) {
+        clock.clearInterval(timerId);
+      } else {
+        clock.clearTimeout(timerId);
+      }
 
       this._timers.delete(key);
     }
@@ -74,9 +79,12 @@ class AbstractTimer {
   _clearAllTimers() {
     for (const timerData of this._timers.values()) {
       const { timerId, isInterval } = timerData;
-      const handler = isInterval ? clock.clearInterval : clock.clearTimeout;
 
-      handler(timerId);
+      if (isInterval) {
+        clock.clearInterval(timerId);
+      } else {
+        clock.clearTimeout(timerId);
+      }
     }
 
     this._timers.clear();

package/src/lib/applyRoomOverrides.js

@@ -40,7 +40,7 @@ export function applyRoomOverrides(room = {}, plugin) {
     game.timers.mapTime = clampTime(room.mapTime);
   }
 
-  // dev-режим вкладки хоста (этап 6 плана plan/ai-debug): включает рекордер
+  // dev-режим вкладки хоста (этап 6 плана plan/done/ai-debug): включает рекордер
   // и хостовый CONSOLE-лог. Прод-бандл его не выставляет — поведение то же
   if (typeof room.isDevMode === 'boolean') {
     game.isDevMode = room.isDevMode;

package/src/lib/createHostRuntime.js

@@ -79,7 +79,7 @@ export async function createHostRuntime(room, options = {}) {
   const host = new HostGame(game, socketManager, core, hostPlugin, {
     hostSocketId: room?.hostSocketId ?? null,
     gameVersion: room.game?.version ?? null,
-    // рекордер (этап 6 плана plan/ai-debug) кладёт seed в сценарий — без него
+    // рекордер (этап 6 плана plan/done/ai-debug) кладёт seed в сценарий — без него
     // записанный матч невоспроизводим
     seed,
     ...hostOptions,

package/src/lib/gamePlugin.js

@@ -51,6 +51,10 @@ const REQUIRED_GAME_CONFIG_PATHS = [
   'parts.friendlyFire',
   'panel.fields',
   'playerKeys',
+  // без них HostGame разыменовывает undefined (this._teams[spectatorTeam])
+  // и игра умирает тремя разными сообщениями вместо одного контрактного
+  'teams',
+  'spectatorTeam',
 ];
 
 function getPath(obj, dottedPath) {
@@ -61,9 +65,14 @@ function getPath(obj, dottedPath) {
 
 // бросает при отсутствии обязательных полей HostPlugin.gameConfig
 export function assertGameConfigShape(hostPlugin) {
-  const missing = REQUIRED_GAME_CONFIG_PATHS.filter(
-    p => getPath(hostPlugin.gameConfig, p) === undefined,
-  );
+  // null проходил бы проверку присутствия, хотя ни одно из этих полей не
+  // бывает пустым по контракту: движок разыменовывает их сразу, и гейт,
+  // заведённый ради текста вместо TypeError, сам отвечал бы TypeError
+  const missing = REQUIRED_GAME_CONFIG_PATHS.filter(p => {
+    const value = getPath(hostPlugin.gameConfig, p);
+
+    return value === undefined || value === null;
+  });
 
   if (missing.length > 0) {
     throw new Error(
@@ -71,6 +80,19 @@ export function assertGameConfigShape(hostPlugin) {
         missing.join(', '),
     );
   }
+
+  // единственная связь между полями, которую стоит проверять здесь:
+  // spectatorTeam — имя ключа внутри teams, и опечатка даёт spectatorId ===
+  // undefined, после чего участник заходит в несуществующую команду
+  // (ParticipantManager.createHuman валится на её счётчике)
+  const { teams, spectatorTeam } = hostPlugin.gameConfig;
+
+  if (teams[spectatorTeam] === undefined) {
+    throw new Error(
+      `game "${hostPlugin.id}": spectatorTeam '${spectatorTeam}' is not a ` +
+        `key of teams (${Object.keys(teams).join(', ')})`,
+    );
+  }
 }
 
 // динамический import ClientPlugin игры (client-entry её сборки). Манифест и