From d31d1f8eab7a2c79e349748939de01895af5de7e Mon Sep 17 00:00:00 2001
From: Valentin Popov <valentin@popov.link>
Date: Sat, 18 Jul 2026 20:40:17 +0400
Subject: feat(script): decode compiled package framing

---
 docs/appendices/script-vm.md | 27 ++++++++++++++++++++++++---
 docs/tomes/06-behavior.md    | 10 ++++++++++
 2 files changed, 34 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/appendices/script-vm.md b/docs/appendices/script-vm.md
index 5e6adb8..128acd9 100644
--- a/docs/appendices/script-vm.md
+++ b/docs/appendices/script-vm.md
@@ -10,9 +10,16 @@ messages, teleports, задачи, research и campaign transitions. Точки
 и `briefing.cfg`.
 
 `.scr` — binary package с version checks, symbol/event sections и offsets;
-полная opcode grammar не доказана. `.fml` — текстовый symbol/formula oracle;
-`varset.var` задаёт `VAR(...)`/`STRING(...)` defaults; `.trf` — NRes tables,
-чей framing подтверждён, а field semantics местами лишь consumer-inferred.
+полная 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;
+`.trf` — NRes tables, чей framing подтверждён, а field semantics местами лишь
+consumer-inferred.
 
 ## Безопасная модель исполнения
 
@@ -32,6 +39,20 @@ instruction dispatcher или jump table `.scr`: bytecode opcode table всё е
 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
+структуру. Команда
+
+```powershell
+cargo run -p fparkan-cli -- script inspect `
+  'C:\GOG Games\Parkan - Iron Strategy\MISSIONS\SCRIPTS\c1m2p.scr' --format json
+```
+
+на исходном пакете возвращает `opcode_handler_count=73`, 9 events, 17 nested
+records, 20 references и 0 trailing bytes. Это corpus evidence для reader-а,
+но не разрешение на исполнение неизвестных 73 opcodes.
+
 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 7f825ad..5e0299e 100644
--- a/docs/tomes/06-behavior.md
+++ b/docs/tomes/06-behavior.md
@@ -133,6 +133,16 @@ Wizard получает желаемое направление и corridor, а
 описывает типы, defaults, ranges и строки через макросоподобные формы
 `VAR(...)` и `STRING(...)`.
 
+Compiled package больше не opaque blob: `fparkan-script` losslessly читает
+проверенный внешний framing. Сначала идут `opcode_handler_count` и
+`event_count` (`u32 LE`), затем именованные события с NUL-terminated raw
+именем и nested records. Reader сохраняет все seven raw header words и
+references каждого record, жёстко ограничивает counts/allocations и отдельно
+сохраняет trailing bytes. На `c1m2p.scr` GOG reader получает `73` handlers,
+`9` events, `17` records и `20` references без trailing bytes. Это структура
+файла, но не таблица семантик: названия opcode/words появятся только после
+handler contracts и runtime traces.
+
 Безопасная runtime-модель:
 
 ```text
-- 
cgit v1.2.3