Skip to content

# TASK_PHASE_INFRA_INVARIANTS_AND_DEPLOY_CHECKS_v1

## Проєкт

DAARION.city — Infra / Deploy / DAGI / microdao

## Фаза

Інваріанти інфраструктури + автоматичні перевірки після деплою

## Статус

✅ COMPLETED

## Мета

Зробити деплой детермінованим і безпечним так, щоб базова логіка Нода → DAGI Router → Агенти → microdao → System Prompts не ламалася після оновлень.

## Problem Statement

### Симптоми

- Після оновлень/деплоїв періодично:
- зникають агенти у Кабінеті Ноди (0 agents total)
- ламаються кабінети агентів (`404`, відсутні `public_slug`)
- зникають метрики GPU/CPU/RAM/Disk
- DAGI Router / microdao втрачають частину зв'язків

### Причина

- Немає формально зафіксованих інваріантів, які перевіряються автоматично після кожного деплою
- Деплой проходить навіть тоді, коли стан системи неконсистентний

## Рішення

### 1. Інваріанти зафіксовані в коді

Файл: `scripts/check-invariants.py`

#### Node Invariants

Node | Інваріант | Severity
--- | --- | ---
NODE1, NODE2 | Існує в `node_cache` | CRITICAL
NODE1, NODE2 | `agent_count_router >= 1` | CRITICAL
NODE1, NODE2 | `agent_count_system >= 1` | CRITICAL
NODE1 | GPU configured | WARNING
NODE1, NODE2 | Heartbeat < 10 min | WARNING

#### Node Agents Invariants

Інваріант | Severity
--- | ---
Node Guardian exists | CRITICAL
Node Steward exists | CRITICAL
Total agents >= 1 | CRITICAL

#### DAGI Router Invariants

Інваріант | Severity
--- | ---
`router_total >= 1` | WARNING
`phantom_count <= 20` | WARNING
`stale_count <= 20` | WARNING

#### Core Agents Invariants

Agent | Required | Severity
--- | --- | ---
DAARWIZZ | core prompt | WARNING
MicroDAO Orchestrator | core prompt | WARNING
DevTools | core prompt | WARNING
SOUL | core prompt | WARNING
GREENFOOD | core prompt | WARNING
Helion | core prompt | WARNING
DRUID | core prompt | WARNING
NUTRA | core prompt | WARNING
Monitor | core prompt | WARNING

### 2. Скрипт перевірки

    # Запуск перевірки
    python scripts/check-invariants.py --base-url http://localhost:7001

    # Перевірка тільки NODE1
    python scripts/check-invariants.py --node node-1-hetzner-gex44

    # JSON output
    python scripts/check-invariants.py --json

#### Exit codes

- `0` — всі критичні інваріанти пройшли
- `1` — є критичні помилки

### 3. Smoke Tests

Файл: `tests/test_infra_smoke.py`

    # Запуск тестів
    pytest tests/test_infra_smoke.py -v

    # З custom URL
    pytest tests/test_infra_smoke.py -v --base-url http://localhost:7001

#### Тести

- `TestHealthChecks` — `/healthz`, `/public/nodes`
- `TestNodeMetrics` — метрики нод, agent counts
- `TestNodeAgents` — Guardian, Steward
- `TestDAGIRouter` — DAGI agents, summary
- `TestCoreAgents` — prompts status, runtime prompts
- `TestIntegration` — end-to-end flows

### 4. Інтеграція в Deploy

Файл: `scripts/deploy-prod.sh`

    # Деплой з автоматичною перевіркою інваріантів
    ./scripts/deploy-prod.sh

    # Деплой зі smoke тестами
    RUN_SMOKE_TESTS=true ./scripts/deploy-prod.sh

#### Pipeline

1. Pre-flight checks (Docker, .env, compose files)
2. Database backup
3. Pull/build images
4. Start core services
5. Run migrations
6. Start all services
7. Basic health checks
8. Infrastructure invariants check ← NEW
9. (Optional) Smoke tests
10. Success/failure report

## Файли

Файл | Опис
--- | ---
`scripts/check-invariants.py` | CLI для перевірки інваріантів
`tests/test_infra_smoke.py` | Pytest smoke тести
`scripts/deploy-prod.sh` | Оновлений deploy script

## Використання

### Щоденна розробка

    # Перевірити інваріанти вручну
    python scripts/check-invariants.py --base-url http://localhost:7001

    # Запустити smoke тести
    pytest tests/test_infra_smoke.py -v

### Production Deploy

    # Повний деплой з інваріантами
    ./scripts/deploy-prod.sh

    # Якщо інваріанти не пройшли:
    # 1. Перевірити міграції
    psql -h localhost -U postgres -d daarion < migrations/037_node_agents_complete.sql
    psql -h localhost -U postgres -d daarion < migrations/038_agent_prompts_full_coverage.sql

    # 2. Перезапустити перевірку
    python scripts/check-invariants.py

### CI/CD Integration

    # GitHub Actions example
    - name: Deploy
      run: ./scripts/deploy-prod.sh

    - name: Check Invariants
      run: python scripts/check-invariants.py --base-url ${{ secrets.CITY_SERVICE_URL }}

    - name: Run Smoke Tests
      run: pytest tests/test_infra_smoke.py -v

## Acceptance Criteria

Критерій | Статус
--- | ---
`scripts/check-invariants.py` існує і працює | ✅
Перевіряє NODE1 та NODE2 | ✅
Перевіряє Node Guardian/Steward | ✅
Перевіряє DAGI Router | ✅
Перевіряє core agents prompts | ✅
Exit code 1 при критичних помилках | ✅
Інтегровано в deploy-prod.sh | ✅
Smoke тести в pytest | ✅

## Наступні кроки

1. Prometheus metrics для інваріантів
2. Alerting при порушенні інваріантів
3. GitHub Actions CI/CD pipeline
4. Rollback automation при failed invariants