Skip to content

# TASK_PHASE_GOVERNANCE_ENGINE.md

## DAARION.city — Governance Engine, Revocation, Audit & Escalation (MVP)

Ціль:
Реалізувати повноцінний Governance Engine згідно з:

- `Agent_Governance_Protocol_v1.md`
- `DAIS_Layer_Architecture_v1.md`
- `Agents_Interface_Architecture_v1.md`
- `Nodes_Interface_Architecture_v1.md`
- `District_Interface_Architecture_v1.md`
- `MicroDAO_Interface_Architecture_v1.md`
- `Rooms_Layer_Architecture_v1.md`

та підключити його до існуючих:

- DAIS API (`/api/v1/dais/*`)
- Assignments Layer (`/api/v1/assignments/*`)
- Event Outbox (`event_outbox`)

## 1. Загальний опис задачі

Побудувати Governance Engine, який:

1. Інтерпретує ролі та рівні агентів (guest → city governance).
2. Застосовує permissions до всіх ключових дій (create microdao, create node, create room, promote/revoke agent).
3. Надає API для:
4. призначення ролей,
5. промоції,
6. ревокації,
7. перевірки доступу.
8. Привʼязує всі governance-події до `event_outbox` для аудиту.
9. Створює базовий Governance UI:
10. City Governance Panel,
11. District Governance Panel,
12. MicroDAO Governance Panel.
13. Додає просту систему ескалації інцидентів (tickets + escalation flow).
14. Додає Audit Dashboard (читання `event_outbox` + фільтри).

## 2. BACKEND — Governance Engine

### 2.1. Модель ролей і рівнів

Орієнтуватися на `Agent_Governance_Protocol_v1.md`.

Реалізувати enum/константи:

- `AGENT_LEVEL_GUEST = 0`
- `AGENT_LEVEL_PERSONAL = 1`
- `AGENT_LEVEL_MEMBER = 2`
- `AGENT_LEVEL_WORKER = 3`
- `AGENT_LEVEL_CORE_TEAM = 4`
- `AGENT_LEVEL_ORCHESTRATOR = 5`
- `AGENT_LEVEL_DISTRICT_LEAD = 6`
- `AGENT_LEVEL_CITY_GOV = 7`

Зберігати рівень:

- або в таблиці `agents.agent_role_level`,
- або в окремій таблиці ролей (якщо вже є — узгодити).

### 2.2. Permission Engine

Створити модуль, умовно:

- `governance/permissions.py` (або відповідний файл у вашому стеку)

Функції:

- `can_create_microdao(agent, context)`
- `can_create_district(agent, context)`
- `can_register_node(agent, context)`
- `can_create_room(agent, context)`
- `can_create_front_portal(agent, context)`
- `can_promote_agent(actor, target, scope)`
- `can_revoke_agent(actor, target, scope)`
- `can_moderate_room(actor, room)`
- `can_moderate_city_room(actor, room)`

Усередині — логіка з `Agent_Governance_Protocol_v1.md`:

- тільки Orchestrator може створювати MicroDAO;
- District Lead / City Governance — створюють District;
- Node Manager / Orchestrator / Core-team DevOps — реєструють ноди;
- Core-team / Orchestrator — створюють DAO-wide rooms;
- DARIO / DARIA / DAARWIZZ — міські кімнати;
- City Governance — глобальна ескалація та revocation.

### 2.3. Governance API

Створити ендпоїнти (REST або GraphQL — згідно існуючого стилю):

- `POST /api/v1/governance/agent/promote`
- body: `{ actor_id, target_id, new_level, scope }`
- перевірити `can_promote_agent`
- оновити роль/рівень

- записати подію в `event_outbox`

- `POST /api/v1/governance/agent/revoke`

- body: `{ actor_id, target_id, reason, scope }`
- перевірити `can_revoke_agent`
- позначити агента як revoked / заблокувати ключі

- записати подію `agent.revoked` в `event_outbox`

- `POST /api/v1/governance/agent/assign`

- body: `{ actor_id, target_id, scope_type, scope_id, role }`
- перевірити, чи actor має право на assign у цьому scope
- створити/оновити запис у Assignments Layer
- подія `agent.assigned`

Додатково (якщо ще немає):

- `GET /api/v1/governance/agent/:id/roles`
- `GET /api/v1/governance/agent/:id/permissions`

### 2.4. Інтеграція з Assignments Layer

При промоції / assign:

- створювати/оновлювати записи в `assignments` (таблиця, яка вже є в схемі).
- використовувати `scope`:
- `city`
- `district:{id}`
- `microdao:{id}`
- `node:{id}`

Переконатися, що Assignments однозначно відповідають ролям з Governance Protocol.

## 3. BACKEND — Revocation Engine

### 3.1. DAIS Key Revocation

На основі `DAIS_Layer_Architecture_v1.md`:

- Додати метод для revocation ключів:
- позначити записи в `dais_keys` як `revoked=true`
- викидати помилки при спробі використання revoked-ключа.

Створити API:

- `POST /api/v1/dais/keys/revoke`
- body: `{ actor_id, dais_id, reason }`
- тільки City Governance / District Lead / Orchestrator (залежно від scope).

### 3.2. Agent State

Додати атрибут (якщо його ще нема) у `agents`:

- `status` = `active | suspended | revoked`

При revocation:

- `status = revoked`
- заблокувати виконання критичних дій цим агентом (через Permission Engine).

## 4. BACKEND — Audit & Event Outbox

### 4.1. Події, які обовʼязково логувати

Через `event_outbox`:

- `agent.promoted`
- `agent.revoked`
- `agent.assigned`
- `microdao.created`
- `district.created`
- `node.registered`
- `room.created`
- `room.published_to_city`
- `incident.escalated`

Створити helper:

