ADR-0006: Описание расширения и KCL

Статус: Принято — 2026-09-23. Владелец проекта утвердил это решение. Принятие фиксирует архитектурный контракт; оно не означает готовую реализацию или успешное прохождение невыполненных проверок.

English | Русский

Уточнение — 2026-09-24: приняты дополнения для единой модели CLI/MCP и агентного использования по ADR-0013 и ADR-0014–0016. Исходная дата принятия и исторические проверки сохранены; новые требования не объявляются реализованными или проверенными.

Контекст и задача

Ядру нужны пути команд, базовая справка, требования исполнения и запрашиваемые права до запуска расширения. Эти сведения должны сохранять один смысл для загрузчика, исполнителя и границы Security Broker. Авторы используют KCL, но установка расширения CLI не должна требовать исполнения конфигурационного кода издателя на машине пользователя.

Этот ADR определяет логическую схему описания и границы проверки. Состав выпуска относится к ADR-0007, подбор среды — к ADR-0008. ADR-0005–0008 приняты; подтверждение их реализации учитывается отдельно.

Критерии выбора

Просмотр команд и требований без кода расширения и подготовки среды.
Сохранение устойчивой идентичности команд, типизированного ввода и отдельных прав справки из ADR-0002.
Разделение требований автора, настроек владельца CLI и предоставленных прав.
Развитие объявления без молчаливого пропуска требований исполнения или безопасности.

Рассмотренные варианты

Вариант	Преимущество	Ограничение
Запускать расширение для получения команд	Произвольная логика автора	Исполнение кода до проверок совместимости и доступа
Выполнять KCL на каждом клиенте	Один формат подготовки везде	Вычислитель и управляемые издателем входные данные сборки участвуют в установке
Компилировать KCL в проверяемое статическое описание	Просмотр без кода расширения; независимая проверка клиента	Нужны версионируемая выходная схема и проверка смысла данных

Решение

Автор пишет KCL; издатель получает ограниченное по размеру описание JSON в UTF-8. Ядро читает и независимо проверяет это описание. KCL — средство подготовки, а не зависимость исполнения или доказательство доверия. Типы и проверки схемы помогают автору, но не заменяют проверку клиента. Схемы KCL.

Раздельные документы и полномочия

Каталоги, группы и правила доступа — конфигурация владельца по ADR-0009, а не полномочия расширения. У них отдельные схемы; их можно писать прямо в JSON или получать из KCL. Выбор KCL для подготовки расширения не требует KCL, входа или службы прав на машине пользователя.

Документ	Содержимое и полномочия
Описание расширения	Заявленная идентичность издателя, команды, требования исполнения/среды и запросы операций ядра; не регистрирует доверенных поставщиков и не выдаёт права
Профиль владельца CLI	Встроенные команды, разрешённые точки подключения и источники, регистрации поставщиков, каталог сред и привязки областей доступа
Документ состава выпуска	Связывает точные байты описания и содержимое для целевых платформ с одним проверяемым выпуском по ADR-0007
Локальная запись выбора	Выбранный выпуск, платформа и идентичность среды; пути конкретной машины отделены от переносимой идентичности

Издатель фиксирует компилятор KCL, пакет схемы, импорты и входные данные сборки и сохраняет сведения об их происхождении. Секреты и личность конкретного пользователя не входят в публикуемый результат. Воспроизводимость проверяется отдельно: KCL сам по себе не гарантирует одинаковые байты. Клиент не загружает импорты KCL, не запускает конфигурационные модули и не перекомпилирует описание при установке.

Схема отделяет подготовку описания от клиентских проверок доверия. Неудачная проверка останавливает путь до активации команд.

Схема описания

Исходный принятый профиль данных — rukh.extension/1; уточнение ниже определяет rukh.extension/2 для программного использования. Имена и варианты ниже задают архитектурный контракт; это не заявление о выпуске пакета схемы или SDK. Описание содержит данные, а не функции, выражения оболочки, реализации поставщиков или вычисляемые шаблоны. Посторонние поля объектов запрещены, кроме явно ограниченного поля annotations.

