120 lines
12 KiB
Markdown
120 lines
12 KiB
Markdown
# P95 — январь 2026: API платформенной команды
|
||
|
||
## Область изолированного draft-пакета
|
||
|
||
Пакет содержит только три overlay-статьи:
|
||
|
||
- editorial-2026-01-practice-platform-api;
|
||
- editorial-2026-01-mechanism-platform-api;
|
||
- editorial-2026-01-field-platform-api.
|
||
|
||
Исполняемый модуль — web/scripts/upgrade-2026-01.mjs. В нём все API, версии, request, response, consumer, статусы, трассы и решения — named fixed synthetic JavaScript literals в памяти. Нет сети, файловой системы, Git, CI, production API, реальных сервисов, компаний, ключей, пользовательских данных, telemetry или side effect. Положительный результат всегда ограничен synthetic-contract-review-hand-off; он не меняет API и не означает выпуск, migration, rollout или production effect.
|
||
|
||
На момент передачи draft registry, README, app-файлы, articles.json, очередь, Git-state и чужие незавершённые изменения не менялись.
|
||
|
||
## Исследование и историческая граница
|
||
|
||
Граница статьи — **31 января 2026**. Все три источника — первичные/официальные и закреплены версией, датой и неизменяемым адресом или commit pin.
|
||
|
||
| Источник | Version / immutable pin | Узкий подтверждённый факт | Явная граница |
|
||
| --- | --- | --- | --- |
|
||
| [OpenAPI Specification v3.1.1](https://spec.openapis.org/oas/v3.1.1.html) | 3.1.1, **24.10.2024**, dated version publication | OAS описывает language-agnostic interface для HTTP API; schema описывает content request, response, parameter или header. | OAS не доказывает поведение implementation, tolerance consumer или success migration. |
|
||
| [Semantic Versioning 2.0.0](https://github.com/semver/semver/blob/7c834b3f3a4940d77ab593bc32583004d6a426a9/semver.md) | commit 7c834b3f3a4940d77ab593bc32583004d6a426a9, **18.06.2013** | SemVer требует precise public API и связывает incompatible public API change с major version. | Номер не определяет public surface сам и не доказывает совместимость конкретного consumer. |
|
||
| [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html) | RFC 9110, **June 2022**, immutable RFC | HTTP задаёт uniform interface и representations, не раскрывая внутреннюю реализацию ресурса. | RFC не задаёт application-level guarantee, escape hatch, contract family или verdict review. |
|
||
|
||
Для изменяемого по природе репозитория SemVer использован exact commit, а не live documentation URL. OAS привязан к датированной версии 3.1.1, RFC — к неизменяемой публикации. В каждой статье sourceList показывает version/pin рядом с ссылкой и повторяет границу применения.
|
||
|
||
## Проход 1 — проблема, плотность, голос и самостоятельность
|
||
|
||
Проверены первые два абзаца: у каждой статьи названы наблюдаемые problem/cost и короткое действие. Голос М9 — прагматичный технический: symptom → distinction → check → next action. Риторические обещания, «универсальные» рецепты и утверждения об эффекте для реальной команды исключены.
|
||
|
||
| Статья | Самостоятельный вопрос | Собственный механизм и visual | Цена ошибки |
|
||
| --- | --- | --- | --- |
|
||
| practice | Как оформить public surface до первого особого случая? | contract card, named surface и узкий documented escape hatch | скрытый флаг становится неявной зависимостью |
|
||
| mechanism | Почему поле, гарантия, exception и version нельзя считать одним объектом? | матрица guarantee/family и fail-closed statuses | изменение обнаруживается после смешения schema, reader и version |
|
||
| field | Как вести compatibility review для разных потребителей без ложного общего verdict? | inventory, family-first loop и return reason | команда чинит следы разных ожиданий вместо контракта |
|
||
|
||
У статей разная точка входа, набор пояснений, таблица, sequence и conclusion. Общий развёрнутый вводный блок не используется.
|
||
|
||
**Вердикт прохода 1: PASS.**
|
||
|
||
## Проход 2 — факты, историческая граница и исполнимость
|
||
|
||
Проверено, что утверждения о стандартах не выходят за их узкий scope. В частности:
|
||
|
||
- SemVer используется только после явного определения public API; номер версии не объявляет synthetic surface совместимой.
|
||
- OAS используется как vocabulary описания HTTP interface; документ не выдаётся за evidence исполнения.
|
||
- RFC 9110 используется для границы interface/representation; из него не выводятся business, latency, security или migration promises.
|
||
|
||
Модуль принимает только named fixed literals. Произвольный объект возвращает stop-unknown-fixed-review. Fixture fail-closed на всех требуемых нарушениях:
|
||
|
||
- stop-undocumented-escape-hatch;
|
||
- stop-implicit-guarantee;
|
||
- stop-incompatible-consumer;
|
||
- stop-incomparable-consumer.
|
||
|
||
Все article snippets импортируют только public exports и выполнены буквально из web/scripts:
|
||
|
||
{ status: 'synthetic-contract-review-hand-off',
|
||
fields: ['id', 'state', 'label'],
|
||
hatch: ['raw-envelope-v1'] }
|
||
|
||
{ status: 'stop-implicit-guarantee',
|
||
reasons: ['implicit-guarantee'],
|
||
next: 'write-the-guarantee-into-the-fixed-contract-or-remove-the-claim' }
|
||
|
||
{ status: 'stop-incomparable-consumer',
|
||
next: 'separate-contract-review-by-family',
|
||
assertions: 15 }
|
||
|
||
Positive output не меняет fixed contract, не вызывает API и не утверждает, что какая-либо внешняя интеграция работает.
|
||
|
||
**Вердикт прохода 2: PASS.**
|
||
|
||
## Проход 3 — release quality, mobile SVG, source/link audit и уникальность
|
||
|
||
| Статья | Основной текст без source list | SVG | Mobile inspection 375 px |
|
||
| --- | ---: | --- | --- |
|
||
| practice | **9 270** знаков | platform-api-2026-contract-surface.svg | PASS: gate разбит на две строки, скрытый обход остаётся читаемым |
|
||
| mechanism | **9 406** знаков | platform-api-2026-guarantee-exception-matrix.svg | PASS: заголовки колонок разнесены на две строки, статусы различимы |
|
||
| field | **9 245** знаков | platform-api-2026-consumer-compatibility-loop.svg | PASS: return route и stop card не обрезаны |
|
||
|
||
После mobile render исправлены три конкретных проблемы первого SVG-прохода: обрезанный текст gate, слипшиеся заголовки матрицы и выходящая за границу подпись return route. В final SVG отсутствуют script, foreignObject, javascript:, data:image и inline event handlers.
|
||
|
||
Cross-article uniqueness по body без source list:
|
||
|
||
- 0 одинаковых абзацев длиной от 160 знаков;
|
||
- 0 общих последовательностей из 12 слов во всех трёх парах.
|
||
|
||
Команды и результаты:
|
||
|
||
- node --check web/scripts/upgrade-2026-01.mjs — PASS.
|
||
- node web/scripts/upgrade-2026-01.mjs --verify-fixture — PASS, **15/15 assertions**.
|
||
- npm run audit:draft -- scripts/upgrade-2026-01.mjs из web/ — PASS: **9 270 / 9 406 / 9 245**; есть problem/cost в начале, table, figure с alt/caption, executable code, ordered sequence и source section.
|
||
- xmllint --noout для трёх SVG — PASS.
|
||
- SVG safety scan через rg — PASS.
|
||
- Sharp render всех трёх SVG на ширине 375 px — PASS и визуально просмотрен.
|
||
- Exact public-export snippets — PASS.
|
||
- Cross-article duplicate scan — PASS: paragraphs=0, fragments12=0 для всех трёх пар.
|
||
- git diff --check — PASS.
|
||
|
||
**Вердикт прохода 3: PASS.**
|
||
|
||
На момент окончания изолированного draft-прохода registry и README не были интегрированы; commit, push и полный site build оставались задачей основного редактора.
|
||
|
||
## Независимая приёмка основного редактора
|
||
|
||
При интеграции повторно проверены не выводы draft, а сами основания:
|
||
|
||
- OAS 3.1.1 по датированной публикации подтверждает дату **24 October 2024** и назначение language-agnostic interface description для HTTP API;
|
||
- GitHub API для exact SemVer commit вернул SHA `7c834b3f3a4940d77ab593bc32583004d6a426a9`, дату `2013-06-18T17:14:52Z`; закреплённый исходник прямо требует declare a public API и связывает incompatible change с major version;
|
||
- immutable RFC 9110 подтверждает uniform interface, определение representation как information и information hiding за interface.
|
||
|
||
Буквально запущены три публичных фрагмента из статей. Они вернули соответственно `synthetic-contract-review-hand-off` с `id/state/label`, `stop-implicit-guarantee` с именованной причиной и `stop-incomparable-consumer` с `separate-contract-review-by-family`; fixture содержит **15** истинных assertions. Ни один пример не имеет внешнего side effect.
|
||
|
||
После подключения overlay в `web/data/editorial-revisions.mjs` production-аудит подтвердил все три slug: **9 270 / 9 406 / 9 245** знаков, по одной figure, table и code example. В реестре **280** ревизий, а каждый январский slug присутствует ровно один раз. Повторная проверка полных body, включая code и исключая source list, дала 0 одинаковых абзацев от 160 знаков и 0 общих фрагментов из 12 слов во всех трёх парах.
|
||
|
||
Повторно подтверждены XML и safety SVG; mobile renders на 375 px просмотрены. `git diff --check` прошёл. `npm run build` завершил production build: TypeScript прошёл, сгенерированы **374/374** статические страницы.
|
||
|
||
**Итог независимой приёмки: PASS.** Январская тройка готова к отдельному commit и push; в неё не включаются сторонние незавершённые изменения.
|