Files
crank/docs/openapi-import.md
T
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

39 KiB
Raw Permalink Blame History

Импорт 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. Выполнение этого сценария относится к отдельной приёмке, а development done требует готового плана всех эпиков, протокола и шаблона 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. Идентификаторы, digest, ключи методов и версии берите из ответов сервера, а не вычисляйте самостоятельно.

После multipart preview создайте план через POST /imports/openapi/{job_id}/plans. Например, для одного анонимного метода без конфликта:

{
  "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:

{
  "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:

{
  "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:

{
  "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.

Новые 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. Проверка включена в единый план приёмки.

Локальная проверка пагинации использует 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-манифесте, например:

{
  "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:

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:

{
  "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; 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.