Поле	Обязательный смысл
`format`, `identity`	Точное имя формата; `identity` содержит `authority`, `package`, `version`, совпадающие с составом выпуска. Описание не содержит `releaseDigest` охватывающего выпуска
`compatibility`	Границы версий ядра, точные поддерживаемые версии взаимодействия и обязательные возможности; требования выбранной привязки. Версии пакета и протокола не считаются одинаковыми
`startupRequirements`	Общие возможности запуска, операции и обязательный доступ до запуска, применяемые к обоим видам вызова
`commands`	Массив с уникальными `id`, относительным массивом токенов `path`, прямыми альтернативными путями, `kind` (`group` или `command`) и ссылками на переводы справки. Только `command` имеет `execute`; необязательный `describe` относится к этой команде
`commands[].execute`	`mode` (`declared` или `passthrough`), `binding`, `executionMode`, `entryPoint`, требования вида вызова `requirements`; `parameters` есть только у объявленного ввода
`commands[].describe`	Явная управляемая привязка, точка входа и отдельные требования; без параметров исполнения. Нужны возможность структурированной справки и готовая среда
`entryPoints`	Записи по ID с `kind` (`native` или `script`) и платформенными `targets`. Каждая цель задаёт ОС/архитектуру/ABI, `payloadRef`, относительный `path`, постоянные `arguments`; скрипт также указывает `runtimeRef` и необязательные ссылки на зависимости
`runtimes`	Требования по ID: семейство, реализация, правила версий и явные ограничения по ADR-0008; без установщика на машине или выражения поиска программы
`requirements`	Обязательные/необязательные возможности и операции, ID/версия каждой операции и ограничение ресурсов; `preLaunchAccess` явно отмечает доступ до запуска. Область доступа указывает привязку владельца, а не реализацию адаптера
`help`	Основной язык и ограниченные переводы назначения, описаний параметров, примеров и статического дополнения; отсутствие запрошенного перевода выбирает основной язык, не меняя грамматику
`annotations`	Необязательные сведения для отображения/происхождения с именами в пространствах имён и простыми значениями или их списками. Они не влияют на исполнение, доступ, пути команд или установку

authority — строчное пространство имён в форме обратного доменного имени, до 253 символов ASCII; такое написание не доказывает владение DNS или доверие издателю. package и локальные ID соответствуют [a-z][a-z0-9]*(?:[.-][a-z0-9]+)*, до 64 символов. Они действуют внутри объявившего пакета; идентичность команды включает сторону и пакет. Версия пакета — полная строка SemVer до 128 символов, а версии сред сохраняют собственные правила. Отображаемые подписи не участвуют в идентичности. Semantic Versioning.

Условия платформ используют зарегистрированные точные значения, а не исполняемые проверки. Каждая цель указывает releaseTarget, соответствующий targets[].id состава выпуска ADR-0007, с согласованными условиями платформы. Её payloadRef должен быть ID артефакта, допущенного в payloads этой цели; ссылки зависимостей — в её locks. Путь точки входа находится внутри корня установки выбранного содержимого. Сначала загрузчик выбирает одну цель выпуска по ADR-0007; затем ядро рассматривает только варианты точки входа с этим ID. Среди них нужна ровно одна совместимая привязка: ноль означает отсутствие поддержки, две — неоднозначность. Точка входа не выбирает другую цель выпуска независимо. Необязательные условия ограничивают цель; отсутствие условия не обещает совместимость ABI. Пути относительные, разделены /, без пустых сегментов, . и .., NUL, абсолютного корня или префикса диска; загрузчик также применяет правила распаковки платформы. Постоянные аргументы — ограниченный массив строк, а не текст командной строки.

Начальные привязки — process-only с прямой передачей и process-managed с объявленным вводом, обе с executionMode=foreground. Управляемый describe — отдельный вызов. Группа не содержит точку входа или параметры. Команда прямой передачи не задаёт одновременно типизированную грамматику; управляемая команда не публикует второе представление исходного списка аргументов. Другой исполнитель или режим жизненного цикла требует объявленной поддерживаемой привязки, а не переосмысления этих вариантов.

Версия 2 и программная совместимость — 2026-09-24

ADR-0013 вводит rukh.extension/2. Все правила версии 1 для идентичности, маршрутов, скаляров и списков входа, справки, платформ и доверия сохраняются. Версия 2 добавляет commands[].execute.result и commands[].machine с точными вариантами, подмножеством схемы и конечными пределами ADR-0013. Описания остаются закрытыми данными: документ версии 1 с этими полями недопустим, а неподдерживаемую версию 2 нельзя понизить удалением требований. Схемы KCL издателя явно выгружают выбранную версию. Документ состава выпуска связывает исходные экспортированные байты, а не преобразованное клиентом описание.

