# Матрица поддерживаемых Connections в Kavor

Connection — не просто линия на Canvas. Она объявляет, что два Nodes участвуют в одном графе, и определяет
возможности, которые эта пара добавляет к работе.

Не все сочетания допустимы. У каждой поддерживаемой пары есть точный контракт: одни Connections делают контекст
достижимым, другие разрешают операции через Kavor, а две передают канонические пути в Terminal с помощью переменных
окружения.

Эта страница — публичный справочник по таким контрактам.

## Как читать Connection

У Connection есть три разных обязанности:

1. **Существование:** она соединяет Nodes в один достижимый компонент графа.
2. **Параметры:** она хранит обязательную настройку, если она нужна этой паре.
3. **Guardrails:** она отнимает возможности у поведения, которое обычно разрешено между двумя Nodes.

Connections — двусторонние отношения. Kavor хранит два endpoints в каноническом порядке, но этот порядок не означает
поток, управление или приоритет. У сообщения по-прежнему есть отправитель и получатель, а у Trigger — цель. Эти
направления относятся к выполняемой операции, а не к сохранённой Connection.

## Поддерживаемые сочетания

| Пара Nodes | Что позволяет Connection | Параметры | Доступный Guardrail | Основной пример |
| --- | --- | --- | --- | --- |
| **CodingAgent + Specification** | Читать метаданные и канонический Markdown, работать с lifecycle и регистрировать долговечные outputs, когда это разрешено. | Нет | `specification_read_only` | Spec Writer, Builder и Reviewer используют общий контракт. |
| **CodingAgent + Sticky Note** | Читать и писать неформальную память в Markdown с контролем версий; при каждой записи выбирается append или replace. | Нет | `sticky_note_read_only` | Открытые решения, прогресс, наблюдения и видимые handoffs. |
| **CodingAgent + Terminal** | Читать output, выполнять команды, отслеживать или прерывать связанный запуск и взаимодействовать с foreground-процессом, когда это разрешено. | Нет | `terminal_read_only` | Диагностика, тесты, логи или помощь в контролируемой SSH-сессии. |
| **CodingAgent + File** | Сделать канонический источник в filesystem явным в графе для чтения, проверки или изменения, когда это разрешено. | Нет | `file_read_only` | Ограничить область модулем, PDF, изображением, отчётом или конфигурацией. |
| **CodingAgent + CodingAgent** | Сформировать достижимый граф для асинхронных сообщений, ответов, независимой проверки и параллельной работы. | Нет | Нет | Builder запрашивает проверку у Reviewer. |
| **Specification + Terminal** | Экспортировать канонический абсолютный путь Specification в сессию Terminal. | Обязательное имя переменной окружения | Нет | Проверить, изучить или сравнить Markdown в Specification. |
| **File + Terminal** | Экспортировать канонический абсолютный путь File в сессию Terminal. | Обязательное имя переменной окружения | Нет | Запустить script или использовать SQL-файл, не копируя его путь между окнами. |
| **Trigger + CodingAgent** | Доставить в заданное время prompt в CodingAgent с активной сессией. | Нет | Нет | Разбудить Maintainer для анализа сбоев, подготовки отчёта и запроса проверки. |
| **Trigger + Terminal** | Доставить в заданное время команду в активную сессию Terminal. | Нет | Нет | Запустить тесты, проверку базы данных или script обслуживания. |

## Guardrails ограничивают, а не предоставляют доступ

Connection изначально предоставляет возможности, реализованные для этой пары. Guardrail хранит выбранное
пользователем ограничение для такой базовой модели:

| Guardrail | Connection | Эффект |
| --- | --- | --- |
| `specification_read_only` | CodingAgent + Specification | Сохраняет чтение и запрещает через Kavor изменения lifecycle и outputs. Прямое редактирование Markdown становится явным контрактом «только для чтения». |
| `sticky_note_read_only` | CodingAgent + Sticky Note | Сохраняет чтение и блокирует append или replace содержимого. |
| `terminal_read_only` | CodingAgent + Terminal | Сохраняет просмотр Terminal и блокирует операции, которые изменили бы сессию, процесс или его ввод. |
| `file_read_only` | CodingAgent + File | Объявляет, что agent не должен изменять канонический источник. |

