Files
crank/docs/openapi-import.md
bsodfather 1b6db09bd1
CI / Rust Checks (push) Successful in 25m54s
CI / UI Checks (push) Successful in 5s
CI / Community Image Smoke (push) Successful in 1m47s
CI / Frontend E2E (push) Successful in 10m12s
CI / Deploy (push) Successful in 1m22s
fix(import): единая идентичность внешних URI (#96)
Единая transport-canonical идентичность внешних документов; normalizer v6 с immutable historical replay; matrix 1.0.4 / corpus 1.0.5. PR CI run840 success, локальная приёмка и independent review выполнены.

Co-authored-by: bsodfather <bsodfather@gmail.com>
2026-10-11 06:19:16 +00:00

282 lines
39 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Импорт OpenAPI
Crank умеет импортировать REST API из OpenAPI 3.x и Swagger 2.0 документов. Импорт создает черновики MCP-инструментов, которые можно проверить и доработать в мастере операции перед публикацией.
## Начало работы из OpenAPI
В **Getting Started** можно выбрать OpenAPI как источник первой Operation. Эта
ветка открывает тот же ограниченный импорт, что и раздел **Операции**: отдельного
парсера для onboarding нет. После preview проверьте methods, findings, security
references, конфликты и точное предложение плана. Устраните blockers или явно
исключите затронутые методы согласно выбранной policy; blocker не скрывается
переходом к частичному применению. Для security используйте совместимый Auth
Profile и ссылку на Secret, не копируйте credential в onboarding.
После Apply внимательно проверьте полный import report. Apply может создать
несколько Drafts; onboarding продолжает путь только после явного выбора одной
актуальной actionable Draft. Никакая Operation не публикуется автоматически.
Далее откройте выбранную Draft в обычном мастере, проверьте её contract и
выполните test, затем отдельно опубликуйте Operation. Создайте и опубликуйте
Agent с опубликованной версией, выпустите MCP client key и выполните первый
публичный `tools/call` через обычный MCP client. Checklist подтверждает шаги по
серверному состоянию; сам факт открытия страницы или возврат из import modal не
считается завершением.
При refresh возобновите Getting Started и проверьте authoritative выбор Draft и
результат импорта. Неизвестный исход Apply восстанавливайте повтором того же
плана с исходной digest/idempotency identity. При stale plan, source correction
или изменившемся digest создайте новый preview и заново подтвердите последствия;
не повторяйте Apply со старым планом и не считайте локальный return context
источником истины. Для защищённых методов проверьте, что onboarding хранит
только Auth Profile reference и серверные идентификаторы; исходный документ
хранится через canonical artifact flow, а secret value не включается в
onboarding state.
Человеческий пятиучастниковый OpenAPI usability run и его обезличенный шаблон
описаны в [ручном regression checklist, раздел 5.10](manual-regression-checklist.md#510-getting-started-ветка-готового-openapi-для-пяти-участников).
Выполнение этого сценария относится к отдельной приёмке, а development done требует готового [плана всех эпиков](acceptance-test-plan.md), протокола и шаблона evidence.
Этот сценарий описывает ожидаемый путь и требования к записи результатов; он не
является свидетельством проведённого запуска. До реального прогона на чистой
ревизии его статус — `not_run`.
## Как импортировать
1. Откройте раздел **Операции**.
2. Нажмите **Импорт OpenAPI** рядом с кнопкой **Новая операция**.
3. Загрузите ровно один UTF-8 `.yaml`, `.yml` или `.json` файл размером от 1 B до 256 KiB. Вставка текста не поддерживается.
4. Нажмите **Разобрать документ**.
Preview принимает до 2 000 methods; документ с большим числом кандидатов отклоняется целиком с typed ошибкой, без скрытого усечения.
5. Проверьте preview: сгенерированный contract сохраняет parameter locations, body formats, варианты успешного ответа и effective security requirements.
API помечает метод `actionable`, `unresolved` или `blocked` по typed findings и доступным security choices; окончательное разрешение выбранного Auth Profile происходит при создании плана.
6. Выберите нужные группы и методы.
7. Проверьте `Base URL`. Если в документе нет `servers`, укажите URL вручную.
8. Для уже существующей операции подтвердите решение отдельно: пропустить точную операцию, создать отдельную операцию с указанным вами свободным именем или добавить новую черновую версию к выбранной REST-операции. Автоматический подбор имени при применении плана не выполняется.
9. Создайте план и проверьте число выбранных, исключённых, доступных и заблокированных методов. По умолчанию действует полный режим: любой blocker запрещает Apply всего документа. Для частичного импорта явно включите режим и выберите только методы без blocker findings с разрешёнными зависимостями и аутентификацией.
10. Для защищённых методов выберите security alternative (OR-варианты preview; неподдерживаемые варианты, включая AND/OAuth, показаны заблокированными) и, если требуется аутентификация, совместимый Auth Profile текущего workspace — по безопасным метаданным `id/name/kind` из preview. Вариант без схем — анонимный вызов без профиля. Статус привязки показывает только API: `Unresolved` до проверки, `Resolved` после подтверждения планом, `Blocked` при отказе; UI не вычисляет resolved локально. Незакрытое обязательное требование или недоступный профиль оставляет метод заблокированным.
11. Подтвердите план и примените его. Создание плана не меняет операции. Применение выполняет все выбранные изменения одной транзакцией и показывает результат для каждого метода.
## Прямые запросы к API плана
Все маршруты ниже имеют префикс `/api/admin/workspaces/{workspace_id}`.
Используйте session cookie и `x-csrf-token` для POST, как описано в
[авторизации Admin API](admin-api.md#авторизация). Идентификаторы, digest,
ключи методов и версии берите из ответов сервера, а не вычисляйте самостоятельно.
После multipart preview создайте план через
`POST /imports/openapi/{job_id}/plans`. Например, для одного анонимного метода
без конфликта:
```json
{
"selection_mode": "partial",
"selected_operation_keys": ["GET /pets"],
"server_url": "https://api.example.com",
"decisions": [{"operation_key": "GET /pets", "action": "create"}]
}
```
Ключ `GET /pets` здесь — пример; используйте точный `key` из preview.
`full` требует полного выбора и не допускает blockers; `partial` явно исключает
невыбранные методы. `server_url` можно не передавать, если URL получен из документа.
Решение `rename` требует `confirmed_name`, `skip` и `new_version` — точный
`target_operation_id`. Для защищённого метода укажите совместимый
`auth_profile_id` и выбранный `security_alternative_index`; значения секретов
в этих запросах не передаются.
Ответ содержит `plan_reference`, `plan_digest`, `catalog_revision`,
`support_matrix_version`, `expires_at`, `selection_mode`, `counts` и `candidates`.
Само создание плана не создаёт Draft. При повторном открытии выполните
`GET /imports/openapi/plans/{plan_reference}` без тела запроса: ответ возвращает
`revalidation_status` (`current` или `stale`), `revalidation_required`, `reason`,
исходные `plan_digest`, `counts` и `candidates`. Срок действия плана ограничен
сроком preview job; после истечения или изменения исходных условий создайте
новый preview и подтвердите новый план.
Применение: `POST /imports/openapi/{plan_reference}/apply`:
```json
{
"plan_digest": "<plan_digest из ответа создания плана>",
"idempotency_key": "import-pets-001"
}
```
Сохраните этот ключ вместе с digest до отправки. При потере ответа повторите
тот же запрос с теми же значениями: сервер возвращает сохранённый отчёт без
повторного создания версий. Ответ содержит `status`, `plan_id`, `plan_digest`,
`idempotency_key`, `counts`, `outcomes` и `recovery`; проверяйте результат каждого
метода, включая excluded/rejected. При отказе не подменяйте digest и не повторяйте
старый план с новым ключом в надежде обойти причину отказа.
Чтобы продолжить Getting Started, получите актуальный `revision` через
`GET /onboarding`, затем вызовите `POST /onboarding/import-context`:
```json
{
"application_idempotency_key": "import-pets-001",
"plan_digest": "<тот же plan_digest>",
"expected_revision": 1
}
```
Вместо `1` используйте текущий `revision`. Сервер возвращает `registered` и
поля актуального onboarding, включая `revision` и `import_context` с вариантами
выбора. Затем `POST /onboarding/select-draft` явно выбирает одну доступную Draft:
```json
{
"application_idempotency_key": "import-pets-001",
"plan_digest": "<тот же plan_digest>",
"operation_id": "<operation_id из применённого отчёта>",
"operation_version": 1,
"expected_revision": 2
}
```
Обе числовые величины здесь — примеры: возьмите версию Draft из серверного
отчёта и revision из последнего onboarding-ответа. Ответ содержит `selected` и
обновлённый onboarding. При конфликте revision перечитайте состояние перед
повтором. Выбор не публикует операцию: test, publish, Agent/key и публичный
MCP-вызов остаются отдельными шагами.
## Загрузка и восстановление
Браузер отправляет выбранный файл как `multipart/form-data`; границу multipart формирует сам браузер. Файл остаётся только в памяти текущего окна импорта. При замене файла, сбросе, закрытии окна, смене workspace/языка или уходе со страницы текущий запрос отменяется, а поздний ответ игнорируется. При `pagehide` (включая BFCache) выбранный файл и Base URL очищаются: после возврата нужно выбрать файл заново, повтор старой загрузки не предлагается.
До сохранения source snapshot импорт проверяет основной документ и загруженные allowlisted `$ref`-документы вместе, включая разрешённые ссылки. Если такая проверка находит literal credential, загрузка отклоняется; значение не попадает в artifact storage, preview или текст ошибки. Безопасные внешние ссылки сохраняются как digest-проверенные immutable snapshots и не загружаются заново при Apply.
Перед разбором документ проходит ограниченную предварительную проверку без материализации YAML-aliases. Для каждого документа допуск на развёрнутые строки и ключи равен `min(16 × max(предел байтов, предел скаляра), 64 MiB)` (при значениях по умолчанию ≈4 MiB), а для набора основной документ + внешние snapshots — `min(сумма допусков, 64 MiB)`. Действуют и позлементные пределы: 256 KiB на документ, 256 KiB на скаляр/ключ, 128 aliases, 50 000 узлов, глубина 64, 10 000 элементов коллекции. Превышение возвращает контролируемую typed-ошибку предела без частичного импорта; обычные небольшие aliases, duplicate keys, non-finite значения и legacy-разбор сохраняют прежнее поведение.
Раскрытие `$ref` в preview учитывает отдельный общий бюджет копируемых строк и ключей: `min(16 × max(предел документа, предел внешнего документа, предел скаляра), 64 MiB)` (по умолчанию ≈4 MiB). Бюджет общий для всего разрешения ссылок и не сбрасывается на каждую ссылку; превышение даёт контролируемую typed-ошибку предела до выделения памяти, а обычные документы, циклы и семантика `$ref` (включая sibling-поля OAS 3.1) не меняются.
Для ошибки можно выбрать файл заново или нажать **Повторить**. Диагностика загрузки показывает только ограниченные имя/размер файла и, если backend их вернул, `Request ID`/`Trace ID`; содержимое спецификации и внутренние пути не выводятся. Подтверждение плана показывает счётчики и решения по кандидатам, но не исходный документ и не учётные данные. Digest плана передаётся в Apply автоматически.
При неизвестном результате Apply, например после разрыва соединения, повторите запрос с теми же ссылкой на план, digest и ключом идемпотентности. Повтор после commit возвращает сохранённый отчёт и не создаёт ещё одну версию; тот же ключ с другим digest даёт конфликт. Пока Apply выполняется, повторное нажатие кнопки не отправляет вторую логическую операцию.
Если с момента создания плана изменились источник или внешние документы, версия импортера, workspace catalog либо состояние выбранной операции, а также конфигурация выбранного Auth Profile или версия его секрета, Apply отклоняет план без частичных изменений и предлагает заново разобрать документ. Read-only `GET /api/admin/workspaces/{workspace_id}/imports/openapi/plans/{plan_id}` проверяет сохранённый план при повторном открытии и возвращает `current` или `stale` с `revalidation_required`; проверка не создаёт операции и не делает запрос к изменяемому внешнему `$ref`. Отозванный или недоступный профиль также приводит к отказу. Срок жизни плана ограничен сроком исходного preview job.
Новые планы `import-plan-v2` содержат source/external snapshot digests, версии normalizer/projection и support matrix, catalog revision, полный список кандидатов и selections, findings, решения по конфликтам и причины исключений. Digest вычисляется из semantic material: случайные идентификаторы plan/job/source/новой операции и время создания в него не входят. Сохранённый payload остаётся неизменяемым, а новый выбор или решение создаёт новую запись. Старые `import-plan-v1` продолжают проверяться по исходному полному digest payload.
Workspace catalog для revision и naming читается целиком до 10 000 записей; превышение лимита даёт ошибку вместо усечения. Revision учитывает релевантные метаданные операций, а состояние выбранных Auth Profile и Secret проверяется по безопасным snapshot-метаданным без чтения raw/ciphertext credentials. Для `import-plan-v2` предел сохранённого payload — 16 MiB при общем пределе 2 000 candidates; исторический `import-plan-v1` сохраняет свой предел 4 MiB. Запрос создания плана ограничен 16 MiB как в API, так и в веб-прокси; предел применяется только к этому маршруту и не отменяет проверки содержимого плана.
## Что создается
Для каждого нового выбранного метода Crank создает отдельную операцию в статусе черновика. Для `new_version` новая Draft Version добавляется к точно выбранной операции; текущая опубликованная версия, прежние версии, привязки и история остаются прежними. `skip` не меняет выбранную существующую операцию. Исключённые методы не создаются, но перечисляются в отчёте.
Контракт нового черновика:
- имя инструмента берется из `operationId`, а если его нет — строится из HTTP-метода и пути;
- отображаемое имя берется из `summary`;
- описание инструмента берется из `description`;
- группа берется из первого `tag`;
- query/path/header/cookie параметры становятся отдельными typed inputs MCP-инструмента;
- JSON, `application/x-www-form-urlencoded` и `multipart/form-data` сохраняются как request contract; при нескольких поддерживаемых форматах вызов передаёт верхнеуровневые `content_type` и `body`;
- все успешные `2xx` варианты сохраняются, включая `204` и response без тела.
Form/multipart поддерживает object root со scalar-полями, массивами scalar-значений и multipart files. Вложенные обычные объекты и массивы массивов блокируют импорт. Для URL-encoded массивов поддержана повторная передача ключей (`style: form`, `explode: true`; в Swagger — `collectionFormat: multi`). CSV и другие неподдерживаемые encoding-настройки получают blocker с указанием места в исходной спецификации.
После импорта откройте созданный черновик в мастере операции. На шаге **Связи полей** Crank покажет уже созданный маппинг в визуальном виде:
- `Path` — параметры из пути, например `/users/{id}`;
- `Query` — query-параметры URL;
- `Header` — заголовки запроса;
- `Cookie` — cookie-параметры, которые adapter сериализует в один wire header;
- `Body` — typed тело запроса. Multipart file передаётся inline-объектом `{data_base64, filename?, content_type?}`; путь к файлу и URL не принимаются.
YAML-маппинг остается доступен в блоке **Дополнительно**, но для обычной настройки его редактировать не нужно.
## Рекомендации
После разбора Crank показывает предупреждения, если в спецификации не хватает данных для качественного MCP-инструмента:
- нет `operationId`;
- нет `summary` или `description`;
- нет схемы успешного ответа;
- нет `servers`;
- слишком много входных параметров;
- требуется ручная проверка неполных metadata.
Эти предупреждения не блокируют импорт, но перед публикацией лучше открыть созданную операцию и проверить:
- описание инструмента;
- входные поля и их обязательность;
- связи `Path / Query / Header / Body`;
- пример входных данных для теста;
- поля ответа, которые увидит MCP клиент.
## Ограничения Community
В Community импортируются только REST/HTTP методы: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`. `TRACE` и `CONNECT`, XML media types и неподдерживаемые serialization constructs получают явный finding и не получают неявного fallback.
Semantic loss получает blocker с source location: такой candidate нельзя применить как actionable Draft. Это относится к неподдерживаемым schema/serialization constructs и невалидным target URL, включая embedded userinfo.
Один endpoint с несколькими request formats остаётся одним Tool. Поля `content_type` и `body` выбирают одну schema и соответствующую сериализацию; неизвестный selector или body другой ветви отклоняются до отправки запроса. Для единственного формата selector не нужен. Подробный inline-file contract описан в [REST](protocols/rest.md).
Новые imports используют `normalized-ir-v6` / `preview-v6`: source-derived candidate, finding и naming conflict включают безопасный RFC 6901 `source_location`; typed findings сохраняют стабильный `code`. Схемы и маппинги принадлежат candidate с его source pointer и проверяемой provenance в IR/reference graph. Производные группы, counts и summary связаны с исходником через membership candidates; единственный pointer или finding code для такой агрегации был бы ложной provenance. Общая pure HTTP(S) URI identity (`url::Url`) появилась в `normalized-ir-v6`: materializer и resolver больше не расходятся на percent-encoded dot segments и special-query символах. Исторические v2/v3/v4/v5 jobs, включая прежнюю пару `normalized-ir-v5`/`preview-v6`, воспроизводят сохранённый preview без повторного разбора, а legacy-v1 использует отдельную историческую projection. Обновление importer не меняет inputs существующих jobs.
Другие форматы спецификаций и протоколов в Community-импорт не входят.
## Проверка больших preview на Reference Deployment
Этот benchmark выполняется на этапе отдельной приёмки; для завершения разработки поставляются harness, параметры среды, порог и evidence template, а не фактический внешний run. Проверка включена в [единый план приёмки](acceptance-test-plan.md).
Локальная проверка пагинации использует mock API и измеряет только browser handler; она не подтверждает требование AC-11 о полной интерактивности ≤2 s p95. Для операторской проверки нужен отдельный Reference Deployment: Linux x86_64, сервисы с PostgreSQL 16 и Valkey 8 на 4 vCPU/8 GiB, SSD не менее 100 GB, 3000 IOPS и 100 MB/s, LAN не менее 1 Gbit/s, и отдельный эквивалентный load-generator с браузером. Перед запуском сохраните подтверждённые параметры без секретов в JSON-манифесте, например:
```json
{
"deployment": {
"host_id": "reference-server", "cpu_model": "record actual model",
"cpu_cores": 4, "ram_gib": 8, "postgres_version": "16.0",
"valkey_version": "8.0", "storage_type": "SSD",
"ssd_capacity_gb": 100, "ssd_iops": 3000,
"ssd_throughput_mb_s": 100, "lan_mbps": 1000
},
"load_generator": { "host_id": "reference-runner", "cpu_cores": 4, "ram_gib": 8 },
"browser": { "host_id": "reference-runner" }
}
```
На load-generator задайте `PLAYWRIGHT_BASE_URL` для удалённого origin, `PLAYWRIGHT_SKIP_WEB_SERVER=1`, абсолютный путь `CRANK_AC11_REFERENCE_ENV_JSON` и учётные данные через `CRANK_E2E_ADMIN_EMAIL`/`CRANK_E2E_ADMIN_PASSWORD` в окружении; затем выполните из `apps/ui`:
```sh
npx playwright test tests/e2e/openapi-preview-reference.spec.js --workers=1
```
Harness отправляет реальный `openapi.yaml` с 2 000 operations (157 023 B), делает warm-up и 20 независимых preview-запросов без mock routes. Каждый замер начинается при нажатии Preview и заканчивается после ответа API, разбора и отображения первой страницы с доступной кнопкой создания плана. JSON attachment/stdout сохраняет все 20 samples, p95, DOM bound и sanitized сведения об окружении. Отсутствующий URL пропускает только отдельный операторский тест; при заданном URL отсутствующий или неподходящий манифест вызывает ошибку. Сам манифест — декларация оператора; результат требует фактического запуска в указанной инфраструктуре.
Локальное ограниченное evidence: `cd apps/ui && npx playwright test tests/e2e/openapi-preview-partial.spec.js --grep 'AC-11' --workers=1` выводит `AC11_LOCAL_SHARED_HOST_METRICS` с сырыми samples. На shared host Linux x86_64 (Intel Core i5-4300U, 4 logical CPUs), headless Chromium 149, viewport 1280×720, mock fixture 2 000 candidates показал максимум 100 строк preview и 100 строк плана. Время ниже — длительность browser event handlers (`performance.now()`, ms), без API и LAN:
```json
{
"search_filter_ms": [7, 26, 12.7, 9.6, 5.3, 5.2, 6.5, 7.8, 5.5, 7.8, 5.6, 9.8, 8.2, 5.2, 7.9, 11.6, 6.9, 5.3, 6.6, 6],
"preview_page_change_ms": [50.1, 30.1, 23.3, 18.8, 21.3, 24.2, 30, 20.6, 69, 23.9, 22.3, 19.5, 18.8, 20.3, 25.1, 20.8, 20.6, 21.2, 22.4, 24.8],
"plan_page_change_ms": [2.8, 1.9, 1.9, 4.1, 2.9, 3.6, 2.9, 3.9, 2.4, 1.8, 4, 4.7, 1.9, 2, 1.7, 2.1, 1.8, 2.1, 1.7, 3.3]
}
```
## Нормативная матрица и regression corpus
Машинная матрица версии `1.0.4` хранится в [`crates/crank-import/tests/support-matrix.yaml`](../crates/crank-import/tests/support-matrix.yaml); corpus version — `1.0.5`. Матрица фиксирует контракт отдельно для OpenAPI 3.0, OpenAPI 3.1 и Swagger 2.0. Acceptance test запускает нормализатор на отдельном probe для каждой строки, включая все 100 успешных кодов в каждом формате, и сверяет сохранённую semantics или точный blocker; выполненные probes списываются со всех строк версии, поэтому неподвергнутая проверкой строка матрицы падает gate. Corpus version `1.0.5` добавляет два hostile external-URI regression fixture (`regression-uri-encoded-dot.yaml`, `regression-uri-query-quote.yaml`) и модуль `reference_uri.rs`: encoded-dot path segment и апостроф в query канонизируются в URL transport identity, поэтому поставленный snapshot разрешается, а default-deny pass, statuses и denominators не ослабляются. Matrix `1.0.4` фиксирует общий external HTTP(S) URI canonicalization contract без изменения statuses. Предыдущий corpus release `1.0.4` был metadata-only SemVer increment; `1.0.3` добавил hostile fixture `hostile-security-scope.json`: document-level требование безопасности применяется только к унаследовавшему его secured candidate (`GET /secure`, location `/security/0`), а операция с явным `security: []` (`GET /public`) остаётся actionable без глобального blocker.
| Конструкция | OpenAPI 3.0/3.1 | Swagger 2.0 | Сохраняемый контракт или finding |
|---|---|---|---|
| `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS` | Поддерживается | Поддерживается | Метод и исходный path переходят в Operation |
| `path`, `query`, `header`, `cookie` параметры | Поддерживается | `path`, `query`, `header` поддерживаются; `cookie` явно unsupported | Имя, schema, required и source location сохраняются; Swagger cookie получает `unsupported_cookie_parameter` |
| Placeholder без объявленного path parameter | Blocker | Blocker | `path_parameter_not_declared` указывает точный operation source node; path-level и operation-level declarations, включая разрешённый `$ref`, учитываются |
| Schema defaults | Scalar сохраняется; object/array — blocker | Scalar сохраняется; object/array — blocker | `unsupported_compound_default` указывает точный `/default`; составное значение не превращается в lossy Draft |
| JSON, urlencoded, multipart | Поддерживается | Поддерживается по `consumes`/body parameter | Schema и content type остаются частью request contract |
| Успешные `2xx`, включая `204` | Поддерживается | Поддерживается | Каждая строка 200–299 проверяется отдельным probe; status сохраняется, а 204/205 остаются bodyless |
| Локальные и allowlisted external `$ref` | Поддерживается | Поддерживается | Разрешение только из загруженного документа или digest-проверенного snapshot; тесты не загружают fixture по сети |
| `allOf`, `oneOf`, `anyOf` | Поддерживается | Поддерживается | Совместимые `allOf` ветви объединяются; `oneOf` и `anyOf` остаются вариантами schema |
| bearer/basic/API key security schemes | Поддерживается | Поддерживается для basic и API key header/query | Схемы типизируются без credential values; preview предлагает только совместимые workspace Auth Profiles с активными current secrets |
| Security requirements с несколькими alternatives | Поддерживается | Поддерживается | Каждая OR alternative сохраняется отдельно и получает собственный список совместимых Auth Profiles; unsupported alternative не блокирует доступную соседнюю alternative |
| Несколько schemes в одной security alternative (AND) | Blocker для этой alternative | Blocker для этой alternative | Составное требование сохраняет имена схем в finding; оно не становится actionable через single-scheme Auth Profile |
| OAuth2, OpenID Connect, mutual TLS и неизвестные схемы | Manual configuration | Manual configuration | Явный unsupported finding; схема не извлекает token/client secret и не становится actionable автоматически |
| security override: operation-level `security: []` | Поддерживается | Поддерживается | Явный пустой массив отключает наследование: только operations с эффективным requirement получают source-located blocker, связанные операции остаются actionable |
| Микс public/secured operations | Поддерживается | Подвергается проверке | Blocker принадлежит только затронутому candidate; global blocker не создаётся для требований одного operation |
| XML, `TRACE`, `CONNECT` | Unsupported | Unsupported | Source-located finding; blocker не становится actionable Draft |
Матрица `1.0.4` фиксирует общий pure HTTP(S) URI canonicalization contract во всех трёх форматах; matrix `1.0.3` добавила исполняемые probes обоих blockers во всех трёх форматах; coverage validation отвергает неподтверждённые source findings. Новые primary документы и external snapshots отвергают повторённые JSON/YAML mapping keys вместо last-key-wins; корректный YAML flow syntax сохраняется. HTTP(S) scheme регистронезависима, percent-encoded dot segments и special-query символы приводятся к `url::Url` identity, а Unicode hostname сопоставляется с punycode snapshot identity. Historical legacy v1 decoder и уже сохранённые completed reports не переписываются; новый preview с изменившейся semantics требует нового подтверждённого плана.
Offline corpus в `crates/crank-import/tests/corpus/` содержит 50 synthetic representative документов и hostile subset. Manifest фиксирует SHA-256 исходных файлов, canonical digest JSON, происхождение и лицензию; для representative документов он также фиксирует полный canonical preview и frozen candidates (schemas, mappings, actionable/blocker), а для hostile — ожидаемые отказы и findings. Команда `just openapi-corpus` прогоняет настоящий normalizer, сравнивает независимо перечисленные raw source pointers с canonical source tree и coverage ledger, проверяет порог 95% actionable от всех representative Operations и отдельно нулевой silent loss. Evidence связывает digest manifest и matrix, включает content digest и создаётся без перезаписи; конфликт содержимого для того же identity останавливает gate. CI прикладывает `crates/crank-import/target/openapi-corpus/evidence-<identity>.json`. Artifact не содержит загруженный исходник или значения secret-like examples.