Программная пригодность требует объявленных входных данных, управляемой привязки с command-result/1, исполнения foreground и совместимых требований взаимодействия. Отсутствие программных метаданных предотвращает автоматическую публикацию MCP, сохраняя обычное использование CLI. Обязательные контракты задачи, последствий и ограниченного исполнения используют существующие точные требования возможностей и операций; их смысл определяют ADR-0014, ADR-0015, ADR-0016. Описание не содержит действующего полномочия задачи, подтверждения или реализации ограничений. Заявление о безвредности не обходит определение действия и ресурса доверенной операцией.

Свойства MCP используют устойчивые ID параметров и те же типы скаляров и списков, значения по умолчанию, границы и множество явно переданных параметров. Сформированная JSON Schema является представлением интерфейса, а не другим источником грамматики. Ядро прямо проверяет типизированные данные MCP: не переосмысляет имена флагов, не приводит произвольные строки JSON к типам и не разбирает искусственный argv. Вложенные программные входные данные остаются вне профиля. Структурированный выход имеет свою ограниченную вложенную схему и не расширяет типы входа. describe и справка не меняют программный контракт.

Активация проверяет полные представления CLI и MCP. Флаг eligible запрашивает совместимость; публикацию выбирает владелец, а допуск определяют текущая задача и права вызывающего. Секретные входные данные исключаются из диагностики и сформированных примеров; отметка чувствительности не выдаёт секрет и не разрешает раскрыть его агенту.

Пути команд и грамматика параметров

Токен пути соответствует [a-z][a-z0-9-]*, до 64 символов. Относительный путь содержит 1–16 токенов. Альтернативные имена — полные прямые пути к тому же ID команды; имена групп и цепочки имён в этот профиль не входят. Явные родительские группы могут быть общими, но исполняемый префикс — одна объявленная команда. Владелец выбирает точки подключения до проверки полного дерева. Корневой путь help зарезервирован. Повтор итогового пути недопустим, даже если два объявления сейчас скрыты от разных пользователей.

Ядро выбирает самый длинный совпадающий непрерывный путь команды, затем разбирает её ввод. Как только следующий токен не является дочерним путём, выбор команды заканчивается; флаги между токенами пути не допускаются. Исполняемый родитель использует --, чтобы передать значение, которое иначе выбрало бы дочернюю команду; группа без обработчика сообщает об отсутствующей/неизвестной команде только после распознавания справки. <group> --help и help <group> используют видимые метаданные без требования дочерней команды или обработчика. Общие флаги ядра находятся перед путём и не переосмысляются внутри данных команды. Для прямой передачи сохраняются точная форма справки и явная граница из ADR-0002.

Поле параметра	Правило
`id`, `source`	Уникальный устойчивый ID и либо `option`, либо `positional`; один параметр не относится к обоим видам
`names` / `position`	У флагов уникальные длинные имена `--[a-z][a-z0-9-]*` и необязательные короткие из одной буквы ASCII. Позиции последовательны и начинаются с нуля
`type`, `itemType`	Один простой тип ниже либо `list` одного простого типа. Вложенные списки и произвольные объекты отсутствуют
`required`, `default`	Обязательность требует явно переданного значения; обязательный параметр не имеет значения по умолчанию. Отсутствующий необязательный простой параметр без значения по умолчанию пропускается, а не становится `null`; необязательный список по умолчанию — `[]`
`min`, `max`, `minLength`, `maxLength`, `choices`	Только ограничения выбранного типа; значения по умолчанию им соответствуют. Размер списка задаётся `minItems`/`maxItems`; произвольных регулярных выражений и функций нет
`sensitive`	Исключает значения из диагностики, журналов и сохраняемых описаний вызова; не скрывает аргументы от ОС и не предоставляет доступ к учётным данным

Длинный флаг принимает --name=value или --name value, короткий со значением — -n value. Логический флаг без значения означает true; длинная форма допускает =true/=false. Нет объединения коротких флагов, слитных коротких значений, неявного no- или счётчиков повторений. Ожидаемое значение флага потребляет следующий токен, даже начинающийся с -, включая отрицательное число или --help; только токен в позиции флага выбирает справку или завершает разбор флагов через --. Неизвестные флаги и повторы простых параметров ошибочны. Повторяемые флаги списков добавляют значения в порядке поступления. Позиционные значения могут следовать за флагами; обязательные позиции идут перед необязательными, списком может быть только последняя позиция. Rukh не вычисляет кавычки, переменные, маски файлов или файлы аргументов.

