G2-MECHANICS — механика эволюции формата: второй взгляд

Что должен сделать читатель, чтобы модель Avro сработала

12Модель Avro [ПО ПАМЯТИ, НЕ ПРОВЕРЕНО]: каждая запись пишется против схемы писателя; читатель обязан добыть именно ту схему писателя, по которой записано, и согласовать её со своей схемой читателя. Обычно — по отпечатку (fingerprint), который лежит в данных, через реестр схем.

13Чтобы это работало у нас, читатель должен:

1. 14Извлечь из данных идентификатор схемы писателя. У нас в repomd.json — schema_version: u32 (repomd.rs:21), не отпечаток схемы. То есть читатель знает «версия 1», но не знает, какой именно текст схемы соответствует версии 1.
2. Где-то этот текст найти. У нас его для каталога нет как артефакта — [ИЗ ДЕРЕВА]: в crates/vibe-index/ нет .json-схемы; схема существует только как Rust-типы (types/) и спека-проза (PROP-005).
3. Запустить согласование схем.

Предпосылка свода неверна: это не «одна история git»

15Свод [ИЗ СВОДА]: «в git-репозитории это стоит указателя, и история схемы лежит в той же истории, что и данные». Но:

• 16Каталог (repomd.json, primary.jsonl, by-name/*.json) — это публикованный артефакт реестра; поле registry/registry_url (repomd.rs:22-23) указывает на репозиторий-источник. Схема (Rust-типы) живёт в исходном репозитории vibevm. Это два разных репозитория с двумя разными историями. История каталога не содержит текста схемы — значит, «одна история» ложно.
• «Схема едет с данными» — тоже ложно сегодня: рядом с repomd.json нет файла схемы. (Контрпример из дерева: для vibe tree --json схема есть — crates/vibe-cli/resources/package-tree.schema.v1.json с $id и schema_version:{const:1}, плюс золотой тест crates/vibe-cli/tests/tree_json.rs. Способность публиковать артефакт схемы в доме есть — просто не применена к каталогу. Это и есть настоящий Avro-смежный пробел.)

Читатель без репозитория / запись, скопированная наружу

• 17Внешний инструмент читает каталог из реестра; он не клонирует исходный репозиторий vibevm с Rust-типами. У него нет ни схемы писателя, ни пути к ней. Механика согласования Avro не запускается — он возвращается к «читать JSON как умею», то есть к терпимому читателю. Avro ему ничего не дал.
• Запись, скопированная из репозитория наружу (строка primary.jsonl в баг-репорте, зеркало метаданных пакета): нет ни версии, ни контекста — чистый JSON. Avro невозможен; терпимое чтение — единственный вариант. А это самый реальный способ, которым нашими данными будут пользоваться.

Вердикт: ДОРОЖЕ

18Avro требует: публиковать машинно-читаемый артефакт схемы с данными (или реестр), учить читателей его доставать и согласовывать, версионировать этот артефакт, держать дисциплину отпечатков. Это большая машинерия — ради выгоды, которую у нас некому потреблять (внешних читателей ноль [ИЗ СВОДА], а своим согласование схем не нужно: писатель и читатель — один бинарник).

19Терпимый читатель требует: читать узкими view, игнорировать незнакомые поля, отсутствующее трактовать как default. Это уже написано (wire.rs). Маржинальная стоимость — около нуля.

20Ответ на вопрос: Avro для нас дороже терпимого читателя, заметно и по машинерии, и по предпосылкам. Настоящий (и полезный) урок Avro — не «возить схему с данными», а «сделать схему машинно-читаемым артефактом вообще». Этого артефакта у каталога сегодня нет; фикс — опубликовать JSON Schema / JTD (паттерн уже есть в vibe-cli/resources/), а не внедрять разрешение схем Avro.

Невосстановление у protobuf — осознанный отказ, а не недоделка

21Свод [ИЗ СВОДА]: для скаляров присутствие вернули через ~5 лет, для списков и словарей — «так и не вернули … слиты навсегда», и подаёт это как незавершённость.

22Я утверждаю, что это осознанный отказ, и вот цена различимости для списка [ПО ПАМЯТИ, НЕ ПРОВЕРЕНО]:

• 23каждое поле-список получает третье состояние (нет / пусто / заполнено);
• сгенерированный код несёт Option<Vec> или has-бит на каждое такое поле;
• каждый читатель обязан решить, что семантически значит «нет» против «пусто» — а это решение не универсально;
• любой инструмент, не понимающий присутствия, молча сколлапсирует их обратно (round-trip-несоответствие).

24Для proto3 цена особенно высока: их двоичный формат не выделяет присутствие для repeated-полей без явного бокового маркера, и реставрация ломала бы компактность и обратную совместимость с существующими данными. Отказ рационален.

Главный аргумент: для машинных данных «отсутствует» — не настоящее состояние

25Ключевое различие, которое свод не провёл: присутствие нужно человеко-написанным данным, где «я не заполнил» реально, и почти не нужно машинно-сгенерированным, где каждое поле детерминированно вычислено.

26Каталог пишет индексатор. Он всегда знает значение каждого поля — читает его из vibe.toml пакета. Поэтому «отсутствует» для каталожного поля — не легитимное «неизвестно», а всегда «вычислено как пустое». Различимость пусто/нет ничего не покупает, потому что состояние «нет» никогда не наступает законно.

27Конкретно по нашим полям [ИЗ ДЕРЕВА]: authors, keywords, requires.packages, provides.capabilities, features, i18n.available — все вычисляются индексатором из манифеста; «нет» у них не бывает. Даже requires_any (entry/mod.rs:96) — «зависимость any-of не задана» — это ограничение, а не присутствие.

Где различимость всё-таки нужна — и это не каталог

28У манифеста vibe.toml, который пишет человек [ИЗ СВОДА], «я не указал» — реальное состояние. Там authors = [] (явно: авторов нет) против отсутствующего authors (не записано) — осмысленное различие. И TOML здесь помогает, а не мешает: отсутствие null в TOML — это фича, она принуждает выражать трёхзначность через «нет ключа» против [], без null-сигнала, который можно перетолковать. JSON и TOML соглашаются в механизме.

Вердикт

29Различимость пусто/нет для списков нам для каталога НЕ нужна. 21 поле со skip_serializing_if = "...is_empty" безопасны для машинных данных. Присутствие стоит сохранять только там, где «неизвестно» легитимно — то есть в человеко-написанном манифесте. И свод сам к этому приходит в рекомендации №2 (null не нужен: в TOML его нет) — но он не развёл, что для каталога это безразлично, а для манифеста — обязательно, и фиксы там разные.

Форма A — явное поле-дискриминатор (стандарт)

#[serde(tag = "kind", rename_all = "lowercase")]
pub enum RepomdFileEntry {
    Directory { entries: u32 },
    File { size: u64, sha256: String },
}

{ "kind": "directory", "entries": 42 }
{ "kind": "file", "size": 184522, "sha256": "..." }

• 34Цена: каждое файловое действие дополнительно несёт "kind":"file" (байты); ломающее изменение файлового варианта (сегодня у файла нет kind) — но внешних потребителей ноль [ИЗ СВОДА], сейчас это даром.
• Чем платим / получаем: чистые ошибки serde, оба варианта симметричны, форма выражается в JTD, JSON Schema (discriminator/oneOf), protobuf (oneof), Avro (union). Это ровно то, что разрешает блокер А6 — тип становится выразимым в языке схемы в тот момент, когда мы перестаём брать untagged. По сути — один атрибут от нынешнего состояния.

Форма B — разные ключи верхнего уровня (разделённые карты)

"files":       { "primary.jsonl": { "size": 184522, "sha256": "..." } },
"directories": { "by-name": { "entries": 42 } }

• 36Цена: одна логическая коллекция (files: BTreeMap<…>, repomd.rs:34) дробится на две; читатель обязан проверять обе; теряется единый детерминированный порядок обхода путей; путь не может мигрировать файл↔каталог без переноса ключа.
• Чем платим: фрагментация API и двойная бухгалтерия. Зато каждый кусок однороден и строго типизирован. Урок PyPI [ИЗ СВОДА] («поле, которое бывает bool или dict → крах») аргументирует за явную структуру — разделение на две типизированные карты структурно явно, но ломает инвариант «один путь → одна запись».

Форма D — вложение в именованный объект (обёртка) — нет в своде

37Соседне-тегированная форма, родная для serde:

#[serde(tag = "kind", content = "value", rename_all = "lowercase")]
pub enum RepomdFileEntry {
    Directory { entries: u32 },
    File { size: u64, sha256: String },
}

{ "kind": "directory", "value": { "entries": 42 } }
{ "kind": "file",      "value": { "size": 184522, "sha256": "..." } }

40(Одно-ключевая форма {"directory":{…}} / {"file":{…}} тоже возможна, но требует ручной ser/deser — serde не даёт её из коробки; adjacent-тег — серде-нативный её аналог.)

• 41Цена: лишний уровень вложенности и value-обёртка → больше байтов и глубины.
• Чем платим / получаем: максимальная самодокументируемость (читатель видит единственный ключ и знает вариант, не сканируя поля) и чистая прямая-совместимость: третий вариант {"kind":"symlink","value":{…}} добавляется без двусмысленности. Самая «будущестойкая» форма; переплата байтами оправдана, если вариантов со временем будет больше двух.

Форма C — вывод вида по обязательному полю (baseline = текущее направление)

{ "entries": 42 }
{ "size": 184522, "sha256": "..." }

• 43Цена: это худшая форма — ровно то нетегированное угадывание, которому свод (справедливо) не доверяет, и ровно форма PyPI «bool или dict», которая роняла pip [ИЗ СВОДА]. Плохие ошибки, двусмысленность при совпадении имён полей в будущих вариантах.
• Чем платим: включена сюда только как ценовой baseline, чтобы оценить остальные. По сути это нынешний дизайн минус тег у Directory.

Форма E — тег в ключе карты — отбраковывается

"dir:by-name": { "entries": 42 }
"primary.jsonl": { "size": 184522, "sha256": "..." }

• 45Цена: загрязняет пространство имён путей (путь — данные, не тег типа); путь, содержащий двоеточие, ломает схему; читатель парсит строки. Сильно не рекомендуется: путь — это идентичность и должен оставаться чистыми данными.

Рекомендация

46Форма A. Один атрибут от нынешнего состояния, стандарт во всех языках схем, дешёвая, и — критически — устраняет блокер А6 («тип невыразим в языке схемы»): он невыразим только пока мы держим untagged. Если ожидается рост числа вариантов — Форма D.

Где терпимость перестаёт быть эволюцией

54В тот момент, когда она отображает нераспознанный вход в определённое значение, на котором потребитель потом действует (паттерн Cloudflare «score zero»). Молчаливый default неизвестного значения enum — единственная самая опасная терпимость. Добавление (новые поля, новая длина, новые ключи карты) — терпимо; нарушение типа — нет; новые значения enum — не молча в default.

Уточнение к рекомендациям свода

55«Строго на двери, терпимо дальше» — верно, но недоспецифицировано на enum'ах. Я бы уточнил: дверь (vibe.toml) отвергает и неизвестные значения enum, и опечатки; каталог (вниз по потоку) терпит незнакомые поля, но всё равно не молча дефолтит неизвестные значения enum — несёт их как Unknown, чтобы будущий читатель мог ими воспользоваться. Это более острая граница, чем просто «терпимо дальше».

Что НЕ переносится

• 56Числа как идентичность поля — ядро protobuf. См. §6: у нас имена. Мы не наследуем их rename-безопасность, но она нам и не нужна при правильной дисциплине имён.
• Двоичный формат — нерелевантен: мы публикуем JSON для читаемости людьми и инструментами, компактность не покупаем.
• Драма с удалением required [ИЗ СВОДА]: protobuf убрал required из-за долго живущих типов через границы организаций. У нас один писатель и ноль внешних потребителей [ИЗ СВОДА] — обязательные поля (VersionEntry полон них, entry/mod.rs:43-121) нормальны и полезны. Урок «required — зло» нельзя тащить оптом: он настроен на их развёртывание (много организаций, типы на десятилетия). Я бы локализовал: required зол лишь когда читатели, которых ты не контролируешь, могут быть вынуждены синтезировать значение. Писателя контролируем мы. Другой случай.
• Коллапс присутствия скаляров в proto3 [ИЗ СВОДА]: proto3 не различает «нет» и default для скаляров. В JSON этого нет: отсутствие ключа, 0 и null — три разных состояния. Так что скалярного коллапса proto3 мы вообще не наследуем.

Наследуем ли мы «проблемы JSON-кодировки без выхода» — НЕ согласен с рамкой

57Свод [ИЗ СВОДА]: JSON-кодек protobuf по умолчанию отвергает незнакомые поля, а на жалобы ответ — «используйте двоичную»; мы наследуем весь набор проблем их JSON без их выхода.

58Я не согласен с рамкой. «JSON-проблема» protobuf в том, что их JSON строг, а двоичный — терпим, и недовольных отсылают в двоичный. Нас никто не заставляет быть строгими в JSON: serde позволяет выбрать deny_unknown_fields или нет. Сейчас мы сами выбрали строгость в 15 местах своего читателя и терпимость — в клиенте. Так что «выход» (терпимое чтение) тривиально доступен нам убиранием одного атрибута — двоичный формат для выхода не нужен. Свод подаёт так, будто двоичный protobuf — единственный выход из строгого JSON; для нас выход — терпимый JSON, и он бесплатен.

59Что мы реально наследуем от JSON-без-схемы: не «проблемы protobuf», а проще — в JSON нет схемы, поэтому дисциплина эволюции живёт целиком в головах + чекере. Это и есть урок Cloudflare [ИЗ СВОДА]: ужесточить приём собственных сгенерированных файлов так же, как пользовательский ввод. И — повторю из §1 — артефакт схемы для каталога у нас отсутствует, хотя способность его публиковать в доме есть (vibe-cli/resources/package-tree.schema.v1.json).