Skip to content

ADR-0001: AgentGit — финальная архитектура после критического аудита

  • Статус: принято. Изменено ADR-0002 (встроенный движок и SQLite на первом этапе); см. также ADR-0003. Соответствие реализации: adr-traceability.
  • Версия: 2.1
  • Дата: 17 октября 2026

Итог. Концепцию сохраняем, но архитектуру существенно исправляем. AgentGit будет независимой Agent-native SCM с собственным VCS-ядром, протоколом, CLI, API и Web UI. Git не используется как внутренний движок.

Предыдущая версия всё ещё содержала серьёзные проблемы: неоднозначную модель данных, неполную атомарность публикации, неформализованную семантику merge, недостаточную изоляцию агентов и слишком широкий MVP.

Главное архитектурное решение: корректность хранения и версионирования должна гарантироваться детерминированным ядром, а интеллектуальные функции агентов должны быть заменяемыми надстройками.

1. Что исправлено

Проблема Окончательное решение
Конфликт между Tree и Delta Канонический changeset DAG; trees — проверяемые производные представления
Нет строгой атомарности Durable object staging + транзакционный CAS
Недоступность объектов после публикации Проверка durable readiness до публикации
Неполная модель merge Формальная семантика первого родителя и результирующего дерева
Потеря изменений при гонках CAS + обязательная повторная валидация
Ненадёжный GC Reachability + grace period + retention roots
Небезопасные агенты Изолированные sandbox-исполнители без прямого доступа к storage
Подмена результатов CI Подписанные аттестации, привязанные к точному состоянию
Неопределённая консистентность Strong metadata, eventual derived indexes
Преждевременная микросервисность Модульный монолит SCM, отдельный execution plane
Неясный offline-режим Online-first в MVP, offline-sync отдельным этапом
Завышенные обещания Нагрузочные SLO устанавливаются после бенчмарков

Это проектные исправления, а не результаты испытаний работающего продукта.

2. Основные архитектурные принципы

  1. VCS работает без LLM. Ни хранение, ни merge, ни восстановление не требуют модели.
  2. История неизменяема. Changeset после публикации не редактируется.
  3. Публикация атомарна для читателей. Новый head становится видимым только после готовности всех необходимых объектов.
  4. Нет глобальной блокировки репозитория. Конкуренция ограничивается конкретными streams.
  5. Любой merge воспроизводим. Детерминированные правила, точные версии входов и фиксация результата.
  6. Агент не является доверенной стороной. Его действия, инструменты и результаты проверяются независимо.
  7. Git — внешний адаптер. Не источник истины.
  8. Каждый шаг наблюдаем. Версии, операции, политики, проверки и решения интеграции имеют аудиторский след.

3. Финальная схема системы

Client layer
  CLI · Web UI · Agent SDK · Git Bridge
        │
        ▼
AGWP Gateway
  HTTP/2 · gRPC · Authentication · Authorization · Quotas
        │
        ├──────────────────────────────┬──────────────────────────────┐
        ▼                              ▼                              ▼
SCM Engine                       Agent Platform               Isolated Execution Plane
Rust · Deterministic             Go · Asynchronous            Sandbox · Build · Tests ·
  Object Store                     Task Orchestrator          SAST/SCA · Attestations
  Changeset DAG                    Agent Sessions
  Tree Resolver                    Conflict Advisor
  Diff / Merge                     Semantic Index
  Integration / CAS                Review / Policy
  Integrity / GC                   Execution Scheduler
        │                              │
        ▼                              ▼
PostgreSQL                       Object Storage
  Metadata · Refs · Intents        Immutable blobs · Changesets
  · Audit
        │
        ▼
Derived Workers                  Outbox Dispatcher
  Trees · History · Blame          Reliable events · Retry

Граница доверия. Agent Platform может предлагать изменения, но не может обходить SCM Core и Policy Enforcement. Даже системный агент не должен иметь прямых прав на изменение опубликованных версий.

4. Каноническая модель VCS

Выбираем delta-oriented модель, похожую по идее на Bonsai, но со своим форматом и независимой реализацией.

Слой Назначение
Changeset DAG Каноническая история
File operations Изменения путей и метаданных
Content blobs Неизменяемые байты
Tree index Derived
Path history Derived
Blame index Derived

Строгие правила

  • Changeset содержит упорядоченных родителей, операции и неизменяемые метаданные.
  • Операции определяют разницу результирующего состояния относительно первого родителя.
  • Merge имеет несколько родителей, но одно однозначное результирующее состояние.
  • Root changeset имеет пустое исходное состояние.
  • Content ID вычисляется из канонического типа объекта, версии формата и содержимого.
  • Tree-индекс может быть пересоздан из истории и blobs.
  • Любая материализация должна проверяться на целостность.
  • Агентная provenance хранится отдельно от канонического changeset, чтобы не смешивать историю кода с изменяемым состоянием оркестрации.

