From 7b0900aa1a37c4c65c9a1abab7c39673b34e60b3 Mon Sep 17 00:00:00 2001
From: Valentin Popov <valentin@popov.link>
Date: Sat, 18 Jul 2026 20:46:37 +0400
Subject: [PATCH] docs(script): trace handler two contract

---
 docs/appendices/script-vm.md         | 11 +++++++++++
 docs/tomes/06-behavior.md            |  7 +++++++
 tools/ghidra/ExportAiVmHandler2.java | 23 +++++++++++++++++++++++
 3 files changed, 41 insertions(+)
 create mode 100644 tools/ghidra/ExportAiVmHandler2.java

diff --git a/docs/appendices/script-vm.md b/docs/appendices/script-vm.md
index 6836f82..d5b1607 100644
--- a/docs/appendices/script-vm.md
+++ b/docs/appendices/script-vm.md
@@ -62,6 +62,17 @@ sentinel records. Поэтому `ScriptInstruction::dispatch_selector()` воз
 (`Handler(0)`, VA `0x10008034`) только устанавливает current context и flag
 `+0x50 = 1`; это не даёт ему игрового имени и не заменяет runtime trace.
 
+`Handler(2)` (третья entry table, VA `0x10009610`) уже имеет статический
+contract, но ещё не Rust execution: он выбирает active event/instruction через
+runtime offsets `+0x48/+0x4c`, разрешает семь 32-bit slots через varset object
+`+0x18`, допускает integer-kind `5` и float-kind `3` для трёх numeric slots
+(`+0x10/+0x14/+0x18`, иначе использует `0.0`), затем вызывает opaque AI object
+по `this + 0x7c` и очищает flag `+0x50`. Три первых slots передаются без
+доказанной semantic type/name. Следующий закрывающий capture должен записать
+raw seven slots, resolved variable values и вход/выход вызова `0x100059f0` в
+controlled mission. До него compatibility VM возвращает явный unsupported
+result, а не «примерный» game command.
+
 TMA properties остаются four raw `u32` words плюс имя, пока consumer/schema не
 задаст тип (integer/float bits/ObjectId/enum/fixed-point/index). В том числе
 сохраняются `NOT USED`; corpus подтверждает `Invulnerability`, life state,
diff --git a/docs/tomes/06-behavior.md b/docs/tomes/06-behavior.md
index ad1832c..ff8dd0a 100644
--- a/docs/tomes/06-behavior.md
+++ b/docs/tomes/06-behavior.md
@@ -151,6 +151,13 @@ handler contracts и runtime traces.
 handler лишь инициирует execution context (`+0x50 = 1`); его gameplay meaning
 пока не назван.
 
+Первый часто встречающийся table entry с side effect — `Handler(2)` (176
+records в corpus). Он берёт active instruction, разрешает семь slots через
+varset, приводит три значения к float по observed kinds `5`/`3`, вызывает
+внутренний AI object и сбрасывает active flag. Смысл вызова и slot names ещё
+не установлены динамически, поэтому Rust не исполняет этот handler как
+гипотетическую команду движения/атаки/строительства.
+
 Безопасная runtime-модель:
 
 ```text
diff --git a/tools/ghidra/ExportAiVmHandler2.java b/tools/ghidra/ExportAiVmHandler2.java
new file mode 100644
index 0000000..d4f3469
--- /dev/null
+++ b/tools/ghidra/ExportAiVmHandler2.java
@@ -0,0 +1,23 @@
+// Emits Handler(2), the third function in the AI DLL's verified 73-entry VM table.
+// 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 ExportAiVmHandler2 extends GhidraScript {
+    private static final long ADDRESS = 0x10009610L;
+
+    @Override
+    public void run() throws Exception {
+        Address address = currentProgram.getAddressFactory().getDefaultAddressSpace()
+            .getAddress(ADDRESS);
+        Function function = currentProgram.getFunctionManager().getFunctionAt(address);
+        println("===== AI VM Handler(2) =====");
+        if (function == null) { println("missing"); return; }
+        DecompInterface decompiler = new DecompInterface();
+        decompiler.openProgram(currentProgram);
+        println(decompiler.decompileFunction(function, 60, monitor).getDecompiledFunction().getC());
+        decompiler.dispose();
+    }
+}