progcode/editorial/reviews/2023-07-draft.md

П65 · 2023-07 · Контрактные тесты API — три прохода саморевью

Рамка пакета

• Slug: editorial-2023-07-practice-contract-tests, editorial-2023-07-mechanism-contract-tests, editorial-2023-07-field-contract-tests.
• Голос: М6, середина 2023 года. Системный практик говорит коротко и различает наблюдение, ожидание consumer, проверку provider и решение о выпуске.
• Sidecar содержит ровно пять новых файлов: этот review, один import-safe script и три локальных SVG. Registry, README, articles.json, очередь, Git и чужие файлы не менялись.
• Граница: это не запуск Pact, consumer, provider, CI, broker, HTTP-клиента или сети; не результат OpenAPI validation, production compatibility, browser trace или инцидента. Все service names, версии и responses в fixture имеют явный synthetic marker и создаются только в памяти Node.

Проход 1 — источники, факты и границы

• Источники перепроверены 31.07.2026. Все были исторически доступны к июлю 2023: OpenAPI Specification v3.1.0, 15.02.2021, Pact Docs: Introduction, обновлено 30.08.2022 и Pact Docs: Verifying Pacts, обновлено 11.08.2022. OAS назван описанием HTTP-интерфейса и не выдан за гарантию прикладной семантики. Pact упомянут как процесс consumer-driven contract и отдельной provider verification, а не как реально запущенный инструмент.
• createSyntheticContract() принимает только synthetic-contract-input-v1; unmarked input отвергается. inspectSyntheticProviderResponse() требует synthetic-provider-response-v1, не читает файловую систему и возвращает отдельные schemaMatch, semanticExpectationMatch, actualProviderVerification: not-run и productionCompatibility: not-claimed.
• Fixture намеренно показывает разные учебные случаи: active + ISO date позже synthetic reference time проходит форму и expectation; active + null и прошедшая дата проходят форму, но не проходят expectation; несуществующая календарная дата и числовой state ломают форму. Это не утверждение о реальном API и не результат provider verification. Rollback восстанавливает лишь snapshot учебного contract и сообщает deployment: not-performed.
• В текстах и проверках явно отделены schema match, semantic expectation и успешная реальная provider verification. Для последней названы contract version, provider version, provider state, исполнение interactions и адресуемый результат; synthetic fixture не может подменить ни один из этих фактов.

Проход 2 — голос, полнота и объём

• Первые два абзаца каждой статьи называют проблему и цену: структурно валидный JSON меняет смысл поля, consumer теряет действие, а команда рискует ошибочным выпуском или откатом. Маршрут везде фиксирован как «симптом → причина → проверка → действие».
• Все тексты соответствуют М6: прагматичны, не выдают учебную модель за личный production-опыт, не обещают универсальную совместимость и оставляют владельцу конкретный следующий шаг. Термины schema, semantic expectation, consumer, provider, provider state и verification раскрываются в связи с примером.
• В каждой ревизии есть одна доступная таблица, один исполнимый synthetic code/fixture, один упорядоченный маршрут, содержательная figure с alt/caption, разделы об ограничениях, rollback и следующем шаге. Источники стоят в отдельном разделе и не включены в объём.
• audit:draft посчитал основной текст: practice — 8 652, mechanism — 9 304, field — 9 229 знаков. Все значения внутри обязательного диапазона 5 000–15 000 и цели 8–10 тыс. знаков.

Проход 3 — визуалы, безопасность и выпуск

• SVG разделяют роли: consumer/provider flow, matrix schema/meaning/verification и release gate. В них нет script, foreignObject, внешних URL, data:image, пользовательского ввода или интерактивного поведения. Их подписи прямо говорят, что это учебные схемы, а не сеть, CI или журнал выпуска.
• Sharp-review всех трёх SVG на ширине 375 px выполнен вручную: заголовки, блоки и стрелки не обрезаны и не перекрываются; ключевые статусы PASS/FAIL/not-run читаются. Для узкого экрана схема оставляет только существенные отношения, а подробность дублируется alt и caption в статье.
• До передачи главному редактору выполнены: node --check web/scripts/upgrade-2023-07.mjs — PASS; node web/scripts/upgrade-2023-07.mjs --verify-fixture — PASS 20/20 после независимого model review; cd web && npm run audit:draft -- scripts/upgrade-2023-07.mjs — PASS для трёх slug; import-safe export без date/author — PASS; xmllint --noout — PASS; SVG safety scan — чистый результат; Sharp 375 px — PASS.
• Пакет не интегрирован, не коммитился и не пушился. Строгий архивный аудит, registry, README и production build оставлены главному агенту для отдельной приёмки.

Приёмка главного редактора

• Источники сверены по первичным страницам: OAS v3.1.0 фиксирует версию и дату 15.02.2021; Pact Introduction прямо различает статическую schema/specification и contract by example и имеет historical update 30.08.2022; Pact provider guide требует проверять локально работающий provider или CI и отмечен 11.08.2022. Эти страницы задают терминологию, но не являются доказательством запуска Pact здесь.
• Независимый model review нашёл, что «actionable date» была только строкой и regex: прошедшая дата могла пройти semantic expectation, а несуществующая дата — schema. Введено фиксированное synthetic reference time, active требует дату строго позже него, timestamp проверяется как календарный; fixture добавил past-date и impossible-date negative cases. Contract shape теперь тоже проверяет baseline semantic rule до inspection, чтобы произвольная подмена reference time не превращалась в accepted model. Fixture проходит 20/20.
• Визуальный review на 375 px подтвердил читаемость трёх схем. На consumer/provider flow подпись уточнена с «точной» до «будущей» даты, чтобы визуальная модель не расходилась с контрактом.
• После подключения трёх revision строгий audit подтвердил 8 868 / 9 515 / 9 459 знаков, по одной figure, table и code example; registry содержит 190 уникальных revision. Production build прошёл с 374 статическими страницами. articles.json и чужие изменения не затронуты.