Исправление относительно предыдущего проекта: автор и сообщение changeset остаются частью неизменяемой истории; расширенные сведения об agent run, модели, промптах, проверках и согласованиях — отдельные подписанные записи.

Пример канонической структуры

ChangesetV1
  format_version
  repository_namespace
  parents[]
  author_identity
  author_timestamp
  message
  file_operations[]
    path
    operation
    content_id
    file_type
    executable

Для хеширования используем SHA-256 с разделением доменов по типам объектов. Канонический формат — собственное однозначное бинарное кодирование с жёсткой спецификацией. Protobuf остаётся транспортным форматом, а не неявным источником правил content addressing.

5. Самое важное: безопасная публикация

Ранее здесь была фундаментальная проблема: PostgreSQL и S3 не поддерживают общую атомарную транзакцию.

Исправляем её через immutable staging, проверку готовности и атомарную публикацию метаданных.

  1. Prepare. Создать publication intent, проверить входные данные, зарезервировать idempotency key.
  2. Upload. Записать blobs и changesets в неизменяемое хранилище.
  3. Verify. Проверить хеши, размеры, родительские ссылки, доступность и требуемую долговечность объектов.
  4. Ready. Зафиксировать готовность объектов и DAG в PostgreSQL.
  5. Integrate. Проверить policy, validation, approvals и ожидаемую версию stream.
  6. Atomic CAS. Одной SQL-транзакцией обновить head, reflog, integration record и outbox.
  7. Derive. Асинхронно вычислить деревья, историю путей и другие индексы.

Дополнительные гарантии

Crash recovery. Незавершённые intents возобновляются или переводятся в терминальное состояние. Повторное выполнение безопасно благодаря idempotency keys.

Object availability. До CAS должны быть подтверждены все необходимые объекты, включая транзитивные зависимости. Для каждого поддерживаемого backend определяется конкретный контракт долговечности; обычный успешный HTTP-ответ сам по себе не доказывает сохранность при отказе всей площадки.

Unknown commit outcome. Если клиент потерял соединение после CAS, он запрашивает результат по operation ID, а не слепо повторяет интеграцию.

Garbage collection. Объекты защищаются roots, активными публикациями, leases, reflog retention и grace period. GC работает по поколениям и учитывает конкурентные записи.

Disaster recovery. Снимок PostgreSQL и состояние object storage должны быть согласованы по достижимым объектам. После восстановления запускается integrity reconciliation; нельзя считать два независимых бэкапа автоматически согласованными.

6. Семантика merge и конкурентных изменений

Semantic Merge не должен быть частью механизма гарантированной корректности. Он является вспомогательным механизмом обнаружения рисков и подготовки решений.

Тип изменения Автоматизация
Разные файлы Автоматический merge при отсутствии структурных конфликтов
Разные участки одного файла Детерминированный трёхсторонний merge
Один участок Конфликт, требуется разрешение
Изменение сигнатуры API Анализ зависимостей и контрактные тесты
Изменение поведения Проверки и review; гарантия отсутствует
Изменение политик безопасности Повышенный уровень согласования

Исправление ещё одной скрытой ошибки

Даже изменения разных файлов нельзя автоматически считать безопасными на уровне поведения. Поэтому различаем:

  • Mergeable: движок способен получить однозначное результирующее дерево.
  • Validated: проверки конкретного дерева завершились успешно.
  • Approved: необходимые политики и согласования выполнены.
  • Integrated: stream атомарно обновлён.

Эти состояния независимы. Успешный merge не означает успешную проверку.

Для интеграции используем:

candidate = merge(base, proposal, current_head)

if candidate.has_conflicts:
    return CONFLICT

validation = validate(
    candidate.tree_id,
    policy_version,
    environment_digest
)

if !validation.passed:
    return VALIDATION_FAILED

transaction:
    assert stream.head == current_head
    assert policy_and_approvals_valid
    publish candidate
    update stream.head
    append reflog
    append outbox
commit

При изменении current_head кандидат рассчитывается заново. Проверки можно переиспользовать только при доказанной эквивалентности их входов и политик.

7. Agent-native возможности

Это то, ради чего имеет смысл создавать новую SCM, а не очередной Git-сервер.

Возможность Поведение
Agent Identity Уникальная идентичность каждого агента и запуска
Task Ownership Ответственность за задачу и область кода
Virtual Workspace Изолированное состояние без обязательного полного checkout
Dependency Awareness Отслеживание зависимостей между задачами
Conflict Prediction Раннее обнаружение пересечений
Integration Queue Управляемая публикация конкурирующих изменений
Provenance Кто, зачем, чем и на основании чего изменил код
Autonomous Review Анализ предложений агентами
Policy-bound Autonomy Автономные действия только в разрешённых пределах
Replay & Trace Восстановление истории действий и решений