Простой тип	Разбор и передаваемое значение
`string`	Точная последовательность символов Unicode без нормализации; пустота допустима, если не ограничена. NUL не передаётся через привязку аргументов процесса
`boolean`	`true` или `false`, либо сокращение флага выше; логическое значение JSON
`integer`	Десятичное целое со знаком, без начального `+`, лишних начальных нулей, дроби или степени; диапазон `-(2^53-1)`…`2^53-1`; число JSON
`number`	Грамматика числа JSON, однократное преобразование в конечное binary64 с округлением к ближайшему и чётному при равенстве; переполнение или бесконечное значение ошибочны. Это явно приближённый числовой тип
`exactInteger`, `exactDecimal`	Явное строковое кодирование, до 256 цифр. Десятичная запись без степени; дробный тип допускает дробную часть. Лишние начальные/конечные нули и отрицательный ноль нормализуются один раз; передаётся каноническая строка, а не приближение binary64
`enum`	Точная строка из `choices` с учётом регистра; строка JSON

Значение через альтернативное имя флага сохраняет ID параметра. Типизированная запись содержит действующие значения и множество явно переданных ID; порядок списков сохраняется. Отсутствие значения, неподдерживаемое кодирование или превышение предела дают отказ без смены режима. Отрицательное позиционное число использует --, если иначе попало бы в позицию флага. Значение по умолчанию точного дробного типа уже является канонической строкой; числовое значение по умолчанию не обходит пределы при передаче. Точные типы принимают соответственно -?[0-9]+ и -?[0-9]+(?:\.[0-9]+)?, без пробелов и начального +; конечные нули целого значимы, удаляются только конечные нули дробной части. Ограничение длины строки считает символы Unicode; пределы байтов действуют отдельно. Границы упорядочены, количество элементов неотрицательно, варианты непусты и уникальны. --help зарезервирован по ADR-0002; -h не имеет неявного значения справки в этом профиле.

Выбранные пределы и сообщения об ошибках

Это осторожные проектные значения, а не измеренные оптимальные пределы. Владелец может установить меньшие; увеличение требует отдельно объявленного и проверенного профиля. Пределы формата отделены от меньших структурных пределов кадра ADR-0003: фактический вызов вместе со служебными полями должен укладываться в выбранную привязку до запуска.

Ресурс	Базовый предел
Описание	1 МиБ UTF-8; вложенность 32; всего 65 536 полей объектов и элементов массивов; без BOM, повторов ключей и неверных символов Unicode
Команды / альтернативные имена	256 команд; 8 имён на команду; 16 токенов пути
Параметры	128 на команду; 256 вариантов перечисления/дополнения; 1 024 элемента списка с учётом меньшего предела вызова/привязки
Точки входа / платформы / требования сред	64 / 16 на точку входа / 64
Тексты и языки	64 КиБ на текстовое поле; 16 языков; 4 КиБ на значение дополнения; общий предел описания сохраняется
Подготовленные данные вызова	256 КиБ JSON в UTF-8 до служебных полей привязки; строковый ввод до 64 КиБ; также действуют 4 096 полей/элементов кадра ADR-0003 и ограничения запуска платформы
Проверка клиента	2 секунды общего времени; до 64 сообщений об ошибках; отмена проверяется при обходе; превышение времени отклоняет кандидат

Проверка возвращает устойчивую категорию (invalid_descriptor, unsupported_requirement, route_conflict, limit_exceeded, invalid_input), экранированный JSON pointer либо ID параметра и безопасное объяснение. Секретные значения не выводятся. Неверный пакет — ошибка кандидата загрузчика; отказ во вводе или выбранном требовании до кода расширения соответствует rejected из ADR-0002. Это категории диагностики, а не дополнительные результаты вызова. Ошибки среды/поставщика сохраняют собственное соответствие результатов.

Режим входных данных следует ADR-0002. Объявленные данные ядро разбирает один раз; прямая передача сохраняет список аргументов и не подменяет типизированный ввод автоматически. Произвольные аргументы требуют полномочий на всю целевую программу. Префикс аргументов передаётся как данные без вычисления оболочкой и не создаёт второй источник выбора команды в управляемом вызове. Группа не имеет обработчика; исполняемый родитель, если он есть, объявляется командой явно, сохраняя однозначные пути дочерних команд.

Альтернативное имя меняет только написание: не входные данные, значения по умолчанию, права или способ исполнения. Ядро проверяет полное подключённое дерево, включая встроенные команды, до активации. Конфликты отклоняются, а не разрешаются порядком установки или правами текущего пользователя. ID не переиспользуется для другого смысла команды. Обновление выпуска не меняет цель уже закреплённого вызова.

