122 lines
14 KiB
Markdown
122 lines
14 KiB
Markdown
# P97 — март 2026: Контракты данных
|
||
|
||
## Область изолированного draft-пакета
|
||
|
||
Пакет содержит только три overlay-статьи:
|
||
|
||
- editorial-2026-03-practice-data-contracts;
|
||
- editorial-2026-03-mechanism-data-contracts;
|
||
- editorial-2026-03-field-data-contracts.
|
||
|
||
Исполняемый модуль — web/scripts/upgrade-2026-03.mjs. Все schema, version, producer, consumer, manifest, compatibility report и boundary data — named fixed synthetic JavaScript literals в памяти. Модуль не обращается к schema registry, сети, файловой системе, Git, CI, часам, telemetry, production data, API или deployment. Положительный verdict ограничен synthetic compatibility-review hand-off; он не изменяет форму и не доказывает результат release, migration или rollout.
|
||
|
||
Registry, README, app-файлы, articles.json, очередь, Git-state и любые чужие незавершённые изменения не менялись. Полный site build намеренно не запускался: это интеграционный шаг вне разрешённого scope.
|
||
|
||
## Исследование и историческая граница
|
||
|
||
Историческая граница статей — **31 марта 2026**. Все ссылки первичные или официальные. Изменяемая документация не используется: RFC неизменяем, IETF draft закреплён номером версии, а Avro привязан exact source commit.
|
||
|
||
| Источник | Version / pin | Узкий подтверждённый факт | Явная граница |
|
||
| --- | --- | --- | --- |
|
||
| [JSON Schema Core, draft-bhutton-json-schema-01](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-01) | draft-bhutton-json-schema-01, **10.06.2022**, immutable versioned IETF draft | Vocabulary описывает object properties и применение additionalProperties к именам, не обработанным другими keywords. | Не задаёт policy конкретного consumer, contract family, manifest или результат данного gate. |
|
||
| [RFC 8927: JSON Type Definition](https://www.rfc-editor.org/rfc/rfc8927.html) | RFC 8927, **November 2020**, immutable publication | JTD различает properties, optionalProperties и additionalProperties; по умолчанию дополнительные properties не разрешены. | Experimental RFC не определяет status review, registry policy или deployment decision. |
|
||
| [Apache Avro Specification 1.12.0](https://github.com/apache/avro/blob/8c27801dc8d42ccc00997f25c0b8f45f8d4a233e/doc/content/en/docs/%2B%2Bversion%2B%2B/Specification/_index.md#schema-resolution) | commit 8c27801dc8d42ccc00997f25c0b8f45f8d4a233e, release tag **05.08.2024** | Specification различает writer and reader schemas и описывает schema resolution. | Не является реализацией fixed JSON-like literal, не подтверждает compatibility этого gate и не заменяет consumer review. |
|
||
|
||
Проверка источников выполнена точечными запросами: RFC подтвердил дату и vocabulary properties/optionalProperties/additionalProperties; IETF draft подтвердил версию и дату; raw Avro file по exact commit подтвердил формулировку writer schema, reader schema и Schema Resolution. Ни один источник не использован как evidence успешного synthetic hand-off.
|
||
|
||
## Проход 1 — качество, problem/cost, голос и самостоятельность
|
||
|
||
Прочитаны полные тела всех трёх статей без source list. Во всех первых двух абзацах есть наблюдаемый problem, стоимость ручной координации и короткое действие. Голос M9 держит последовательность symptom → mechanism → check → next action; текст не обещает эффект вне synthetic boundary.
|
||
|
||
| Статья | Самостоятельный вопрос | Свой механизм и visual | Цена ошибки |
|
||
| --- | --- | --- | --- |
|
||
| practice | Как перевести ручное schema change в явную карточку? | baseline/candidate/manifest + эволюция контракта | позднее восстановление обещаний после change |
|
||
| mechanism | Что именно вычисляет backward compatibility? | direction, field maps, manifest и capability reader + gate loop | спор о слове compatible вместо проверяемого отношения |
|
||
| field | Как вести несколько consumer без ложного общего verdict? | pair matrix, inventory и адресный возврат stop | поздний поиск владельца и ручное исправление для разных readers |
|
||
|
||
Таблица, ordered sequence, executable public-export snippet, ограничения и следующий шаг есть в каждой статье. У статей нет общего развёрнутого вступления, общего примера или общей таблицы.
|
||
|
||
Во время первого uniqueness check найден один общий 12-словный фрагмент только в префиксе двух code snippets. Mechanism snippet переписан через локальные public-export aliases; поведение и output сохранены. Финальный cross-article check: 0 одинаковых абзацев от 160 знаков и 0 общих 12-словных фрагментов во всех трёх парах.
|
||
|
||
**Вердикт прохода 1: PASS после целевой правки.**
|
||
|
||
## Проход 2 — источники, историческая граница и буквальное выполнение кода
|
||
|
||
Проверены ссылки, их version/date/pin и границы применимости. В sourceList каждой статьи версия или commit показывается рядом со ссылкой. Все даты находятся до 31.03.2026. Для Avro используется immutable GitHub commit, а не live documentation; RFC и versioned IETF draft также не опираются на текущую mutable страницу. Во время проверки дата IETF draft была уточнена с ошибочных 16.06.2022 на фактические 10.06.2022 и сразу исправлена в sourceList и этой таблице.
|
||
|
||
Все visible snippets импортируют только public exports из upgrade-2026-03.mjs и выполнены буквально из директории web/scripts:
|
||
|
||
practice:
|
||
{ added: ['priority'],
|
||
status: 'synthetic-compatibility-review-hand-off',
|
||
effect: 'not-attempted' }
|
||
|
||
mechanism:
|
||
{ status: 'stop-backward-incompatible-schema',
|
||
removed: ['state'],
|
||
next: 'retain-required-baseline-field-or-name-a-separate-migration' }
|
||
|
||
field:
|
||
{ status: 'stop-incompatible-consumer',
|
||
reason: 'incompatible-consumer',
|
||
assertions: 15 }
|
||
|
||
Fixture принимает только known fixed case. Он fail-closed на требуемых границах:
|
||
|
||
- stop-backward-incompatible-schema при исчезновении required state;
|
||
- stop-undocumented-schema-field для routingHint вне manifest;
|
||
- stop-incompatible-consumer для strict reader;
|
||
- stop-implicit-comparison, когда relation не названа;
|
||
- stop-unknown-fixed-contract-case для произвольного object input.
|
||
|
||
Единственный положительный путь заканчивается synthetic-compatibility-review-hand-off и productionEffect: not-attempted. Он не создаёт release, API change, registry update или deployment.
|
||
|
||
**Вердикт прохода 2: PASS.**
|
||
|
||
## Проход 3 — visual, аудит, объём и выпускное качество
|
||
|
||
| Статья | Основной текст без source list | SVG | Mobile inspection 375 px |
|
||
| --- | ---: | --- | --- |
|
||
| practice | **9 210** знаков | data-contracts-2026-contract-evolution.svg | PASS: карточки v1.0/v1.1, gate и hidden field читаемы |
|
||
| mechanism | **9 426** знаков | data-contracts-2026-compatibility-gate-loop.svg | PASS после сокращения обрезанного заголовка |
|
||
| field | **9 748** знаков | data-contracts-2026-producer-consumer-matrix.svg | PASS: статусы матрицы и подписи различимы |
|
||
|
||
Sharp render всех SVG на ширине 375 px просмотрен визуально. В первом visual-проходе у схемы gate loop заголовок выходил за правую границу; он сокращён до «У каждого stop есть своя причина» и повторно проверен. Final SVG не содержат script, foreignObject, javascript:, data:image или inline event handlers.
|
||
|
||
Команды и результаты:
|
||
|
||
- node --check web/scripts/upgrade-2026-03.mjs — PASS.
|
||
- node web/scripts/upgrade-2026-03.mjs --verify-fixture — PASS, **15/15 assertions**.
|
||
- npm run audit:draft -- scripts/upgrade-2026-03.mjs из web/ — PASS: 9 210 / 9 426 / 9 748; problem/cost в начале, table, figure с alt/caption, code, ordered sequence и source section присутствуют.
|
||
- Literal execution трёх visible snippets — PASS.
|
||
- xmllint --noout для трёх SVG — PASS.
|
||
- SVG safety scan через rg — PASS.
|
||
- Sharp render 375 px для всех трёх SVG и ручной visual inspection — PASS.
|
||
- Cross-article duplicate scan — PASS: paragraphs160=0 и fragments12=0 для каждой пары.
|
||
- git diff --check и no-index whitespace check для untracked draft-файлов — PASS.
|
||
|
||
**Вердикт прохода 3: PASS после целевой visual-правки.**
|
||
|
||
Пакет намеренно остаётся изолированным draft: registry и README не подключены; stage, commit и push отсутствуют.
|
||
|
||
## Независимая приёмка основного редактора
|
||
|
||
Проверено 2026-07-31 перед подключением.
|
||
|
||
- Первичные источники перепроверены отдельно: RFC 8927 опубликована в November 2020 и содержит `optionalProperties`/`additionalProperties`; exact Avro commit `8c27801dc8d42ccc00997f25c0b8f45f8d4a233e` содержит Schema Resolution и различает writer/reader schema; versioned IETF draft закреплён как `draft-bhutton-json-schema-01`. Эти документы использованы только как терминологическая опора, не как доказательство совместимости fixture.
|
||
- `node --check`, fixture 15/15 и `audit:draft` прошли повторно. Дословно выполнены три public-export примера: additive case заканчивается только `synthetic-compatibility-review-hand-off` с `not-attempted`; отсутствие `state` и строгий reader получают разные fail-closed статусы.
|
||
- Три SVG прошли XML и safety scan. PNG на 375 px просмотрены повторно: labels, стрелки и матрица читаемы без обрезания.
|
||
- Строгий scan полного body, включая code и без source list, подтвердил для каждой пары `0` общих абзацев от 160 знаков и `0` общих 12-словных фрагментов. После подключения production audit и сборка должны быть обязательной частью релиза.
|
||
|
||
Решение: принять P97 как учебный synthetic overlay. Он не подтверждает реальную схему, consumer, registry, migration или deployment.
|
||
|
||
## Фактическая release-проверка
|
||
|
||
После публикации overlay проверен из основного checkout. `node --check`, fixture **15/15**, `audit:draft` и production `audit:articles` прошли для всех трёх slug: 9 210 / 9 426 / 9 748 знаков, по одной figure, table и code example. Реестр содержит **286** редакционных ревизий; каждый мартовский slug присутствует ровно один раз.
|
||
|
||
Сборка `npm run build` завершилась без ошибок TypeScript и сгенерировала **374/374** статические страницы. `git diff --check` чист. Это подтверждает интеграцию overlay в сайт, но не расширяет границу модели: данные, producer, consumer и результат compatibility review по-прежнему только fixed synthetic literals.
|
||
|
||
Источники повторно сверены по точным адресам: архив IETF содержит date `10 June 2022` для `draft-bhutton-json-schema-01`; RFC 8927 — November 2020; GitHub API подтверждает, что annotated tag `release-1.12.0` от `2024-08-05T12:03:21Z` указывает на commit `8c27801dc8d42ccc00997f25c0b8f45f8d4a233e`. Их роль остаётся терминологической, а не доказательством совместимости конкретной внешней схемы.
|
||
|
||
**Итог release-проверки: PASS.**
|