# Сценарная VM, формулы и игровые свойства

## Подтверждённый surface

Миссионный сценарный слой задаёт стартовые события, completion/failure,
messages, teleports, задачи, research и campaign transitions. Точки входа и
файлы: `ai.dll: CreateSuperAI/GetSuperAI`, `MisLoad.dll: LoadResearch`,
`ArealMap.dll: CalcFullResearchCost`, `MISSIONS/SCRIPTS/*.scr`, `*.fml`,
`*.trf`, `varset.var`, `MISSIONS/dispatcher.ini`, `mission.cfg`, `messages.cfg`
и `briefing.cfg`.

`.scr` — binary package с version checks, symbol/event sections и offsets;
полная opcode grammar не доказана. Его внешний framing читает
`fparkan-script`: первый little-endian `u32` является числом required opcode
handlers, второй — числом event records. Каждый event хранит `name_len`,
`name_len + 1` raw bytes с обязательным NUL, opaque event word и count вложенных
records. Вложенный record сохраняет семь `u32` header words (в disk order),
список `u32` references после шестого header word и trailing seventh word.
Никакой из этих words ещё не получает semantic name. `.fml` — текстовый
symbol/formula oracle; `varset.var` задаёт `VAR(...)`/`STRING(...)` defaults.
`fparkan-script::parse_varset` уже читает подтверждённые numeric
`VAR(float|DWORD, name, default)` declarations byte-safe (comments остаются
opaque, поэтому legacy non-UTF-8 text не ломает загрузку); `STRING(...)` и
`FUNCTION(...)` пока сохранены за границей этого numeric contract;
GOG `MISSIONS/SCRIPTS/varset.var` даёт через него ровно 231 declaration:
31 `float` и 200 `DWORD` (от `f0` до `fY`);
loader `ai.dll!0x10001000` сначала открывает `<bundle-base>.var` и только при
`not found` откатывается к этому shared file. Runtime повторяет данный порядок
транзакционно и публикует selected `MissionScriptVarSet` с путём/provenance, но
ещё не исполняет declarations как VM state;
`.trf` — NRes tables, чей framing подтверждён, а field semantics местами лишь
consumer-inferred.

## Безопасная модель исполнения

Новая VM разделяет immutable package (bytecode, symbols, events, constants),
per-mission variables/timers/frames, bindings logical-name/ObjectId/clan/
research key и typed commands к World3D/Behavior/UI/campaign. После varset
defaults и bindings она dispatches Init/start, на каждом tick обновляет timers,
ставит готовые events в стабильную очередь и исполняет bounded instruction
budget. Опасное удаление идёт через World3D queue и общий deferred lifecycle.

До восстановления opcode table package mode читает header/strings/symbols/
event offsets/raw bytecode losslessly. Статический анализ уже выделил отдельный
evaluator записей условий (`ai.dll` RVA `0x5180`). Его подтверждённые ветви и
точные границы описаны ниже; он не является dispatcher-ом инструкций или jump
table `.scr`. Bytecode opcode table всё ещё требует отдельного доказательства.
Unknown opcode нельзя пропустить как один byte: это ломает синхронизацию. Для
каждого доказанного opcode фиксируются number, size, operands, control flow,
effects, errors и минимальный test.

GOG `ai.dll` доказывает этот framing двумя consumer-ами: loader по
`0x10001000` открывает `<bundle>.scr`, `varset.var`, `<bundle>.fml`, затем
собирает ровно 73 pointers handlers; `0x10011b20` читает описанную count-driven
структуру. В GOG `c1m2p.scr` reader находит 73 handler slots,
9 events, 17 nested records и 20 references, заканчивая на EOF.
Это подтверждает разбор пакета, но не смысл всех opcodes.

Selector устроен следующим образом: loader `0x10001000` создаёт 73 pointers в
фиксированном порядке, а `0x10011e70` копирует их без перестановки в runtime
array. Во всех 58 GOG `.scr` первый header word каждого nested record равен
`0..72` либо `0xffff_ffff`: соответственно 2095 handler selectors и 3992
sentinel records. Поэтому `ScriptInstruction::dispatch_selector()` возвращает
`Handler(0..72)`, `Sentinel` или сохраняемый `Unknown(u32)`. Первый handler
(`Handler(0)`, VA `0x10008034`) только устанавливает current context и flag
`+0x50 = 1`; это не даёт ему игрового имени и не заменяет runtime trace.

