Добавить дизайн Invest Harness и контракты платформы

designDocument/configuration-ui.md

@@ -0,0 +1,38 @@
+# Пользовательская конфигурация
+
+## Контракт автора
+
+Шаблон содержит config.schema.json, config.defaults.json и необязательную ui.schema.json. JSON Schema описывает данные, UI Schema — только представление. Собственные параметры harness и plugins располагаются в пространствах имён harness и plugins.<packageId>; схема template объединяет их без конфликтов имён.
+
+Базовый диалект — JSON Schema Draft 2020-12. MVP renderer поддерживает object, string, number, integer, boolean, array, enum, required, additionalProperties, minimum/maximum, minLength/maxLength, minItems/maxItems и локальные $ref/$defs. oneOf и условные секции включаются только после проверки renderer и валидатора. Неизвестные UI-компоненты и неподдерживаемые keywords отвергаются при публикации, а не игнорируются. Удалённые $ref запрещены. Ограничиваются размер, вложенность и сложность схемы. На старте запрещены пользовательские regex pattern, пока не реализованы лимиты их выполнения.
+
+## Применение значений
+
+1. Загрузить схему и defaults, закреплённые по digest.
+2. Создать конфигурацию из defaults и явных значений пользователя: objects объединяются по ключам, arrays заменяются целиком; null допустим только по схеме и не означает удаление.
+3. Проверить итоговую конфигурацию одним согласованным набором правил.
+4. Проверить права на подключения и ограничения организации.
+5. Сохранить полный результат как новую AgentRevision с schemaDigest.
+
+JSON Schema default — аннотация, а не команда валидатору. defaults-файл при публикации обязан соответствовать схеме после объединения с обязательными вводимыми полями; отсутствующие обязательные поля пользователь заполняет до сохранения. Сервер не доверяет клиентской валидации.
+
+## UI
+
+Web UI: TypeScript, React, JSON Forms; серверный валидатор — совместимая Go-библиотека Draft 2020-12, точная реализация выбирается по общему корпусу контрактных примеров. UI schema использует только встроенные контролы и layout, без JavaScript, HTML и внешних скриптов. Описания отображаются как безопасный текст.
+
+Поля для подключения к сервису отображают selector ConnectionRef. Секретные значения не входят в JSON конфигурации, defaults, пример или URL. readOnly, writeOnly и скрытие поля в UI не заменяют server-side permission checks. Пользователь не может через config повысить лимит ресурсов, изменить tenantId или разрешить новые сетевые доступы.
+
+## Версии и изменения
+
+PUT конфигурации требует If-Match. При конфликте ревизии сервер возвращает 412. UI показывает различия, пользователь повторно сохраняет результат. Запуск фиксирует agentRevisionId, schemaDigest и effectiveConfig; последующие изменения агента не влияют на Run.
+
+Новая версия шаблона сначала проверяется на копии конфигурации. При несовместимости показываются JSON Pointer путей и сообщения ошибок. Старая ревизия остаётся рабочей до явного обновления. В MVP автоматических исполняемых миграций нет.
+
+## Источники и пример
+
+- [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12)
+- [Аннотации и default](https://json-schema.org/understanding-json-schema/reference/annotations)
+- [JSON Forms UI Schema](https://jsonforms.io/docs/uischema/)
+- [Пример схемы](contracts/examples/config.schema.json)
+- [Начальные значения](contracts/examples/config.defaults.json)
+- [Представление формы](contracts/examples/ui.schema.json)