microdao-daarion/docs/tasks/TASK_PHASE_GOVERNANCE_ENGINE.md

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. Привʼязує всі governance-події до event_outbox для аудиту.
5. Створює базовий Governance UI:
   • City Governance Panel,
   • District Governance Panel,
   • MicroDAO Governance Panel.
6. Додає просту систему ескалації інцидентів (tickets + escalation flow).
7. Додає 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 ✅

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

Frontend ✅

• API clients: governance.ts, audit.ts, incidents.ts
• Types: governance.ts
• City Governance Panel
• Governance Level Badge component
• Audit Dashboard
• Incidents List & Detail
• Agent Governance Views in AgentCabinet ✅
• Report Button component ✅
• GovernancePage with tabs ✅
• 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