### Evaluator записей условий: `ai.dll` RVA `0x5180`

Ниже описан отдельный слой готовых условий, а не декодирование instructions.
Результат привязан к GOG `ai.dll` версии `1.00`, SHA-256
`c19cd6cd31cd2896f8c4ba0f0e700dd3408aec8182daaf4863d98a7d233a2abc`;
PE image base — `0x10000000`, адрес функции — VA `0x10005180` / RVA `0x5180`.
Функция занимает 910 байт и имеет единственного прямого caller-а
`FUN_10004ee0` (RVA `0x4ee0`). Это статический вывод по машинному коду; сам
evaluator и его внешний объектный интерфейс здесь не запускались.

Функция принимает signed index в массив записей по `this + 0x34`. Проверенный
доступ `FUN_100070c0` возвращает 16-byte запись:

| Смещение | Поле | Роль в evaluator-е |
| ---: | --- | --- |
| `+0x00` | `u32 tag` | Выбор одной из пяти ветвей |
| `+0x04` | `u32 subtype` | Дополнительная проверка формата ветви |
| `+0x08` | payload | Ключ объекта или индекс списка, в зависимости от tag |
| `+0x0c` | byte completion | Записывается в `1` только после успешной проверки |

Общие проверки допускают только пары `(tag 1..3, subtype 0)` и
`(tag 4..5, subtype 1)`. Неизвестный tag и неподходящий subtype не завершают
условие. При провале evaluator не очищает и не меняет байт завершения; при
успехе он устанавливает его в `1`. Вызывающая функция `0x4ee0` отдельно
пропускает уже завершённые записи, поэтому этот пропуск нельзя приписывать
самому evaluator-у. Прямая запись evaluator-а в запись — только этот байт, но
вызываемые виртуальные методы могут иметь внешние эффекты.

Пары tag/subtype проверяются так:

| Запись | Условие установки флага завершения |
| --- | --- |
| `(1, 0)` | Менеджер объектов, полученный из контекста `this + 0x60` по полю `+0x35c`, ищет payload через виртуальный слот `+0x1c`; поиск должен вернуть null. Найденный объект оставляет условие незавершённым. |
| `(2, 0)` | Поиск payload через тот же слот `+0x1c` должен найти объект. Затем его слот `+0x10` должен вернуть `0`, либо слот `+0x18` должен заполнить переданную структуру результата так, чтобы её первый `u32` был `1`, `0x12` или `0x13`. |
| `(3, 0)` | Поиск должен найти объект; его слот `+0x44` должен вернуть тот же `u32`, что и первый word контекста, на который указывает поле `this + 0x60`. |
| `(4, 1)` | Payload выбирает 32-byte запись в списке `this + 0x4c`; вложенный в неё список дочерних ссылок находится по смещению `+0x0c`. Ни один проверяемый дочерний ключ не должен разрешиться в объект. |
| `(5, 1)` | Используется тот же список. Отсутствующий объект пропускается; найденный объект проходит проверку, только если его слот `+0x10` вернул `0`. Первый найденный объект с ненулевым результатом завершает обход неуспехом. |

Для tag 2 структура размером `0x138` байт инициализируется функцией
`FUN_10004330`, затем передаётся в slot `+0x18`. x87-значение, которое
возвращает этот вызов, инструкция `FSTP ST0` по RVA `0x5256` сразу удаляет со
стека FPU. Следовательно, ветвь принимает решение только по первому word
выходной структуры, а не по возвращённому числовому значению.

У tag 4 и 5 есть важная граница индекса. Сравнение payload с количеством
элементов — unsigned `CMP` с условием `JA`: только `payload > count` сразу
оставляет запись незавершённой. Значение `payload == count` проходит эту
проверку и доходит до проверенного доступа `FUN_10002e20`; тот отвергает
`index >= count` и выбрасывает C++ exception. Это не эквивалентно обычной проверке
`payload < count` с безопасным отказом для всех неверных индексов.

