# Universal Container

Экспериментальный C++20-контейнер индексируемой последовательности, который во
время работы выбирает представление и его геометрию:

```text
contiguous vector <-> segmented tiered storage
                         |
                         +-> leaf 64 / 128 / 256 / 512 / 1024
                         +-> минимально достаточная глубина каталога
```

Это не контейнер с одним «лучшим» размером блока. `CostModelPolicy` собирает
выборочную статистику чтений и полную статистику структурных изменений,
оценивает стоимость кандидатов и выдаёт `AdaptationDecision`: целевой режим и
`TieredConfig`. Переход выполняется, только если прогнозируемая экономия на
будущем горизонте превышает стоимость O(N)-перестройки с запасом.

Проект исследовательский. Сохранённые измерения показывают, что оптимальный
leaf действительно меняется с `N`, размером элемента и локальностью правок, но
пока не доказывают превосходство adaptive-варианта во всех или в среднем по
финальной holdout-матрице. Ограничения честно перечислены в
[docs/findings.md](docs/findings.md).

`std::deque` и `std::list` присутствуют только как внешние benchmark-baselines.
Они не являются режимами контейнера: `AdaptiveSequence` переключается только
между contiguous vector и tiered storage.

## Быстрый старт

Из обычной командной строки Windows:

```bat
build.bat baseline test
```

Доступные профили:

```bat
build.bat scalar test
build.bat baseline test
build.bat avx2 test
build.bat all test
```

Проект проверен с Visual Studio 18 2026 и workload «Desktop development with
C++». `build.bat` сам находит комплектный CMake из Visual Studio. Готовые
программы находятся в
`out\bin\<profile>\Release\`:

- `uc_demo.exe` — минимальный пример;
- `uc_tests.exe` — differential/property-тесты;
- `uc_bench.exe` — benchmark runner.

Все Release-цели собираются с `/O2` и статическим MSVC runtime (`/MT`). Профиль
`scalar` — проверенный для MSVC 19.51 режим `project-novec`: внутренний ключ
`/d2Qvec-`, `/Oi-` и отключение vector algorithms STL. Это не универсальная
гарантия отсутствия SIMD внутри ABI/CRT. `baseline` оставляет штатную
автовекторизацию без AVX-флага, `avx2` добавляет `/arch:AVX2`. Перед запуском
AVX2-тестов и benchmark выполняется проверка CPU/OS; неподдерживаемый профиль
безопасно пропускается. Подробности приведены в
[docs/benchmarking.md](docs/benchmarking.md).

Полный воспроизводимый запуск:

```bat
benchmark.bat smoke
benchmark.bat quick
benchmark.bat full
```

Для multi-core сравнения `std::vector`, пяти fixed-tiered geometry и adaptive
вплоть до 100 миллионов `uint32_t`:

```bat
large_benchmark.bat smoke 12
large_benchmark.bat full 12 3
large_benchmark.bat full 12 3 huge
```

Третий аргумент ограничивает число одновременно работающих N=100M-ячеек;
значение 3 — эвристически более безопасный вариант для машины с 32 GiB RAM.
Четвёртый аргумент оставляет в матрице только N=100M.

Каждый запуск создаёт отдельную timestamp-папку в `results\benchmarks\`, куда
пишутся raw CSV, сводки и описание окружения. `out\` полностью игнорируется
Git, результаты исследования — намеренно нет.

## API

```cpp
#include <universal_container/adaptive_sequence.hpp>

uc::AdaptiveSequence<std::uint32_t> values;
values.push_back(10);
values.insert(0, 5);
values.erase(1);
auto x = values[0];

values.force_vector_mode();
values.force_tiered_mode({256, 64, 4});
values.enable_auto_mode();
values.adapt_now();             // явная безопасная maintenance point
```

Опциональный flat hash index со stable IDs:

```cpp
uc::AdaptiveSequence<std::uint32_t, true> indexed;
indexed.push_back(5);
indexed.push_back(5);
auto ids = indexed.find_all_ids(5);
indexed.erase_by_id(ids.front());
```

При включённом индексе запись через `operator[]` идёт через proxy и обновляет
индекс. Сам индекс не хранит логические позиции как ключи дубликатов.

## Каталоги

```text
include/universal_container/  публичные header-only компоненты
src/                          demo и benchmark runner
tests/                        correctness/differential tests
tools/                        анализ CSV, аудит флагов, AVX2 probe и metadata
docs/                         архитектура и выводы
results/benchmarks/           сохранённые результаты
out/build/                    промежуточная сборка (ignored)
out/bin/                      exe по профилям (ignored)
out/lib/                      библиотеки (ignored)
out/symbols/                  PDB по профилям (ignored)
```

Архитектура и контракт инвалидирования описаны в
[docs/architecture.md](docs/architecture.md).