obfuskator/docs/stack.md

Стек: почему именно так

Документ фиксирует решения, которые трудно отменить. Для каждого - альтернативы, критерии, цена и что меняет решение.

1. Собственный IR, а не API чужой библиотеки

Решение: пассы работают с noxis-classfile::model::{Program, ClassFile, Code, Insn}, а не с типами парсера.

Почему не «просто использовать готовую библиотеку целиком»:

• библиотека диктует API - каждый пасс привязывается к чужим миграциям мажорной версии (наш лимит «≤4 файлов» легко разрывается «транзитивно»);
• у нас есть конкретное требование, которого нет ни в одном парсере: Insn::Mark(Label) вместо смещений;
• мы не знаём заранее, захочет ли пользователь backend'а ещё одну библиотеку (например, для StackMapTable) - изоляция через IR даёт смену backend'а без переписывания пассов.

Что IR даёт на практике:

свойство	эффект
метки вместо смещений	пассы никогда не пересчитывают jump-офсеты
Attribute::Raw	round-trip без потерь: неизвестный атрибут возвращается как есть
Program включает ресурсы архива	переименование и патч ресурсов в одном прогоне
одна точка записи	пересчёт смещений, max_stack и StackMapTable - ровно один раз

Цена: конвертация model ↔ backend на границах (чтение и запись) - примерно один файл на направление. Дёшево.

2. Backend для чтения/записи - ristretto_classfile

Решение: format::parse / format::write реализуются поверх ristretto_classfile 0.34, наш IR остаётся единим API для пассов. Реализация - этап P1, до него обе функции возвращают Unimplemented.

Кандидаты

крейт	чтение	запись	верификация	активность	загрузки	MSRV
ristretto_classfile 0.34	✓	✓	✓ (JVMS §4.10.2)	2026-09	41k	1.97.1
jclassfile	✓	- (parser)	-	2026-08	28k	-
classfile-parser	✓	- (parser)	-	2024-10 (устарел)	31k	-
java-bytecode	✓	✓	?	2026-10	41	-
jvm-assembler	-	-	-	2015, мёртв	3k	-

Критерии и что подтвердил spike

MSRV ≤ 1.97.1 (наш тулчейн), лицензия Apache-2.0 OR MIT (совместима с нашим deny(unsafe_code)), запись, а не только чтение, разбор StackMapTable, живой апстрим (CI, бенчи, релиз 2026-09). Спайк tests/spike_ristretto.rs подтверждает round-trip, verify() и конструирование кадров.

Что отвергнуто

• Писать парсер с нуля - спецификация JVMS §4 по формату классов плюс MUTF-8, constant pool, модули, records, переполнения - это месяцы работы ради того, что уже написано и покрыто тестами. Это нарушает KISS и не добавляет ни одной защиты.
• classfile-parser, jclassfile - только чтение, значит writer всё равно наш; classfile-parser не обновлялся с 2024-10.
• java-bytecode - 41 загрузка: у проекта нет инерции и нет экосистемы.
• jvm-assembler - последний коммит в 2015.

3. StackMapTable: генерируем сами, пользуемся верификатором

Проблема. Классы версии ≥ 50 требуют StackMapTable. Любая техника, меняющая CFG (Flow), и любая, добавляющая ветки (Strings, Constants, Noise), делает сохранённые кадры неверными → VerifyError.

Решение: не считать кадры самим, а вывести их типовым выводом (JVMS §4.10.2) из готового байткода:

наш IR → Instruction[] → inference (worklist, LUB на merge-точках)
                     → кадры на каждом target'е ветвления
                     → StackMapTable → запись

ristretto_classfile содержит всё нужное в исходном виде - но снаружи, к сожалению, отдаёт не всё (см. результат спайка ниже):

• verifiers/bytecode/inference.rs - итеративный dataflow, LUB, фикспоинт;
• verifiers/bytecode/control_flow.rs - compute_successors, worklist;
• verifiers/bytecode/stackmap.rs - декодер/кэш StackMapTable;
• attributes/{max_stack,max_locals,instruction/stack_effect}.rs - пересчёт max_stack/max_locals из инструкций;
• attributes/{stack_frame,verification_type}.rs - типы для записи.

Почему это лучше, чем свои кадры: это ровно та часть JVMS, в которой ошибка невидима в исходниках и всплывает только на VerifyError в чужом рантайме. Писать такой верификатор - самая дорогая и самая опасная часть всего проекта.

Альтернативы, которые отвергнуты:

• Понижать версию класса до 49 и выкинуть StackMapTable - ломает invokedynamic/лямбды и включает дорогой fallback-верификатор; на Java 9+ это заметно и противоречит цели.
• Не делать Flow вообще - лишает технику, которая даёт ★★★★ к читаемости. Не вариант: вычислим кадры.

Результат spike'а (tests/spike_frames.rs) - главный вывод раздела:

что проверяли	что получили
verify_class + FallbackStrategy::AlwaysInference на классе с ветвлением и без StackMapTable	✅ success, path_used == Inference - движок вывода типов работает
FallbackStrategy::Strict на том же классе	✅ Err("StackMapTable required ... with control flow") - требование v50+ реально проверяется
StackMapTable с кадром не на том сдвиге	✅ Err("Merge point at offset N requires StackMapTable frame") - ошибка локализована точно
получить сам кадр из крейта	❌ нельзя

Причина последней строки: в ristretto_classfile/src/verifiers/bytecode.rs модули inference, diagnostics, frame, stackmap, control_flow объявлены как pub(crate). Публично отданы только verify, verify_class, verify_method, VerificationResult, VerifierConfig и VerificationContext. Диагностика в VerificationResult.diagnostic заполняется лишь на отдельных путях отказа, а в строгом режиме крейт возвращает Err(VerifyError) целиком - то есть ожидаемый кадр до нас не доходит, только его смещение.

