Executable Documentation

Запрос, который случайно сработал один раз, ещё не означает, что команда поняла API. AIRUS продаёт не «API похож на OpenAI», а предсказуемость: код клиента продолжит работать после смены модели, provider и версии. Поэтому документация здесь не описывает продукт — она исполняется вместе с ним.

Совместимость, которую нельзя опубликовать устаревшей

Executable Example Registry

Каждый пример имеет test_status, дату последней проверки, SDK-версию и оценку стоимости. Ответ сверяется с зафиксированной схемой детерминированно(структура, не текст — без живой модели), поэтому устаревший пример виден сразу.

Stable Error Intelligence

Ошибка сообщает не только статус, но и следующее действие: стабильный reason_code, retryable, retry_after, scope, safe_alternatives и docs_slug. Разработчик не уходит в археологическую экспедицию по Telegram-чатам.

Machine-readable Changelog

Changelog не только для людей: change_type / affected_endpoints / effective_at / replacement / requires_ci_action. Ваш pipeline сам заведёт issue на breaking-изменение.

Developer Experience Receipt

Итог миграции: example pass rate, stale-примеры, покрытие error-контракта → статус production_ready / conditional / not_ready. Метрика — не только Time to First Request, но и Time to First Diagnosed Error.

Actionable error object

POST /v1/airus/exec-docs/error/explain
{ "reason_code": "PROVIDER_RATE_LIMIT", "request_id": "req_1842" }
→
{
  "reason_code": "PROVIDER_RATE_LIMIT",
  "retryable": true,
  "retry_after_ms": 2400,
  "scope": "provider",
  "safe_alternatives": ["capability-route с fallback", "resolved_model backup"],
  "docs_slug": "errors/provider-rate-limit",
  "request_id": "req_1842"
}

HTTP-статус остаётся стандартным, но reason_code стабилен — на него можно писать логику ретраев и fallback.

Честно про слой

Движки детерминированы: error intelligence (actionable object), shape-верификация, freshness, changelog (requires_ci_action), DX receipt (sha256).
Правило зашито: пример verify сверяет фактический ответ с зафиксированной schema — без живой модели (структура, не текст); statuses passed/failed/stale/untested; неизвестный error-код → fail-safe (не retryable).
Без дублирования: Compatibility Contract/matrix/validator/deprecations — DevExperienceOps; capability/quickstart/debug — DevExOps; человеческий Error Doctor — /docs; migration lab и SDK — отдельно. Этот слой их дополняет машинным контрактом.
Ключевой caveat: реальный per-provider live-прогон контракт-тестов и live-исполнение примеров (Run in Sandbox) — roadmap (нужны ключи; текстовый smoke — Playground/EvalOps). estimated_cost — справочная оценка, не списание.
Деньги: money-ledger (append-only) не затрагивается; rule #6 metadata-only.

Для разработчиков Compatibility Exec-Docs API