vimp-engine 0.22.0 → 0.23.0

package/bin/vimp-surface.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  collectSurface,
+  formatSurface,
+  diffSurface,
+} from '../src/devtools/surface/collect.js';
+
+// CLI слепка плагинной поверхности (этап 1 плана plugin-forward-compat):
+// без флага печатает расхождение с закоммиченным contract/surface.json и
+// возвращает 1 при нарушении И1/И3, с --write перезаписывает слепок.
+// Внутренний инструмент репозитория движка: в поле `bin` публикуемого
+// пакета он не значится.
+
+const SURFACE_PATH = fileURLToPath(
+  new URL('../contract/surface.json', import.meta.url),
+);
+
+const USAGE = `Usage: vimp-surface [options]
+
+  --write   rewrite contract/surface.json with the collected surface
+  --help
+`;
+
+async function main(argv) {
+  if (argv.includes('--help')) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const surface = await collectSurface();
+
+  if (argv.includes('--write')) {
+    await mkdir(path.dirname(SURFACE_PATH), { recursive: true });
+    await writeFile(SURFACE_PATH, formatSurface(surface));
+    process.stdout.write(`surface: written ${SURFACE_PATH}\n`);
+
+    return 0;
+  }
+
+  let committed;
+
+  try {
+    committed = JSON.parse(await readFile(SURFACE_PATH, 'utf8'));
+  } catch (err) {
+    process.stderr.write(
+      `surface: no snapshot at ${SURFACE_PATH} — run ` +
+        '`npm run surface:update` to create it\n',
+    );
+
+    return 1;
+  }
+
+  const { violations, additions } = diffSurface(committed, surface);
+
+  for (const addition of additions) {
+    process.stdout.write(`surface: добавлено ${addition}\n`);
+  }
+
+  if (additions.length > 0 && violations.length === 0) {
+    process.stdout.write(
+      'слепок устарел, запусти `npm run surface:update` (добавление ' +
+        'поверхности совместимость не ломает)\n',
+    );
+  }
+
+  for (const violation of violations) {
+    process.stderr.write(`${violation}\n\n`);
+  }
+
+  if (violations.length === 0 && additions.length === 0) {
+    process.stdout.write('surface: слепок совпадает\n');
+  }
+
+  return violations.length > 0 ? 1 : 0;
+}
+
+main(process.argv.slice(2)).then(
+  code => {
+    process.exitCode = code;
+  },
+  err => {
+    process.stderr.write(`${err.message}\n`);
+    process.exitCode = 1;
+  },
+);

package/core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vimp-engine-core"
-version = "0.8.4"
+version = "0.9.0"
 edition = "2024"
 description = "VIMP — движковый каркас симуляции (физика, карта, снапшот-фрейминг, интерполяция/предикт/raycast-примитивы, нав-утилиты). Без wasm-bindgen — обёртки для WASM-ABI собирает game-crate."
 license = "MIT"

package/package.json

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

package/src/client/lib/formBuilder.js

@@ -1,10 +1,14 @@
 import { anchorPattern } from '../../lib/formPattern.js';
 import { normalizeOptions } from '../../lib/formOptions.js';
+import { resolveDescriptor } from '../../lib/formControls.js';
 
 // Общий билдер полей форм (room-форма и auth-форма используют один
 // контракт дескрипторов — docs/en/plugin-api.md, раздел "Form schema").
 // control: 'select'|'text'|'checkbox'|'radio'; все контролы — нативные
-// элементы формы, без визуальной кастомизации. Валидация — не нативная
+// элементы формы, без визуальной кастомизации. Имя контрола приезжает от
+// игры и разрешается через append-only реестр (lib/formControls.js): имена,
+// выведенные из эксплуатации в v3 ('range', 'number', 'toggle',
+// 'segmented'), продолжают строиться алиасами своих нативных замен (И1). Валидация — не нативная
 // (никаких браузерных попапов): collectFormErrors/renderFormErrors ниже
 // собирают и рисуют ошибки в разметку (#lobby-error/#auth-error).
 // Проверяются только поля, у которых есть строка в DOM: ошибка на скрытом
