Уточнить DSH, плагины, roadmap и контракты исполнения

designDocument/provider-edge-cases.md

@@ -0,0 +1,25 @@
+# Граничные случаи провайдеров
+
+Эта матрица — обязательные проверки adapter conformance, а не утверждение, что все API одинаковы.
+
+| Случай | Поведение платформы / адаптера | Проверка |
+|---|---|---|
+| 401 и истечение токена | Один refresh, затем reauth_required; без бесконечного replay | Два параллельных вызова не теряют новый refresh token |
+| 403 / отсутствие модели в плане | AUTH_SCOPE_DENIED или MODEL_UNAVAILABLE | Каталог моделей не считается entitlement |
+| 429 / Retry-After | Ограниченный backoff + jitter в пределах дедлайна | Не больше maxAttempts, отмена прерывает backoff |
+| 5xx до принятия запроса | Повтор только безопасной операции | Сохранение invocationId и provider request id |
+| Сеть оборвалась после отправки | outcome_unknown; не повторять автоматически tool side effects | Нет двойной сделки/письма при неопределённом ответе |
+| Обрыв SSE/WebSocket | Сохранить partial output; resume только при поддержке провайдера | Partial output не становится final result |
+| Разные tool-call форматы | Адаптер нормализует id/name/arguments; schema validation до выполнения | Фрагменты JSON и несколько параллельных tools |
+| Structured output не поддержан | Явный capability mismatch либо согласованный validate/repair режим | Нет обещания строгой схемы при text-only API |
+| Превышение контекста | CONTEXT_LIMIT; адаптация только по policy template | Не теряются обязательные инструкции и источники |
+| Usage отсутствует | usageStatus=unknown, не 0 | Биллинг не принимает неизвестный расход за бесплатный |
+| Разные модели или цены | Только явная fallbackPolicy | Не меняются провайдер/аккаунт/платёжный режим молча |
+| Отмена запроса | Локальный abort + доступный remote cancel | Отмена не обещает отсутствия списания |
+| OAuth callback повторён | Одноразовый code/state; replay отвергается | Binding tenant + actor + placement |
+| Device flow pending / slow_down | Соблюдать interval, expiry и cancel | Нет polling storm |
+| Пользовательский base URL | Allowlist или egress policy; запрет metadata/private ranges по умолчанию | Redirect не обходит SSRF-проверку |
+| Mobile background / sleep | Клиент переподключается по cursor, job живёт на Runner | Закрытие экрана не считается отменой Run |
+| API dialect version drift | Закреплённая adapter version, capability probe и контрактные fixtures | Несовместимость отключает конкретный mode |
+
+Каждый новый provider mode сначала проходит fake-provider fixtures без реальных списаний, затем минимальный opt-in live smoke с бюджетом. Артефакты проверки содержат redacted status, timings, capabilities, версии и date; не токены и не полные prompts. Provider mode включается независимо по local/on_prem/managed_remote.