Сами дочерние ссылки списка читаются как signed `i32`. Ровно `-1` — sentinel,
который пропускается. Остальные значения проверяются как индексы в контекстном
массиве `context + 0x10` с 32-byte элементами; в элементе по `+0x04` берётся
ключ следующего поиска объекта. Для tag 4 первый найденный объект немедленно
прерывает обход с незавершённым результатом; для tag 5 обход прекращается на
первом найденном объекте с ненулевым результатом slot `+0x10`. Если обход
достигает конца без такого запрета, соответствующая ветвь устанавливает byte
completion.

Из этих ветвей нельзя выводить языковые имена вроде «объект уничтожен» или
«объект принадлежит игроку»: в коде подтверждены только поиски, виртуальные
вызовы, сравнения и коды результата. Неизвестно и то, какая функция создаёт
массив 16-byte записей. Считыватель `FUN_10011b20` (RVA `0x11b20`) отдельно
разбирает `.scr` с переменной длиной: событие содержит длину и байты имени,
счётчик вложенных записей, а вложенная запись — семь заголовочных `u32` и список
ссылок. При разборе reader хранит описатели событий с шагом `0x14` и описатели
вложенных записей с шагом `0x20`; это шаги элементов внутренних контейнеров, а не
фиксированные размеры записей на диске. Связь этих контейнеров с массивом
`this + 0x34` не найдена, поэтому приравнивать их нельзя. Не установлены и
объект-владелец массива, соглашение его runtime-вызова и предметные эффекты
внешних виртуальных вызовов; границы перечислены в
[`knowledge-boundaries.md`](knowledge-boundaries.md).

`Handler(1)` — второй table entry, VA `0x10007fd0`, — не создаёт игровую
команду. Он сохраняет active VM context, берёт один instruction-derived index
через current event/instruction offsets `+0x48/+0x4c`, а затем разрешает его
в varset object по `this + 0x18`. Resolver `0x10002d30` проверяет
`0 <= index < count` и возвращает record `base + index * 0x30`; invalid index
вызывает C++ exception, а не становится нулём. Полученный 48-byte record
передаётся в `0x10013190`, который возвращает x87 floating result: kinds `0`
и `4` идут через отдельный opaque conversion path, kind `1` — signed integer,
kind `2` выбирает одну из двух static scalar constants по нулевости payload,
kind `3` — float, kind `5` — unsigned integer; остальные и пустые cases дают
один fixed fallback scalar. Это доказанный numeric
bridge для VM, но пока не Rust handler: неизвестны точный disk operand slot,
ownership значения на FPU stack и следующий consumer, поэтому нельзя назвать
его арифметическим opcode или silently заменить portable `f32` execution.
Отдельный проход по всем 58 GOG `.scr` (6 087 instruction records) не нашёл
ни одного selector `1`: из них 2 095 записей выбирают один из handlers, а
3 992 являются sentinel. Значит, это установленная, но не corpus-reachable
ветка данного издания; её нельзя делать приоритетным execution path без
отдельного dynamic/evidence route.

`Handler(2)` (третья entry table, VA `0x10009610`) уже имеет статический
contract, но ещё не Rust execution: он выбирает active event/instruction через
runtime offsets `+0x48/+0x4c` и разрешает семь 32-bit slots через varset object
`+0x18`. Их доказанный dataflow: slot 0 даёт один `u32` и base string, slot 1
даёт numeric scalar, slots 2 и 3 — по `u32`, slots 4, 5 и 6 принимают только
kind `5`/`3` и иначе дают `0.0`. Затем он вызывает `0x100059f0` объекта по
`this + 0x7c` и очищает flag `+0x50`.

Этот callee больше не opaque. Он строит key из семи значений, ищет matching
record в своей collection по `this + 0x24` и при совпадении обновляет только
record fields `+0x0c` и `+0x14`, затем вызывает его refresh path `0x10005070`.
При отсутствии record он лениво ищет в event table имена `<base>_Start` и
`<base>_Continue`, сохраняет их IDs в indexed state и materializes новый
internal record. В этой ветке не видно прямого World3D/Behavior call, поэтому
это доказанная scheduler/event-record boundary, а не команда движения, атаки
или строительства. Semantic names семи slots и consumer нового record остаются
открытыми; до dynamic capture Rust возвращает явный
unsupported result, а не «примерный» game command.

