docs(ai): recover expression evaluator contract

3 files changed, 62 insertions, 4 deletions

diff --git a/docs/appendices/script-vm.md b/docs/appendices/script-vm.md
index 0664bdf..5e6adb8 100644
--- a/docs/appendices/script-vm.md
+++ b/docs/appendices/script-vm.md
@@ -24,10 +24,13 @@ defaults и bindings она dispatches Init/start, на каждом tick обн
 budget. Опасное удаление идёт через World3D queue и общий deferred lifecycle.
 
 До восстановления opcode table package mode читает header/strings/symbols/
-event offsets/raw bytecode losslessly. Disassembly mode использует подтверждённую
-`ai.dll` jump table. Unknown opcode нельзя пропустить как один byte: это ломает
-синхронизацию. Для каждого доказанного opcode фиксируются number, size,
-operands, control flow, effects, errors и минимальный test.
+event offsets/raw bytecode losslessly. Статический анализ уже выделил отдельный
+five-way evaluator condition records (`ai.dll` VA `0x10005180`): tags `1..5`,
+type guards, object lookup и completion flag. Это не следует выдавать за
+instruction dispatcher или jump table `.scr`: bytecode opcode table всё ещё
+требует отдельного доказательства. Unknown opcode нельзя пропустить как один
+byte: это ломает синхронизацию. Для каждого доказанного opcode фиксируются
+number, size, operands, control flow, effects, errors и минимальный test.
 
 TMA properties остаются four raw `u32` words плюс имя, пока consumer/schema не
 задаст тип (integer/float bits/ObjectId/enum/fixed-point/index). В том числе
diff --git a/docs/tomes/06-behavior.md b/docs/tomes/06-behavior.md
index 5764bb0..7f825ad 100644
--- a/docs/tomes/06-behavior.md
+++ b/docs/tomes/06-behavior.md
@@ -154,6 +154,36 @@ IDs и отправляет команды через игровые interfaces,
 открытым направлением. До появления decompiler-а `.scr` binary body сохраняется
 lossless, а доказанные symbol/event tables документируются отдельно.
 
+### Подтверждённый evaluator выражений
+
+Ghidra 12.1.2 decompile GOG `ai.dll` фиксирует отдельный evaluator по VA
+`0x10005180` (не dispatcher инструкций `.scr`). Он получает индекс записи,
+ищет её в контейнере `this + 0x34`, переключается по `u32 tag` в offset `+0`
+и при успешном результате пишет completion byte в `+0x0c`. Из кода доказаны
+ровно пять ветвей `tag = 1..5`; `tag = 1..3` требуют `u32` subtype в
+`+0x04 == 0`, а `tag = 4..5` — `+0x04 == 1`. Поле payload находится по
+`+0x08`.
+
+Ветки 1--3 делают lookup через object/interface, достижимый от
+`this + 0x60 + 0x35c`, и используют его virtual slot `+0x1c`. Ветка 2
+дополнительно читает virtual slots `+0x10`/`+0x18` возвращённого объекта и
+разрешает result tags `1`, `0x12`, `0x13`. Ветка 3 сравнивает virtual slot
+`+0x44` с текущим object value. Ветки 4--5 используют `payload` как index в
+контейнере `this + 0x4c`, обходят его child indices и делают тот же lookup;
+их разные success-guards пока не именуются семантически. Это доказывает
+typed condition/evaluation layer, но **не** формат `.scr`, размеры инструкций
+или связь чисел tag с языковыми операторами.
+
+Выгрузка воспроизводится без изменения PE:
+
+```powershell
+& 'C:\Tools\ghidra_12.1.2_PUBLIC\support\analyzeHeadless.bat' `
+  C:\temp\fparkan-ghidra ai -import 'C:\GOG Games\Parkan - Iron Strategy\ai.dll' `
+  -processor x86:LE:32:default `
+  -scriptPath C:\Develop\fparkan\tools\ghidra `
+  -postScript ExportAiExpressionDispatcher.java -deleteProject
+```
+
 ### TRF и preload-данные
 
 TRF-файлы проходят структурный разбор. `auto.trf`, `data.trf` и tutorial
diff --git a/tools/ghidra/ExportAiExpressionDispatcher.java b/tools/ghidra/ExportAiExpressionDispatcher.java
new file mode 100644
index 0000000..1f3e8fa
--- /dev/null
+++ b/tools/ghidra/ExportAiExpressionDispatcher.java
@@ -0,0 +1,25 @@
+// Emits the decompiled AI expression evaluator containing the recovered
+// tag 1..5 dispatch. Run through Ghidra headless analysis only; it never
+// mutates the original PE image.
+import ghidra.app.decompiler.DecompInterface;
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.Function;
+
+public class ExportAiExpressionDispatcher extends GhidraScript {
+    private static final long ADDRESS = 0x10005180L;
+
+    @Override
+    public void run() throws Exception {
+        Address address = currentProgram.getAddressFactory().getDefaultAddressSpace()
+            .getAddress(ADDRESS);
+        Function function = currentProgram.getFunctionManager().getFunctionContaining(address);
+        println("===== AI expression dispatcher =====");
+        if (function == null) { println("missing"); return; }
+        println("entry=" + function.getEntryPoint());
+        DecompInterface decompiler = new DecompInterface();
+        decompiler.openProgram(currentProgram);
+        println(decompiler.decompileFunction(function, 60, monitor).getDecompiledFunction().getC());
+        decompiler.dispose();
+    }
+}