Realisation v1

2026-08-11 22:19:34 +03:00
commit aea6e330e3
194 changed files with 62580 additions and 0 deletions
@@ -0,0 +1,122 @@
+# 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
+```
+
+Каждый запуск создаёт отдельную 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).