# CMF v2 — Спецификация формата *Языки: [English](SPEC.md) · **Русский** · [中文](SPEC.zh.md)* **Cortiq Model Format** — единый файл, несущий всё необходимое для разреженного, маршрутизируемого по задачам инференса: квантованные веса, токенизатор, маски по задачам, предвычисленный разреженный индекс — и, что уникально, **рой скиллов**, разделяющих одну базовую модель (Patent 15). > Нормативный источник: этот документ. Референсные > реализации: Rust-ридер/рантайм (`crates/cortiq-core`, > `crates/cortiq-engine`), Python-райтер (`converter/`) и > ридер на Python без зависимостей (`python/cmf_reader.py`, только numpy). Три требования, в порядке приоритета: 1. **Корректность.** Никаких режимов тихого повреждения: строгий magic, версия, `required_features`, границы на каждую секцию, 64-битный хэш на каждый тензор. Файл либо валиден, либо open() возвращает ошибку — третьего состояния нет. 2. **Скорость.** Секция весов выровнена по странице для mmap, каждый тензор выровнен по 64 байтам (SIMD без копирования), каталог тензоров бинарный — читается без разбора. Холодные (замаскированные) веса не стоят RSS. 3. **Компактность.** Маски упакованы побитово (1 бит на нейрон), веса — q4/q8/переменной битности, весь файл адресуется одним 128-байтовым конвертом. Гармония достигается не количеством фич, а **единым каноном**: одна раскладка на уровень (конверт, каталог, квант-блок, маска), байт-в-байт совместимая с валидированным форматом `.vmfc` v2 там, где домены пересекаются (каталог тензоров, раскладки квантования, `hash64`). Никогда двух определений одного и того же. Физическая основа (VMF): модель — это вакуумный конденсат 𝒲; скилл — его регулярный кор выше критической плотности; маска задачи выбирает активное подмножество, не меняя веса. Формат несёт следствия этой физики (двухполевое 𝒲×θ квантование, Born-важность, критический порог маски) — но **только те, что подтверждены измерением**. --- ## 1. Конверт (фиксированные 128 байт) Все целые числа — little-endian. ``` [0x00 : 0x04] magic = b"CMF\x01" (4 bytes) [0x04 : 0x08] version : u32 = 2 [0x08 : 0x0C] flags : u32 (reserved, 0) [0x0C : 0x10] required_features : u32 (bitmask, §1.1) [0x10 : 0x18] header_off : u64 (= 128) [0x18 : 0x20] header_len : u64 — JSON header (§2) [0x20 : 0x28] dir_off : u64 — tensor directory (§3) [0x28 : 0x30] dir_len : u64 [0x30 : 0x38] data_off : u64 — weight blob; multiple of 4096 (§4) [0x38 : 0x40] data_len : u64 [0x40 : 0x48] masks_off : u64 — masks section (§5); 0 = absent [0x48 : 0x50] masks_len : u64 [0x50 : 0x58] vocab_off : u64 — tokenizer (§6); 0 = absent [0x58 : 0x60] vocab_len : u64 [0x60 : 0x68] index_off : u64 — sparse index (§7); 0 = absent [0x68 : 0x70] index_len : u64 [0x70 : 0x80] reserved : 16 bytes (§8.1: header/dir hashes) ``` Порядок секций на диске: конверт → JSON-заголовок → каталог → **блоб весов (выровнен по 4096)** → маски → словарь → разреженный индекс. Ридер ОБЯЗАН адресовать секции ТОЛЬКО через конверт, никогда не предполагая порядка. ### 1.1 `required_features` Бит, которого ридер не знает → ошибка `UnsupportedFeature` (fail-fast; никакого «читаем как можем»). | bit | name | значение | |-----|----------------|---------| | 0 | `TENSOR_DIR` | бинарный каталог тензоров (всегда установлен в v2) | | 1 | `BINARY_MASKS` | секция масок (§5) присутствует | | 2 | `QUANT_2F` | каталог содержит тензоры `q8_2f`/`vbit` (двухполевое 𝒲×θ квантование) | | 3 | `DELTA_MASKS` | reserved: XOR-дельты масок от родителя | | 4 | `HOT_PACKS` | reserved: материализованные плотные срезы | | 5 | `LOOP_MASKS` | ряды масок хранятся ПО ВИЗИТАМ (физические слои × циклы, проход-мажорно) — у зацикленного трансформера каждый проход несёт независимую маску (§5.1) | | 6 | `SKILL_FILE` | файл — САМОСТОЯТЕЛЬНЫЙ СКИЛЛ: частичный набор тензоров, вырезанный против конкретной базы и привязанный ключом `SkillRecord.base_dir_hash` (§9.1). Не запускается — прикладывается через `cortiq skill apply` | Неизвестные поля **header-JSON** игнорируются (аддитивная эволюция); ломающие изменения проходят только через биты фич или инкремент `version`. ### 1.2 Правила валидации (нормативные) Ридер ОБЯЗАН вернуть ошибку (не значение по умолчанию, не предупреждение), когда: - magic ≠ `CMF\x01` → `InvalidMagic`; - `version` ≠ 2 → `UnsupportedVersion` (v1 мертва: реальных файлов v1 не существует, программа поддержки не будет запущена); - установлен неизвестный бит `required_features` → `UnsupportedFeature`; - любая секция выходит за EOF, `data_off` не кратен 4096, `off + nbytes` тензора превышает `data_len` → `Bounds`; - имя тензора не UTF-8, dtype неизвестен, `ndim > 6` → `Parse`. Проверка хэша тензоров — по требованию (`cortiq verify`, флаг загрузчика), не при каждом open: страницы mmap читаются лениво. ## 2. JSON-заголовок UTF-8 JSON, без выравнивания. Критичные для машины данные живут в бинарных секциях; JSON несёт архитектуру и происхождение — те части, что читает человек. ```jsonc { "format": "cmf", "version": 2, "arch": { "arch_name": "qwen3.5", "hidden_size": 5120, "intermediate_size": 17408, "num_layers": 64, "num_attention_heads": 24, "num_kv_heads": 4, "head_dim": 256, "vocab_size": 248320, "layer_types": ["LinearAttention", "...", "FullAttention"], "rms_norm_eps": 1e-6, "norm_style": "qwen", // "qwen": x̂·w | "gemma": x̂·(1+w) "rope_theta": 1000000.0, "tie_word_embeddings": false, "max_position_embeddings": 262144, "linear_conv_kernel_dim": 4, "linear_num_key_heads": 16, "linear_num_value_heads": 48 }, "quant_type": "Q4_BLOCK", // informational default; truth = per-tensor dtype in the directory "provenance": { "tool": "…", "source_model": "…" } // optional, free-form } ``` `norm_style` обязателен для движка: gemma-стиль `(1+w)`, применённый к весам Qwen, — это тихий мусор во всех ~130 нормализациях прямого прохода. Диспетчеризация возможностей **управляется наличием тензоров**: движок решает по-слойно, какие операторы применять, по тому, что есть в каталоге (q/k-смещения, qk-нормы, выходной гейт по ширине проекции, MoE-роутер, GDN-проекции) — а не по совпадению имён моделей. Новые модели известного семейства загружаются с нулевыми изменениями движка. ### 2.1 MTP — предсказание нескольких токенов (опционально) Если модель несёт MTP-голову (в стиле DeepSeek/Qwen), arch объявляет: ```jsonc "mtp": { "num_layers": 1, "share_lm_head": true, "share_embed": true } ``` Тензоры MTP — обычные записи каталога под каноническими именами (`model.mtp.*`): `enorm.weight`, `hnorm.weight`, `eh_proj.weight [hidden, 2·hidden]`, `layers.{i}.*` (стандартный блок трансформера), `norm.weight`. Семантика: `x = eh_proj·[enorm(embed(t_{p+1})); hnorm(h_p)]` — эмбеддинг ПЕРВЫМ (проверено оракулом: обратный порядок даёт ровно 0% принятия) → блок → общий lm_head → черновик токена `t_{p+2}`. Ридер не обязан исполнять MTP (метаданные + обычные тензоры, аддитивная эволюция, без бита фичи); рантайм CMF использует голову для спекулятивного декодинга со строгой гарантией: **выход в точности равен обычному жадному декодингу** — отклонённый черновик откатывается из KV. ### 2.2 MoE — FFN со смесью экспертов (опционально) Если модель несёт MoE-слои (Qwen2-MoE / Qwen3-MoE / Qwen3.5-MoE), arch объявляет: ```jsonc "moe": { "num_experts": 256, "top_k": 8, "moe_intermediate_size": 512, "norm_topk_prob": true, // Qwen2-MoE: false "shared_expert_intermediate_size": 512 // absent if no shared expert } ``` Тензоры — обычные записи каталога под HF-именами: ``` model.layers.{i}.mlp.gate.weight [num_experts, hidden] router model.layers.{i}.mlp.experts.{e}.{gate,up,down}_proj.weight model.layers.{i}.mlp.shared_expert.{gate,up,down}_proj.weight model.layers.{i}.mlp.shared_expert_gate.weight [1, hidden] ``` Какие слои являются MoE — определяется ПРИСУТСТВИЕМ роутера в каталоге (по-слойно, не по-модельно): `mlp_only_layers`/ `decoder_sparse_step` у Qwen2-MoE дают смешанные модели, и плотные слои сохраняют обычные `mlp.*_proj`. Семантика исполнения (паритет с HF, под воротами `tests/moe_parity.sh` по четырём семействам, включая фьюженную раскладку AgentWorld): softmax по ВСЕМ логитам роутера → top-k (ничьи: меньший индекс, порядок torch.topk) → если `norm_topk_prob`, перенормировка выбранных k → Σwₑ·FFNₑ(x); общий эксперт всегда добавляется с весом `sigmoid(shared_expert_gate·x)`. Эксперты остаются квантованными в mmap; на токен затрагиваются только страницы выбранных k — та же история резидентности, что и у скиллов. Райтерам СЛЕДУЕТ раскладывать тензоры экспертов слоя ролево-смежно (все `gate_proj` экспертов 0…N−1 подряд, затем все `up_proj`, затем все `down_proj`) — GPU-бэкенды тогда работают с банком экспертов слоя как с одним регионом вместо сборки сотен слайсов; нативный импортёр и `moe-defrag` оба пишут такой порядок. Каждый эксперт — отдельная запись каталога со СВОИМ dtype: это и есть носитель по-экспертного распределения битов (P15 claim 12) — реализовано, под воротами `tests/moe_vbit.sh`; B-поле (частоты выбора роутером через `--route-stats`) измерено end-to-end на модели 35B. ## 3. Каталог тензоров Байт-в-байт раскладка `.vmfc` v2 (единый канон, общий референсный парсер): ``` [0 : 8 ] count : u64 [8 : 16] pool_off : u64 (name-pool offset from section start) [16 : 16 + count·56] 56-byte records: name_off : u32 (relative to pool_off) name_len : u16 dtype : u8 (§3.1) ndim : u8 (≤ 6) shape : u32 × 6 (zero-padded tail) off : u64 (RELATIVE to data_off; multiple of 64) nbytes : u64 hash : u64 (hash64 of the tensor bytes, §8) [pool_off : …] UTF-8 name pool ``` Имена тензоров **1:1 с исходной моделью** (`model.layers.{i}.mlp.gate_proj.weight`, `model.embed_tokens.weight`, `lm_head.weight`, …). Формат не предписывает набор тензоров: каталог — единственный источник истины о том, что содержит блоб. «Вычисляемой раскладки» не существует. ### 3.1 `dtype` Нумерация общая с `.vmfc` (id никогда не переиспользуются): | id | name | статус в CMF v2 | |----|-----------|------------------| | 0 | `f32` | ✅ чтение/запись | | 1 | `f16` | ✅ чтение/запись (нормы и 1-D всегда f16) | | 2 | `bf16` | ✅ чтение/запись | | 3 | `q8_row` | ✅ чтение/запись | | 4 | `q4_block`| ✅ чтение/запись | | 5 | `mix8_4` | reserved | | 6 | `u8` | reserved | | 7 | `q4_col` | reserved | | 8 | `vbit` | ✅ чтение/запись (бит `QUANT_2F`), переменная 3–8 бит | | 9 | `q8_2f` | ✅ чтение/запись (бит `QUANT_2F`), 𝒲×θ | | 10 | `vbit_ro` | ✅ чтение/запись — `vbit` + таблица row-offsets в файле (O(1) доступ к строке); дефолт конвертера для `--quant vbit` | | 11 | `q4_tiled`| ✅ чтение/запись — q4 интерливными тайлами `[f16 scale][16B nibbles]` (`--quant q4t`) | | 12 | `q1` | ✅ чтение/запись — 1-битные бинарные веса, только для 1-бит-ОБУЧЕННЫХ моделей (`--quant q1`); тайл `[f16 scale][4B бит-знаков]` на 32-группу, `w = s·(2·bit−1)` | | 13 | `q1s` | ✅ чтение/запись — база `q1` + разреженный оверлей выбросов высокой точности (1-битный PTQ обычных чекпойнтов) | | 14 | `q1t` | ✅ чтение/запись — тернарные `{−s, 0, +s}` base-3-тайлы + построчный оверлей выбросов (~2.25 bpw + оверлей) | | 15 | `q4tp` | ✅ чтение/запись — ниббли `q4_tiled`, но масштаб тайла — 5-битная ступень на лестнице строки (`--quant q4tp`, либо `requant` на месте) | ### 3.2 Раскладки квантования (канон = `.vmfc`: «сначала кванты, затем скейлы») - **`q8_row`** (только 2-D `[out, in]`): `[int8 : out·in][f16 : out]` — один скейл на строку, `w = q[o,i]·scale[o]`, `scale[o] = absmax(row_o)/127`. - **`q4_block`**: группы по 32 над уплощённым тензором, с нулевым добиванием; `[u8 : ceil(n/32)·16][f16 : ceil(n/32)]`. - **`q4tp`** (только 2-D, `in % 32 == 0`): `[ниббли: rows·gpr·16][параметры строки: rows × (f16 lo, f16 step)] [коды: rows × ceil(gpr·5/8), 5 бит LSB-first, выровнено по строке]`, `gpr = in/32`. Масштаб тайла — `2^(lo[r] + code·step[r])`, поэтому читатель раскрывает 32-ступенчатую лестницу строки один раз и дальше берёт масштабы из таблицы. Значения и порядок нибблов совпадают с `q4_tiled`, отличается только представление масштаба: 4.17 бит/вес против 4.50 — f16-масштаб занимал 11% q4t-файла. `lo`/`step` берутся из точных min/max логарифма масштаба по строке, поэтому код никогда не выходит за диапазон и escape-механизм не нужен. Кодировщик ОБЯЗАН округлить `lo`/`step` до f16 **перед** выбором кодов и квантовать ниббли по восстановленному масштабу — иначе писатель и читатель разойдутся (та же ловушка, из-за которой q4-кодер сначала округляет свой масштаб). Ниблы: элемент `2k` младший, `2k+1` старший; `w = (q − 8)·scale`, `scale = absmax(group)/7`. - **1-D тензоры и тензоры < 32 элементов всегда `f16`** (точность нормализации при максимальном сжатии матриц). - **`q8_2f`**: `[int8][f16 row-scale][f16 col-field]`, `w = q·scale[o]·col[i]` — двухполевой Madelung-сплит 𝒲×θ, валидирован в vmfcore (+37% при равном размере; восстанавливает ~75% разрыва q8→f16 на выбросных входных каналах). - **`vbit`** (только 2-D, `in % 32 == 0`; P13 FIG.3): `[u8 bits: rows][f16 scales: rows·in/32][bit-packed rows, MSB-first, each row padded to a byte]`; `w = (u − L)·scale[r,g]`, `L = 2^{b−1}−1`, уровни b ∈ {3,4,5,6,8}, пол 3 (claim 13). Распределение b_r: water-filling по логарифму амплитуды строки к средней битности тензора; для MoE-экспертов бюджет ОБЩИЙ на всё семейство (слой × проекция): сдвиг `ā_expert − ā_family` эквивалентен совместному water-filling по строкам всех экспертов — громкий эксперт получает больше бит, тихий прижимается к полу (P15 claim 12; ворота `tests/moe_vbit.sh`). Опционально распределение берёт произведение с B-полем — частотами выбора роутером, собранными на калибровке (`b ∝ log2(A·B)`, усечённый Fisher). - **`q1s`** (только 2-D, `in % 32 == 0`): база `q1` (те же 6-байтные тайлы; выбросы ИСКЛЮЧЕНЫ из группового скейла), затем разреженный оверлей: `[u32 count]` и `count × { [u32 плоский-индекс][f16 значение] }` — веса-выбросы, сохранённые в полной точности (голографический перенос / стиль SpQR) и восстанавливаемые дословно при деквантовании. Переменная длина: `expected_nbytes` не определён, ридер доверяет записанному в каталоге размеру. Позволяет ОБЫЧНОМУ чекпойнту пережить 1 бит там, где чистый `q1` не может. - **`q1t`** (только 2-D, `in % 32 == 0`, `in` должен помещаться в `u16`): тернарный BitNet-b1.58-стиль `{−s, 0, +s}`. База: `на 32-группу { [f16 scale][7B base-3 коды] }` — 9-байтные тайлы, 5 тернарных значений на байт (3⁵ = 243 ≤ 256; код 0 → 0, 1 → +s, 2 → −s), ~2.25 бит/вес. Затем построчный оверлей выбросов: `[u32 row_ptr[rows+1]]` и записи `{ [u16 col][f16 значение] }`, сгруппированные по строкам (выбросы строки `r` — диапазон `[row_ptr[r], row_ptr[r+1])`; `col` — индекс внутри строки) — 4 байта на выброс, без бинарного поиска. Точное сохранение множества почти нулевых весов — решающий PTQ-выигрыш над бинарным. Переменная длина, правило размера как у `q1s`. ## 4. Блоб весов `data_off` кратен 4096 (выровненный по странице mmap); каждый тензор внутри начинается на границе 64 байт (SIMD-загрузки, кэш-линии). Нулевое добивание между тензорами. Ридер интерпретирует блоб только через каталог. ## 5. Секция масок Маска задачи = битовые поля «что активно» над общими весами (веса не меняются — принцип VMF: скилл выбирает подмножество конденсата). ``` [0 : 4] n_masks : u32 [4 : 8] meta_len : u32 [8 : 8 + meta_len] JSON meta (§5.1) […] mask blobs, each aligned to 8 from the section start ``` Один блоб маски (размеры выводятся из arch, без внутренних заголовков): ``` [n_layers × ffn_bytes] FFN bitfields ffn_bytes = ceil(intermediate_size / 8) [n_layers × head_bytes] head bitfields head_bytes = ceil(num_attention_heads / 8) [gates_bytes] layer_gates gates_bytes = ceil(num_layers / 8) [n_layers × expert_bytes] expert bitfields ОПЦИОНАЛЬНО — только когда мета маски ставит "has_expert_fields": true; expert_bytes = ceil(moe.num_experts / 8) ``` Порядок битов LSB-first: нейрон `i` = бит `i % 8` байта `i / 8`; бит установлен → активен. **Хвостовые биты за пределами размерности ОБЯЗАНЫ быть нулём** (иначе popcount видит фантомные нейроны/головы). Опциональная экспертная область (аддитивно: старые ридеры не читают дальше gates, а `blob_len` каждой маски явный) позволяет задачной маске сужать РОУТИНГ MoE: бит `e` строки слоя `l` установлен → эксперт `e` маршрутизируем для этой задачи; выбор идёт только по маршрутизируемым, softmax роутера ренормализуется по ним. Это переключаемый в рантайме близнец физического дефрага экспертов из §11.1 — один файл с полным набором экспертов обслуживает много специалистов (`cortiq moe-mask` пишет такие маски, `run --task <имя>` активирует; проверено токен-в-токен с эквивалентным рантайм-ограничением). Слой со строкой все-единицы — без ограничения; маска без области ничего не сужает. ### 5.1 JSON-мета маски ```jsonc { "default_task": "general", "masks": [{ "task_id": 0, "name": "general", "description": null, "sparsity": 0.62, "quality": { // null = NOT MEASURED (declaring 1.0 is forbidden) "metric": "heldout_ppl_ratio", "value": 0.97, "baseline_dense": 6.10, "n_samples": 512, "dataset_sha256": "…" }, "parent": null, "priority": "Fallback", "has_hot_pack": false, "blob_off": 4096, "blob_len": 139328 // relative to section start }] } ``` `quality` — это **контракт на held-out**, а не декларация: конвертер без измеренной метрики пишет `null`; рантайм логирует предупреждение при переключении на неизмеренную маску. ## 6. Секция токенизатора Байты HuggingFace `tokenizer.json`, дословно. Модель самодостаточна: один файл = одна единица распространения. Sidecar-файл остаётся отладочным запасным вариантом. ### 6.1 Chat-бандл (`header.tokenizer_config`) Файл — а не рантайм-бинарник — определяет поведение чата. Заголовок несёт опциональный блок (аддитивная эволюция, без бита фичи): ```json "tokenizer_config": { "chat_template": "", "eos_token_ids": [248044, 248045], "bos_token_id": null, "pad_token_id": 248055 } ``` Рантайм рендерит шаблон с семантикой HF (trim_blocks, lstrip_blocks, управление циклами, строковые методы Python) и останавливает генерацию на любом id из `eos_token_ids`. Ворота: `tests/chat_template_parity.sh` — рендер рантайма равен референсному jinja2 байт-в-байт. Файлы без блока получают ChatML-fallback. ## 7. Разреженный индекс Предвычисленный мост «маска → пропуск вычислений»: активные квант-группы FFN (по 32 нейрона каждая) и головы, на пару (задача, слой). > Честный статус: движок берёт активные индексы напрямую из битовых > полей маски; индекс читается и отображается CLI, но в исполнении не > использовался никогда. **Кандидат на деприкацию**: райтерам СЛЕДУЕТ > перестать его писать (ридеры продолжают понимать существующие файлы); > он оживёт, только если путь «маски × квантованный mmap» > материализуется с измеренным выигрышем. ``` [0 : 4] n_entries : u32 [4 : 8] reserved : u32 (0) entry (4-aligned): task_id : u32 layer_idx : u32 n_groups : u32 n_heads : u32 [u16 × n_groups] active FFN-group indices (sorted) [u8 × n_heads] active head indices (sorted) zero padding to a multiple of 4 ``` Группа активна, если содержит хотя бы один активный бит маски. ## 8. `hash64` Некриптографический 64-битный хэш байтов тензора: murmur3 `fmix64` над 64-битными LE-словами с позиционной солью `i·0x9E3779B97F4A7C15`, XOR-свёртка, `xor len`, финальный `fmix64`. Бит-в-бит совместим с `vmfcore.hash64` (Python) и `vmfcore::hash64` (Rust) — хэши общих тензоров совпадают между `.cmf` и `.vmfc` (дедупликация базовой модели между файлами скиллов бесплатна). Использование: `cortiq verify` (детекция повреждений), дедупликация, ключи кэша. ### 8.1 Хэши секций Целостность метаданных (не только тензоров): - Резерв конверта `[0x70:0x78]` = hash64(JSON-заголовок), `[0x78:0x80]` = hash64(каталог). Ноль = «отсутствует» (старые файлы проходят). - JSON-заголовок несёт `section_hashes` — hex hash64 масок/словаря/индекса (u64 как JSON-число потерял бы точность за 2^53). Хэш заголовка в конверте транзитивно покрывает их. - Сам конверт (первые 0x70 байт) не хэшируется: хэш не может защитить сам себя; повреждённые смещения ловятся границами/хэшами дальше по цепочке. - `cortiq verify` проверяет всю цепочку; единственный перевёрнутый байт заголовка — это ошибка. ### 8.2 Отсоединённая подпись (аутентичность, опционально) Хэш-цепочка доказывает целостность, но не авторство. `cortiq sign` пишет отсоединённый `.sig` — JSON `{alg: "ed25519-sha256", pubkey, sha256, sig}`, Ed25519 поверх SHA-256 файла — сам контейнер не переписывается, старый инструментарий не затронут. `cortiq verify` проверяет подпись автоматически, когда `.sig` лежит рядом с моделью; отсутствие — не ошибка. Ключ — файл с 32-байтовым hex-сидом, который подписант хранит приватно. ## Анти-фичи — чего формат намеренно НЕ имеет - **Вычисляемой раскладки весов** — баг-класс #1 в v1 (райтер и ридер «вычисляли» раскладку независимо и расходились). - **Тихих fallback'ов** — v1 интерпретировала любой мусорный файл как «модель 27B»; v2 обязана падать. - **JSON для битовых данных** — маски v1 в JSON раздувались в 3–4×. - **Декларативных полей** — `quality_score: 1.0` по умолчанию, «ёмкости» по закону площади, Born-множители в динамике: метафора не становится полем формата, пока не измерена. ## 9. Скиллы — рой в одном файле (Patent 15, claims 2/12/15) Одна общая базовая модель + K записей на скилл; ни одна запись не хранит полную модель. Хранилище масштабируется как |backbone| + Σ|deltas|. **Замещающие тензоры** — обычные записи каталога с именами `skill.{skill_id}.{name_of_replaced_tensor}`, напр. `skill.sql.model.layers.3.mlp.gate_proj.weight`. Полная логическая форма замещаемого тензора (full-shape — НЕ low-rank, НЕ список diff, НЕ маска), в любой кодировке §3. Помасочный delta-индекс (claim 2) материализуется каталогом: префиксный фильтр даёт скилл → байт-смещения; ленивая пейджинг = mmap-доступ ровно к тем смещениям (claim 12). **Реестр** — JSON-заголовок, аддитивный: ```json "skills": [{ "id": "sql", "name": "SQL assistant", "layers": [3, 4, 5], "selection": {"metric": "mse", "phi_layer": 20, "mean": "", "basis": ""}, "input_mask_task": null, "quality": {"metric": "ppl", "backbone": 21.4, "overlaid": 17.9, "dataset_sha256": "…"} }] ``` `selection` держит параметры аффинного подпространства для маршрутизации recon-argmin (`E = ‖r − BBᵀr‖²/‖φ‖²`, выбирается скилл с минимальным E); файл самодостаточен для отбора. `quality` — честный контракт claim-16 (overlaid против backbone на held-out данных). **Семантика исполнения (claims 1/3/18)**: индирекция источника тензора — для каждого тензора рантайм читает ЛИБО запись базовой модели, ЛИБО `skill.{active}.{name}`, если она есть; замещение вместо сложения, полная модель на скилл никогда не собирается (все тензоры — указатели в один mmap). Мягкая суперпозиция (claim 14): смешанные рабочие тензоры `Σwᵢ·Tᵢ`, `wᵢ = softmax(−E/T)`. **Только-добавочный рост (claim 11)**: добавление скилла = дописывание новых тензоров в хвост файла + переиздание каталога/заголовка/индекса в хвост + обновление смещений конверта на месте (смещение 0 фиксировано). Байты и смещения ранее записанных тензоров никогда не меняются; старые байты dir/header становятся мёртвыми хвостами секций (совместимо: ридеры навигируют только через конверт). Компактификация (`converter/cmf_compact.py`) = обычная перезапись. ### 9.1 Самостоятельные скилл-файлы (`SKILL_FILE`, бит 6) Скилл может путешествовать БЕЗ своей базы: `.cmf`, чей набор тензоров — только то, что изменил бейк (плюс каталог масок), привязанный к базе ключами идентичности в записи реестра: ```json "skills": [{ "id": "gfx-html", "layers": [0, 1, "...", 21], "base_dir_hash": "9f22593eb458bc6f", "base_arch": "nanbeige", "task": "specialist", "provenance": {"corpus": "…", "tensors": 30} }] ``` - `base_dir_hash` — hex `hash64` байтов каталога тензоров БАЗЫ (то же значение конверт несёт по адресу `[0x78]`). Скилл — дельта против точных байтов, а не против архитектуры: `apply` ОБЯЗАН отвергнуть базу с другим хешем каталога (явный `--force` может переопределить; результат вне спецификации). - `base_arch`, `task`, `provenance` — информационные ключи: человеческая проверка, задача каталога масок, происхождение. Любая запись с `base_dir_hash` поднимает бит 6: читатель до этого бита откажет громко, а рантайм, знающий бит, откажется ЗАПУСКАТЬ файл (частичный набор тензоров — не модель) и укажет на `cortiq skill apply <база> <скилл> -o out.cmf`, который проверит ключ, наложит тензоры и маски поверх базы и запишет полный файл — байт-эквивалент специалиста, из которого скилл был вырезан. Жизненный цикл: `skill bake` (специалист) → `skill export --base` (дельта + ключи) → публикация маленького файла → `skill apply` на любой копии базы. Статус: полностью реализовано и под воротами (контейнер + индирекция, продакшн-рецепты, маршрутизация recon-argmin, только-добавление + компактификация, soft-blend); claim 16 подтверждён измерением (−24.9% task-PPL в рантайме). ## 10. Шардинг — модель в N файлах Именование: `{base}-{no:05}-of-{count:05}.cmf` (духовно совместимо с safetensors). Пользователь открывает ЛЮБОЕ имя; рантайм нормализует к шарду 1 и подбирает соседей по паттерну. **Каждый шард — самодостаточный валидный .cmf**: полный конверт, JSON-заголовок, каталог СВОИХ тензоров, свой блоб данных, свои хэши (`section_hashes` + по-тензорные). `cortiq verify` работает на любом отдельном шарде без его соседей. Заголовок каждого шарда несёт: ```json "shard": { "no": 1, "count": 5 } ``` Нет блока = обычный одиночный файл (обратно совместимо: старые ридеры видят шард 1 как валидную, но неполную модель и честно падают на отсутствующем тензоре). **Распределение содержимого**: тензоры разбиваются жадно в каноническом порядке (порог `--shard-max-gb`, грубый размер f32); секции масок/словаря/разреженного индекса, `tokenizer_config` (chat-бандл) и реестр `skills` живут ТОЛЬКО в шарде 1 — у остальных секции пустые и `tokenizer_config: null`. Тензоры скиллов (`skill.{id}.*`) распределяются как обычные записи каталога — реестр шарда 1 ссылается на них по имени через объединённый каталог. **Загрузка** (`CmfModel::open_sharded`): открыть шард 1 → mmap всех соседей → слияние каталогов (каждая запись помнит свой индекс шарда — рантайм-поле, никогда не пишется на диск) → рантайм далее работает как с одним файлом. Ошибки: прямое открытие не-первого шарда, отсутствующий сосед, несовпадение `count`. Ворота (Qwen3.5-0.8B q8_2f, 5 шардов ≤ 0.6 GB): шардированная PPL == нешардированной байт-в-байт на том же бинарнике; `verify` зелёный на каждом шарде по отдельности. ## 11. Дефрагментация — физический прунинг (USPTO App. 19/452,464, claims 9/10 — [PATENTS.md](../PATENTS.md)) Маска (§5) — это **виртуальная разреженность**: вырезанные нейроны помечены, но хранятся целиком (все задачи делят один бэкбон — резать физически нельзя, пока не выбрана ОДНА задача). Дефрагментация превращает виртуальную разреженность в **физическое сжатие**: мёртвые FFN-нейроны выбрасываются из файла — они **не хранятся и не вычисляются**. **Представление — без нового фичебита, обратная совместимость.** Физический прунинг выражается ТОЛЬКО меньшими формами тензоров в каталоге (§3 «нет вычислимой раскладки»; каталог — единственный авторитет форм). Рантайм выводит размер FFN из формы тензора (`gate_proj.rows()`), а не из `arch.intermediate_size`, поэтому дефрагированный файл — обычная меньшая dense-модель, которую существующие ридеры грузят без изменений. Секция масок в дефрагированном файле **отсутствует** (после прунинга маска — тождество). `arch.intermediate_size` становится номиналом (= максимум по слоям); истинный размер живёт в каждом тензоре — и каждый слой сжимается до СВОЕГО числа живых нейронов (лучше патента, который обязан резать все слои под `max(active)`). **Инварианты (обязательные):** тройка слоя `gate_proj.rows() == up_proj.rows() == down_proj.cols() == inter'ₗ` и `down_proj.rows() == hidden_size`; ось нейронов — строки для `gate/up`, столбцы для `down`; квант-группа 32: `down_proj` с `inter' % 32 ≠ 0` пишется как `q8_2f` (конвертер даунгрейдит сам); это НЕ байтовое усечение — деквант → выбор живых → **переквант** в меньшей форме, хэши пересчитываются; `hidden_size`, эмбеддинги, `lm_head` и нормы не трогаются. **Одна задача — автономный файл.** Дефраг деструктивен: один `.cmf` запекает ровно одну задачу. Мульти-задачность остаётся на масках (§5) или скиллах (§9). Провенанс — честный контракт в `provenance.defrag {source_skill, pre_intermediate, post_intermediate_max, kept_per_layer, pruned_ratio}`. Производство (нативный Rust): `cortiq convert --model … --defrag --quant q8_2f --output model.cmf`. **Охват:** здесь — dense-FFN-нейроны; MoE-эксперты — в §11.1. Прунинг голов внимания вне охвата. ### 11.1 MoE-дефраг экспертов (`cortiq moe-defrag`) MoE-близнец §11, управляемый B-полем роутинга вместо нейронной маски: использование экспертов сильно задачно (замерено на кодере 34.7B: top-64 наборы экспертов для кода и прозы пересекаются с Jaccard 0.25), поэтому однозадачный файл может выбросить экспертов, к которым задача не маршрутизирует. Из дампа `CMF_MOE_STATS` (пер-слойные счётчики выбора экспертов на репрезентативном прогоне) для каждого слоя сохраняется минимальный top-набор, покрывающий `--cover` записанной массы роутинга; остальные выбрасываются. **Представление — та же философия, без фичебита.** - Оставленные эксперты перенумеровываются в ПЛОТНЫЙ пер-слойный префикс `mlp.experts.0 … mlp.experts.{k−1}` с сохранением относительного порядка; ридер перечисляет экспертов слоя по НАЛИЧИЮ тензоров до `arch.moe.num_experts`, который становится номиналом (= исходное число) — зеркально правилу §11 для `intermediate_size`. - Строки роутера собираются в соответствие в том же порядке: `mlp.gate.weight` становится `[kept_l, hidden]`, и `router.rows() == (число присутствующих экспертов)` — инвариант загрузки. `top_k` клампится к пер-слойному числу экспертов. - Семантика выбора не меняется (§2.2): softmax просто ренормализуется по оставшимся. То же ограничение применимо В РАНТАЙМЕ без перезаписи файла (`CMF_MOE_MASK=` + `CMF_MOE_MASK_COVER`) — математически идентично, так cover-уровень гейтится перплексией до физического выброса. - Payload'ы экспертов копируются дословно (переквант не нужен — ось экспертов режет целые тензоры, не квант-группы), выжившие веса байт-в-байт равны исходным, перезапись стримится из mmap источника. Замеренный референс (KAT-Coder 34.7B-A3B, кодовая калибровка, cover 0.95): 19.6 → 12.7 ГБ (−35%), ppl held-out кода +2.8%, а на машине с 24 ГБ — где полная модель пейджилась — декод ×1.8, префилл ×3.3. Вне задачи качество падает по построению; как и в §11, один дефрагированный файл запекает одну задачу. ## 12. Pipeline-контейнеры — text-to-image в одном файле Та же машинерия конверт/каталог/блоб несёт не-LLM конвейеры. Отличия — только тег `arch_name` и неймспейсы имён тензоров; ни новых секций, ни фичебита (ридер, не исполняющий конвейер, всё равно валидирует и инспектирует файл). Текущий экземпляр — `arch_name: "lumina2-image"` (Lumina-Image 2.0, `cortiq imagine-pack` / `cortiq imagine`): один файл содержит весь text-to-image стек. - **Неймспейсы**: `te.*` — трансформер текст-энкодера (LLM класса Gemma-2; блок `arch` заголовка описывает ИМЕННО эту компоненту, так что общие инструменты читают осмысленные размерности), `dit.*` — денойзер Next-DiT, `vae.*` — VAE-декодер. Config-JSON'ы компонент едут u8-тензорами `{prefix}.config_json` — файл самодостаточен. - **Квантование**: пер-тензорное как всегда (§3, каталог — истина) — обычно q4t/q8 матрицы для te/dit, f16 для свёрток VAE и норм. - **Секция токенизатора** (§6) несёт токенизатор текст-энкодера; `provenance.pipeline` + `provenance.components` называют рецепт. --- *Связанное: [COMPARISON.md](COMPARISON.md) (CMF против других форматов моделей), [README проекта](../README.md) (обзор и быстрый старт), `python/cmf_reader.py` (автономный ридер: stdlib + numpy, читает каждый dtype, шарды, скиллы, verify).*