fuse_proj: Initial operational package for 3 researchers (Pavlenko/Blizno/Moroz)

Multimodal fusion research on StripNet+GTA-UAV proxy: - 3 independent fusion tracks: condition-aware (A), token/bottleneck (B), role-aware (C) - Shared interfaces, protocol, dataset audit, baseline benchmarks - Canonical version-chain references to vault (SPEC, ANALYSIS, TRIAGE) - Personalized task plans and decision tables for each researcher - 3 generated DOCX task assignment files with milestones and DoD checklist - Full modality dropout diagnostics and missing-modality robustness requirements - Data contract, benchmark registry, experiment tracking infrastructure Operational documents: - docs/00_project/: MERIDIAN context, protocol, repository reuse guide, experiment specification - docs/01_tasks/: Master assignment + 3 individual researcher tracks + joint integration - docs/02_references/: Core literature, version-chain bases, code maps - docs/03_codebase_guides/: Existing code snapshots from vault - scripts/: gen_task_plans.js (DOCX generation), placeholder infrastructure - vendor_reference/: Snapshots of caption_test, depth_edges_annotate, existing SOFIA/SegModel code - reports/, results/, experiments/: Shared output structure for all 3 researchers 3 DOCX files generated from gen_task_plans.js (Times New Roman 14pt, GOST format): - План_заданий_Павленко_БВ.docx (Condition-Aware track, fusion API owner) - План_заданий_Близно_МВ.docx (Token/Bottleneck track, benchmark owner) - План_заданий_Мороз_ЕС.docx (Role-Aware track, data contract owner) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-06-11 17:16:57 +03:00
commit 2c6a00a4ca
155 changed files with 39765 additions and 0 deletions
--- a/docs/00_project/00_PROJECT_CHARTER.md
+++ b/docs/00_project/00_PROJECT_CHARTER.md
@@ -0,0 +1,69 @@
+# Паспорт проекта
+
+## 1. Название
+
+Совместное исследование мультимодального fusion для cross-view geo-localization на GTA-UAV-LR.
+
+## 2. Проблема
+
+RGB содержит основной визуальный сигнал, но cross-view matching осложняется различиями ракурса, масштаба, перспективы и визуального домена. Дополнительные модальности могут добавить:
+
+| Модальность | Satellite | UAV | Потенциальный сигнал |
+|---|---:|---:|---|
+| RGB | да | да | текстура, форма, пространственная компоновка |
+| Text | да | да | глобальная семантика и отличительные объекты |
+| Segmentation | да | да | land-cover и пространственная семантика |
+| Geometry | CHM | Depth | высота, рельеф, структура, масштабные признаки |
+
+Задача не сводится к конкатенации. Нужно определить, как привести модальности к совместимому представлению, где включить их в StripNet и как не потерять retrieval-сигнал RGB.
+
+## 3. Цель
+
+Разработать, реализовать и сравнить три семейства fusion:
+
+1. Condition-aware residual fusion.
+2. Token/bottleneck aggregation.
+3. Role-aware hierarchical fusion.
+
+После сравнения выбрать:
+
+- primary: лучший подтверждённый вариант;
+- fallback: более простой или стабильный вариант;
+- research-arm: перспективный вариант, требующий дальнейшей проверки.
+
+## 4. Исследовательские вопросы
+
+1. Какие модальности дают положительный вклад в cross-area R@1 поверх StripNet RGB-only?
+2. Нужна ли fusion на нескольких stages или достаточно late fusion?
+3. Следует ли segmentation, geometry и text обрабатывать разными операторами?
+4. Улучшает ли content-aware управление вкладом модальностей результат относительно static weights?
+5. Сохраняют ли bottleneck tokens достаточно spatial information?
+6. Какие схемы дают лучший Pareto trade-off accuracy, VRAM, latency и число параметров?
+7. Повторяется ли улучшение минимум на трёх seed?
+
+## 5. Не является частью проекта
+
+- Замена StripNet другим backbone.
+- Обучение на World-UAV как primary dataset.
+- Совместная обработка paired satellite и UAV до retrieval objective.
+- Использование GPS, координат или имён локаций как признаков.
+- Разработка нового caption generator.
+- Разработка новой модели depth, CHM или segmentation.
+- Случайное отключение модальностей как отдельная training-задача.
+
+## 6. Итоговые артефакты
+
+| Артефакт | Ответственный | Место |
+|---|---|---|
+| Общий API fusion | Павленко + вся команда | `src/fuse_proj/models/fusion/` |
+| Condition-aware implementation | Павленко | тот же пакет |
+| Token/bottleneck implementation | Близно | тот же пакет |
+| Role-aware implementation | Мороз | тот же пакет |
+| Единый dataloader contract | Мороз + вся команда | `src/fuse_proj/data/` |
+| Benchmark runner и aggregation | Близно + вся команда | `scripts/`, `experiments/` |
+| Общий comparative report | все | `reports/joint/` |
+| Персональные design reports | каждый сотрудник | `reports/<surname>/` |
+
+## 7. Критерий завершения
+
+Проект завершён, когда три реализации проходят одинаковые тесты, обучены по единому protocol, оценены на одинаковом cross-area split и сведены в совместный отчёт с воспроизводимым выбором primary/fallback/research-arm.
--- a/docs/00_project/01_INPUT_OUTPUT_CONTRACT.md
+++ b/docs/00_project/01_INPUT_OUTPUT_CONTRACT.md
@@ -0,0 +1,96 @@
+# Контракт входов и выходов
+
+## 1. Единица данных
+
+Одна обучающая запись содержит UAV query и один положительный satellite candidate. Для evaluation одна UAV query может иметь несколько допустимых satellite matches.
+
+## 2. Satellite view
+
+| Поле | Форма | Dtype | Нормализация | Назначение |
+|---|---|---|---|---|
+| `rgb` | `[B, 3, 256, 256]` | `float32` | ImageNet mean/std | вход StripNet |
+| `text` | `list[str]` или tokens | string/int | согласно text encoder | описание сцены без location leakage |
+| `geometry` | `[B, 1, 256, 256]` | `float32` | robust per-frame CHM normalization | высотная структура |
+| `segmentation` | `[B, 1, 256, 256]` class IDs или `[B, 17, 256, 256]` probabilities | `uint8`/`float32` | IDs `0..16` или probabilities | land-cover semantics |
+| `geometry_valid` | `[B, 1, 256, 256]` | `bool` | нет | валидные CHM pixels |
+| `segmentation_valid` | `[B, 1, 256, 256]` | `bool` | нет | валидные segmentation pixels |
+| `sample_id` | `[B]` | string | нет | только логирование, не feature |
+
+## 3. UAV view
+
+| Поле | Форма | Dtype | Нормализация | Назначение |
+|---|---|---|---|---|
+| `rgb` | `[B, 3, 256, 256]` | `float32` | ImageNet mean/std | вход StripNet |
+| `text` | `list[str]` или tokens | string/int | согласно text encoder | описание сцены без location leakage |
+| `geometry` | `[B, 1, 256, 256]` | `float32` | relative depth normalization | структура и масштабные признаки |
+| `segmentation` | `[B, 1, 256, 256]` class IDs или `[B, 17, 256, 256]` probabilities | `uint8`/`float32` | IDs `0..16` или probabilities | spatial semantics |
+| `geometry_valid` | `[B, 1, 256, 256]` | `bool` | нет | валидные depth pixels |
+| `segmentation_valid` | `[B, 1, 256, 256]` | `bool` | нет | валидные segmentation pixels |
+| `sample_id` | `[B]` | string | нет | только логирование, не feature |
+
+## 4. StripNet contract
+
+| Stage | Tensor | Spatial stride | Разрешённое использование |
+|---:|---|---:|---|
+| 1 | `[B, 64, 64, 64]` | 4 | преимущественно RGB low-level; auxiliary fusion только после отдельного обоснования |
+| 2 | `[B, 128, 32, 32]` | 8 | dense segmentation/geometry кандидаты |
+| 3 | `[B, 320, 16, 16]` | 16 | основной mid-level fusion |
+| 4 | `[B, 512, 8, 8]` | 32 | high-level fusion и readout |
+| GAP | `[B, 512]` | global | RGB anchor descriptor |
+| Projection | `[B, 1024]` | global | retrieval descriptor до L2 normalization |
+
+Backbone weights shared между satellite и UAV. Базовый вариант заморожен, адаптеры stages 3-4 рассматриваются одинаково для всех fusion families.
+
+## 5. Выход fusion-модуля
+
+Каждый `encode_view` возвращает:
+
+| Поле | Форма | Требование |
+|---|---|---|
+| `descriptor` | `[B, 1024]` | finite, L2 norm `1 +/- 1e-4` |
+| `rgb_descriptor` | `[B, 1024]` | RGB anchor для диагностики |
+| `modality_contributions` | `[B, 3]` или dict | text, segmentation, geometry |
+| `diagnostics` | dict tensors/scalars | gates, attention mass, norms, entropy |
+
+Диагностика не должна менять descriptor в eval mode.
+
+## 6. Парный forward
+
+```text
+satellite batch -> encode_view(view="satellite") -> z_sat [B, 1024]
+UAV batch       -> encode_view(view="uav")       -> z_uav [B, 1024]
+
+similarity = z_uav @ z_sat.T / temperature
+```
+
+Между двумя вызовами `encode_view` нет обмена признаками. Положительные и отрицательные связи используются только при вычислении retrieval objective.
+
+## 7. Text contract
+
+- Поддержать L1, L2, L3 или выбранную объединённую схему.
+- Пустой satellite caption обрабатывается через explicit validity mask.
+- Пустая строка не должна кодироваться как полноценный semantic signal.
+- Caption не должен содержать координаты, названия районов, file names и прямые match identifiers.
+- Text encoder и token budget фиксируются для честного сравнения fusion variants.
+
+## 8. Geometry contract
+
+- CHM и depth имеют общий ключ `geometry`, но разные preprocessing и projector parameters.
+- Нельзя считать численные значения depth и CHM сопоставимыми до view-specific normalization.
+- PNG допускается только для визуальной проверки. Для обучения использовать dense tensors/SafeTensors.
+- Любая производная карта, например depth gradient, считается внутри documented preprocessing block.
+
+## 9. Segmentation contract
+
+- Канонический набор: 17 unified classes.
+- Primary representation определяется командой на interface-freeze: class IDs + embedding или probabilities/logits.
+- Hard RGB palette images не используются как model input.
+- Редкие и отсутствующие классы не должны приводить к NaN при mask pooling.
+
+## 10. Запрещённые признаки
+
+- GPS и координаты.
+- Название карты, района или локации.
+- Индекс paired image как embedding.
+- Features второй view-ветки внутри текущего encoder.
+- Evaluation labels внутри preprocessing.
--- a/docs/00_project/02_TEAM_WORKFLOW.md
+++ b/docs/00_project/02_TEAM_WORKFLOW.md
@@ -0,0 +1,128 @@
+# Регламент совместной работы
+
+## 1. Принцип
+
+У команды три архитектурных трека, но одна кодовая и экспериментальная система. Каждый сотрудник отвечает за собственную гипотезу и одновременно за один общий слой проекта.
+
+## 2. Распределение ответственности
+
+| Область | Driver | Обязательные reviewers |
+|---|---|---|
+| Fusion API и registry | Павленко | Близно, Мороз |
+| Dataset и modality validation | Мороз | Павленко, Близно |
+| Training/eval benchmark | Близно | Павленко, Мороз |
+| Condition-aware module | Павленко | Мороз |
+| Token/bottleneck module | Близно | Павленко |
+| Role-aware module | Мороз | Близно |
+| Общая experiment matrix | Близно | все |
+| Финальная архитектурная оценка | все | все |
+
+## 3. Этапы
+
+### Gate 0. Environment audit
+
+- Проверить локальные пути двух внешних проектов.
+- Зафиксировать путь GTA-UAV RGB, captions, pair JSON и annotations.
+- Проверить checkpoint StripNet.
+- Выполнить чтение обязательного пакета.
+- Создать `reports/joint/ENVIRONMENT_AUDIT.md`.
+
+### Gate 1. Interface freeze
+
+До реализации архитектур команда совместно утверждает:
+
+1. Формат segmentation: IDs/embedding или probabilities.
+2. Формат CHM/depth и normalization.
+3. Text encoder, уровни captions и output dimension.
+4. `FusionModelBase` API.
+5. Common diagnostics keys.
+6. Baseline config и output directory convention.
+
+Результат: `reports/joint/INTERFACE_DECISION.md`. Изменения после freeze требуют записи причины и влияния на все три варианта.
+
+### Gate 2. RGB-only baseline
+
+- Один общий StripNet-only run.
+- Один общий dataloader.
+- Один общий evaluation script.
+- Smoke run на малом subset.
+- Полный baseline минимум на seed 42, затем финальный baseline на 42/123/456.
+
+Без подтверждённого baseline реализация fusion не переходит к полным запускам.
+
+### Gate 3. Independent implementation behind common API
+
+Каждый сотрудник реализует свой модуль в отдельной feature branch. Разрешены разные внутренние операторы, но входы, выходы, loss и logging одинаковы.
+
+### Gate 4. Pair review
+
+Reviewer проверяет:
+
+- shape contract;
+- отсутствие cross-view leakage;
+- корректность masks;
+- identity/residual path;
+- вычислительную сложность;
+- диагностируемость вклада модальностей;
+- тесты и gin config.
+
+### Gate 5. Smoke comparison
+
+Все три модуля запускаются:
+
+- на одном subset;
+- с одним seed;
+- на одинаковом числе batches;
+- с одинаковым optimizer/loss;
+- с logging peak VRAM и latency.
+
+Цель: найти ошибки интеграции, а не выбрать победителя.
+
+### Gate 6. Full experiment matrix
+
+После smoke comparison выполняются primary runs и выбранные ablations по общему protocol.
+
+### Gate 7. Joint decision
+
+Команда совместно заполняет decision table. Архитектура не выбирается по одному лучшему run. Учитываются mean, variance, compute, стабильность и интерпретируемость вклада модальностей.
+
+## 4. Git workflow
+
+| Действие | Правило |
+|---|---|
+| Branch | один трек на feature branch |
+| Commit | один логический change set |
+| PR | содержит design link, config, tests и ожидаемые shapes |
+| Review | минимум один назначенный reviewer, общие API требуют двух |
+| Merge | только после тестов и smoke forward |
+| Experiment tag | `FUS-{family}-{variant}-s{seed}` |
+
+## 5. Ежедневная синхронизация
+
+Короткая запись в `reports/joint/WORKLOG.md`:
+
+| Поле | Содержание |
+|---|---|
+| Сделано | конкретный код, анализ или run |
+| Проверено | tests, shapes, metrics |
+| Решение | принятое архитектурное решение |
+| Блокер | что мешает и кто помогает |
+| Следующий шаг | один проверяемый результат |
+
+## 6. Правила разрешения конфликтов
+
+1. Общий protocol имеет приоритет над удобством отдельной реализации.
+2. Если архитектуре нужен иной input contract, сначала готовится RFC с влиянием на все варианты.
+3. Если два варианта требуют несовместимых изменений, адаптация помещается внутрь variant module, а общий batch сохраняется.
+4. Изменение метрики после просмотра результатов запрещено без отдельной записи причины.
+5. Любой найденный data leakage немедленно останавливает затронутые runs.
+
+## 7. Обязательные совместные документы
+
+- `ENVIRONMENT_AUDIT.md`
+- `INTERFACE_DECISION.md`
+- `BASELINE_REPORT.md`
+- `WORKLOG.md`
+- `EXPERIMENT_STATUS.md`
+- `FINAL_COMPARISON.md`
+- `DECISION_RECORD.md`
--- a/docs/00_project/03_EXPERIMENT_PROTOCOL_GTA_UAV.md
+++ b/docs/00_project/03_EXPERIMENT_PROTOCOL_GTA_UAV.md
@@ -0,0 +1,210 @@
+# Единый экспериментальный protocol GTA-UAV
+
+## 1. Dataset
+
+Primary dataset: GTA-UAV-LR.
+
+| Компонент | Ожидаемый источник |
+|---|---|
+| UAV RGB | `drone/images/`, 33,763 изображений, исходно 512x384 |
+| Satellite RGB | `satellite/`, 14,640 изображений, 256x256 |
+| Pair labels | `cross-area-drone2sate-{train,test}.json` |
+| Captions | GTA-UAV-LR-captions для UAV и satellite |
+| Auxiliary maps | GTA-UAV-LR-aug SafeTensors |
+| Split snapshots | `caption-test/meta/train_80.json`, `test_20.json` |
+| Segmentation filter | `caption-test/meta/seg_filter.json` |
+
+Фактические пути задаются через gin и записываются в run manifest.
+
+## 2. Split
+
+- Primary: cross-area.
+- Same-area: только sanity check.
+- Train/test split не пересоздаётся для разных fusion variants.
+- Evaluation учитывает несколько допустимых satellite matches для одной UAV query.
+- Диагональная оценка одного match на query считается некорректной для GTA-UAV.
+
+### 2.1. Обязательная верификация split (Gate 0)
+
+Унаследованные снапшоты `caption-test/meta/train_80.json` / `test_20.json` создавались скриптом `make_split.py --ratio 0.8 --seed 42`. До baseline команда обязана установить и записать в `ENVIRONMENT_AUDIT.md`:
+
+1. К какому множеству пар применялся 80/20: ко всем парам или внутри официального `cross-area-drone2sate-train.json`.
+2. Если 80/20 — случайный split по всем парам, он не эквивалентен официальному cross-area протоколу (train и test делят область → задача проще). В этом случае:
+   - примary-сравнение допускается на унаследованном split (главное — одинаковость для всех вариантов);
+   - финалисты дополнительно оцениваются на официальном `cross-area-drone2sate-test.json` без дообучения;
+   - в отчётах оба числа маркируются явно: `split=inherited-80/20` и `split=official-cross-area`.
+3. Количества пар train/test и размер satellite gallery фиксируются в manifest каждого run.
+
+### 2.2. Числа датасета (для контроля аудита)
+
+| Компонент | Ожидаемое значение |
+|---|---|
+| UAV RGB | 33,763 PNG, 512×384 |
+| Satellite RGB | 14,640 PNG, 256×256, RGBA |
+| Captions UAV / satellite | 33,411 / 6,546 (покрытие ~99% / ~44.7%) |
+| Auxiliary maps | 48,403 (segm, depth, edge, chm) |
+| Seg-filter passed | 37,498 из 48,403 (исключение ≥90% background+water) |
+| Унаследованный split | train 26,966 → 24,891 после seg-filter; test 6,742 → 6,252 |
+| Test gallery | ~2,684 unique satellite tiles в test_20 |
+
+Расхождение фактических чисел с таблицей — находка data audit, а не повод молча продолжить.
+
+## 3. Common model settings
+
+| Параметр | Значение |
+|---|---|
+| Backbone | StripNet-small |
+| Input size | 256x256 |
+| Backbone sharing | shared satellite/UAV |
+| Primary backbone state | frozen |
+| Optional adaptation | одинаковые Conv-MONA stages 3-4 |
+| Descriptor dim | 1024 |
+| Descriptor norm | L2 |
+| Segmentation classes | 17 |
+| Text encoder | фиксируется на Gate 1 |
+
+## 4. Retrieval objective
+
+Primary objective: symmetric contrastive retrieval loss.
+
+```math
+L = w_{q2g} CE(z_{uav} z_{sat}^{T} / tau, y)
+  + w_{g2q} CE(z_{sat} z_{uav}^{T} / tau, y)
+```
+
+Начальная конфигурация:
+
+| Параметр | Значение |
+|---|---:|
+| `w_q2g` | 0.6 |
+| `w_g2q` | 0.4 |
+| `tau_init` | 0.07 |
+| temperature | learnable, bounded |
+| label smoothing | 0.1 |
+| sampler | mutually exclusive для снижения false negatives |
+
+Hard-negative strategy должна быть общей для всех вариантов. Нельзя включить memory bank только для одного fusion family в primary comparison.
+
+## 5. Baselines
+
+| ID | Конфигурация | Назначение |
+|---|---|---|
+| B0 | StripNet RGB-only | обязательная точка отсчёта |
+| B1 | Late concat pooled auxiliary embeddings | простой multimodal baseline |
+| B2 | Static additive residual | контроль против dynamic fusion |
+| B3 | Multi-FiLM + additive merge | сильный общий baseline |
+| A-primary | Condition-aware | трек Павленко |
+| B-primary | Token/bottleneck | трек Близно |
+| C-primary | Role-aware | трек Мороза |
+
+## 6. Общие аблации
+
+Оценочные аблации выполняются без изменения основного training protocol.
+
+| ID | Вариант |
+|---|---|
+| G-AB1 | full multimodal |
+| G-AB2 | без text на evaluation |
+| G-AB3 | без segmentation на evaluation |
+| G-AB4 | без geometry на evaluation |
+| G-AB5 | RGB + text |
+| G-AB6 | RGB + segmentation |
+| G-AB7 | RGB + geometry |
+| G-AB8 | late-only fusion |
+| G-AB9 | multi-stage fusion |
+| G-AB10 | frozen StripNet |
+| G-AB11 | StripNet + одинаковая Conv-MONA adaptation |
+| G-AB12 | shared vs view-specific auxiliary projectors |
+
+Стохастическое отключение входных модальностей в training loop не входит в protocol.
+
+## 7. Primary metrics
+
+| Группа | Метрики |
+|---|---|
+| Retrieval | R@1, R@5, R@10, MRR, AP |
+| Directions | UAV-to-satellite и satellite-to-UAV |
+| Generalization | cross-area primary, same-area sanity |
+| Improvement | delta к B0 по каждому seed и mean delta |
+| Stability | mean, std, 95% bootstrap CI |
+| Efficiency | params, trainable params, peak VRAM, latency, throughput |
+| Fusion health | contribution, gate/attention entropy, descriptor variance |
+
+## 8. Diagnostic metrics
+
+- L2 norm descriptor.
+- Per-dimension descriptor standard deviation.
+- Cosine similarity между RGB-only и fused descriptor.
+- Gradient norm по modality projectors и fusion core.
+- Contribution каждого auxiliary path.
+- Attention mass или gate statistics по модальностям.
+- CKA/cosine redundancy между modality representations.
+- Доля NaN/Inf и invalid auxiliary pixels.
+
+## 9. Seeds
+
+| Фаза | Seeds |
+|---|---|
+| Smoke | 42 |
+| Development | 42 |
+| Final primary comparison | 42, 123, 456 |
+| Expensive secondary ablations | 42, если primary effect подтверждён |
+
+## 10. Run artifacts
+
+Каждый run сохраняет:
+
+```text
+out/<experiment_id>/
+├── config/                 # копии всех gin-файлов
+├── manifest.json           # commit, seed, paths, hardware, timestamp
+├── metrics.csv             # epoch metrics
+├── eval_report.json        # final retrieval metrics
+├── diagnostics.json        # gates, attention, norms, contributions
+├── model_best.safetensors  # если нужен checkpoint
+├── model_last.safetensors
+└── logs/
+```
+
+## 11. Предварительные decision rules
+
+Fusion candidate допускается к финальным трём seed, если:
+
+1. Не хуже B0 более чем на 0.5 п.п. R@1 в smoke/full seed 42.
+2. Не содержит NaN/Inf.
+3. Дополнительный peak VRAM не превышает 6 GB относительно B0 на согласованном batch.
+4. Latency не превышает B0 более чем в 2 раза без доказанного accuracy gain.
+5. Хотя бы одна дополнительная модальность имеет измеримый положительный contribution.
+
+Primary promotion:
+
+- mean cross-area R@1 выше B0 минимум на 1.0 п.п.;
+- улучшение положительно минимум на двух из трёх seed;
+- 95% bootstrap CI для парного delta не пересекает существенное отрицательное значение;
+- нет критического modality collapse;
+- compute укладывается в RTX 4090 24 GB.
+
+Если thresholds не достигнуты, команда выбирает самый информативный отрицательный результат и формулирует, какая fusion hypothesis опровергнута.
+
+## 12. Внешние ориентиры (не targets)
+
+Из предыдущих экспериментов на GTA-UAV (другой протокол: полное обучение backbone, 100 epochs, batch 64, без auxiliary модальностей):
+
+| Конфигурация | R@1 | Комментарий |
+|---|---:|---|
+| StripNet, полный fine-tuning + ImageNet pretrain | ~0.775 | верхний ориентир возможностей backbone на этих данных |
+| Лучший компактный экспериментальный backbone | ~0.665 | средний диапазон |
+
+В этом проекте StripNet заморожен (адаптация только Conv-MONA stages 3-4), поэтому B0 будет заметно ниже верхнего ориентира — это ожидаемо и нормально. Ориентиры используются только для sanity-контроля порядка величин: B0 с R@1 около нуля или выше 0.8 — признак ошибки протокола, а не выдающегося результата.
+
+## 13. Поведение при missing modality (оценочное требование)
+
+Для каждого primary-варианта в финальном отчёте обязательна таблица: descriptor при validity=0 для каждой auxiliary модальности по очереди (eval-time, без переобучения).
+
+| Режим | Требование |
+|---|---|
+| full-modal | базовое качество варианта |
+| без text / без seg / без geometry (по одному) | descriptor конечен; деградация плавная, без обвала ниже B0 более чем на оговорённый командой порог |
+| только RGB (все aux отключены) | descriptor близок к RGB-якорю; cosine(fused, rgb_descriptor) фиксируется |
+
+Это не modality-dropout-обучение, а проверка well-posedness архитектуры (см. `06_MERIDIAN_CONTEXT.md` §5); результат входит в decision table.
--- a/docs/00_project/04_ACCEPTANCE_CRITERIA.md
+++ b/docs/00_project/04_ACCEPTANCE_CRITERIA.md
@@ -0,0 +1,72 @@
+# Критерии приёмки
+
+## 1. Общий код
+
+- [ ] Есть единый `FusionModelBase`.
+- [ ] Три fusion family зарегистрированы через один registry.
+- [ ] Все варианты принимают одинаковый view batch.
+- [ ] Все варианты возвращают `[B, 1024]` и diagnostics.
+- [ ] Batch sizes 1 и 4 проходят shape tests.
+- [ ] Satellite и UAV forward тестируются отдельно.
+- [ ] Нет координатных или paired-view features.
+- [ ] Конфигурация вынесена в gin.
+- [ ] Датасет и веса не хранятся в репозитории.
+
+## 2. Персональная архитектура
+
+Для каждого сотрудника:
+
+- [ ] Рассмотрено минимум три кандидата внутри своего семейства.
+- [ ] До реализации выбран primary и fallback.
+- [ ] Есть формулы и полная tensor table.
+- [ ] Описаны shared и view-specific параметры.
+- [ ] Рассчитаны params и оценена attention/conv complexity.
+- [ ] Есть unit tests и smoke config.
+- [ ] Есть минимум один механизм измерения вклада модальностей.
+- [ ] Есть falsification criteria.
+- [ ] Код прошёл назначенное взаимное ревью.
+
+## 3. Эксперименты
+
+- [ ] B0 запущен по общему protocol.
+- [ ] Все primary variants запущены на одном split и seed 42.
+- [ ] Финалисты запущены на 42/123/456.
+- [ ] R@1/R@5/R@10 рассчитаны с multi-match ground truth.
+- [ ] Сохранены VRAM и latency.
+- [ ] Сохранены config snapshots и git commit.
+- [ ] Выполнены общие modality ablations.
+- [ ] Выполнены персональные ablations победившего варианта каждого трека.
+
+## 4. Отчёты
+
+- [ ] Три персональных design reports.
+- [ ] Три implementation reports.
+- [ ] Общая сравнительная таблица.
+- [ ] Таблица mean/std по трём seed.
+- [ ] Pareto table accuracy/VRAM/latency/params.
+- [ ] Ошибки и failure cases с примерами.
+- [ ] Decision record с primary, fallback, research-arm.
+- [ ] Все утверждения отделяют наблюдение от гипотезы.
+
+## 5. Оценка работ
+
+| Критерий | Вес |
+|---|---:|
+| Retrieval quality и статистическая устойчивость | 30 |
+| Корректность общей интеграции | 20 |
+| Соответствие modality roles | 15 |
+| Воспроизводимость экспериментов | 15 |
+| Compute feasibility | 10 |
+| Качество анализа и falsification | 10 |
+
+## 6. Блокирующие дефекты
+
+Работа не принимается при наличии любого пункта:
+
+1. Cross-view leakage внутри encoder.
+2. Некорректная diagonal-only evaluation GTA-UAV.
+3. Разные split или loss для сравниваемых primary variants.
+4. Отсутствие RGB-only baseline.
+5. Невоспроизводимые пути и отсутствующий config snapshot.
+6. NaN/Inf в descriptor или loss без разобранной причины.
+7. Изменение общего protocol после просмотра результатов без decision record.
--- a/docs/00_project/05_REPOSITORY_REUSE_GUIDE.md
+++ b/docs/00_project/05_REPOSITORY_REUSE_GUIDE.md
@@ -0,0 +1,105 @@
+# Руководство по переиспользованию существующих проектов
+
+## 1. Проект генерации модальностей
+
+Локальный путь:
+
+```text
+C:\Users\Lisadminipc\Documents\code\depth_edges_annotate_worlduav
+```
+
+Remote:
+
+```text
+https://git.lissad.keenetic.name/Pikaliov/depth_edges_annotate_worlduav
+```
+
+### Использовать
+
+| Файл | Что взять |
+|---|---|
+| `scripts/run_gta_uav.py` | GTA-UAV layout, source mapping satellite/UAV, параметры annotation run |
+| `scripts/seg_classes.py` | канонические 17 segmentation classes |
+| `src/augmentor/io_utils.py` | SafeTensors layout и безопасная запись |
+| `src/augmentor/inference.py` | normalization и post-processing модальностей |
+| `in/config_files/*.gin` | hardware, input size, model и segmentation settings |
+| `README.md` | формат выходов и pipeline stages |
+
+### Не переносить автоматически
+
+- Хардкодированные Linux paths.
+- CLI на `argparse` из `run_gta_uav.py`; в новом проекте параметры задаются gin.
+- World-UAV-specific subset logic, если она не нужна GTA-UAV.
+- Edge modality как обязательный fusion input: в текущей постановке она не входит в full-modal contract.
+
+### Ожидаемый annotation output
+
+На одно изображение рекомендуется SafeTensors с ключами:
+
+| Key | Dtype | Shape | Использование здесь |
+|---|---|---|---|
+| `depth` | float16 | `[1,H,W]` | UAV geometry |
+| `segm` | uint8 | `[1,H,W]` | обе ветки |
+| `chm` | float16 | `[1,H,W]` | satellite geometry |
+| `edge` | float16 | `[1,H,W]` | не входит в primary input |
+
+## 2. Проект StripNet и GTA-UAV training
+
+Локальный путь:
+
+```text
+C:\Users\Lisadminipc\Documents\code\caption-test
+```
+
+Remote:
+
+```text
+https://git.lissad.keenetic.name/Pikaliov/caption-test
+```
+
+### Использовать
+
+| Файл | Что взять |
+|---|---|
+| `src/models/stripnet/model.py` | StripNet-small stages и feature maps |
+| `src/models/stripnet_encoder.py` | GAP и projection 512->1024 |
+| `src/models/stripnet/conv_mona.py` | optional common adaptation stages 3-4 |
+| `src/datasets/gtauav_dataset.py` | pair parsing, captions, multi-match ground truth |
+| `src/datasets/mutually_exclusive_sampler.py` | защита от false negatives |
+| `src/losses/multi_infonce.py` | symmetric retrieval objective |
+| `src/training/train_gtauav.py` | training utilities, logging, checkpoints |
+| `src/eval/evaluate.py` | retrieval evaluation |
+| `conf/gtauav_balanced_stripnet.gin` | исходный StripNet config |
+
+### Требуемые изменения
+
+1. Расширить dataset output auxiliary tensors и validity masks.
+2. Отделить image encoder от fusion family через общий API.
+3. Сделать fusion variant выбираемым через gin.
+4. Унифицировать diagnostics.
+5. Убрать хардкодированные пути из training config.
+6. Проверить multi-match evaluation после переноса.
+7. Сохранить один StripNet instance shared для обеих view-веток.
+
+## 2.1. Что уже скопировано в vendor_reference
+
+Для чтения без доступа к исходным репозиториям в `vendor_reference/` лежат снимки: StripNet (`model.py`, `stripnet_encoder.py`, `conv_mona.py`), GTA-UAV dataset + `mutually_exclusive_sampler.py`, losses (`multi_infonce.py`, `weighted_infonce.py`, `hard_negatives.py`), `train_gtauav.py`, `trackers.py`, `profiling.py`, `evaluate.py`, `make_split.py`, `filter_segmentation.py`, конфиги gin, а из annotation-проекта — `run_gta_uav.py`, `seg_classes.py`, `io_utils.py`, `inference.py`, `models.py`. Снимки предназначены для аудита; рабочий перенос выполняется из живых репозиториев по правилам ниже.
+
+Снапшоты split (`meta/train_80.json`, `test_20.json`, `seg_filter.json`) в vendor_reference сознательно не копировались (30+ MB данных): брать из `caption-test/meta/`.
+
+## 3. Правило переноса кода
+
+1. Сначала написать тест, фиксирующий поведение исходного компонента.
+2. Перенести минимальный необходимый модуль.
+3. Указать source project и исходный файл в module docstring.
+4. Удалить неиспользуемые зависимости только после smoke comparison.
+5. Не редактировать `vendor_reference/`; это контрольный снимок.
+
+## 4. Минимальная проверка окружения
+
+```powershell
+Test-Path 'C:\Users\Lisadminipc\Documents\code\caption-test\src\models\stripnet_encoder.py'
+Test-Path 'C:\Users\Lisadminipc\Documents\code\depth_edges_annotate_worlduav\scripts\run_gta_uav.py'
+```
+
+Дополнительно команда фиксирует фактические dataset paths в `reports/joint/ENVIRONMENT_AUDIT.md`, не добавляя их в исходный код.
--- a/docs/00_project/06_MERIDIAN_CONTEXT.md
+++ b/docs/00_project/06_MERIDIAN_CONTEXT.md
@@ -0,0 +1,103 @@
+# Контекст: место проекта в системе MERIDIAN
+
+Этот документ объясняет, частью какой большой системы является fuse_proj, почему эксперимент поставлен именно на StripNet и GTA-UAV и что произойдёт с победившей архитектурой дальше. Понимание этого контекста обязательно для всех трёх сотрудников: оно определяет вторичные критерии выбора архитектуры.
+
+## 1. Большая система: MERIDIAN
+
+MERIDIAN — асимметричная Teacher–Student система кросс-видовой геолокализации БПЛА (UAV ↔ satellite) с привилегированными модальностями (LUPI/KD) и лёгким edge-инференсом.
+
+- **Задача:** Cross-View Geo-Localization (CVGL) — поиск satellite tile, соответствующего UAV-снимку, без GPS.
+- **Teacher (cloud, training-time):** frozen DINOv3-L + дополнительные модальности (depth, CHM, segmentation, text) от готовых foundation-моделей. Teacher видит всё, его задача — построить максимально информативный fused-эмбеддинг.
+- **Student (edge, inference-time):** компактный RGB-only backbone (SOFIA), Jetson Orin NX, INT8 TensorRT, <50 мс. Student видит только RGB sat + RGB UAV и учится у Teacher через feature-KD.
+
+```
+═══ Training-time (cloud) ════════════════════════════════════════
+Teacher (multimodal, frozen):
+  T_main      DINOv3-L                                 🔵 готовый
+  T_depth     Depth-Anything-V3                        🔵 готовый
+  T_chm       CHMv2 (canopy height map)                🔵 готовый
+  T_seg       SegEarth / SegFormer                     🔵 готовый
+  T_text      DGTRS-CLIP / RemoteCLIP                  🔵 готовый
+  Fusion      ??? ← ПРЕДМЕТ ЭТОГО ПРОЕКТА              🟢 наш
+                 ↓ fused privileged embedding
+  KD bridge → Student (RGB-only, edge)
+═══════════════════════════════════════════════════════════════════
+```
+
+**Граница «готовое / своё»:** foundation-модели используются как есть и не модифицируются. Наша зона проектирования — fusion-механизм, объединяющий их выходы.
+
+## 2. Восемь входных потоков Teacher
+
+| # | Поток | View | Источник | Природа сигнала |
+|---|---|---|---|---|
+| 1 | RGB satellite | sat | датасет | основной визуальный якорь |
+| 2 | Text caption satellite | sat | VLM (Qwen3-VL) | глобальная семантика сцены |
+| 3 | CHM satellite | sat | CHMv2 | высота растительности/структура |
+| 4 | Segmentation satellite | sat | SegFormer, 17 классов | land-cover semantics |
+| 5 | RGB UAV | uav | датасет | основной визуальный якорь |
+| 6 | Text caption UAV | uav | VLM (Qwen3-VL) | глобальная семантика сцены |
+| 7 | Relative depth UAV | uav | Depth Anything | геометрия/структура сцены |
+| 8 | Segmentation UAV | uav | SegFormer, 17 классов | spatial semantics |
+
+Геометрия асимметрична намеренно: CHM-модель обучена на nadir-снимках и работает только для satellite; metric depth на UAV ненадёжен, поэтому UAV получает relative depth. Это не дефект данных, а инвариант системы.
+
+## 3. Зачем нужен этот проект (fuse_proj)
+
+Прямой перебор fusion-архитектур на полном Teacher (DINOv3-L, ~300M+ params) слишком дорог: один полный прогон занимает часы и съедает всю VRAM. Поэтому архитектурный поиск выполняется на **быстром прокси**:
+
+| Компонент | Полная система (цель) | Прокси (этот проект) |
+|---|---|---|
+| Visual backbone | DINOv3-L frozen + адаптеры | StripNet-small frozen + Conv-MONA |
+| Датасет | World-UAV / реальные данные | GTA-UAV-LR (синтетика, полная разметка) |
+| Модальности | те же 8 потоков | те же 8 потоков |
+| Выход ветки | fused embedding | L2-нормированный descriptor [B, 1024] |
+| Вопрос | — | какой КЛАСС fusion работает и почему |
+
+Прокси сохраняет главное: frozen visual anchor + лёгкие обучаемые модули, те же модальности, тот же retrieval-протокол. Вывод «какой класс fusion-операторов выигрывает и за счёт чего» переносится; конкретные гиперпараметры — нет, и это нормально.
+
+## 4. Что произойдёт с результатом
+
+1. Победившее семейство (primary) + fallback фиксируются в decision record.
+2. Primary-механизм переносится на Teacher DINOv3 (адаптация: CNN stage maps → ViT token maps) и входит в спецификацию fusion MERIDIAN.
+3. Fused-эмбеддинг Teacher становится KD-таргетом для RGB-only Student.
+4. Ваши diagnostics (вклад модальностей, gate statistics) станут инструментами анализа Teacher.
+
+## 5. Вторичный критерий: устойчивость к отсутствию модальности
+
+В production Teacher модальности могут отсутствовать или быть деградированными (нет caption у ~55% satellite tiles уже сейчас; depth/CHM могут быть зашумлены). Кроме того, на следующем этапе MERIDIAN планируется обучение с **modality dropout** (стохастическое отключение модальностей) — оно НЕ входит в ваше задание, но накладывает требование на архитектуру:
+
+> **Fusion-оператор обязан оставаться well-posed, когда любая дополнительная модальность отсутствует (validity mask = 0): выход определён, конечен и осмыслен, RGB-путь не искажается.**
+
+Сводка по классам операторов (из свежего аудита литературы, 2026-06):
+
+| Класс | Поведение при отсутствии модальности | Вердикт |
+|---|---|---|
+| Cross-attention над пулом модальных токенов | softmax перенормируется на оставшиеся токены | безопасен by construction |
+| FiLM / gating с zero-init (identity-at-init) | выпавшая модальность даёт identity | безопасен при корректной init |
+| Gated additive residual | residual = 0 → чистый RGB-путь | безопасен при корректной init |
+| Чисто multiplicative gating (выход = RGB × f(aux)) | near-zero aux уничтожает RGB-сигнал | опасен, требует additive-ветки |
+| Differential conditioning (f(Xi − Xj)) | теряет смысл при отсутствии одного из Xi | опасен |
+| SSM/Mamba cross-state fusion | состояние дестабилизируется | research-arm, не primary |
+
+Практическое следствие для всех трёх треков: тест «отключи модальность через validity mask и проверь, что descriptor конечен и близок к RGB-only» входит в обязательные unit-тесты, а поведение при missing modality — в decision table финального сравнения.
+
+## 6. Каноническая терминология
+
+| Термин | Значение в проекте |
+|---|---|
+| View | satellite или uav; кодируются независимо |
+| Modality | rgb / text / segmentation / geometry (CHM или depth) |
+| Anchor | RGB-путь StripNet, который нельзя терять |
+| Validity mask | булева маска «модальность присутствует и валидна» |
+| Identity-at-init | при инициализации fusion-модуль эквивалентен RGB-only |
+| Modality collapse | descriptor фактически зависит от одной модальности |
+| Shortcut | модальность выигрывает метрику нечестным путём (утечка, артефакт данных) |
+| LUPI | learning using privileged information: модальности доступны при обучении, недоступны на inference Student |
+| Primary / fallback / research-arm | роли вариантов в итоговом решении |
+
+## 7. Чего в этом проекте сознательно нет
+
+- Никакого modality dropout в training loop (это следующий этап MERIDIAN, отдельная задача).
+- Никакой дистилляции в Student (KD-мост строится после выбора fusion).
+- Никакой замены StripNet или обучения собственных моделей depth/seg/CHM/captions.
+- Никакого использования GPS, координат, имён локаций и paired-view признаков.