Справочник

Справочник информационно-ориентирован. Его задача — быть точным и полным, а не обучать или убеждать: он излагает, что представляют собой интерфейсы, каковы их входы и выходы и каковы значения по умолчанию — и на этом останавливается. Проза суха намеренно. Если вы хотите изучить систему на практике, начните с учебника; если хотите выполнить конкретную задачу, используйте практическое руководство; если хотите понять, почему система построена так, как построена, прочитайте пояснение. Этот раздел — для случаев, когда вы строите против продукта и вам нужен точный контракт.

Большая часть того, что следует, генерируется или выводится вручную непосредственно из собственных исходных артефактов продукта, поэтому справочник не может тихо отклониться от того, что движок на самом деле отдаёт. Там, где возможность находится на стадии проектирования или после v1, соответствующая страница говорит это прямо; см. Честность и пределы об общем контракте.

Справочные области

Область	Что она документирует	Источник истины
REST API	HTTP API control plane: аутентификация, настройка, тенантность, агенты, R/RW access map, токены и журнал аудита.	Контракт продукта OpenAPI 3.1 (53 базовых пути), рендерится во время сборки из реального файла — не копия.
Маршруты модулей (beta)	Маршруты модулей продукта (`/v1/m/<ns>/…`) — finops, compliance, governance, sessions, models, knowledge и др. — как отдельный beta-документ OpenAPI.	Тот же контракт OpenAPI 3.1, отражаемый во время сборки из маршрутов, которые регистрируют модули.
Политика стабильности	Версионирование, уровни стабильности, сигнализация deprecation/sunset и минимальные окна поддержки для API, поставщика и клиентских SDK.	Внутрикодовая таблица устаревания и её тесты окон, проваливающие сборку.
gRPC	gRPC-зеркало движка и версионированный протокол плагинов, по которому общается каждый внепроцессный коннектор и модуль.	Таблицы регистрации `grpc.ServiceDesc`, которые серверы передают gRPC.
Шина событий	Внутренняя шина событий: конверт события, первичные типы событий и полезные нагрузки наблюдений, которые коннекторы поднимают на неё.	Контракт AsyncAPI 3.0, выведенный вручную из Go SDK.
Экраны консоли	Каждый маршрут, публикуемый консолью, с требуемым разрешением RBAC и справочной страницей, которую открывает его встроенная ссылка справки.	Перечень маршрутов консоли, сверяемый с собранным маршрутизатором.
Каталог модулей	30 продуктовых модулей — что каждый из них представляет, его статус и какие маршруты (если есть) он раскрывает вне базового API.	Каталог возможностей продукта и типизированные интерфейсы модулей.
CLI	Бинарный файл `olivares` и его подкоманды — `serve`, `collector`, `audit`, `license`, `openapi`, `version` — и их флаги.	Скомпилированные определения команд.
Конфигурация	Переменные окружения и опции среды выполнения: каталог данных, обвязка источников, движок авторизации и подпись журнала.	Загрузчики конфигурации движка.

REST API

Справочник REST API рендерится во время сборки из контракта продукта OpenAPI 3.1 — того же документа, который движок отдаёт на собственной конечной точке /openapi.json. Ничто не переписывается вручную, поэтому отрендеренный справочник и есть контракт. Он покрывает поток первой загрузки без учётных данных (POST /v1/setup с одноразовым токеном настройки, затем POST /v1/auth/login), идентичность и тенантность, агентов, access map чтения/записи (GET /v1/access-edges; её сверенный дрейф наименьших привилегий отдаётся модулем access-map, а не базовой поверхностью), управление токенами и журнал аудита.

Контракт описывает 53 базовых пути. Это намеренно: это стабильная, версионированная поверхность control plane, а не каждый маршрут, на который движок может ответить. То, к чему обязывает «стабильность» — версионирование, сигнализация устаревания и минимальные окна поддержки — это политика стабильности API.