Что это меняет для P1. Кадры считаем сами, а крейт используем как приёмочный тест:

наш IR → Instruction[] → наши кадры → StackMapTable → запись ристретто
                                                     ↓
                              verify_class(Strict) = Ok  → артефакт валиден

Три способа получить сами кадры, в порядке предпочтения:

1. Вендор verifiers::bytecode::inference. - отвергнут после оценки объёма. Один модуль не оторвать: в inference.rs 14 ссылок crate::, включая private-модули frame, type_system, handlers, control_flow, diagnostics. Вендорить пришлось бы весь verifiers/bytecode/ (~9 700 строк) или весь крейт (61 193 строки src/, 2.3 MB) ради одной патчи pub(crate) → pub. Чужой код становится третьей по объёму частью репозитория, отстаёт от апстрима и не проходит наши правила (250 строк / 4 файла).
2. Свой вывод на своём IR - принято. Кадры считаются по noxis::model, а не по ристретто: format::parse → IR → пассы → compute_frames(IR) → Attribute::StackMapTable → format::write. Ристретто остаётся парсером, писателем и приёмочным тестом из crates.io, без форка.
3. Итеративная починка через diagnostic - отвергнута спайком: поля expected/pre_frame в этом пути недостижимы.

Почему 2, а не 1. Наш dataflow живёт на типах, которые и так нужны пассам: Insn, метки вместо смещений, иерархия классов из noxis-analysis::hierarchy для LUB на merge-точках. Кадры - это ровно те же инструкции, что уже переписывает rename::rewrite, поэтому промежуточная конвертация model → Instruction[] → model (требование вендора) добавляет ещё один источник расхождений. Цена - своя реализация (~1 000–1 500 строк: границы блоков, worklist, merge, LUB, эмиссия StackFrame), но она покрывается двумя независимыми судьями:

наш IR → compute_frames → StackMapTable → запись ристретто
                ↓                              ↓
     noxis-verify (red-паттерны)    verify_class(Strict) = Ok
                                           ↓
                                  java -Xverify:all jar

Второй судья - ристретто verify_class со стратегией Strict - ловит ровно тот класс ошибок, ради которого вендор и рассматривался: неверный сдвиг кадра, пропущенная merge-точка, неверный тип.

Критерий готовности этапа: на всех jar из fixtures (см. todo.md) verify_class(Strict) == Ok и java -Xverify:all без VerifyError.

4. Генерация рантайма, а не вшитая таблица

Решение: noxis-runtime - это заготовки Rust-кода, из которых собирается класс-декодер (P2), а не готовый бинарь.

Почему: ABI декодера - d(Ljava/lang/String;I)Ljava/lang/String;, но схем шифрования несколько (xor-splitmix, xtea-ctr) и их число растёт. Константная таблица селекторов рядом с текстом - ровно та ошибка, которую мы разбирали (info/evo-weaknesses.md §1): ключ рядом с шифротекстом. Генератор выбирает схемы на этапе сборки артефакта и кодирует выбор в самих вызовах, а мастер-секрет выводится в рантайме.

Что нельзя делать: вшивать мастер-секрет как константу в LDC.

5. PRNG: свой, не rand

Решение: xoshiro256++ + splitmix64 + доменное разделение по FNV-1a.

• Детерминированность обязана: один seed на одинаковой версии → байт-в-байт одинаковый jar. Это свойство, а не удобство: без него воспроизводимая сборка, откат и сравнение версий невозможны.
• Доменное разделение: ctx.rng("rename/classes"), ctx.rng("noise/junk") - сид деривается из имени домена, поэтому случайности разных пассов не статистически коррелированы.
• Зависимость rand тянет OS-энтропию и меняющееся поведение между версиями. Нам нужен ровно обратный эффект.

6. ZIP: zip

Критерии: чтение, запись, сохранение порядка и сжатия, контроль дубликатов. Берём zip (стабильный релиз, без time/aes/zstd - лишние фичи только раздувают бинарь; default-features = false, features = ["deflate"]). Подпись (*.SF/*.RSA/*.DSA/*.EC) вырезаем на уровне записей архива - после перепаковки она всё равно невалидна.

Альтернатива zip6 - форк того же кода; при равном API он даёт меньше тестов и меньшую инерцию. Нет причины платить за это.

MSRV воркспейса поднят до 1.97 - это ровно наш тулчейн (rustc 1.97.1) и минимум ristretto_classfile 0.34. Заявлять 1.85, когда зависимость требует 1.97, - враньё в Cargo.toml.

7. CLI: clap (derive)

Стандарт, стабильный API, поддержка цветов и автодополнения. Альтернативы (bpaf, gumdrop, ручной парсер) экономят размер сборки, но не решают ни одной нашей задачи.

8. Верификация: java -Xverify:all первым делом

Единственная честная проверка «я ничего не сломал» - запустить настоящую JVM. noxis-verify гоняет java -Xverify:all на обфусцированном jar и по red-паттернам ищет дыры в защите.

Запасной вариант, если JDK не гарантирован: ristretto_vm - встраиваемый JVM на Rust из того же репозитория. Для нас это означает noxis-verify без внешних зависимостей. Стоит проверить в P3, пока используем системный java (в окружении есть OpenJDK 21).

Сводка

решение	альтернатива	цена
свой IR + метки	писать пассы поверх чужого API	конвертер на границе
ristretto_classfile	свой парсер / parse-only крейты	зависимость 1 уровня
inference-кадры	свой верификатор / downgrade версии	spike на публичность API
генерация декодера	вшитая таблица селекторов	сложнее собирать
свой PRNG	rand	~1 файл
java -Xverify:all	только красные паттерны	нужен JDK