159 lines
13 KiB
Markdown
159 lines
13 KiB
Markdown
# Автономное тройное ревью П42 · август 2021 · «Контракт хранилища»
|
||
|
||
Статус: **принята к публикации после независимой интеграции**. Изначально
|
||
registry и Git автономным пакетом не менялись.
|
||
|
||
Пакет заменяет через overlay только три стабильных slug:
|
||
|
||
- <code>editorial-2021-08-practice-storage-contracts</code>;
|
||
- <code>editorial-2021-08-mechanism-storage-contracts</code>;
|
||
- <code>editorial-2021-08-field-storage-contracts</code>.
|
||
|
||
Созданы ровно пять файлов П42:
|
||
|
||
- <code>web/scripts/upgrade-2021-08.mjs</code>;
|
||
- <code>web/public/assets/editorial/2021/storage-contract-compatibility-2021.svg</code>;
|
||
- <code>web/public/assets/editorial/2021/storage-contract-evolution-2021.svg</code>;
|
||
- <code>web/public/assets/editorial/2021/storage-contract-diagnosis-2021.svg</code>;
|
||
- этот документ.
|
||
|
||
Revision-модуль экспортирует только изменяемые редакционные поля. В нём нет
|
||
<code>date</code>, <code>author</code>, registry import или изменения
|
||
<code>articles.json</code>. Fixture использует только Array, Map и objects в
|
||
одном Node-процессе; не запускает БД, broker, реальные файлы, сеть, provider,
|
||
миграционный job или сервис.
|
||
|
||
## Проход 1. Структура, тон и объём — пройдено
|
||
|
||
| Revision | Ситуация и цена в первых двух абзацах | M4 и практическая граница | Объём body |
|
||
| --- | --- | --- | --- |
|
||
| Практика | Новый <code>timezone</code> смешивается с absent/null; цена — запись, которую старый reader трактует иначе | owner, поддержка старых pair и reader-before-writer rollout | **10 574** знака body |
|
||
| Механизм | Reader принял форму, но не смог объяснить значение; цена — закреплённая догадка вместо договора | type, presence, narrowing и semantic break разделены | **11 259** знаков body |
|
||
| Полевой разбор | Reader упал после записи; цена — потеря evidence при поспешном rollback | evidence, stop criterion и rollback-safe действия | **10 349** знаков body |
|
||
|
||
- У всех трёх текстов есть ситуация и стоимость ошибки в первых двух абзацах,
|
||
таблица, привязанный SVG с содержательными <code>alt</code>/<code>figcaption</code>,
|
||
рабочие JS-фрагменты, нумерованный маршрут, ограничения и отдельный раздел
|
||
источников.
|
||
- Голос М4 августа 2021 года: короткая инженерная речь «симптом → причина →
|
||
проверка → действие», явный owner и граница между reader, writer и contract.
|
||
Текст не изображает автора владельцем platform/SLA или реальной migration
|
||
program.
|
||
- Удалены универсальные формулы о «современном подходе»: каждое обобщение
|
||
привязано к profile.settings, matrix или fixture.
|
||
|
||
Вердикт: **пройден**. <code>audit:draft</code> подтвердил диапазон 5 000–15 000
|
||
знаков и наличие sections, table, figure, code, route, sources и локального
|
||
asset у каждого revision.
|
||
|
||
## Проход 2. Техника, source boundaries и fixture — пройдено
|
||
|
||
| Граница | Что утверждает пакет | Как это проверяется | Чего пакет не утверждает |
|
||
| --- | --- | --- | --- |
|
||
| JSON object | reader читает именованные key, а не их позицию | reordered v2 record даёт тот же нормализованный result | одинаковый порядок во всех parser или storage |
|
||
| Optional field | absent, <code>null</code> и строка — разные states | v1 → v2 даёт absent; v2 clear даёт explicit-null | absent всегда должен означать clear |
|
||
| Additive change | v2 добавляет only optional <code>timezone</code> | v2 writer → v1 reader и v1 writer → v2 reader зелёные в matrix | любой новый key безопасен для любого consumer |
|
||
| Breaking changes | narrowing, semantic change и required timezone отвергаются | три отдельные negative matrix assertions | generic JSON сам даёт эволюционную совместимость |
|
||
|
||
Первичные и официальные источники ограничивают историческую рамку:
|
||
|
||
- [RFC 8259](https://www.rfc-editor.org/rfc/rfc8259.html) для JSON object,
|
||
literal <code>null</code> и отсутствия переносимого договора о порядке
|
||
object members;
|
||
- [JSON Schema draft 2019-09 Validation](https://json-schema.org/draft/2019-09/draft-handrews-json-schema-validation-02), официальный опубликованный Draft от 17 сентября 2019 года (не IETF RFC),
|
||
для vocabulary structural assertions и типа <code>null</code>;
|
||
- [Apache Avro 1.10.2 Specification](https://avro.apache.org/docs/1.10.2/spec.pdf)
|
||
для ограниченного, форматно-зависимого примера writer/reader schema resolution.
|
||
|
||
<code>runStorageContractFixture()</code> создаёт v1, additive v2, v2 clear,
|
||
legacy <code>daily</code>, type error и семь направлений matrix. Она требует
|
||
тринадцать истинных assertions: v1/v2 reads, additive direction, absent versus
|
||
explicit null, order independence, required-field rejection, type rejection,
|
||
narrowing, semantic and presence break. Функция не вызывает файловую систему,
|
||
сеть, БД, broker или внешний API.
|
||
|
||
Вердикт: **пройден**. Технические claims ограничены fixture и указанными
|
||
документами; format-specific Avro rules не переносятся на generic JSON.
|
||
|
||
## Проход 3. Фактическая точность, SVG и preflight — пройдено
|
||
|
||
- Во всех SVG есть <code>title</code>, <code>desc</code> и
|
||
<code>role="img"</code>. В схемах показаны только contract-level шаги:
|
||
compatibility directions, reader-before-writer evolution и diagnostic tree.
|
||
Статическая safety-проверка не нашла <code>script</code>,
|
||
<code>foreignObject</code>, внешние asset URL или raster data URI. Тексты,
|
||
стрелки и карточки рассчитаны на статичный просмотр, а не заменяют browser
|
||
или screen-reader проверку.
|
||
- Первый Sharp-рендер обнаружил два настоящих дефекта: длинная подпись
|
||
выходила за правую границу в evolution SVG, а четыре узкие ветви diagnosis
|
||
SVG плохо читались на 375 px. Заголовок и нижняя подпись evolution сокращены;
|
||
diagnosis перестроен в четыре широкие карточки. После правки повторный
|
||
375 px рендер просмотрен вручную: clipping, overlap и horizontal overflow
|
||
внутри трёх схем не обнаружены.
|
||
|
||
### Команды preflight
|
||
|
||
<pre><code>cd web && node --check scripts/upgrade-2021-08.mjs
|
||
cd web && npm run audit:draft -- scripts/upgrade-2021-08.mjs
|
||
cd web && node scripts/upgrade-2021-08.mjs --verify-fixture
|
||
cd web && xmllint --noout \
|
||
public/assets/editorial/2021/storage-contract-compatibility-2021.svg \
|
||
public/assets/editorial/2021/storage-contract-evolution-2021.svg \
|
||
public/assets/editorial/2021/storage-contract-diagnosis-2021.svg</code></pre>
|
||
|
||
### Финальные фактические результаты
|
||
|
||
Проверки выполнены 31 июля 2026 года после всех правок:
|
||
|
||
| Проверка | Реальный результат |
|
||
| --- | --- |
|
||
| <code>node --check</code> | PASS, code 0 |
|
||
| <code>npm run audit:draft</code> | PASS: **10 574 / 11 259 / 10 349** знаков body; у всех трёх slug есть table, figure, code, route, sources и локальный SVG |
|
||
| In-memory fixture | PASS: **13/13** assertions истинны; зелёные v1/v2 направления и три отрицательные matrix-пары проверены |
|
||
| <code>xmllint --noout</code> | PASS, три SVG — корректный XML |
|
||
| SVG safety scan | PASS: не найдены active tags, <code>foreignObject</code>, внешние assets или raster data URI |
|
||
| Sharp mobile preflight | PASS: три финальных PNG шириной 375 px вручную просмотрены после правки; нет clipping, overlap или horizontal overflow |
|
||
| Scope/self-review | PASS: П42 создала только пять разрешённых файлов; registry, README, <code>articles.json</code>, audit scripts, общие правила/очередь и Git не менялись; mascot PNG не затрагивались |
|
||
|
||
<code>npm run audit:draft</code> вывела старые предупреждения пользовательской
|
||
конфигурации npm о <code>store-dir</code>, <code>cache-dir</code> и
|
||
<code>public-hoist-pattern</code>. Они не относятся к П42 и не изменялись.
|
||
|
||
Integration registry audit, production build, browser, реальное storage,
|
||
migration, CI, commit и push намеренно не запускались: они находятся за
|
||
границей автономной П42.
|
||
|
||
Выпусковой вердикт автономной партии: **готова к независимой интеграции**.
|
||
|
||
## Независимая редактура и интеграция · 31 июля 2026
|
||
|
||
Основной редактор провёл ещё один технический и исторический проход.
|
||
|
||
1. Assertion `genericJsonDoesNotBypassTheContract` дублировал проверку
|
||
`timezone: 3`. Его заменили на отдельный случай: синтаксически корректное
|
||
JSON-значение <code>emailDigest: "hourly"</code> не входит в договор и
|
||
отклоняется reader v1. Так fixture различает форму JSON и доменное
|
||
перечисление, не увеличивая формальное число assertions.
|
||
2. Источник JSON Schema уточнён как официальный опубликованный Draft 2019-09
|
||
от 17 сентября 2019 года, а не IETF RFC. Avro 1.10.2 дополнительно
|
||
сверена по официальному анонсу выпуска от 15 марта 2021 года. Оба источника
|
||
существовали к августу 2021-го; правила Avro по-прежнему не переносятся на
|
||
generic JSON.
|
||
3. Все три SVG повторно просмотрены после независимого Sharp-рендера на 375 px:
|
||
читабельны направления совместимости, порядок rollout и четыре ветви
|
||
диагностики; clipping, overlap и overflow не обнаружены.
|
||
|
||
| Проверка | Результат независимого прохода |
|
||
| --- | --- |
|
||
| `node --check` и draft gate | PASS: **10 574 / 11 259 / 10 349** знаков body |
|
||
| Fixture | PASS: 13/13; есть отдельные проверки absent/null, type, допустимого формата с недопустимым enum, narrowing, semantic и presence break |
|
||
| `xmllint` и SVG safety scan | PASS: три XML-диаграммы корректны; не найдены script, foreignObject, внешние URL или raster data URI |
|
||
| Strict audit через registry | PASS: 1 figure, 2 table и 3–4 code examples в каждой revision; объёмы **10 574 / 11 259 / 10 349** |
|
||
| Production build | PASS: Next.js сгенерировал 374 статические страницы |
|
||
|
||
Три revision подключены к `web/data/editorial-revisions.mjs`; архив остаётся
|
||
владельцем stable slug, даты и автора. После интеграции строгий охват —
|
||
**130 из 358**, осталось **228** материалов.
|
||
|
||
Финальный вердикт: **ACCEPTED FOR PUBLICATION**.
|