У этой границы также нет скрытого immediate dispatch: после добавления новой
записи `0x100059f0` вызывает `0x1000f920`, а Ghidra 12.1.2 декомпилирует эту
функцию как пустой `return`. Следовательно, найденные `<base>_Start` и
`<base>_Continue` только кэшируются в scheduler state; их фактический consumer
находится в отдельном позднем update path.

Во всех 58 GOG `.scr` имеются 6 087 instruction records, включая 3 992
sentinel. Самый частый non-sentinel selector — `Handler(30)`, 246 records.
Его VA `0x1000c266` читает первые два слова-ссылки активной инструкции,
разрешает каждое через varset (`0x10002d30` и `0x10013570`) и вызывает внешний
обратный вызов с тремя `u32`: `(0, first, second)`. Он не принадлежит `ai.dll`:
указатель из десятого аргумента сохраняет экспорт `CreateSuperAI`. В
проверенном GOG AutoDemo он указывает на `iron3d.dll` RVA `0x611d0` (SHA-256
`d1dc4ea8535e2069b0a05c9e8be2724dd438ba44cca7a83007d8b2e50f9e35fa`).
Вызываемая функция использует ABI `__cdecl(mode, command, payload)`. При
`mode == 0`, `command == 0` аргумент `payload` со значением `0` выбирает ветвь
отказа, а `1` — ветвь завершения миссии; обе срабатывают только при условиях,
описанных ниже. Среда выполнения Rust может
записать соответствующее целевое состояние в собственный
`MissionScriptOutcome`, но не проверяет эти условия и пока не исполняет
команду из диспетчера `.scr`.
`Handler(57)` передаёт тому же обратному вызову режим `2`, для которого в
вызываемой функции есть отдельная ветвь IGame; отдельный путь жизненного цикла
передаёт режим `1`, но ветви для него в `FUN_100611d0` не найдено. По одному
вызову нельзя присвоить общее игровое имя остальным командам или называть весь
`Handler(30)` сообщением, приказом либо кодом интерфейса. Преобразователь
текстовых ссылок в varset находится за обёрткой `0x10011ea0`, в
`0x100174a0`.

`0x100174a0` добавляет каждый
recognized source declaration в encounter order как 48-byte record; GOG shared
`varset.var` не содержит `STRING(...)`, поэтому его 231 numeric `VAR` entries
образуют точно это index space. `0x10013570` возвращает `DWORD` record kind
raw `u32`; float kind проходит `__ftol`, чей x87 rounding profile ещё требует
capture. Полный GOG scan всех 246 Handler(30) instructions показывает 492
operand references: все 492 in-range и указывают на `DWORD`. Поэтому
`VarSet::resolve_handler30` уже materializes точный opaque callback command
`(mode=0, first, second)` для данного corpus path, но явно отклоняет float,
out-of-range и incomplete instructions вместо silent coercion.

Identity ровно равна
`(slot0 word, slot4 IEEE-754 bits, slot5 IEEE-754 bits)`, поэтому `-0.0` и
`+0.0` различаются. Новый 100-byte record получает slot1 в поле `+0x14`,
slot2 одновременно в `+0x24/+0x28`, slot3 в `+0x2c` и slot6 в `+0x0c`. При
совпавшем key refresh случается только когда slot1 сравнивается unequal
(включая NaN); он заменяет `+0x14` и `+0x0c`, затем прибавляет сохранённый
`+0x28` к `+0x24` с x86 wrapping arithmetic. `fparkan-script` отражает эту
изолированную часть как `Handler2RecordScheduler`; он не выполняет bytecode,
не назначает игровых имён и не делает event lookup за original VM.

