--- documentId: infrastructure-operations-architecture-options documentVersion: 0.1.0 status: research normative: false language: ru --- # Единый контракт сервисов и инфраструктуры: три варианта архитектуры **Дата исследования:** 2026-08-19 **Статус:** концепция, изменений в исследованных репозиториях и системах не выполнялось **Рекомендация:** вариант 1 — федеративный GitOps-контракт с единым протоколом операций; затем, при необходимости, поверх него вариант 3 — MCP-интерфейс. ## 1. Короткий вывод Здесь уже есть почти все строительные блоки нужной системы, но они реализованы локально и несовместимо: - сервисные репозитории Antivirus и GuardPlus хорошо отделяют знание о продукте от способа его размещения; - LXD уже имеет машинную базу знаний с `constraints`, `tooling`, `workflows` и исполняемый handler с `validate`, `audit`, `diff`, `pull`, `push --dry-run`; - Monitoring уже разделяет read-only audit, проверку дрейфа KDB и безопасный provisioning; - AD уже использует правильную модель «несколько источников истины, каждый отвечает за свою грань» и отдельную reconciliation-операцию; - Network уже использует inventory, dry-run, diff и специализированные drivers; - Docker уже имеет достаточно устойчивые соглашения для стеков, но почти не имеет машинного контракта уровня всего репозитория. Главный вывод: не следует начинать с общего сервера, которому разрешён произвольный SSH. Сначала нужно стандартизировать **описание сущностей, отношений, требований и операций** в Git. Исполнение должно оставаться в доменных адаптерах LXD, Docker, AD, Network и Monitoring. Получится «MCP без транспорта»: 1. каждый репозиторий публикует одинаково устроенный контракт; 2. общий `opsctl` умеет найти контракты, построить граф и вызвать объявленную операцию; 3. операции имеют единый жизненный цикл `inspect → validate → plan → apply → verify → reconcile/rollback`; 4. skills лишь объясняют агенту, какую операцию выбрать, и не дублируют изменчивые факты; 5. позже тот же registry операций можно без переделки handlers опубликовать как настоящий MCP server. ## 2. Что было исследовано ### 2.1. Локальные репозитории Проверены структура, управляющие документы, KDB, скрипты, skills и перекрёстные ссылки в: - `Infra/Docker`; - `Infra/LXD`; - `Infra/AD`; - `Infra/Network`; - `Infra/Server-Hardware`; - `Services/Antivirus`; - `Services/GuardPlus`; - `Services/Monitoring`; - обзорно — остальные прямые подпапки `Infra/` и `Services/`. В 14 прямых репозиториях/каталогах под `Infra/` и `Services/` соглашения распределены неравномерно: только 3 имеют корневой `AGENTS.md`, 4 — корневую или каталожную KDB, 4 — repo-local skills. Даже имя и положение базы знаний расходятся: `LXD/kdb.yaml`, `Antivirus/kdb/kdb.yaml`, набор отдельных файлов в `AD/kdb/` и `Monitoring/kdb/`. ### 2.2. Read-only SSH-проверка Проверка выполнялась без копирования файлов, изменения конфигураций, рестартов и других записей. - `cloud1`: Ubuntu 24.04.4 LTS, оба члена LXD-кластера ONLINE, предупреждений нет, ZFS-пулы healthy; - LXD live inventory: 35 инстансов и новый проект `drweb`; документация от 2026-08-18 ещё содержит 34 инстанса и 9 проектов; - `docker-manager0`: 6 Swarm-узлов Ready/Active, live-лидер — `docker-manager1`, 53 сервиса в 17 стеках; - `dc01`: Debian 10, 26 GPO. Эти расхождения не являются признаком плохой документации. Они показывают, что live-состояние по природе изменчиво и не должно копироваться в несколько README, skills и снимков без явной provenance и срока актуальности. ### 2.3. Внешние первичные источники - MCP задаёт JSON-RPC base protocol, capability negotiation и раздельные server features: resources, prompts и tools. Для tools предусмотрены input/output schemas, структурированный результат, ошибки исполнения и подтверждение чувствительных операций клиентом: [MCP specification — Overview](https://modelcontextprotocol.io/specification/2025-11-25/basic), [MCP specification — Tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools). - Backstage показывает полезный, но более тяжёлый паттерн: YAML-descriptor хранится рядом с кодом, центральный каталог его агрегирует, а сам каталог не считается первоисточником. Отдельные сущности и relations формируют граф: [Software Catalog](https://backstage.io/docs/features/software-catalog/), [Creating the Catalog Graph](https://backstage.io/docs/features/software-catalog/creating-the-catalog-graph/), [Descriptor Format](https://backstage.io/docs/features/software-catalog/descriptor-format/). ## 3. Наблюдения, которые определяют архитектуру ### 3.1. Граница ответственности уже найдена GuardPlus формулирует её особенно удачно: - чтобы **поднять контейнер** — артефакт принадлежит LXD; - чтобы **понять или наполнить СКУД** — артефакт принадлежит GuardPlus. Antivirus следует тому же принципу: - продуктовые факты, проверенные пути, принятие сервиса и rollout — в `Services/Antivirus`; - LXD profiles — в `Infra/LXD`; - IP/DNS/firewall — в `Infra/Network`; - proxy stack — в `Infra/Docker`; - rollout Windows agent — в `Infra/AD`; - наблюдаемость должна связываться с `Services/Monitoring`. Эту границу не надо размывать общим монорепозиторием. Надо сделать её машинно-читаемой. ### 3.2. Единственной «истины обо всём» быть не должно Для одного объекта существуют разные авторитетные грани: | Грань | Кто владеет | Пример | |---|---|---| | Назначение и продуктовые требования | service repo | Antivirus знает порты DWCP, лицензию и правильный health probe | | Желаемая инфраструктурная конфигурация | infra repo | LXD владеет profiles, Docker — stack spec, AD — GPO | | Фактическое состояние | runtime API/CLI | `lxc list`, Docker API, Samba/UDM, Zabbix API | | Исторический снимок | dated report | `reports/*-YYYY-MM-DD.md`, `instances.yaml` | | Проверенные особенности продукта | KDB | provenance `VERIFIED/MANUAL/DRAFT/STALE` | | Связь requirement → implementation | consumer + provider binding | Antivirus требует instance; LXD фиксирует, чем требование выполнено | Центральный каталог может агрегировать эти грани, но не должен становиться ещё одним местом ручного редактирования тех же фактов. ### 3.3. Повторяющийся протокол операций уже сложился Реальные handlers используют почти одинаковые понятия: | Домен | Уже существующие операции | |---|---| | LXD | `list`, `pull`, `validate`, `audit`, `diff`, `push --dry-run`, `push` | | Monitoring | read-only `audit --json`, KDB `validate/stale/drift`, provisioning `check/plan/apply/prune` | | Network | inventory, discover, `check --diff`, `apply --dry-run`, `apply`, status | | Docker | compose validation, stack deploy, service/stack inspection | | AD | backup, apply via управляющий слой, reconciliation AD × audit × Fleet × assets | Нужно унифицировать **семантику**, но не заменять эти handlers одним универсальным shell runner. ### 3.4. Skills не могут быть источником изменчивых фактов В LXD одновременно отслеживаются `.agents/skills/lxd-profiles` и `.claude/skills/lxd-profiles`. Они уже различаются: - старый handler: около 12.6 КБ; - актуальный handler: около 29.9 КБ; - актуальная версия добавила `audit`, JSON output, secret placeholders и cloud-init replay guard; - обе копии отслеживаются Git и имеют разные SHA-256. Это не косметический drift: агент, выбравший старую копию, получает менее безопасное поведение. Аналогично длинный Docker agent содержит снимочные сведения о topology, а `CLUSTER_STATE.md` уже отстал от live-лидера. Следствие: skill должен быть тонким UX-слоем, а исполняемый код, constraints и registry операций — иметь ровно одну каноническую копию. ### 3.5. Cross-repo транзакции невозможны, но возможен проверяемый план Добавление сервиса часто меняет LXD, Network, Docker, AD и Monitoring. Git и эти runtime не поддерживают общую транзакцию. Поэтому правильная единица работы — не «одна атомарная команда», а **неизменяемый план с checkpoints**: 1. зафиксировать revisions входных репозиториев и live snapshots; 2. построить план и dependency order; 3. применить один provider change; 4. выполнить provider verification; 5. выполнить service acceptance; 6. только затем перейти к следующему шагу; 7. хранить run evidence и явно указывать, где rollback невозможен. ## 4. Общая модель, одинаковая для всех трёх вариантов ### 4.1. Минимальный шаблон репозитория Не нужно немедленно переносить существующие `profiles-source/`, Docker stack folders или `endpoint-management/`. Контракт декларирует их как domain-native paths. ```text repo/ ├── README.md # вход для человека, без дублирования live-снимков ├── AGENTS.md # короткий pointer: прочитать ops/contract + constraints ├── ops/ │ ├── contract.yaml # канонический repo/service/infra contract │ ├── handlers/ # исполняемая реализация операций │ ├── schemas/ # repo-specific input/output schemas при необходимости │ ├── templates/ # scaffolds новых компонентов/ресурсов │ └── tests/ # contract, safety и handler tests ├── kdb/ │ ├── index.yaml # навигация, provenance и routing вопросов │ └── *.yaml # проверенные факты и ограничения по подсистемам ├── docs/ │ ├── architecture/ # живые объяснения и ADR │ ├── runbooks/ # процедуры и rollback │ └── reports/ # датированные, неизменяемые snapshots/evidence ├── / # profiles-source, stacks, endpoint-management и т. п. ├── .agents/skills/ # тонкие adapters для агента; без handlers и live facts └── .secrets.example # только схема/имена, без значений ``` Для постепенного внедрения допустимо оставить текущую KDB на месте и указать её через `spec.knowledge.entrypoint`. Стандартизировать путь можно позже; семантика важнее миграции каталогов. ### 4.2. Контракт репозитория Пример намеренно сокращён. Реальная схема должна валидироваться JSON Schema и иметь versioning. ```yaml apiVersion: ops.corsus.pro/v1alpha1 kind: RepositoryContract metadata: name: antivirus repo: Services/Antivirus class: service # service | infrastructure | platform | data lifecycle: production owners: [corsus-it] spec: authority: owns: - product.requirements - product.knowledge - service.acceptance doesNotOwn: - lxd.profile - network.ipam - docker.stack - ad.gpo knowledge: entrypoint: kdb/kdb.yaml provenance: [VERIFIED, MANUAL, DRAFT, STALE] requires: - id: ess-compute capability: compute.lxd.instance constraints: environment: production placement: cloud1 - id: ess-address capability: network.static-address - id: ess-dns capability: network.dns-record - id: windows-rollout capability: identity.software-rollout - id: service-monitoring capability: observability.service provides: - id: drweb-control-plane capability: antivirus.endpoint-control operations: - id: service.inspect summary: Read deployed state without trusting the SysV-generated systemd status effect: read risk: low handler: ops/handlers/service.py args: [inspect] outputSchema: ops/schemas/service-state.json - id: service.accept summary: Verify process, listeners, API and licence after an infrastructure change effect: read risk: low handler: ops/handlers/service.py args: [accept] outputSchema: ops/schemas/acceptance-result.json secrets: policy: references-only allowedRefs: [repo-local-env, runtime-secret] ``` Provider repo публикует capabilities и bindings, а не копирует требования сервиса: ```yaml spec: provides: - capability: compute.lxd.instance bindings: - id: drweb-ess-lxd fulfills: repo:Services/Antivirus#requirement/ess-compute implementation: project: drweb instance: drweb-ess profiles: [default, drweb-base, drweb-server] desiredStatePaths: - projects/drweb/ - profiles-source/drweb-base.yaml - profiles-source/drweb-server.yaml inspectOperation: lxd.instance.inspect ``` Правило владения связью: - consumer владеет `requires` и acceptance criteria; - provider владеет `bindings` и инфраструктурной реализацией; - агрегатор строит relation только если обе стороны совместимы; - unresolved requirement и orphan binding являются диагностируемым drift. ### 4.3. Унифицированный жизненный цикл операций | Фаза | Семантика | Разрешённый эффект | |---|---|---| | `describe` | показать контракт, capabilities, constraints, schemas | read | | `inspect` | получить live state из авторитетного API/CLI | read | | `snapshot` | записать датированное evidence | local-write | | `validate` | проверить source, schema, policy и preconditions | read/local temp | | `diff` | сравнить desired ↔ live ↔ last verified | read | | `plan` | построить точный change set и verification plan | read/local artifact | | `apply` | применить ровно сохранённый plan | external-write | | `verify` | platform checks + service acceptance | read | | `reconcile` | классифицировать drift и предложить направление исправления | read; apply отдельно | | `rollback` | восстановить snapshot или выполнить compensating action | external-write/disruptive | Не каждый домен обязан поддерживать все verbs. Неподдерживаемая операция объявляется явно, как сейчас в LXD объявлены out-of-scope instance lifecycle и project management. ### 4.4. Обязательные поля операции Каждая исполняемая операция должна объявлять: - стабильный `id` и краткое назначение; - input/output JSON Schema; - `effect`: `read`, `local-write`, `external-write`, `disruptive`, `destructive`; - `risk`: `low`, `medium`, `high`, `critical`; - target selector и границы допустимого scope; - credential references без значений; - preconditions; - поддержку `dryRun` и idempotency, если она реальна; - `mutates`: какие repo paths и runtime objects могут измениться; - confirmation policy; - verification operation; - rollback/compensation или явное `rollback: unavailable`; - timeout и exit-code semantics; - redaction policy; - evidence, которое записывается после запуска. Нельзя объявлять произвольную shell-строку как публичную операцию. Registry должен ссылаться на allowlisted handler и argv; handler сам ограничивает команды и targets. ### 4.5. Формат plan и run evidence `plan` должен быть самостоятельным артефактом, например `ops-plan.json`: ```json { "apiVersion": "ops.corsus.pro/v1alpha1", "operation": "lxd.instance.migrate", "createdAt": "2026-08-19T12:00:00Z", "inputsHash": "sha256:...", "repoRevisions": { "Infra/LXD": "", "Services/Antivirus": "" }, "liveSnapshotHash": "sha256:...", "targets": ["lxd:drweb/drweb-ess"], "steps": [], "verification": [], "rollback": {}, "risk": "high" } ``` `apply` принимает plan hash и отказывается работать, если revisions, targets или критичные live preconditions изменились. Это защищает от применения старого dry-run к уже изменившейся среде. ### 4.6. Базовый набор skills Skills должны быть короткими orchestrators, а не вторыми README или копиями Python handlers. | Skill | Задача | |---|---| | `ops-discover` | найти contracts под `~/Git`, построить catalog и relation graph | | `ops-repo-onboard` | проверить/сгенерировать минимальный contract для существующего repo | | `ops-change-plan` | разрешить requirements к providers и построить cross-repo plan | | `ops-drift-audit` | вызвать domain inspect/diff и классифицировать drift | | `ops-safe-apply` | проверить plan hash, approval и вызвать domain apply | | `ops-verify` | собрать provider verification и service acceptance | | `ops-reconcile` | найти unresolved requirements, orphan bindings, stale facts и snapshots | | `ops-incident-snapshot` | read-only evidence из нескольких providers с redaction | | `ops-service-integrate` | сценарий «новый компонент сервиса → инфраструктурные bindings» | | `ops-workload-migrate` | сценарий «инфраструктурное перемещение → service-aware plan» | Domain skills остаются, но становятся adapters: - `lxd-ops`; - `swarm-ops`; - `ad-ops`; - `network-ops`; - `monitoring-ops`; - `hardware-ops`. Каждый такой skill обязан сначала читать `ops/contract.yaml` и KDB constraints, затем вызывать канонический handler. Hostnames, current leaders, instance counts и версии в skill не помещаются. ### 4.7. Два ключевых сценария #### Сервис добавляет компонент Пример: Antivirus добавляет proxy и rollout endpoints. 1. Service repo добавляет/уточняет requirements и acceptance criteria. 2. `ops-change-plan` находит providers: - LXD — server instance; - Docker — proxy на NAS02; - Network — route/IP/DNS/firewall; - AD — Windows rollout; - Monitoring — service checks. 3. Каждый provider возвращает свой `validate/diff/plan`. 4. Общий plan строит dependency order, но не склеивает changes в одну непрозрачную команду. 5. После каждого apply выполняется provider verify. 6. В конце Antivirus выполняет end-to-end acceptance. 7. Providers записывают bindings; service repo не копирует их конфигурацию. #### Инфраструктура переносит сервисы на новые хосты 1. LXD выбирает candidate instances и публикует proposed placement plan. 2. Catalog находит связанные service contracts и их требования: downtime, backup, affinity, address stability, health/acceptance operations. 3. Capacity/placement validation выполняется инфраструктурой; service impact validation — сервисом. 4. Миграция идёт batch-ами с checkpoints. 5. После platform verification выполняются service acceptance и monitoring verification. 6. Binding обновляется только после успешной проверки; старый host остаётся в evidence, а не в актуальном contract. ```mermaid flowchart LR S[Service requires + acceptance] --> C[Catalog / relation graph] I[Infrastructure capabilities + bindings] --> C C --> P[Immutable cross-repo plan] P --> L[LXD adapter] P --> D[Docker adapter] P --> N[Network adapter] P --> A[AD adapter] P --> M[Monitoring adapter] L --> V[Provider verification] D --> V N --> V A --> V M --> V V --> E[Service end-to-end acceptance] ``` ## 5. Вариант 1 — федеративный GitOps-контракт + общий CLI **Рейтинг: 9.2/10 — рекомендуемый первый этап и основная архитектура.** ### Суть Каждый repo хранит `ops/contract.yaml`, свои handlers и свои authoritative artifacts. Небольшой общий `opsctl` сканирует `~/Git/Infra` и `~/Git/Services`, валидирует contracts, строит relation graph и вызывает repo-local operations. Центрального постоянно работающего сервера нет. Catalog — производный локальный JSON/SQLite cache, который всегда можно перестроить из Git. Пример UX: ```text opsctl catalog build ~/Git/Infra ~/Git/Services opsctl entity show service:antivirus opsctl operations list --entity service:antivirus opsctl plan service.integrate --service antivirus --component drweb-proxy opsctl apply --plan .ops/runs//plan.json --confirm "APPLY " opsctl verify --run opsctl reconcile --all ``` ### Сильные стороны - совпадает с текущей границей ответственности repo; - не требует переносить domain-native конфигурацию; - минимальная blast radius: handler работает только в своём домене; - Git остаётся источником desired state и review trail; - можно внедрять по одному repo; - работает без отдельной платформы, БД, OAuth и высокой доступности; - создаёт правильный фундамент для будущего MCP; - легче всего автоматизировать CI-проверки contracts, duplicate skills и stale facts. ### Слабые стороны - первый catalog/graph будет CLI, без красивого портала; - cross-repo plan требует дисциплины versioning и стабильных IDs; - локальный запуск зависит от доступности нескольких repos и credentials; - нужно поддержать Windows и Linux execution paths. ### Как устроены skills - общий набор orchestration skills устанавливается один раз; - domain skills остаются рядом с repo; - handlers лежат только в `ops/handlers`, а `.agents/skills` содержит инструкции и ссылки; - если нужна совместимость `.agents` и `.claude`, wrapper-файлы генерируются из одного template, а CI сравнивает их hash/semantic version. ### Когда выбирать Сейчас. Это наименьшее изменение, которое решает реальные проблемы ownership, drift, discoverability и безопасного исполнения. ## 6. Вариант 2 — центральный Ops Catalog / Ops Hub **Рейтинг: 7.4/10 — полезен для обзора, слабее как первичный control plane.** ### Суть Создаётся отдельный repo, например `Ops/Catalog`, содержащий registry всех entities, operations, templates и связей. В более полном виде рядом разворачивается web UI по модели Backstage-lite. Есть два подварианта: 1. центральные descriptor files редактируются вручную; 2. рекомендуемый — repo-local contracts остаются первоисточниками, а hub только harvest/cache/UI. Только второй подвариант приемлем: официальный Backstage также рекомендует считать Git descriptor files первоисточником, а catalog — агрегатором. ### Сильные стороны - лучший обзор ownership, lifecycle, dependencies и незакрытых требований; - удобная точка входа для людей; - templates и onboarding новых repos можно сделать через формы; - проще строить отчёты: orphan services, stale verification, неподключённый monitoring; - хорошо масштабируется, если репозиториев станет много. ### Слабые стороны - отдельный сервис, БД, auth, backup и upgrade lifecycle; - соблазн начать редактировать runtime facts в каталоге и получить ещё один источник drift; - центральная команда/схема становится bottleneck; - custom actions с правом SSH/API резко увеличивают blast radius; - для текущих 14 прямых repos полноценный Backstage, вероятно, преждевременен. ### Как устроены skills - skills сначала спрашивают catalog API о relations и operation endpoints; - исполнение всё равно делегируется domain adapters; - hub не получает универсального `run_shell`; - templates создают merge requests в owning repos, а не меняют live напрямую. ### Когда выбирать После варианта 1, если CLI-каталог перестанет удовлетворять людей или появится необходимость в self-service portal. Как замена repo-local contracts этот вариант не рекомендуется. ## 7. Вариант 3 — полноценный Ops MCP control plane **Рейтинг сейчас: 6.8/10. Потенциал после варианта 1: 9.0/10.** ### Суть Registry операций публикуется через настоящий MCP server: - **resources**: entities, contracts, KDB sections, plans, run evidence, live read-only snapshots; - **tools**: `catalog.search`, `entity.describe`, `operation.plan`, `operation.apply`, `operation.verify`, `drift.inspect`; - **prompts**: типовые сценарии onboarding, migration, incident triage; - tool schemas автоматически выводятся из того же contract schema. MCP является транспортом и discovery layer, но не заменяет GitOps, domain handlers и safety policy. ### Сильные стороны - естественный discovery операций для Codex/Claude и других клиентов; - строгие schemas вместо разбора текстового CLI output; - единый structured result и actionable tool errors; - можно централизовать audit events, rate limits и policy checks; - удобно подключать уже существующие Grafana/Prometheus MCP servers как read-only providers; - отличный long-term интерфейс поверх стабильного operation registry. ### Слабые стороны - высокий начальный объём: server, authorization, scopes, audit, secrets broker, availability; - опасно публиковать write-tools до формализации effects, plan hashes и approvals; - MCP tool annotations нельзя считать достаточной защитой: сервер обязан валидировать input и access сам; - один компрометированный control plane может получить доступ сразу к LXD, Docker, AD и Network; - без варианта 1 MCP server быстро превратится в набор hand-written tools с разными semantics; - transport/API versioning добавится к contract и handler versioning. ### Рекомендуемые scopes ```text catalog:read state:read plan:create evidence:write lxd:apply docker:apply network:apply ad:apply monitoring:apply destructive:approve ``` Write scopes должны быть domain-specific. Нельзя выдавать один общий `infra:write`. Credentials downstream-систем не должны передаваться MCP client: server использует отдельные audience-bound credentials для каждого provider. ### Как устроены skills Skills становятся в основном routing/policy инструкциями: - какие resources сначала прочитать; - когда разрешён только `plan`; - какой confirmation нужен; - как объединить provider verification с service acceptance. Вся фактическая schema операции и её execution остаются на server/handler side. ### Когда выбирать После того как минимум LXD, Docker, Network, AD и один service repo реализовали вариант 1 и показали одинаковые semantics на реальных сценариях. Начинать сразу с write-capable MCP не рекомендуется; допустим ранний read-only MCP для catalog/search/inspect. ## 8. Сравнение вариантов Вес критериев отражает текущую ситуацию: безопасность и устойчивость к drift важнее UI. | Критерий | Вес | Вариант 1: federated CLI | Вариант 2: Ops Hub | Вариант 3: MCP сейчас | |---|---:|---:|---:|---:| | Соответствие существующим repos и ownership | 25% | 9.5 | 7.5 | 8.0 | | Безопасность исполнения | 25% | 9.5 | 7.5 | 5.5 | | Устойчивость к drift | 20% | 9.5 | 6.5 | 7.0 | | Стоимость запуска | 15% | 8.5 | 6.5 | 4.5 | | Расширяемость и discoverability | 15% | 8.5 | 9.0 | 10.0 | | **Итог** | **100%** | **9.2/10** | **7.4/10** | **6.8/10** | MCP получает 9.0/10 как следующий слой после варианта 1, потому что к тому времени самые сложные части — ownership, schemas, effects, handlers и safety — уже проверены независимо от транспорта. ## 9. Рекомендуемая последовательность внедрения ### Фаза 0 — договориться о semantics Зафиксировать один schema package: - `RepositoryContract`; - `Requirement`; - `Capability`; - `Binding`; - `Operation`; - `Plan`; - `RunEvidence`. Стабильные IDs важнее полноты первой версии. Начать с `v1alpha1`, не обещая обратную совместимость до двух пилотов. ### Фаза 1 — два вертикальных пилота Пилот A, service-driven: - `Services/Antivirus` как consumer; - `Infra/LXD`, `Infra/Network`, `Infra/AD`, `Services/Monitoring` как providers; - сценарий: описать уже работающий `drweb-ess`, обнаружить fulfilled и unresolved requirements, выполнить read-only acceptance. Пилот B, infrastructure-driven: - `Infra/LXD`; - выбрать тестовый workload; - построить migration plan с service-owned acceptance; - apply пока не выполнять — проверить полноту plan, preconditions и rollback. ### Фаза 2 — канонические handlers и thin skills - перенести LXD handler в единственное каноническое место; - убрать код и volatile facts из skills; - добавить одинаковый `--json` envelope и exit codes; - покрыть safety self-tests; - добавить CI-проверку, запрещающую drift между compatibility wrappers; - адаптировать Monitoring audit/provisioning как эталон разделения read/write; - формализовать Docker repository-level KDB и operations, не копируя stack facts в agent text. ### Фаза 3 — локальный catalog и reconciliation - `opsctl catalog build`; - graph requirements/bindings; - `opsctl validate --all`; - `opsctl reconcile --all`; - отчёт по stale verified facts, unresolved requirements, orphan bindings и unsupported operations. ### Фаза 4 — только затем интерфейс Выбор по фактической потребности: - достаточно CLI — остаться на варианте 1; - нужен human portal — добавить вариант 2 как derived UI; - нужен agent/tool interoperability — добавить read-only MCP, затем строго scoped write-tools. ## 10. Что принципиально не делать - Не создавать центральный YAML со всеми IP, hostnames, versions и counts вручную. - Не считать snapshot desired state. - Не помещать live topology в `SKILL.md` или `AGENTS.md`. - Не дублировать один handler под `.agents` и `.claude` без generation/hash check. - Не давать общему агенту произвольный SSH/shell как «универсальную операцию». - Не считать `--dry-run` безопасным без измерения before/after, как уже правильно делает Monitoring. - Не считать source автоматически правильнее live: LXD уже знает случаи intentional drift. - Не выполнять cross-repo apply без сохранённого plan, revisions и checkpoints. - Не требовать rollback там, где он физически невозможен; объявлять compensating action и остаточный риск. - Не хранить secret values в contract, KDB, evidence или MCP result. - Не делать catalog новым источником истины: это rebuildable projection. ## 11. Критерии готовности первой версии Первая версия считается полезной, если выполняются все условия: 1. `opsctl` находит contracts минимум Antivirus, LXD, Network, AD и Monitoring. 2. Contract validation работает полностью offline. 3. Catalog показывает requirement `Antivirus → LXD` и соответствующий provider binding. 4. Read-only `inspect` выдаёт единый JSON envelope независимо от домена. 5. LXD и Monitoring поддерживают `validate/diff-or-drift/plan/verify` с одинаковой семантикой exit codes. 6. Ни один mutating handler не доступен без plan и явного approval. 7. Service acceptance живёт в service repo и вызывается после provider verification. 8. Stale snapshot не выглядит как current state: есть `observedAt`, provenance и probe reference. 9. Две agent ecosystems не могут незаметно получить разные handlers. 10. `reconcile` обнаруживает как минимум: - unresolved requirement; - orphan binding; - stale verified fact; - desired/live drift; - отсутствующую verification operation. ## 12. Итоговое решение Рекомендуемая архитектура — **вариант 1 как ядро, вариант 3 как будущий транспорт**. Ключевая идея не в едином инструменте, который умеет всё, а в едином договоре о том: - как repo сообщает, чем он владеет; - что сервис требует от инфраструктуры; - чем provider это требование выполнил; - какие операции доступны; - что операция читает и меняет; - как строится план; - как проверяется результат; - где лежит rollback; - откуда взят каждый факт и когда он был проверен. После этого локальный CLI, портал и MCP становятся взаимозаменяемыми интерфейсами над одной моделью. Без этого любой «импровизированный MCP» лишь централизует текущую неоднородность и увеличит blast radius.