- `governance/log_event.py` або подібний модуль:
- `log_governance_event(type, actor_id, target_id, payload)`

### 4.2. Audit API

- `GET /api/v1/audit/events`
- фільтри: `type`, `actor_id`, `target_id`, `scope`, `created_at_from/to`
- `GET /api/v1/audit/events/:id`

## 5. BACKEND — Escalation System (MVP)

### 5.1. Таблиця `incidents`

Створити таблицю:

- `id`
- `created_by_dais_id`
- `target_scope_type` (`city|district|microdao|room|node|agent`)
- `target_scope_id`
- `status` (`open|in_progress|resolved|closed`)
- `priority` (`low|medium|high|critical`)
- `assigned_to_dais_id` (опціонально)
- `escalation_level` (`microdao|district|city`)
- `title`
- `description`
- `created_at`
- `updated_at`

### 5.2. API

- `POST /api/v1/incidents/create`
- `POST /api/v1/incidents/:id/assign`
- `POST /api/v1/incidents/:id/escalate`
- `POST /api/v1/incidents/:id/resolve`
- `GET /api/v1/incidents`
- `GET /api/v1/incidents/:id`

Логувати у `event_outbox` події:

- `incident.created`
- `incident.assigned`
- `incident.escalated`
- `incident.resolved`

Ескалація:

- MicroDAO core-team → District Lead → City Governance (DAARWIZZ/DARIA).

## 6. FRONTEND — Governance UI

### 6.1. City Governance Panel

Сторінка (наприклад):

- `/governance/city`

Показує:

- список city-agentів (DARIO, DARIA, DAARWIZZ, інші)
- список Districts
- список відкритих інцидентів з escalation_level=`city`
- панель дій:
- promote/revoke agent (global / city scope)
- approve new district
- view audit events (фільтр по city)

### 6.2. District Governance Panel

Сторінка:

- `/governance/district/[id]`

Показує:

- District Lead Agent
- core-team district-рівня
- підлеглі MicroDAO
- інциденти з escalation_level=`district`
- панель:
- призначення/зняття ролей в межах district
- view audit за district scope

### 6.3. MicroDAO Governance Panel

Сторінка:

- `/governance/microdao/[id]` або вкладка в `/microdao/[id]`

Показує:

- Orchestrator
- Core-team
- Workers / Members
- відкриті інциденти для цього DAO
- панель:
- promote/demote agents у межах DAO
- revoke (локально або з ескалацією)
- audit DAO-подій

## 7. FRONTEND — Agent Governance Views

У `AgentCabinet`:

- блок "Ролі та повноваження":
- рівень агента (guest/personal/member/…)
- ролі у MicroDAO
- ролі у District
- участь на City рівні
- блок "Дії" (видимий, якщо actor має права):
- promote
- revoke
- assign

## 8. FRONTEND — Audit Dashboard

Сторінка:

- `/audit`

Функціонал:

- список подій з `event_outbox`
- фільтри: тип, actor, target, scope, період
- детальний перегляд події
- базова візуалізація (наприклад, кількість governance-подій за період)

## 9. FRONTEND — Incidents / Escalation UI

Сторінки:

- `/incidents`
- `/incidents/[id]`

Можливості:

- створити інцидент із будь-якого контексту (room, microdao, district, node, agent):
- кнопка "Поскаржитись / Report"
- перегляд:
- статус,
- масштаби,
- виконавець,
- історія змін,
- дії (для тих, хто має права):
- assign to agent,
- escalate,
- resolve.

## 10. Тести та перевірка

Cursor повинен:

- додати unit-тести для Permission Engine,
- додати інтеграційні тести для:
- promote,
- revoke,
- assign,
- incident escalation,
- протестувати audit-лог (event_outbox) для ключових governance-дій.

## 11. Очікуваний результат TASK-фази

Після завершення цієї фази:

1. Усі ключові дії в системі підконтрольні Governance Engine.
2. Агенти не можуть перевищувати свої повноваження.
3. Є чіткі API для промоції, ревокації, призначення ролей.
4. Всі governance-події логуються в event_outbox.
5. Є UI для City/District/MicroDAO-governance.
6. Є Incidents/Escalation система для проблем і конфліктів.
7. Є Audit Dashboard для аналізу історії рішень.

Це створює надійний керований фундамент для подальшого розвитку DAARION.city.

## 12. Checklist

### Backend ✅

- [x] Migration: `agents.agent_role_level`, `agents.status` fields
- [x] Migration: `incidents` table
- [x] Domain types: `governance/types.ts`
- [x] Permission Engine: `governance/permissions.ts`
- [x] Governance Service: `governance/governance.service.ts`
- [x] Revocation Service: `governance/revocation.service.ts`
- [x] Audit Service: `governance/audit.service.ts`
- [x] Incidents Service: `governance/incidents.service.ts`
- [x] Governance Routes: `governance.routes.ts`
- [x] Audit Routes: `audit.routes.ts`
- [x] Incidents Routes: `incidents.routes.ts`
- [x] Event logging helper

### Frontend ✅

- [x] API clients: `governance.ts`, `audit.ts`, `incidents.ts`
- [x] Types: `governance.ts`
- [x] City Governance Panel
- [x] Governance Level Badge component
- [x] Audit Dashboard
- [x] Incidents List & Detail
- [x] Agent Governance Views in AgentCabinet ✅
- [x] Report Button component ✅
- [x] GovernancePage with tabs ✅
- [x] Route `/governance` ✅
- [ ] District Governance Panel (TODO: окрема фаза)
- [ ] MicroDAO Governance Panel (TODO: окрема фаза)

### Tests

- [ ] Permission Engine unit tests
- [ ] Governance API integration tests
- [ ] Revocation flow tests
- [ ] Incidents escalation tests