Вид исполнителя, режим жизненного цикла и языковая среда независимы. Данные описания могут указывать другой зарегистрированный исполнитель, но не реализуют его и не означают поддержку. Поддерживаемый синхронный режим ADR-0004 сохраняется как основа; неподдерживаемые обязательные режимы/возможности предотвращают активацию или вызов по соответствующей проверке. Нативная точка входа не получает требование языковой среды автоматически.

Проверки и совместимость

Проверка	Где выполняется
Типы полей, обязательные варианты, повторяющиеся ключи, конечные числа и пределы размера/вложенности	У издателя и клиента; решение клиента не зависит от проверок автора
Ссылки, ID команд/параметров, альтернативные имена, зарезервированные пути/флаги справки и неоднозначные платформы	Проверка смысла данных, включая итоговое дерево команд
Правила и диапазоны версий, поддерживаемые привязки и обязательные возможности	Ядро по доверенным каталогам поставщиков и исполнителей
Полномочия издателя, связь описания и содержимого, безопасные пути распаковки	Загрузчик по ADR-0007; отображаемое имя издателя не доказывает полномочий
Подбор среды и представимость фактического запуска	Поставщик/исполнитель по ADR-0002 и ADR-0008, без смены выбранной команды
Видимость, доступ до запуска и реальные операции ядра	Граница проверки прав ядра, включая ADR-0005 при необходимости

Пакет схемы должен выразить выбранные выше варианты полей, правила простых значений и пределы. Значения по умолчанию — обычные данные. Собственные проверки расширения выполняются только внутри разрешённого вызова и не добавляют команды или меняют грамматику ядра. Клиент проверяет статические требования и итоговое дерево независимо от успешной компиляции KCL у издателя.

Базовая справка и статическое дополнение строятся по проверенному описанию без установки среды или запуска расширения. Правила видимости сохраняются. --help, граница -- и контекстная справка сохраняют смысл ADR-0002; describe не меняет пути, схему ввода или требования доступа.

Формат описания, контракт взаимодействия, привязка исполнителя, версии служб ядра и правила версий среды версионируются независимо. Поддержка формата не означает поддержки возможностей. Неизвестные поля вне annotations и неизвестные обязательные требования отклоняются; неподдерживаемая необязательная возможность пропускается только по известному контракту. Смена структуры или смысла разбора требует другого профиля описания. Дополнительные сведения для отображения используют annotations, а не неизвестное поле безопасности с пометкой необязательности. Преобразование формата выполняется при публикации, а не изменением проверенных байтов на клиенте.

Последствия

Просмотр команд не зависит от языка расширения и наличия среды.
Авторы KCL и ядро используют один выходной контракт с проверками смысла данных сверх типов KCL.
Существующий прототип KCL иллюстративен и неполон: он не реализует типизированный ввод, альтернативные имена, отдельные требования describe и состав брокера. Его исторические проверки компиляции не подтверждают этот ADR.

Подтверждение

Проверки уточнения 2026-09-24 ещё не выполнены. Требуется подтвердить общий путь CLI/MCP, отказ при неподдерживаемой возможности результата, текущую привязку профиля и задачи, пределы данных, отсутствие повторов и разделение каналов в пределах ответственности этого ADR. Исторические результаты ниже на эти дополнения не распространяются.

Решение принято владельцем проекта 2026-09-23. Следующий перечень сохраняется как обязательная проверка реализации, а не условие, уже выполненное при принятии.

Для проверки реализации реализовать пакет схемы и проверку смысла данных по выбранным правилам, затем проверить:

Два исходника KCL с одинаковым выходным смыслом дают допустимые описания; клиент независимо от KCL отклоняет неверный или изменённый JSON.
Конфликты путей/имён, неверные ссылки, неизвестные требования и неоднозначные платформы отклоняются; альтернативные имена сохраняют идентичность и область прав команды. Проверить исполняемых родителей, --, отрицательные значения, повторы флагов, пустой ввод и точные числа на выбранных границах.
Базовая справка работает без подготовки среды; объявления типизированного/прямого ввода и контекстной справки сохраняют поведение ADR-0002.
Заявления описания не регистрируют поставщиков, не снимают требование брокера владельца и не выходят за проверенные файлы выпуска.

Эти проверки не запускались для ADR-0006. Запись предлагает контракт и не заявляет готовой реализации схемы.