Guardrails принадлежат прямой Connection между CodingAgent и ресурсом. Альтернативный маршрут в графе не снимает
ограничение, существующее для этой прямой пары.

Если Guardrail блокирует операцию через Kavor, она отклоняется до появления побочных эффектов. Files и содержимое
Specifications также могут быть доступны через собственные filesystem-инструменты harness. В таких случаях
Guardrail — видимый и контролируемый контракт, а не sandbox операционной системы.

Guardrail не создаёт Connection, не делает Node достижимым и не повышает разрешения. Если ресурс не должен участвовать
в графе, не создавайте Connection.

## Connections с переменными окружения

Сохранённые параметры есть только у двух пар:

- **File + Terminal**;
- **Specification + Terminal**.

В обоих случаях вы выбираете имя переменной окружения. Значение, предоставленное Terminal, — канонический абсолютный
путь к источнику, а не содержимое файла.

Например, File, подключённый как `CHECK_SQL`, можно использовать в shell так:

```sh
sqlite3 app.db < "$CHECK_SQL"
```

Kavor применяет значение при запуске сессии Terminal. Если Connection или её параметр изменятся, пока shell открыт,
интерфейс покажет, что для применения переменной требуется перезапуск сессии. `TERM` и `COLORTERM` — зарезервированные
имена, которые нельзя использовать для этих параметров.

## Особое ограничение Trigger

У Trigger может быть не более одной прямой цели: CodingAgent или Terminal. Он не соединяется напрямую со
Specification, File или Sticky Note и не распределяет одно срабатывание между несколькими целями.

Остальная часть графа может расширить возможности цели, не расширяя её разрешения. Разбуженный Trigger CodingAgent
может работать с уже достижимыми Nodes при тех же Guardrails и ограничениях сессии.

Для доставки Kavor должен быть запущен, а сессия цели — активна. Trigger не запускает оставленную вами выключенной
сессию, не определяет цель работы и не превращает внешние эффекты в exactly-once операции. Каждый TriggerFiring хранит
долговечный результат для последующей проверки.

## Несуществующие сочетания

Kavor отклоняет любую пару, которой нет в матрице. В частности:

- Trigger + Specification;
- Trigger + File;
- Trigger + Sticky Note;
- Specification + File;
- Specification + Sticky Note;
- File + Sticky Note;
- File + File;
- Sticky Note + Terminal;
- Sticky Note + Sticky Note;
- Terminal + Terminal.

Node также нельзя соединить с самим собой. Перестановка двух одинаковых endpoints не создаёт другую Connection,
поскольку у отношения нет сохранённого направления.

Близость на Canvas, упоминание в сообщении или участие в одном Workspace не заменяют Connection. Если сочетание
отсутствует на этой странице, оно не предоставляет возможностей только потому, что визуально находится рядом с
другим Node.

## Выбирайте минимальную Connection, которая решает задачу

Прежде чем соединить два Nodes, спросите, какой конкретной возможности не хватает:

- agent нужен долговечный замысел? Подключите Specification;
- человеку и agent нужна общая рабочая память? Подключите Sticky Note;
- agent должен выполнить или наблюдать процесс? Подключите Terminal;
- нужно явно обозначить канонический источник? Подключите File;
- другая точка зрения улучшит реализацию или проверку? Подключите ещё один CodingAgent;
- время действительно должно запускать активность? Добавьте Trigger в последнюю очередь.

Хорошая Connection делает работу более явной. Если вы не можете назвать возможность, которую она добавляет, скорее
всего, графу она не нужна.

## Что дальше

- Прочитайте [центральное руководство по Nodes](./nodes.md), чтобы понять ответственность каждого участника.
- Изучите отдельные руководства по [CodingAgent](./coding-agent.md), [Specification](./specification.md) и
  [Terminal](./terminal.md).
- [Замкните первый цикл](./first-loop.md) с замыслом, реализацией, проверкой и решением человека.
- Узнайте, [как выбирать CodingAgents и роли](./agents-and-roles.md), прежде чем расширять граф.