Координация без опасных блокировок

Агент может запросить soft lease на файл, модуль или задачу. Это сигнал другим агентам, а не эксклюзивное право на изменение исходного кода.

Истечение lease не приводит к потере изменений. Для операций, которые действительно требуют эксклюзивности, используем fencing token и проверку его актуальности на стороне сервера.

Это позволяет масштабировать количество агентов без глобального lock.

8. Безопасность и модель угроз

Отдельно выделяем четыре недоверенные зоны: пользовательский код, содержимое репозитория, агенты и результаты выполнения инструментов.

Обязательные меры:

  • OIDC для пользователей; краткоживущие scoped credentials для агентов.
  • RBAC/ABAC с ограничением прав по репозиторию, stream и операциям.
  • Изоляция выполнения через sandbox с ограничениями CPU, RAM, сети и файловой системы.
  • Отсутствие постоянных секретов в окружении недоверенного кода.
  • Подписанные CI-аттестации от доверенного execution plane.
  • Защита от prompt injection через README, комментарии, issues и результаты инструментов.
  • Ограничения на размер blobs, количество операций, глубину DAG, API-запросы и потребление ресурсов.
  • Независимые audit events с защитой от несанкционированного изменения.
  • Защита от path traversal, symlink escape, zip bombs и подмены объектов.
  • Раздельные полномочия агента, reviewer и администратора.

Важно: подпись агентом собственного результата не делает его достоверным. Доверие к проверке определяется идентичностью и изоляцией проверяющего исполнителя, а не наличием подписи.

9. AGWP v1 — собственный протокол

Транспорт: gRPC поверх HTTP/2 с TLS. Для браузера — отдельный HTTPS API, а для событий — SSE или WebSocket.

Контракт протокола

Группа Операции
Repository Create, Describe, Configure
Objects Upload, Get, Verify
History GetChangeset, Ancestors, MergeBase
Tree ResolvePath, ListDirectory
Workspace Create, Modify, Snapshot
Proposal Create, Update, Review
Integration Prepare, Validate, Integrate, GetResult
Stream ReadHead, CompareAndSwap
Agent Register, Heartbeat, Complete
Events Subscribe, Replay

Каждая изменяющая операция получает operation_id и idempotency key. Протокол предусматривает capability negotiation, версионирование сообщений, пагинацию, backpressure, дедлайны и структурированные коды ошибок.

Для offline-разработки позднее добавляем локальное object storage, очередь публикаций и reconciliation. В MVP работа с сервером обязательна.

10. Технологический стек

Компонент Технология
VCS Core Rust
SCM Server Rust, Tokio, tonic
CLI Rust, clap
Agent Orchestrator Go
Web API Rust / HTTP JSON
Frontend Vue 3, TypeScript
UI Components Собственная дизайн-система
Metadata PostgreSQL
Object Storage S3-compatible / MinIO
Async Jobs MVP PostgreSQL-backed queue
Event Bus позднее NATS JetStream
Observability OpenTelemetry, Prometheus
Auth OIDC, scoped service credentials
Sandbox Изолированные OCI/VM workers
Deployment Docker Compose, затем Kubernetes

Для MVP не нужны Redis, Elasticsearch, Kafka и отдельная микросервисная платформа.

Предлагаемая структура репозитория

agentgit/
├── crates/
│   ├── ag-types/
│   ├── ag-object/
│   ├── ag-changeset/
│   ├── ag-dag/
│   ├── ag-tree/
│   ├── ag-diff/
│   ├── ag-merge/
│   ├── ag-storage/
│   ├── ag-integrate/
│   ├── ag-policy/
│   ├── ag-protocol/
│   ├── ag-server/
│   └── ag-cli/
├── services/
│   └── agent-orchestrator/
├── apps/
│   └── web/
├── sdk/
│   ├── typescript/
│   └── python/
├── proto/
├── migrations/
├── deployments/
├── tests/
│   ├── conformance/
│   ├── property/
│   ├── fault-injection/
│   └── integration/
└── docs/
    ├── architecture/
    ├── adr/
    ├── protocol/
    └── operations/

11. Web UI — не копия GitHub

Вместо того чтобы делать очередной интерфейс со списком веток и pull requests, AgentGit должен показывать жив

Текст обрывается. Исходное сообщение с ADR было обрезано на этом месте, поэтому раздел 11 и всё, что шло после него, в документ не вошли. Дополнить, когда будет полная версия.