Реестр источников¶

Проект может добавить .embraion/sources.yaml. Файл говорит про каждый стабильный source ID: для чего источник нужен, можно ли в него писать и где лежит его документация. Файл необязателен. Без него ничего не меняется.

Реестр коммитится. В нём нет путей на конкретной машине. Пути машины хранятся в игнорируемом локальном состоянии (см. Локальная доступность).

schema-version: 1
sources:
  - id: App
    role: canonical-code
    write: workspace-write
    description: Репозиторий приложения.
    doc: docs/sources.md
  - id: SharedLib
    role: shared-library
    write: workspace-write
  - id: OldApp
    role: reference
    write: read-only
  - id: VendorSdk
    role: external-upstream
    write: forbidden
    data-class: CONFIDENTIAL

Поля¶

Поле	Обязательно	Значение
`id`	да	Стабильный source ID. Должен быть уникальным.
`role`	да	Одна из ролей ниже.
`write`	да	`read-only`, `workspace-write` или `forbidden`.
`description`	нет	Одно короткое предложение.
`doc`	нет	Путь от корня репозитория к документу, который описывает источник. Файл должен существовать.
`data-class`	нет	`PUBLIC`, `PRIVATE` или `CONFIDENTIAL`. Может только повысить класс источника.

Роли:

canonical-code: собственный авторитетный код проекта.
shared-library: библиотека проекта, которую используют несколько проектов.
reference: пример или прежняя реализация, только для чтения.
external-upstream: источник вендора или третьей стороны, которым проект не владеет.
application-data: данные времени выполнения или пользовательские данные.

Политики записи:

read-only: агенты читают источник и никогда не пишут в него.
workspace-write: агенты могут писать в него в разрешённой задаче.
forbidden: агентам нельзя писать в него ни в какой задаче.

Правила¶

embraion validate проверяет файл. Неизвестные ключи, неизвестные значения и неверный schema-version дают ошибку. Ошибкой также являются:

повторяющийся id;
id, которого нет в privacy.sources файла .embraion/policy.yaml, если эта карта объявлена (см. Политика);
doc с абсолютным путём, путём за пределами проекта или несуществующим файлом;
data-class ниже класса, объявленного для источника. Основа — privacy.sources для этого ID или privacy.default-class, если карта не объявлена.

Повышенный data-class становится действующим классом источника. Data class execution request должен быть не ниже него. Это действует и тогда, когда privacy.sources не объявлена; тогда проверяются только ID с повышенным data-class, остальные ID не проверяются.

Политика записи при выполнении¶

Когда файл существует, запрос с access: workspace-write может называть только источники с write: workspace-write. Запрос с источником read-only, forbidden или без записи в реестре отклоняется до выбора provider. Запросы только на чтение не проверяются по политике записи. Некорректный реестр закрывает доступ: он отклоняет все execution requests, включая запросы только на чтение, пока файл не исправлен. Без файла проверки запросов не меняются.

Local availability¶

Источник может быть на одной машине и отсутствовать на другой. Путь записывается в игнорируемый файл .embraion/state/sources-local.yaml. Он сопоставляет source ID с абсолютным путём:

App: /absolute/path/on/this/machine

Файл можно написать вручную или выполнить embraion sources set <id> <path>. Он не коммитится. Команды печатают только ID и available, missing или unset, но не путь. embraion security scan выдаёт находку machine-path уровня medium для отслеживаемого содержимого, в котором есть записанный путь. Пути короче двух сегментов пропускаются.

embraion sources set не использует блокировку, поэтому запускайте его по одному. Команда отказывается работать, если .embraion или папка state — символьная ссылка.

Локальный файл — это данные обнаружения. Он не может изменить роль или политику записи.

Команды¶

embraion sources list [--json]
embraion sources status [--json]
embraion sources set <id> <path>

См. справочник CLI.