Шаг прибавления проверен прямым вызовом оригинального helper-а
`FUN_10005070` (RVA `0x5070`) из GOG `ai.dll`, SHA-256
`c19cd6cd31cd2896f8c4ba0f0e700dd3408aec8182daaf4863d98a7d233a2abc`.
Исходник x86 test harness-а хранится в
[`handler2_native_oracle.cs`](../../crates/fparkan-script/tests/handler2_native_oracle.cs):
он сначала сверяет hash DLL, затем вызывает helper с 100-byte record и
проверяет оба поля. Пример воспроизведения в Windows PowerShell:

```powershell
$env:FPARKAN_ORIGINAL_AI_DLL = 'C:\GOG Games\Parkan - Iron Strategy\ai.dll'
& "$env:WINDIR\Microsoft.NET\Framework\v4.0.30319\csc.exe" /nologo /platform:x86 /out:target\Handler2NativeOracle.exe crates\fparkan-script\tests\handler2_native_oracle.cs
.\target\Handler2NativeOracle.exe
```

Полученные значения:

| `+0x24` до вызова | сохранённый `+0x28` | `+0x24` после вызова | `+0x28` после вызова |
| ---: | ---: | ---: | ---: |
| `0x00000004` | `0x00000004` | `0x00000008` | `0x00000004` |
| `0x00000008` | `0x00000004` | `0x0000000C` | `0x00000004` |
| `0xFFFFFFFF` | `0xFFFFFFFF` | `0xFFFFFFFE` | `0xFFFFFFFF` |
| `0xFFFFFFFE` | `0xFFFFFFFF` | `0xFFFFFFFD` | `0xFFFFFFFF` |

Rust-тест повторяет эти начальные значения. Для первой пары обновлений входы
несут slot 2, равный `99` и `7`, однако сохранённый при создании шаг равен `4`;
для второй пары оба счётчика и шаг начинаются с `0xFFFFFFFF`, а новые входы
несут `2` и `17`. Правило refresh читается прямо из модели:

```rust
record.counter = record.counter.wrapping_add(record.increment);
```

Native helper получает только указатель на record, поэтому напрямую проверяет
сложение текущего `+0x24` с сохранённым `+0x28`; свежий slot 2 принадлежит
сценарию Rust-теста, а не аргументам helper-а. Проверка не охватывает полный
scheduler path внутри запущенной игры.

На границе mission runtime выбранный TMA clan `first_resource`
материализуется как отдельный `MissionScriptBundle`: loader нормализует
`<base>.scr`, декодирует его тем же bounded reader-ом и публикует immutable
package вместе с clan provenance. Это именно wiring входных данных, не VM
execution: Init и остальные events пока не dispatch-ятся, а ошибка чтения сохраняет
transactional rollback mission loader-а.

TMA properties остаются four raw `u32` words плюс имя, пока consumer/schema не
задаст тип (integer/float bits/ObjectId/enum/fixed-point/index). В том числе
сохраняются `NOT USED`; corpus подтверждает `Invulnerability`, life state,
`ClanID`, ore, speed и free-time properties.

Research/economy работают в simulation: `LoadResearch` и
`CalcFullResearchCost` доказывают данные и вычислимую стоимость, но не полный
layout prerequisites/modifiers/unlocks. Formula evaluator требует strict
grammar/version, typed operands, deterministic numeric policy, bounded stack и
явных errors; x87-compatible rounding нужен там, где оно выбирает ветку.

### Handler(19): AutoDemo Init varset initialization

`Handler(19)` is the twentieth VM-table entry at GOG `ai.dll` VA `0x1000aa38`.
It is the only instruction in the `Init` event of the two `default.scr` bundles
referenced by `MISSIONS\\Autodemo.00\\data.tma`; together those bundles account for
the observed 18 named script events. Each instruction references varset records
`224`, `225`, and `226`: `ClanBaseX`, `ClanBaseY`, and `ClanID` respectively.

The original writes three raw DWORD values in order. It converts the VM fields
at `+0x80` and `+0x84` through the x87 `__ftol` helper and stores the resulting
words into references 0 and 1. It copies the raw word from `+0x7c` into reference
2, then clears VM field `+0x50`. The default targets are `DWORD` records; the
shared setter preserves the incoming word for that type. Therefore this is not
a license to replace the first two conversions with Rust float casts: their
rounding behavior remains an x87 compatibility boundary until it has captured
test vectors.