Маршруты модулей — например /v1/m/accessmap/graph, /v1/m/accessmap/neighbors и /v1/m/accessmap/drift модуля access-map — не входят в стабильный базовый документ из 53 путей. Они опубликованы как отдельный beta-документ OpenAPI в справочнике маршрутов модулей (обслуживается по адресу /openapi.beta.json и отражает фактически регистрируемые модулями маршруты), так что стабильная поверхность остаётся отличимой, а полная поверхность продукта — программируемой. Beta означает, что формы могут изменяться с уведомлением (окно поддержки короче, чем для stable); детали на уровне полей по-прежнему живут в типизированных интерфейсах Go и TypeScript. Результат access-map с наименьшими привилегиями — это маршрут drift; отдельной конечной точки diff нет.

Зеркало gRPC (`olivares.api.v1`)

Control plane также раскрывает gRPC-поверхность — службу ControlPlane в версионированном proto-пакете olivares.api.v1. Это сфокусированное, замороженное зеркало подмножества REST-контракта выше (информация о сервере, список/получение/создание агентов, верификация аудита), используемое там, где предпочтителен типизированный бинарный контракт (например, коллекторы). Оно зеркалит REST-контракт, а не расширяет его; документ OpenAPI остаётся канонической поверхностью для полного API.

Шина событий

Справочник по шине событий — это контракт AsyncAPI 3.0. Шина по умолчанию внутрипроцессная — коннекторы поднимают нормализованные наблюдения на неё как типизированные события, а модули и коннекторы вывода подписываются по типу события и реагируют, без того, чтобы кто-либо из них вызывал друг друга напрямую. Распределённая привязка над NATS опциональна, не требуется.

Контракт выведен вручную из Go SDK, не сгенерирован: авторитетные определения — это конверт события, первичные типы событий и полезные нагрузки наблюдений (наблюдения доступа агент→ресурс, образцы стоимости и отчёты о находках). Там, где шина ещё не формализует что-то, справочник так и говорит, а не изобретает это.

Каталог модулей

Каталог модулей перечисляет 30 модулей, которые сидят поверх базового движка, в девяти областях возможностей. Один из самых полезных — R/RW access map с её диффом Permitted-vs-Observed: она читает из логов, OTEL и (как несотрудничающую подстраховку) eBPF, а не сидит в пути данных, и хранит только отношение какой агент может читать или писать какой ресурс — никогда полезные нагрузки, секреты или PII.

Каталог честен относительно статуса и покрытия. Каждый модуль несёт свою зрелость — большинство живут и подключены от начала до конца, некоторые частичны или opt-in. Пассивное наблюдение разбито на уровни по типу хранилища — clean для SQL-, объектных и warehouse-хранилищ; lossy для документных и векторных хранилищ; невозможно без сотрудничества для in-memory или встроенных хранилищ — и каталог помечает, где модуль на стадии проектирования. Реестр собственных моделей и тонкая настройка — это планируемая возможность, а не один из 30 поставленных модулей.

CLI

Справочник CLI документирует единый бинарный файл olivares и его подкоманды. Та, которую вы запускаете для управления control plane — это serve, которая запускает HTTP-слушатели (REST + встроенный веб-UI) и gRPC; TLS включён по умолчанию. Другие подкоманды покрывают коллектор, журнал аудита (verify, checkpoint, export), инструментарий лицензий и эмиссию документа OpenAPI.

Конфигурация

Справочник конфигурации перечисляет переменные окружения и опции среды выполнения, которые формируют развёртывание. Несущие — это каталог данных (OLIVARES_DATA_DIR), реальная (не демо) обвязка источников, читаемая из OLIVARES_SOURCES_CONFIG до запуска движка, и селектор движка авторизации OLIVARES_PDP_ENGINE (cedar, opa или none).

Два правила проектирования проходят через всю поверхность конфигурации. Ненастроенный источник честно предупреждает, а не проваливает движок. И шов авторизации только когда-либо ограничивает, никогда не расширяет: RBAC по умолчанию запрещающий, просмотр графа доступа — привилегированное действие, и каждое такое чтение аудируется.