tf_provider/docs/FORENSIC_ANALYSIS_BRIEF_2026-09-23.md

Forensic Analysis: API Model to Ordinary YAML

Цель

Исследовать существующую цепочку:

API model
    ↓
ordinary generator
    ↓
API YAML

Цель этапа — получить подтверждённую картину движения данных и установить, что сохраняется, преобразуется или теряется до формирования API YAML.

Этот документ предназначен для передачи Opus перед анализом.

Строгие ограничения

На этом этапе запрещено:

• изменять файлы;
• писать код;
• менять ordinary generator;
• проектировать ModifierSpec;
• проектировать modifiers.yaml;
• проектировать delete_rule;
• проектировать output layout или orchestration;
• обсуждать inverse и dependency ordering;
• придумывать API identifiers;
• придумывать parameter_path;
• придумывать HTTP method или payload structure;
• считать API YAML полным источником данных без доказательства.

Если факт невозможно установить, его нужно обозначить как unknown или как требующий проверки фактическим API. Нельзя закрывать неизвестность архитектурным предположением.

Что исследовать

1. Исходная API-модель

Установить:

• где находится canonical API model;
• в каком формате она представлена;
• как представлены services и operations;
• как представлены параметры;
• как представлены nested objects и arrays;
• как представлены типы параметров;
• существует ли стабильный operation ID;
• существует ли стабильный parameter ID;
• какие данные доступны до запуска ordinary generator.

2. Ordinary generator

Установить:

• какой input получает generator;
• где он читает API-модель;
• какие внутренние структуры строит;
• какие преобразования выполняет;
• какие поля нормализует или переименовывает;
• какие поля вычисляет;
• какие поля отбрасывает;
• где формируется API YAML;
• где именно могут происходить потери данных.

Обязательно различать:

данные отсутствуют уже в API

и:

данные присутствуют в API, но теряются ordinary generator

3. API YAML

Установить:

• какие поля сохраняются;
• какие поля представлены иначе, чем в API-модели;
• сохраняются ли nested objects и arrays;
• сохраняются ли типы;
• сохраняются ли operation identity и parameter identity;
• сохраняются ли HTTP method и path, если они есть в исходной модели;
• какие данные доступны будущему modifier layer;
• какие данные потенциально доступны только в исходной API-модели.

Обязательные трассировки

vc_org

Отдельно проследить vIPConfigure и count:

API model
    → generator input
    → internal generator representation
    → generator transformation
    → API YAML

Для каждого этапа указать:

• присутствует ли vIPConfigure;
• присутствует ли count;
• в каком типе они представлены;
• в какой структуре находятся;
• изменяются ли их имена или типы;
• теряются ли они;
• если теряются, в какой точке.

Не считать заранее известной структуру vIPConfigure или count.

vc_nsxt

Отдельно проследить ipSpaceName и связанные параметры по той же цепочке:

API model
    → generator input
    → internal generator representation
    → generator transformation
    → API YAML

Установить:

• где появляется ipSpaceName;
• к какой operation или структуре он относится;
• в каком типе представлен;
• является ли обычным полем, nested field или частью массива;
• какие связанные параметры находятся рядом;
• сохраняется ли он в API YAML;
• изменяются ли его значение или тип;
• теряются ли связанные поля.

Требования к доказательности

Каждый вывод разделять на:

• Подтверждённый факт — непосредственно виден из кода, структуры данных, фактического API input, generator input или API YAML.
• Неизвестное — информация отсутствует или неоднозначна.
• Предположение — не использовать как основание для архитектуры; только явно перечислять как неподтверждённое.

Для каждого важного вывода указывать конкретное основание: файл, функцию, структуру, входной документ или фрагмент YAML/JSON. Если точное место невозможно назвать, это указать как ограничение анализа.

Формат итогового отчёта

Отчёт должен содержать только следующие разделы:

1. Подтверждённые факты
2. Исходная API-модель
3. Как ordinary generator читает модель
4. Как формируется API YAML
5. Цепочка данных для vc_org.vIPConfigure.count
6. Цепочка данных для vc_nsxt.ipSpaceName и связанных параметров
7. Что сохраняется
8. Что преобразуется или нормализуется
9. Что теряется
10. Где происходят потери
11. Какие данные доступны в API YAML
12. Какие данные доступны только в API-модели
13. Неизвестные места
14. Что необходимо проверить фактическим API

Критерий завершения

Forensic analysis завершён только тогда, когда для каждого потенциально необходимого modifier-элемента можно проследить происхождение:

API model
    → generator input
    → internal representation
    → transformation
    → API YAML

без неизвестных промежуточных преобразований.

Для vc_org и vc_nsxt должны быть подтверждены:

operation identity
parameter identity
parameter structure
parameter type
API model representation
generator representation
YAML representation
transformation
loss or absence

Если на существенном этапе остаётся ???, исследование не завершено. Этот пункт нужно зафиксировать как unknown, а не проектировать решение.

Главный принцип

Сначала:

исследовать
    ↓
зафиксировать факты
    ↓
зафиксировать неизвестное
    ↓
отличить отсутствие данных от потери данных

Только после отдельного согласования forensic report можно переходить к проектированию ModifierSpec, modifiers.yaml, delete_rule, modifier generator, output boundary и orchestration.

На текущем этапе никаких решений по этим компонентам принимать нельзя.