The missing source-field provenance is now constrained by the public creation
boundary. `CreateSuperAI` at `ai.dll` VA `0x1000f710` allocates `0x8b0` bytes
and calls constructor `0x10001000` with its first eight arguments. That
constructor calls `0x10006340(this + 0x7c, clan_id, base_x, base_y)`: these are
the fields later read by `Handler(19)`. `base_x` and `base_y` are unsigned and
the constructor rejects values greater than `10000`. The actual `__ftol` helper
at `0x1001df70` saves the x87 control word, sets its rounding-control bits to
truncate, executes `fistp qword`, then restores the control word.

Consequently the runtime resolves and retains this one proved vertical slice
during mission loading: each selected clan's TMA anchor is accepted only in the recovered
`0..=10000` base range, truncated through the recovered x87 rule, and paired
with its zero-based clan index. For every `Init` instruction whose selector is
`Handler(19)`, `VarSet::resolve_handler19` produces the three per-clan DWORD
writes. The runtime then materializes an independent declaration-ordered value
array for each selected clan and applies those writes, so later recovered
handlers can consume `ClanBaseX`, `ClanBaseY`, and `ClanID` as runtime cells
rather than loader defaults. Other Init selectors and all other events remain
decoded but unexecuted. AutoDemo validates the path end-to-end: its non-integral first
anchor (`500.2857`) yields captured `ClanBaseX=500`, and the live GOG process
contains two initialized SuperAI entries `(500, 752, 0)` and `(728, 449, 1)`;
the Rust loader reports `script_init_states=2` and `script_varset_states=2`.

`GetSuperAI` returns element `n` of the 64-pointer global table at preferred
`ai.dll + 0x55398` for `n <= 63`. A read-only capture of the running GOG
AutoDemo process observed `(500, 752, 0)` for entry 0 and `(728, 449, 1)` for
entry 1 at fields
`(+0x80, +0x84, +0x7c)`. These values are integral samples, not a rounding
profile.

The Rust reader exposes `VarSet::resolve_handler19`. It accepts the already
converted first two words and the third raw word, produces three typed writes,
and rejects missing, out-of-range, or non-`DWORD` targets. The runtime only
binds it to the proven creation/anchor path above; it does not guess the
remaining script event semantics.

### Аргументы и обратный вызов Handler(30)

`resolve_handler30_with_values` сохраняет восстановленное ABI типов объявлений,
но читает аргументы из экземпляра ячеек varset конкретного клана, а не из
текстовых значений по умолчанию. `resolve_loaded_handler30` возвращает точную
команду обратного вызова `(mode=0, first, second)`, не приписывая ей
дополнительный смысл. Отдельная функция `apply_loaded_script_host_callback`
моделирует в Rust состояние исхода для `(0, 0, payload=0|1)`; она не выбирает
событие `.scr` и не вызывает машинный код оригинала.

Снимок работающей GOG AutoDemo определяет обратный вызов: прочитанный без записи
указатель по `ai.dll + 0x555e4` равен `0x100611d0`, то есть `iron3d.dll +
0x611d0` при наблюдавшейся базе загрузки. Восстановленное ABI вызываемой
функции — `__cdecl(mode, command, payload)`; `Handler(30)` передаёт те же поля как
`(0, first, second)`. Обратный вызов принимает интересующую нас команду только
при `mode == 0`, `command == 0` и нулевом байте `IGame + 0xe5`. Ветвь отказа
(`payload == 0`) запускает `VOICE_MISSION_FAIL`, записывает `1` в слово `IGame + 8`
и обнуляет байт `*(IGame + 4) + 0x157`, только если прежнее слово не равно `1`.
Ветвь завершения (`payload == 1`) запускает `VOICE_MISSION_COMPLETE`, записывает
`0` в слово и устанавливает байт в `1`, только если прежнее слово не равно `0`.
Оба звуковых вызова предшествуют этим записям. Команды 3, 4 и 5 ведут к другим
ветвям игры; режим `2` выполняет отдельный вызов IGame, а ветви для режима `1`
в этой функции нет.