@@ -43,11 +47,14 @@ function forcedValue(options) {
 // то же правило вне формы: solo-путь (boot.autoAuth) отвечает хосту без
 // всякой формы и должен прийти ровно к тому же значению, что и она
 export function resolveForcedValue(descriptor, ctx = {}) {
-  if (!OPTION_CONTROLS.includes(descriptor.control)) {
+  // после разрешения алиаса: 'segmented' — та же группа вариантов, что radio
+  const resolved = resolveDescriptor(descriptor);
+
+  if (!OPTION_CONTROLS.includes(resolved.control)) {
     return undefined;
   }
 
-  const forced = forcedValue(resolveOptions(descriptor, ctx));
+  const forced = forcedValue(resolveOptions(resolved, ctx));
 
   // форма отдала бы строку: и <option>.value, и <input type=radio>.value —
   // DOM-свойства, они всегда строки. Нестроковое значение (options: [1, 2])
@@ -265,18 +272,27 @@ const builders = {
   radio: buildRadio,
 };
 
+// имена control, которые билдер умеет строить. Активный набор имён диктует
+// реестр (lib/formControls.js), и совпадение этих двух списков проверяет
+// tests/client/formControls.test.js: разъехавшись, они дали бы «unknown
+// control» на имени, которое реестр считает живым
+export const FORM_CONTROLS = Object.keys(builders);
+
 // строит одно поле формы по дескриптору (docs/en/plugin-api.md, "Form schema")
 export function buildField(descriptor, ctx = {}) {
-  const build = builders[descriptor.control];
+  // алиас выведенного контрола ('range' → numeric 'text') разрешается
+  // здесь же, где строится поле, и теми же правилами, что в валидации
+  const patched = resolveDescriptor(descriptor);
+  const build = builders[patched.control];
 
   if (!build) {
     throw new Error(`formBuilder: unknown control "${descriptor.control}"`);
   }
 
-  const field = build(descriptor, ctx);
+  const field = build(patched, ctx);
 
-  if (descriptor.default !== undefined) {
-    field.setValue(descriptor.default);
+  if (patched.default !== undefined) {
+    field.setValue(patched.default);
   }
 
   return field;
@@ -441,7 +457,10 @@ export function collectFormErrors(descriptors, fields) {
       return;
     }
 
-    const error = validateField(descriptor, field);
+    // тот же резолв алиаса, что и в buildField: валидация обязана смотреть
+    // на контрол, которым поле построено, иначе бывшее range-поле уезжает
+    // на хост без проверки диапазона
+    const error = validateField(resolveDescriptor(descriptor), field);
 
     if (error) {
       errors.push({

package/src/client/lib/socketDispatch.js

@@ -0,0 +1,34 @@
+// Диспетчеризация входящего JSON-сообщения [portId, payload] по разрежённому
+// массиву обработчиков (client/main.js: socketMethods).
+//
+// Порт без обработчика — не исключение, а тишина (этап 3 плана
+// plugin-forward-compat). До этого `socketMethods[msg[0]](msg[1])` бросал
+// `TypeError: ... is not a function` и ронял обработку сообщения целиком:
+// получатель падал от того, что отправитель знает больше. Это не плагинная
+// ось (хост и клиент комнаты — один бандл движка, их расхождение ловится
+// codeVersion), но хрупкость ровно та же, и лечится она веткой по умолчанию.
+
+/**
+ * Отдаёт сообщение обработчику своего порта.
+ * @param {Array<Function>} methods - Обработчики по номеру порта.
+ * @param {Array} msg - Сообщение [portId, payload].
+ * @returns {boolean} Было ли сообщение обработано.
+ */
+export function dispatchSocketMessage(methods, msg) {
+  const port = msg?.[0];
+  const method = methods?.[port];
+
+  if (typeof method !== 'function') {
+    // console.debug, а не error: неизвестный порт — штатная встреча со
+    // «стороной, которая знает больше», а не дефект
+    console.debug(`client: no handler for port ${port} — message ignored`);
+
+    return false;
+  }
+
+  method(msg[1]);
+
+  return true;
+}
+
+export default dispatchSocketMessage;

package/src/client/main.js

@@ -36,6 +36,7 @@ import { ensureGameShell, ensureCanvas } from './views/gameShell.js';
 import { createContextTracker } from './lib/contextTracker.js';
 import { createLocalPlayer } from './lib/localPlayer.js';
 import { createAccolades } from './lib/accolades.js';
+import { dispatchSocketMessage } from './lib/socketDispatch.js';
 import { createDebugApi, debugLog, DEBUG_PREFIX } from './debug.js';
 import { buildClientCoreConfig } from '../lib/clientCoreConfig.js';
 import {
@@ -109,6 +110,13 @@ function bindActiveGame(manifest, plugin) {
   gameStyleNode.textContent = plugin.styles ?? '';
 }
 
+// поле `compat` появляется у манифеста каталога мастера, только когда игра
+// просит возможность, которой в этой сборке движка нет; манифест без него
+// (все опубликованные до этапа 5) доступен по определению
+function isGameAvailable(manifest) {
+  return manifest.compat?.ok !== false;
+}
+
 // режим загрузки (Этап 2 плана standalone-sdk): lobby — прод с мастером,
 // solo — хост в этой же вкладке (standalone SDK), dedicated — прямой WS к
 // Node-серверу. Ветвлений ровно пять: манифест, сигналинг/лобби, транспорт,
@@ -146,9 +154,13 @@ try {
       throw gamesManifest;
     }
 
+    // недоступная игра (manifest.compat.ok === false, этап 5 плана
+    // plugin-forward-compat) не годится в активные: её плагин не загрузится,
+    // и вкладка встала бы на первой же игре каталога. В список лобби она
+    // при этом попадает — с причиной
     activeGameManifest = boot.gameId
       ? gamesManifest.find(manifest => manifest.id === boot.gameId)
-      : gamesManifest[0];
+      : (gamesManifest.find(isGameAvailable) ?? gamesManifest[0]);
   }
 
   if (!activeGameManifest) {
@@ -278,6 +290,12 @@ const socketMethods = []; // методы для обработки сокет-
 let clientCore = null;
 let wasm = null;
 
+// возможности загруженного клиентского ядра ({ abi, core, ops }) —
+// читаются один раз при создании ядра, а не в момент вызова. Ядро старше
+// самоописания даёт поколение 0 с пустым списком опкодов: это не ошибка,
+// а игра, собранная до появления механизма (И2 плана plugin-forward-compat)
+let clientCoreAbi = { abi: 0, core: null, ops: [] };
+
 // сервис пула зависимостей: «эта сущность моя или чужая?». Ядро читается
 // геттером — оно создаётся позже пула сервисов (см. lib/localPlayer.js)
 const localPlayer = createLocalPlayer(() => clientCore);
@@ -312,6 +330,10 @@ socketMethods[PS_CONFIG_DATA] = async data => {
 
   clientCore = core;
   wasm = { memory };
+  clientCoreAbi =
+    typeof core.abi_describe === 'function'
+      ? JSON.parse(core.abi_describe())
+      : { abi: 0, core: null, ops: [] };
 
   // инициализация сущностей игры
   for (const entity of Object.keys(entitiesOnCanvas)) {
@@ -1170,11 +1192,30 @@ function handleVisibilityChange() {
         }
       }
 
-      debugLog('clientCore', clientCore?.debug_json?.());
+      debugLog('clientCore', clientCoreDebug());
     }
   }
 }
 
+// дамп клиентского ядра: сначала опкод dispatch, затем замороженный метод.
+// Метод не удаляется никогда (И1), поэтому запасной путь остаётся навсегда:
+// ядро, собранное до появления dispatch, отдаёт дамп по-старому
+function clientCoreDebug() {
+  if (!clientCore) {
+    return undefined;
+  }
+
+  if (clientCoreAbi.ops.includes('debug.json')) {
+    const out = clientCore.dispatch('debug.json', new Uint8Array(0));
+
+    if (out.length > 0) {
+      return new TextDecoder().decode(out);
+    }
+  }
+
+  return clientCore.debug_json?.();
+}
+
 // единая точка управления рендер-циклом: Ticker.add дубликаты не отсеивает,
 // а добавить renderTick могут и runModules, и восстановление контекста
 function startRenderLoop() {
@@ -1270,10 +1311,9 @@ function handleMessage(data) {
     return;
   }
 
-  // JSON-сообщение [portId, payload]
-  const msg = unpacking(data);
-
-  socketMethods[msg[0]](msg[1]);
+  // JSON-сообщение [portId, payload]; порт без обработчика игнорируется, а
+  // не роняет обработку (lib/socketDispatch.js)
+  dispatchSocketMessage(socketMethods, unpacking(data));
 }
 
 // разрыв P2P: выход хоста = смерть комнаты (host-migration нет). Останавливаем
@@ -1965,9 +2005,17 @@ function populateGameSelect() {
 
   gamesManifest.forEach(manifest => {
     const option = document.createElement('option');
+    const available = isGameAvailable(manifest);
 
     option.value = manifest.id;
-    option.textContent = manifest.title;
+    // недоступная игра остаётся видимой (раньше мастер выкидывал её из
+    // каталога, и игрок видел пустое лобби без причины), но выбрать её
+    // нельзя: комнату по ней всё равно не поднять
+    option.textContent = available
+      ? manifest.title
+      : `${manifest.title} — unavailable`;
+    option.disabled = !available;
+    option.title = available ? '' : manifest.compat.text;
     gameSelect.appendChild(option);
   });
 

package/src/config/abiOps.js

@@ -0,0 +1,31 @@
+import { createRegistry } from '../lib/registry.js';
+
+// Реестр опкодов `dispatch` (этап 4 плана plugin-forward-compat). Таблица
+// экспортов wasm-ядра заморожена: символ, которого нет в уже опубликованном
+// `.wasm`, там не появится никогда, и никакой адаптер его не синтезирует.
+// Поэтому КАЖДАЯ будущая возможность ядра приезжает опкодом — строкой,
+// которую ядро либо понимает, либо нет, — а не новым методом.
+//
+// Реестр append-only (И1): опкод, который могла начать понимать игра,
+// существует вечно. Удаление опкода = удаление возможности, на которую
+// игра уже могла опереться.
+//
+// Форма записи: `payload`/`response` фиксируют кодировку байтов конкретного
+// опкода (сам `dispatch` их не знает — он возит сырые `Uint8Array`).
+// Пустой ответ ядра — «опкод не обработан»; `[0x00]` — «обработан, ответа
+// нет» (соглашение `abi::dispatch_result` в крейте).
+export const abiOps = createRegistry('abiOps', [
+  // курированный дамп мира ядра; дублирует замороженный метод debug_json,
+  // с которого началась проверка механизма (этап 4.6)
+  {
+    value: 'debug.json',
+    since: 4,
+    payload: 'none',
+    response: 'json',
+  },
+]);
+
+// плоский список активных опкодов — то, что вправе позвать движок
+export const ABI_OPS = abiOps.values();
+
+export default abiOps;

package/src/config/clientServices.js

@@ -0,0 +1,27 @@
+import { createRegistry } from '../lib/registry.js';
+
+// Реестр движковых сервисов клиентского пула (этап 3 плана
+// plugin-forward-compat). Пул ими не исчерпывается: игра доливает туда свои
+// через ClientPlugin.hooks.services(core) — движок о них не знает ничего.
+//
+// Реестр append-only (И1): имя, которое игра написала в
+// componentDependencies, существует вечно. Ключевое поведение, на которое
+// опирается совместимость: пул отдаёт ЗАПРОШЕННОЕ, а не всё подряд
+// (client/providers/DependencyProvider.js), поэтому шестой сервис ничего не
+// требует от старых игр — они его не просят и не получают. Незнакомое имя —
+// не отказ загрузки, а undefined в парте; ловит его правило контракта C4.
+export const clientServices = createRegistry('clientServices', [
+  { value: 'renderer', since: 1 },
+  { value: 'soundManager', since: 1 },
+  // база ассетов пакета игры (`${assetsBase}img/...`)
+  { value: 'assetsBase', since: 3 },
+  // «свой ли это персонаж» (lib/localPlayer.js)
+  { value: 'localPlayer', since: 3 },
+  // места в глобальном топе (lib/accolades.js)
+  { value: 'accolades', since: 4 },
+]);
+
+// плоский список имён — то, чем правило C4 проверяет componentDependencies
+export const SERVICES = clientServices.values();
+
+export default clientServices;

package/src/config/opcodes.js

@@ -3,8 +3,17 @@
 // живут в Rust-ядре: packages/engine/core/src/snapshot.rs (pack) и packages/engine/core/src/client/unpack.rs.
 
 // версия контракта движок ↔ игра-плагин (GameManifest, HostPlugin,
-// ClientPlugin, Wasm Host ABI — docs/{en,ru}/plugin-api.md);
-// проверяется при загрузке плагинов; ломающие изменения контрактов → +1.
+// ClientPlugin, Wasm Host ABI — docs/{en,ru}/plugin-api.md).
+//
+// ЗАМОРОЖЕНО на 4. Больше не гейт совместимости и больше не бампается:
+// после этапов 1-4 плана plugin-forward-compat плагинная поверхность
+// append-only, и отвергать плагин за возраст стало не за что. Остаётся как
+// метка поколения контракта в манифестах и диагностике; удалять нельзя —
+// константу импортируют скрипты сборки всех уже существующих игр
+// (build-game-manifest.js) и правило контракта B2. Совместимость решается
+// переговорами о возможностях, см. lib/capabilities.js.
+//
+// История поколений (для чтения манифестов постарше):
 // v2: явная схема форм (roomForm/authSchema.params[].options — Form schema
 // в plugin-api.md), движок больше не выводит контролы из типа значения
 // v3: набор control сокращён до нативных элементов — 'select'|'text'|

package/src/config/wsports.js

@@ -1,3 +1,12 @@
+// Номера портов JSON-канала (docs/en/network.md). Реестр append-only, как и
+// остальные словари плагинной поверхности (этап 3 плана
+// plugin-forward-compat): номер НИКОГДА не переиспользуется и не
+// перенумеровывается — уже опубликованная сборка игры шлёт и слушает те
+// номера, что видела при сборке, и её dist больше никто не тронет.
+// Выведенный из эксплуатации порт остаётся в этом файле со своим номером и
+// пометкой `// retired in vN`, чтобы номер не был выдан повторно. За
+// механикой следит раздел `ports` слепка поверхности
+// (contract/surface.json): удаление имени или смена номера валит тест.
 export default {
   // порты получения данные от сервера
   server: {

package/src/devtools/contract/loadContext.js

@@ -2,6 +2,7 @@ import { access, readFile, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { ENGINE_API_VERSION } from '../../config/opcodes.js';
+import { createGameConfigView } from '../../lib/gameConfigView.js';
 
 // Сбор контекста статической проверки: по каталогу пакета игры собирается
 // всё, что удалось прочитать, и помечается недостающее. Ни одна неудача не
@@ -53,12 +54,30 @@ export async function loadContext(gameDir) {
   ctx.clientPlugin = await loadHalf(ctx, 'client', CLIENT_ENTRIES);
 
   ctx.gameConfig = ctx.hostPlugin?.gameConfig ?? null;
+  // то же представление, что построит движок при загрузке (этап 2 плана
+  // plugin-forward-compat): правило, которое спрашивает «что получится»,
+  // а не «что объявлено», обязано смотреть сюда — иначе оно краснеет на
+  // конфиге, который движок принимает. Невалидный конфиг о себе скажет
+  // правилом B3, поэтому здесь падение вырождается в исходный объект
+  ctx.gameConfigView = resolveConfigView(ctx);
   ctx.authSchema = ctx.hostPlugin?.authSchema ?? null;
   ctx.clientConfig = buildClientConfig(ctx);
 
   return ctx;
 }
 
+function resolveConfigView(ctx) {
+  if (!ctx.gameConfig) {
+    return null;
+  }
+
+  try {
+    return createGameConfigView(ctx.gameConfig, ctx.hostPlugin?.id);
+  } catch {
+    return ctx.gameConfig;
+  }
+}
+
 // Половина плагина: сначала исходник (он свежее сборки), при неудаче —
 // собранный entry из манифеста. Клиентский исходник в Node обычно не
 // импортируется вовсе (`import './game.css'` — расширение Vite, не Node),
@@ -156,7 +175,9 @@ async function readEngineCoreVersion() {
 // Разбор обязан совпадать — правьте обе или ни одной (см. тест
 // tests/scaffold/versions.test.js).
 export function parseCrateVersion(text) {
-  const section = text.split(/^\s*\[/m).find(part => part.startsWith('package]'));
+  const section = text
+    .split(/^\s*\[/m)
+    .find(part => part.startsWith('package]'));
 
   return section?.match(/^\s*version\s*=\s*"([^"]+)"/m)?.[1] ?? null;
 }
@@ -226,7 +247,9 @@ async function listFiles(root) {
       // симлинк-каталог (обычная dev-раскладка: dist/img -> ../assets/img)
       // у readdir не isDirectory(); без разыменования он попал бы в список
       // файлом, и правила ассетов дали бы ложный отказ
-      if (entry.isSymbolicLink() ? await isDirectory(full) : entry.isDirectory()) {
+      if (
+        entry.isSymbolicLink() ? await isDirectory(full) : entry.isDirectory()
+      ) {
         await walk(full, rel);
       } else {
         found.add(rel);

package/src/devtools/contract/rules/b10-respawns.js

@@ -18,9 +18,11 @@ export default {
       return skip('no gameConfig.maps or gameConfig.teams');
     }
 
-    const playing = Object.keys(teams).filter(
-      team => team !== ctx.gameConfig.spectatorTeam,
-    );
+    // эффективное значение: игра вправе не объявлять spectatorTeam (И2), а
+    // по объявленному команда наблюдателей попала бы в играющие и правило
+    // потребовало бы для неё респауны
+    const spectatorTeam = ctx.gameConfigView?.spectatorTeam ?? null;
+    const playing = Object.keys(teams).filter(team => team !== spectatorTeam);
     const maxPlayers = ctx.gameConfig.roomDefaults?.maxPlayers;
     const violations = [];
 

package/src/devtools/contract/rules/b2-engine-api.js

@@ -1,20 +1,32 @@
 import { ERROR, skip, verdict } from '../result.js';
+import { CAPABILITIES } from '../../../lib/capabilities.js';
 
-// engineApi живёт в трёх местах (манифест, HostPlugin, ClientPlugin) и во
-// всех трёх обязан быть импортом ENGINE_API_VERSION, а не числом: литерал
-// не расходится со сборкой движка в момент написания и молча расходится
-// через релиз, после чего плагин отклоняется гейтом совместимости.
+// `engineApi` живёт в трёх местах (манифест, HostPlugin, ClientPlugin).
+// Расхождение между ними — рассинхрон сборки внутри пакета, и это ошибка.
+// Расхождение с установленным движком ошибкой БОЛЬШЕ НЕ является (этап 5
+// плана plugin-forward-compat): `ENGINE_API_VERSION` заморожен на 4 и не
+// гейт, а игра, собранная год назад против движка не последней версии, —
+// нормальное состояние, ради которого весь план и делался.
+//
+// Импортом, а не литералом, значение остаётся по-прежнему: литерал не
+// расходится со сборкой движка в момент написания и молча расходится через
+// релиз, после чего манифест игры врёт о своём поколении.
+//
+// Возможности из `manifest.requires` проверяются по реестру установленного
+// движка: имени, которого нет, движок дать не может — игра просит будущее.
 export default {
   id: 'B2',
   name: 'engineApiVersion',
   level: ERROR,
-  title: 'engineApi matches ENGINE_API_VERSION in all three places',
+  title: 'engineApi is consistent and requires name existing capabilities',
 
   check(ctx) {
+    // манифест первый: он — то, что о поколении пакета читает движок,
+    // и с ним сверяются половины плагина
     const declared = [
+      ['manifest', ctx.manifest?.engineApi],
       ['host plugin', ctx.hostPlugin?.engineApi],
       ['client plugin', ctx.clientPlugin?.engineApi],
-      ['manifest', ctx.manifest?.engineApi],
     ].filter(([, value]) => value !== undefined);
 
     if (!declared.length) {
@@ -22,11 +34,13 @@ export default {
     }
 
     const violations = [];
+    const [source, reference] = declared[0];
 
     for (const [where, value] of declared) {
-      if (value !== ctx.engineApi) {
+      if (value !== reference) {
         violations.push(
-          `${where} declares engineApi v${value}, this engine is v${ctx.engineApi}`,
+          `${where} declares engineApi v${value}, but ${source} declares ` +
+            `v${reference} — rebuild the package`,
         );
       }
     }
@@ -42,6 +56,15 @@ export default {
       }
     }
 
+    for (const name of ctx.manifest?.requires ?? []) {
+      if (!CAPABILITIES.includes(name)) {
+        violations.push(
+          `manifest.requires names '${name}', which this engine does not ` +
+            `provide — known capabilities: ${CAPABILITIES.join(', ')}`,
+        );
+      }
+    }
+
     return verdict(violations);
   },
 };