# Forensic Analysis: API Model to Ordinary YAML

## Цель

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

```text
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;
- где именно могут происходить потери данных.

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

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

и:

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

### 3. API YAML

Установить:

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

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

### `vc_org`

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

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

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

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

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

### `vc_nsxt`

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

```text
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-элемента можно проследить происхождение:

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

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

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

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

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

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

Сначала:

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

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

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