vimp-engine 0.22.1 → 0.24.0

package/src/devtools/surface/collect.js

@@ -0,0 +1,413 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import wsports from '../../config/wsports.js';
+import {
+  KNOWN_GAME_CONFIG_PATHS,
+  REQUIRED_GAME_CONFIG_PATHS,
+} from '../../lib/gameConfigView.js';
+import { formControls } from '../../lib/formControls.js';
+import { ENGINE_CAPABILITIES } from '../../lib/capabilities.js';
+import { clientServices } from '../../config/clientServices.js';
+import { abiOps } from '../../config/abiOps.js';
+import { SNAPSHOT_FORMAT_VERSION } from '../../config/opcodes.js';
+import { parseAbi } from './abiParse.js';
+
+// Слепок плагинной поверхности (этап 1 плана plugin-forward-compat).
+// Поверхность — всё, что игра может написать или прочитать: поля gameConfig,
+// имена сервисов, контролы форм, номера портов, поля манифеста, члены
+// объектов плагина, методы wasm-ABI. Инвариант И1 говорит, что ни одно из
+// этих имён не исчезает и не переименовывается, И3 — что форма данных
+// (сигнатура ABI, номер порта) не меняется.
+//
+// Слепок ничего не объявляет сам: каждый раздел собирается из существующего
+// модуля движка — импортом там, где имя есть значением, и разбором текста
+// там, где его нет (методы внутри `macro_rules!`, поля манифеста, которые
+// движок читает точечно). Продублированный руками список устарел бы молча.
+//
+// Живёт в devtools/, потому что в бандл приложения devtools не попадает
+// (граница из CLAUDE.md).
+
+const SRC_DIR = fileURLToPath(new URL('../../', import.meta.url));
+const ABI_PATH = fileURLToPath(
+  new URL('../../../core/src/abi.rs', import.meta.url),
+);
+
+// модули, читающие GameManifest: поля манифеста — их точечные обращения
+const MANIFEST_READERS = [
+  'master/GameCatalog.js',
+  'lib/loadGamePackage.js',
+  'lib/gamePlugin.js',
+];
+
+/**
+ * Собирает поверхность плагинного контракта.
+ * @returns {Promise<Object>} JSON-объект слепка (см. contract/surface.json).
+ */
+export async function collectSurface() {
+  const abi = parseAbi(await readFile(ABI_PATH, 'utf8'));
+  const sources = await readSources();
+
+  return sortDeep({
+    abi,
+    // опкоды dispatch: append-only на тех же правилах, что имена (И1) —
+    // удаление опкода отнимает возможность, на которую игра уже оперлась
+    abiOps: registrySection(abiOps),
+    clientPluginMembers: collectMembers(sources, 'clientPlugin'),
+    // словари-реестры отдают и активные записи, и выведенные из
+    // эксплуатации: вывод алиасом — не удаление (И1), и слепок обязан
+    // отличать одно от другого
+    clientServices: registrySection(clientServices),
+    // возможности движка (этап 5): имя отсюда игра пишет в
+    // manifest.requires — исчезнувшее имя отвергает уже опубликованную игру
+    // ровно так же, как исчезнувший контрол формы
+    engineCapabilities: registrySection(ENGINE_CAPABILITIES),
+    formControls: registrySection(formControls),
+    // поля gameConfig с умолчаниями (И1): движок читает их через view, а не
+    // точечно с плагина, поэтому в hostPluginMembers они уже не видны
+    gameConfigFields: [
+      ...KNOWN_GAME_CONFIG_PATHS,
+      ...REQUIRED_GAME_CONFIG_PATHS,
+    ],
+    hostPluginMembers: collectMembers(sources, 'hostPlugin'),
+    manifestFields: collectManifestFields(sources),
+    ports: { server: { ...wsports.server }, client: { ...wsports.client } },
+    requiredGameConfig: [...REQUIRED_GAME_CONFIG_PATHS],
+    // движковая (не плагинная) величина: плагин её не читает, но смена
+    // раскладки кадра разводит хост и клиент разных сборок движка — пусть
+    // попадает в diff и меняется осознанно
+    snapshotFormatVersion: SNAPSHOT_FORMAT_VERSION,
+  });
+}
+
+// запись реестра в слепке: имя плюс механика вывода из эксплуатации.
+// `note` не пишем — это пояснение для человека, а не форма данных
+function registrySection(registry) {
+  return registry.list().map(({ value, since, alias, retiredIn }) => ({
+    name: value,
+    since,
+    ...(alias === undefined ? {} : { alias, retiredIn }),
+  }));
+}
+
+// текст всех модулей движка без комментариев и строковых литералов: путь
+// 'manifest.json' в строке — не чтение поля манифеста, и попади он в слепок,
+// раздел жил бы своей жизнью
+async function readSources() {
+  const files = await listJsFiles(SRC_DIR);
+  const sources = new Map();
+
+  for (const file of files) {
+    const rel = path.relative(SRC_DIR, file).replaceAll(path.sep, '/');
+
+    sources.set(rel, stripNoise(await readFile(file, 'utf8')));
+  }
+
+  return sources;
+}
+
+async function listJsFiles(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    // `_`-префикс — черновики, которые не коммитятся (CLAUDE.md)
+    if (entry.name.startsWith('_')) {
+      continue;
+    }
+
+    const full = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...(await listJsFiles(full)));
+    } else if (entry.name.endsWith('.js')) {
+      files.push(full);
+    }
+  }
+
+  return files;
+}
+
+// комментарии и литералы вырезаются одним проходом, в порядке появления:
+// раздельные проходы спаривают апостроф внутри шаблонной строки с чужим
+// апострофом и молча съедают код между ними
+const NOISE =
+  /\/\*[\s\S]*?\*\/|\/\/[^\n]*|'(?:\\.|[^'\\\n])*'|"(?:\\.|[^"\\\n])*"|`(?:\\.|[^`\\])*`/g;
+
+function stripNoise(source) {
+  return source.replace(NOISE, ' ');
+}
+
+// имена, которые движок читает с объекта плагина: точечные обращения
+// (`hostPlugin.gameConfig`, `clientPlugin.hooks.onAuth`) и деструктуризация
+function collectMembers(sources, holder) {
+  const names = new Set();
+
+  for (const source of sources.values()) {
+    for (const name of readPaths(source, holder)) {
+      names.add(name);
+    }
+  }
+
+  if (names.size === 0) {
+    throw new Error(
+      `collectSurface: no member of "${holder}" is read anywhere in ` +
+        'src/ — the engine was restructured; fix the collector instead of ' +
+        'letting the surface snapshot go silently empty',
+    );
+  }
+
+  return [...names];
+}
+
+function collectManifestFields(sources) {
+  const names = new Set();
+
+  for (const file of MANIFEST_READERS) {
+    const source = sources.get(file);
+
+    if (source === undefined) {
+      throw new Error(
+        `collectSurface: manifest reader ${file} is gone — the engine was ` +
+          'restructured; fix the collector',
+      );
+    }
+
+    for (const name of readPaths(source, 'manifest')) {
+      names.add(name);
+    }
+  }
+
+  if (names.size === 0) {
+    throw new Error(
+      'collectSurface: no GameManifest field is read anywhere in ' +
+        `${MANIFEST_READERS.join(', ')} — fix the collector`,
+    );
+  }
+
+  return [...names];
+}
+
+// пути, которые модуль читает с объекта `holder`: `holder.a.b` → 'a.b',
+// `const { a, b } = holder` → 'a', 'b'
+function readPaths(source, holder) {
+  const names = [];
+  const dotted = new RegExp(
+    `\\b${holder}\\??\\.([A-Za-z_$][\\w$]*(?:\\??\\.[A-Za-z_$][\\w$]*)*)`,
+    'g',
+  );
+  let match;
+
+  while ((match = dotted.exec(source)) !== null) {
+    names.push(match[1].replaceAll('?.', '.'));
+  }
+
+  // ровно `= holder`, а не `= holder.gameConfig`: во втором случае имена
+  // принадлежат не плагину, а его конфигу — у того свой раздел слепка
+  const destructured = new RegExp(
+    `\\{([^{}]*)\\}\\s*=\\s*${holder}(?![\\w$.])`,
+    'g',
+  );
+
+  while ((match = destructured.exec(source)) !== null) {
+    for (const part of match[1].split(',')) {
+      const name = part
+        .split(':')[0]
+        .trim()
+        .replace(/^\.\.\./, '');
+
+      if (/^[A-Za-z_$][\w$]*$/.test(name)) {
+        names.push(name);
+      }
+    }
+  }
+
+  return names;
+}
+
+// списки, порядок которых сам по себе является контрактом: аргументы
+// ABI-метода читаются позиционно, и алфавит здесь тихо переписал бы
+// сигнатуру
+const ORDERED_LISTS = ['args'];
+
+// стабильный порядок: ключи объектов и строковые списки — по алфавиту,
+// записи ABI — по имени. Слепок читается диффом, а не глазами
+function sortDeep(value, key = null) {
+  if (Array.isArray(value)) {
+    const items = value.map(item => sortDeep(item));
+
+    if (ORDERED_LISTS.includes(key)) {
+      return items;
+    }
+
+    return items.every(item => typeof item === 'string')
+      ? items.sort()
+      : items.sort((a, b) => String(a?.name).localeCompare(String(b?.name)));
+  }
+
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map(name => [name, sortDeep(value[name], name)]),
+    );
+  }
+
+  return value;
+}
+
+/**
+ * Сериализация слепка для записи в contract/surface.json.
+ * @param {Object} surface - Результат collectSurface().
+ * @returns {string} JSON с отступом 2 и переводом строки в конце.
+ */
+export function formatSurface(surface) {
+  return `${JSON.stringify(sortDeep(surface), null, 2)}\n`;
+}
+
+const INVARIANT_1 =
+  'Инвариант И1 (plan/plugin-forward-compat/README.md): имя, которое игра\n' +
+  'могла написать, существует вечно. Выведи его из эксплуатации алиасом,\n' +
+  'а не удалением. Если это осознанный security-фикс — удали строку из\n' +
+  'contract/surface.json тем же коммитом и опиши в CHANGELOG под\n' +
+  '⚠️ Breaking + Migration.';
+
+const INVARIANT_2 =
+  'Инвариант И2 (plan/plugin-forward-compat/README.md): ничто новое не\n' +
+  'обязательно. Новое обязательное поле gameConfig отвергает КАЖДУЮ уже\n' +
+  'опубликованную игру, которая о нём не знает. Заведи поле в FIELDS\n' +
+  'модуля lib/gameConfigView.js с безопасным умолчанием — список REQUIRED\n' +
+  'может только сокращаться.';
+
+const INVARIANT_3 =
+  'Инвариант И3 (plan/plugin-forward-compat/README.md): форма данных\n' +
+  'неизменна — рядом добавляется новая. Уже опубликованная сборка игры\n' +
+  'вызывает старую форму и не пересоберётся. Если это осознанный слом —\n' +
+  'поправь строку в contract/surface.json тем же коммитом и опиши в\n' +
+  'CHANGELOG под ⚠️ Breaking + Migration.';
+
+/**
+ * Сравнение закоммиченного слепка с собранным.
+ * @param {Object} committed - Слепок из contract/surface.json.
+ * @param {Object} collected - Результат collectSurface().
+ * @returns {{violations: string[], additions: string[]}} Нарушения И1/И3 и
+ *   добавления (добавление поверхности совместимость не ломает).
+ */
+export function diffSurface(committed, collected) {
+  const violations = [];
+  const additions = [];
+
+  walk(committed, collected, [], violations, additions);
+
+  return { violations, additions };
+}
+
+function walk(before, after, trail, violations, additions) {
+  const where = trail.join('.') || 'surface';
+
+  if (Array.isArray(before)) {
+    walkList(before, after ?? [], where, violations, additions);
+    return;
+  }
+
+  if (before !== null && typeof before === 'object') {
+    for (const key of Object.keys(before)) {
+      if (after?.[key] === undefined) {
+        violations.push(`surface: '${key}' исчез из ${where}.\n${INVARIANT_1}`);
+        continue;
+      }
+
+      walk(before[key], after[key], [...trail, key], violations, additions);
+    }
+
+    for (const key of Object.keys(after ?? {})) {
+      if (before[key] === undefined) {
+        additions.push(`${where}.${key}`);
+      }
+    }
+
+    return;
+  }
+
+  if (before !== after) {
+    violations.push(
+      `surface: ${where} изменился: ${JSON.stringify(before)} → ` +
+        `${JSON.stringify(after)}.\n` +
+        (ENGINE_VALUES.has(where) ? ENGINE_VALUE_NOTE : INVARIANT_3),
+    );
+  }
+}
+
+// Движковые величины: плагин их не читает, поэтому И3 к ним не относится —
+// но менять их молча всё равно нельзя.
+const ENGINE_VALUES = new Set(['snapshotFormatVersion']);
+
+const ENGINE_VALUE_NOTE =
+  'Это движковая величина, а не плагинная: игра её не читает и от неё не\n' +
+  'зависит. Но раскладка кадра разводит хост и клиент разных сборок\n' +
+  'движка — если смена осознанна, поправь contract/surface.json тем же\n' +
+  'коммитом и убедись, что расхождение ловит codeVersion.';
+
+// Разделы с инвертированным правилом: у них расширение — это слом, а
+// сокращение — норма. Пока такой один: список обязательных полей
+// gameConfig (И2).
+const SHRINK_ONLY = new Set(['requiredGameConfig']);
+
+// требование, которого раньше не было, отвергает старые игры — а снятое
+// требование не ломает никого: правило зеркально общему
+function walkShrinkOnly(before, after, where, violations, additions) {
+  const known = new Set(before);
+
+  for (const name of after) {
+    if (!known.has(name)) {
+      violations.push(
+        `surface: '${name}' добавлен в ${where}.\n${INVARIANT_2}`,
+      );
+    }
+  }
+
+  const kept = new Set(after);
+
+  for (const name of before) {
+    if (!kept.has(name)) {
+      additions.push(`${where}: снято требование ${name}`);
+    }
+  }
+}
+
+function walkList(before, after, where, violations, additions) {
+  if (SHRINK_ONLY.has(where)) {
+    walkShrinkOnly(before, after, where, violations, additions);
+    return;
+  }
+
+  const key = item => (typeof item === 'string' ? item : item?.name);
+  const seen = new Map(after.map(item => [key(item), item]));
+
+  for (const item of before) {
+    const name = key(item);
+    const found = seen.get(name);
+
+    if (found === undefined) {
+      violations.push(`surface: '${name}' исчез из ${where}.\n${INVARIANT_1}`);
+      continue;
+    }
+
+    if (JSON.stringify(found) !== JSON.stringify(item)) {
+      violations.push(
+        `surface: сигнатура '${name}' в ${where} изменилась: ` +
+          `${JSON.stringify(item)} → ${JSON.stringify(found)}.\n${INVARIANT_3}`,
+      );
+    }
+  }
+
+  const known = new Set(before.map(key));
+
+  for (const item of after) {
+    if (!known.has(key(item))) {
+      additions.push(`${where}: ${key(item)}`);
+    }
+  }
+}
+
+export default collectSurface;