Статический анализ восстановил также `command == 1`, но не дал основания
присвоить этой ветви предметное имя. Её аргумент `payload` — знаковый ключ
бинарного дерева поиска. Поле `+0x04` у получателя указывает на корневой
сторожевой узел; в каждом узле ссылки на дочерние узлы лежат по `+0x08` и
`+0x0c`, ключ — по `+0x10`, а передаваемый дальше аргумент — по `+0x14`. При
совпадении ключа вызывается `FUN_10095600(node + 0x14)`. У этого объекта есть
одноразовый флаг `+0x19` и второй флаг `+0x18`. При первом вызове Iron3D
устанавливает `+0x19`, получает строку из менеджера ресурсов через виртуальный
слот `+0x1c` и передаёт значение `+0x0c` объекта-аргумента в `FUN_10061fb0`.
При повторных вызовах используются идентификаторы менеджера ресурсов `0x181a`
и `0x184f`, селектор IGame `0x2ed` и непрозрачный запрос с категорией `3` или
`4`, выбираемой по `+0x18`. Это подтверждает поиск и различие первого и
повторных вызовов, но не назначение сообщения интерфейса или смысл этих
идентификаторов; в Rust команда `1` поэтому остаётся `Unhandled`.

### Состояние обратного вызова исхода миссии

Слово `IGame + 8` создаётся не загрузчиком миссии. В исследованной GOG-сборке
`iron3d.dll` (SHA-256
`d1dc4ea8535e2069b0a05c9e8be2724dd438ba44cca7a83007d8b2e50f9e35fa`, image base
`0x10000000`) конструктор `FUN_1005c820` записывает туда `5` (RVA `0x5c84f`), а
байт `IGame + 0xe5` обнуляет (RVA `0x5c9f6`). При настройке игры функция
`FUN_1005cbb0` задаёт `+0xe5` выражением `(*AppState == 3)` (RVA `0x5cc4a`);
обработчик таймера главного меню выставляет режим `3` для AutoDemo (RVA `0x70f3`).
Отдельный обработчик выбора миссии записывает режим `1` (RVA `0x29142`) перед
переходом к пути `missions/single.*`. После успешной стандартной инициализации
игровой цикл записывает в `IGame + 8` значение `4` (`FUN_1005eb70`, RVA `0x5eb70`).
Этот переход запуска не выполняется при статическом просмотре миссии и здесь не
моделируется.

`MissionRequest` в Rust несёт явный `MissionMode::{SingleMission, AutoDemo}`;
режим задаёт вызывающая сторона и его нельзя выводить из имени пути. Во время
загрузки Rust инициализирует своё слово состояния значением `5`, как у нового
IGame, и сохраняет запрошенный режим; сама загрузка не вызывает нативный
конструктор.
Публичный `apply_loaded_script_host_callback` применяет те же интересующие нас
проверки: режим `AutoDemo` закрывает ветвь, а в `SingleMission` обратный вызов
меняет только слово состояния и исход Rust, если выполняется исходное условие
по этому слову. Поэтому при состоянии `4` ветвь завершения разрешена, как и
ветвь отказа, пока слово не равно `1`. Повторный отказ при состоянии `1` либо
завершение при состоянии `0` ничего не меняют; если тест намеренно
рассинхронизирует исход Rust и слово состояния, повтор оставляет это
расхождение. Так работает исходная проверка слова, а не выравнивание всех полей.

Изолированное сравнение с оригинальной DLL выполнено небольшой тестовой
x86-программой `crates/fparkan-runtime/tests/original_host_callback_oracle.cs`:
программа проверяет SHA-256, загружает `iron3d.dll` и вызывает RVA `0x611d0` с
синтетическими IGame и AppState. Для изоляции проверки она временно подставляет
синтетический IGame через глобальную переменную `DAT_1010a5f8` (RVA `0x10a5f8`)
и заменяет слот таблицы импортов звукового интерфейса (RVA `0xe42cc`)
регистратором; машинный код обратного вызова остаётся исходным. Проверка сверяет
записи полей, повторные/обратные переходы, блокирующий `+0xe5` и порядок вызова
звука. Это
подтверждает локальную семантику обратного вызова, но не запуск исходной миссии,
диспетчеризацию Handler(30) или весь игровой цикл. Rust пока не запускает
диспетчеризацию сценария автоматически. Команды 1, 3, 4, 5 и режим 2 остаются
`Unhandled` в этом обработчике исхода.

