docs(ai): trace handler two event scheduler

docs/appendices/script-vm.md

@@ -84,14 +84,22 @@ ownership значения на FPU stack и следующий consumer, поэ
 
 `Handler(2)` (третья entry table, VA `0x10009610`) уже имеет статический
 contract, но ещё не Rust execution: он выбирает active event/instruction через
-runtime offsets `+0x48/+0x4c`, разрешает семь 32-bit slots через varset object
+runtime offsets `+0x48/+0x4c` и разрешает семь 32-bit slots через varset object
-`+0x18`, допускает integer-kind `5` и float-kind `3` для трёх numeric slots
+`+0x18`. Их доказанный dataflow: slot 0 даёт один `u32` и base string, slot 1
-(`+0x10/+0x14/+0x18`, иначе использует `0.0`), затем вызывает opaque AI object
+даёт numeric scalar, slots 2 и 3 — по `u32`, slots 4, 5 и 6 принимают только
-по `this + 0x7c` и очищает flag `+0x50`. Три первых slots передаются без
+kind `5`/`3` и иначе дают `0.0`. Затем он вызывает `0x100059f0` объекта по
-доказанной semantic type/name. Следующий закрывающий capture должен записать
+`this + 0x7c` и очищает flag `+0x50`.
-raw seven slots, resolved variable values и вход/выход вызова `0x100059f0` в
+
-controlled mission. До него compatibility VM возвращает явный unsupported
+Этот callee больше не opaque. Он строит key из семи значений, ищет matching
-result, а не «примерный» game command.
+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, key equality и consumer нового
+record остаются открытыми; до dynamic capture Rust возвращает явный
+unsupported result, а не «примерный» game command.
 
 На границе mission runtime выбранный TMA clan `first_resource` теперь
 материализуется как отдельный `MissionScriptBundle`: loader нормализует

docs/tomes/06-behavior.md

@@ -153,10 +153,12 @@ handler лишь инициирует execution context (`+0x50 = 1`); его ga
 
 Первый часто встречающийся table entry с side effect — `Handler(2)` (176
 records в corpus). Он берёт active instruction, разрешает семь slots через
-varset, приводит три значения к float по observed kinds `5`/`3`, вызывает
+varset, приводит три значения к float по observed kinds `5`/`3`, затем
-внутренний AI object и сбрасывает active flag. Смысл вызова и slot names ещё
+materializes или refresh-ит внутренний event record. Его base string связывает
-не установлены динамически, поэтому Rust не исполняет этот handler как
+`<base>_Start` и `<base>_Continue` с event table; прямого World3D/Behavior
-гипотетическую команду движения/атаки/строительства.
+call на этой ветке не найдено. Slot names и consumer record ещё не установлены
+динамически, поэтому Rust не исполняет handler как гипотетическую команду
+движения/атаки/строительства.
 
 Безопасная runtime-модель:
 

tools/ghidra/ExportAiVmHandler2Callee.java

@@ -0,0 +1,23 @@
+// Emits the opaque direct callee reached by corpus-reachable AI VM Handler(2).
+// Run through Ghidra headless analysis; the original PE remains read only.
+import ghidra.app.decompiler.DecompInterface;
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.Function;
+
+public class ExportAiVmHandler2Callee extends GhidraScript {
+    private static final long ADDRESS = 0x100059f0L;
+
+    @Override
+    public void run() throws Exception {
+        Address address = currentProgram.getAddressFactory().getDefaultAddressSpace()
+            .getAddress(ADDRESS);
+        Function function = currentProgram.getFunctionManager().getFunctionAt(address);
+        println("===== AI VM Handler(2) direct callee =====");
+        if (function == null) { println("missing"); return; }
+        DecompInterface decompiler = new DecompInterface();
+        decompiler.openProgram(currentProgram);
+        println(decompiler.decompileFunction(function, 60, monitor).getDecompiledFunction().getC());
+        decompiler.dispose();
+    }
+}