package/src/host/GameCoreAdapter.js

@@ -1,3 +1,5 @@
+import { ABI_OP_DEBUG_JSON } from '../config/abiOps.js';
+import { readCoreAbi, dispatchCoreOp } from '../lib/coreAbi.js';
 // Адаптер Rust-ядра (GameCore) под интерфейс, который потребляют мета-модули
 // хоста (RoundManager, SocketManager) и host-фасад. За поверхностью Game.js
 // (+ упаковка снапшотов) стоит WASM-ядро; события ядра (take_events) несут
@@ -9,6 +11,7 @@
 // scripted-участник создаётся как танк + ИИ-контроллер внутри ядра
 // (spawn_scripted_actor/remove_scripted_actor), человек — только танк
 // (spawn_actor/remove_actor).
+
 export default class GameCoreAdapter {
   /**
    * @param {GameCore} core - экземпляр WASM-ядра.
@@ -23,6 +26,21 @@ export default class GameCoreAdapter {
     this._participants = participants;
     this._onCoreEvent = onCoreEvent;
     this._services = {}; // { vimp, panel } — инъекция как у Game.js
+
+    // Метода нет (или самоописание нечитаемо) — ядро собрано до появления
+    // механизма. Это не ошибка: поколение 0, ни одного опционального опкода
+    // (И2). Читается один раз здесь, а не при вызове: ветку упаковки, поле
+    // формы или ответ лобби движок выбирает заранее, а не посреди матча.
+    this._abi = readCoreAbi(core, 'game core');
+  }
+
+  /**
+   * Возможности загруженного ядра: { abi, core, ops }. `abi: 0` — ядро
+   * старше самоописания.
+   * @returns {Object}
+   */
+  get abi() {
+    return this._abi;
   }
 
   // получает сервисы (аналог Game.injectServices): { vimp, panel }
@@ -215,6 +233,14 @@ export default class GameCoreAdapter {
    * @returns {Object|null}
    */
   debugJson() {
+    const { handled, bytes } = this._op(ABI_OP_DEBUG_JSON);
+
+    if (handled && bytes !== null) {
+      return JSON.parse(new TextDecoder().decode(bytes));
+    }
+
+    // ядро старше опкода, но с замороженным методом — метод не удаляется
+    // никогда (И1), поэтому запасной путь остаётся навсегда
     if (typeof this._core.debug_json !== 'function') {
       return null;
     }
@@ -222,6 +248,29 @@ export default class GameCoreAdapter {
     return JSON.parse(this._core.debug_json());
   }
 
+  /**
+   * Единственный разрешённый способ позвать необязательную возможность
+   * ядра: прямой вызов нового метода на `this._core` запрещён (И2) — у
+   * ядра, собранного год назад, его нет и не будет. ESLint стережёт это
+   * правилом no-restricted-syntax.
+   *
+   * Исходов ровно три, и они РАЗЛИЧИМЫ (соглашение `abi::dispatch_result`,
+   * core/src/abi.rs): пустой ответ — «опкод не понят», маркер `[0x00]` —
+   * «понят, ответа нет», иначе — полезные байты. Схлопывать первые два в
+   * один `null` нельзя: опкод-команда (ради них механизм и делался) отдавала
+   * бы вызывающему сырой `Uint8Array [0]`, который поехал бы в TextDecoder
+   * и JSON.parse.
+   * @param {string} op - Опкод из config/abiOps.js.
+   * @param {Uint8Array} [payload] - Полезная нагрузка опкода.
+   * @returns {{handled: boolean, bytes: Uint8Array|null}} `handled: false` —
+   *   ядро опкода не знает (вызывающий идёт по запасному пути);
+   *   `handled: true, bytes: null` — обработано без ответа.
+   * @see lib/coreAbi.js — то же для клиентского ядра
+   */
+  _op(op, payload) {
+    return dispatchCoreOp(this._core, this._abi, op, payload);
+  }
+
   // бот ли участник (спавн/удаление в ядре различаются)
   _isScripted(gameId) {
     const participant = this._participants.get(gameId);

package/src/lib/applyRoomOverrides.js

@@ -2,9 +2,23 @@
 // пользовательские настройки комнаты. Используется host.worker.js; вынесено
 // в lib для тестируемости (worker вешает self.onmessage при импорте)
 import hostDefaults from '../config/hostDefaults.js';
+import { createGameConfigView } from './gameConfigView.js';
 
-export function applyRoomOverrides(room = {}, plugin) {
-  const game = structuredClone({ ...hostDefaults, ...plugin.gameConfig });
+/**
+ * @param {Object} [room] - Переопределения комнаты.
+ * @param {Object} plugin - HostPlugin игры.
+ * @param {Object} [view] - Готовая gameConfig-view (createHostRuntime строит
+ *   её один раз на прогон). Путь по умолчанию — ТЕСТОВЫЙ: он строит вторую
+ *   view, и deriveSpectatorTeam предупреждает в консоль дважды за прогон.
+ *   Прод-вызов всегда передаёт готовую.
+ * @returns {Object} Конфиг матча: движковые дефолты + игровая половина.
+ */
+export function applyRoomOverrides(
+  room = {},
+  plugin,
+  view = createGameConfigView(plugin.gameConfig, plugin.id),
+) {
+  const game = structuredClone({ ...hostDefaults, ...view });
 
   // Этап 5.1: актуальные карты мастера (фетчит главный поток) вместо бандла
   if (room.maps && Object.keys(room.maps).length) {

package/src/lib/capabilities.js

@@ -0,0 +1,32 @@
+import { createRegistry } from './registry.js';
+
+// Реестр возможностей движка (этап 5 плана plugin-forward-compat). После
+// этапов 1-4 плагинная поверхность append-only, и отвергать игру за возраст
+// стало не за что: единственная законная причина отказа — игра просит
+// возможность, которой в этой сборке движка ещё нет, то есть она НОВЕЕ
+// движка. Список запрошенного игра пишет в необязательное поле
+// `GameManifest.requires`; манифест без него (все опубликованные до этапа 5)
+// значит «ничего сверх базового не нужно».
+//
+// Реестр append-only (И1): имя, однажды объявленное, поддерживается вечно —
+// опубликованная игра могла записать его в `requires`, и её dist больше
+// никто не тронет. Вывод из эксплуатации = алиас на новое имя, но не
+// удаление строки.
+//
+// Что сюда попадает: возможность, без которой игра не запустится вовсе, а не
+// каждое движковое улучшение. Игре, которая деградирует штатно (не просит
+// сервис, не подписана на порт), объявлять ничего не нужно — умолчания
+// этапа 2 и словари этапа 3 её и так примут.
+export const ENGINE_CAPABILITIES = createRegistry('engine-capabilities', [
+  // срезы рейтинга (day/month/all) в лобби и на хосте
+  { value: 'stat.leaderboard', since: '0.20.0' },
+  // порт ACCOLADES_DATA (18) + сервис пула `accolades`
+  { value: 'accolades', since: '0.21.0' },
+  // dispatch/abi_describe в ядре (этап 4): опциональные вызовы ядра
+  { value: 'dispatch', since: '0.23.0' },
+]);
+
+// плоский список имён — то, чем правило контракта B2 проверяет `requires`
+export const CAPABILITIES = ENGINE_CAPABILITIES.values();
+
+export default ENGINE_CAPABILITIES;

package/src/lib/coreAbi.js

@@ -0,0 +1,116 @@
+// Единственная точка чтения самоописания wasm-ядра (`abi_describe`).
+//
+// Фрагмент жил в трёх местах — конструкторе GameCoreAdapter и двух местах
+// client/main.js — и дефолт `{abi: 0, core: null, ops: []}` был написан
+// руками трижды: разъехавшись, они дали бы `ops === undefined` и TypeError
+// в первом же вызове опкода.
+//
+// Плюс `JSON.parse` не был обёрнут. Ядро, отдающее не-JSON, роняло
+// конструктор адаптера и (на клиенте) async-обработчик PS_CONFIG_DATA —
+// невыловленным промисом, после которого конфиг не применяется вовсе. Это
+// тот же режим «получатель падает от того, что отправитель другой», который
+// на JSON-портах уже вылечен веткой по умолчанию
+// (client/lib/socketDispatch.js): битое самоописание обязано читаться как
+// поколение 0, а не как отказ движка.
+
+import { abiOps } from '../config/abiOps.js';
+
+// пустая нагрузка опкода: ядро ждёт байты всегда, даже когда их нет
+const EMPTY_PAYLOAD = new Uint8Array(0);
+
+// «опкод не обработан»: ядро его не знает либо вернуло пустой вектор
+// (соглашение abi::dispatch_result в крейте)
+const NOT_HANDLED = Object.freeze({ handled: false, bytes: null });
+
+// ядро старше самоописания: ни одного опционального опкода (И2 плана
+// plugin-forward-compat). Один объект на все такие ядра — он заморожен и
+// никем не правится
+export const ABI_UNKNOWN = Object.freeze({ abi: 0, core: null, ops: [] });
+
+/**
+ * Читает самоописание ядра: версия формата, версия движкового крейта,
+ * список опкодов `dispatch`.
+ * @param {Object} core - Экземпляр wasm-ядра (игрового или клиентского).
+ * @param {string} [label] - Имя ядра в тексте предупреждения.
+ * @returns {{abi: number, core: string|null, ops: Array<string>}} Всегда
+ *   пригодный к чтению объект: `abi: 0` с пустым `ops` — ядро старше
+ *   механизма ЛИБО его самоописание нечитаемо.
+ */
+export function readCoreAbi(core, label = 'core') {
+  if (typeof core?.abi_describe !== 'function') {
+    return ABI_UNKNOWN;
+  }
+
+  let described;
+
+  try {
+    described = JSON.parse(core.abi_describe());
+  } catch (err) {
+    console.warn(`${label}: abi_describe is not JSON (${err.message})`);
+
+    return ABI_UNKNOWN;
+  }
+
+  // нормализация, а не проверка: движок обязан продолжить работу на любом
+  // содержимом. Не-строки из ops выбрасываются — по ним всё равно нечего
+  // диспетчеризовать
+  return {
+    abi: Number.isInteger(described?.abi) ? described.abi : 0,
+    core: typeof described?.core === 'string' ? described.core : null,
+    ops: Array.isArray(described?.ops)
+      ? described.ops.filter(op => typeof op === 'string')
+      : [],
+  };
+}
+
+export default readCoreAbi;
+
+/**
+ * Зовёт необязательную возможность ядра опкодом. Единственное место, где
+ * движок вызывает `dispatch` — и игровой половины, и клиентской: таблица
+ * экспортов wasm заморожена (И1/И3), поэтому новая возможность приезжает
+ * строкой, а не новым символом.
+ *
+ * Исходов ровно три, и они РАЗЛИЧИМЫ (соглашение `abi::dispatch_result`,
+ * core/src/abi.rs): пустой ответ — «опкод не понят», маркер `[0x00]` —
+ * «понят, ответа нет», иначе — полезные байты. Схлопывать первые два в один
+ * `null` нельзя: опкод-команда (ради них механизм и делался) отдавала бы
+ * вызывающему сырой `Uint8Array [0]`, который поехал бы в TextDecoder и
+ * JSON.parse.
+ * @param {Object} core - Экземпляр wasm-ядра.
+ * @param {Object} abi - Результат readCoreAbi для этого ядра.
+ * @param {string} op - Опкод из config/abiOps.js.
+ * @param {Uint8Array} [payload] - Полезная нагрузка опкода.
+ * @returns {{handled: boolean, bytes: Uint8Array|null}} `handled: false` —
+ *   ядро опкода не знает (вызывающий идёт по запасному пути);
+ *   `handled: true, bytes: null` — обработано без ответа.
+ */
+export function dispatchCoreOp(core, abi, op, payload = EMPTY_PAYLOAD) {
+  // опкод вне реестра — дефект ДВИЖКА, а не старого ядра: имя, которого нет
+  // в config/abiOps.js, не попадает ни в слепок поверхности, ни в CHANGELOG.
+  // Падаем сразу, а не на игре, которая его однажды поймёт
+  if (!abiOps.has(op)) {
+    throw new Error(
+      `dispatchCoreOp: unknown opcode "${op}" — declare it in ` +
+        'config/abiOps.js (append-only, И1)',
+    );
+  }
+
+  const resolved = abiOps.resolve(op);
+
+  if (!abi.ops.includes(resolved)) {
+    return NOT_HANDLED;
+  }
+
+  const out = core.dispatch(resolved, payload);
+
+  if (out.length === 0) {
+    return NOT_HANDLED;
+  }
+
+  // [0x00] — «обработан, ответа нет»: полезных байтов у него нет
+  return {
+    handled: true,
+    bytes: out.length === 1 && out[0] === 0x00 ? null : out,
+  };
+}