Повторить из корня репозитория в PowerShell на Windows с установленными GOG
ресурсами можно так:

```powershell
$env:FPARKAN_ORIGINAL_IRON3D_DLL = 'C:\GOG Games\Parkan - Iron Strategy\iron3d.dll'
New-Item -ItemType Directory -Force -Path target\original-host-callback-probe | Out-Null
& 'C:\Windows\Microsoft.NET\Framework\v4.0.30319\csc.exe' /nologo /platform:x86 /out:target\original-host-callback-probe\HostCallbackOracle.exe crates\fparkan-runtime\tests\original_host_callback_oracle.cs
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
& .\target\original-host-callback-probe\HostCallbackOracle.exe
exit $LASTEXITCODE
```

### Handler(8): problem-record state write

`Handler(8)` is the ninth VM-table entry at GOG `ai.dll` VA `0x10009b0d`.
All 179 corpus records have exactly one in-range `DWORD` reference; the two
observed entries are `ST_SOLVING=1` (122 records) and `ST_SOLVED=2` (57).
The handler resolves loader-bound `dCurrentProblem` through varset index
`this+0x868`, uses that live DWORD as a bounds-checked index into a table at
`this+0xa0` with 100-byte records, then resolves the instruction's one DWORD
and writes it to the selected record at `+0x18`.

The write has two statically proven exceptional branches. State `2` calls a
reset helper that zeroes record words `0..=3` and `6` before invoking two
opaque callback slots; state `3` does the same except word `3` is preserved.
Both then write `+0x18`. Every other state simply writes the state word.
`VarSet::resolve_handler8` emits a `Handler8StateChange` with the caller-owned
live record index, resolved state, and explicit reset kind. It does not invent
the table owner, the pre-reset helper, or callback semantics.

### Handler(15): typed target-call boundary

`Handler(15)` is the sixteenth VM-table entry at GOG `ai.dll` VA `0x10008054`
and the second most frequent non-sentinel selector: 236 records in 28 of 58
GOG packages. It is not a one-word opcode. Across the complete corpus,
references `0..3` are `DWORD`, `4..7` are `float`, and `8` is the DWORD mode.
The original resolves the first four through `0x10013570`, the next four
through x87 scalar helper `0x10013190`, then reads the mode through
`0x10013570`.

The shipped `varset.var` names the only observed mode values: `NONE=0` uses
9 total references; `TARGET_BY_LOGIC_ID=0x0201`, `TARGET_BY_TYPE=0x0203`,
`TARGET_NOT_DEFINED=0x0204`, and `TARGET_BY_NAME=0x0205` use 10; and
`TARGET_BY_PLACE=0x0202` uses 11. The corpus contains 34/122/80 records in
these three arities. The trailing references at positions 9 and, only for
`TARGET_BY_PLACE`, 10 are all in-range DWORD declarations.

After resolving those inputs, the handler looks up an opaque target through
virtual slot `+0x1c` on `this+0x3d8` using the first word. A missing target
sets VM flag `+0x50=5`; otherwise the handler builds a temporary call record,
applies the mode-specific tail, and invokes the target's `+0x0c` virtual slot
with that record and the third word. Its zero/non-zero result becomes
`+0x50=0/1`. The target type, the virtual method's semantic action, and its
return value remain unproven. Accordingly `VarSet::resolve_handler15` only
materializes a type-checked `Handler15Invocation` and `Handler15TargetPayload`;
it never executes the opaque target call. Missing, out-of-range, wrong-type,
and unobserved-mode inputs are explicit errors.

## Готовность

Все demo packages должны проходить package/version checks, offsets оставаться
в bytecode, а confirmed disassembler — не терять синхронизацию. VM считается
готовой после deterministic Init/basic mission events, stable object bindings,
typed research/property tests и save/load script state. Для закрытия остаются
dispatcher/jump table, minimal differential packages и traces world/variable
effects; до них unknown opcode — явная unsupported branch, не no-op.