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, який:

Інтерпретує ролі та рівні агентів (guest → city governance).
Застосовує permissions до всіх ключових дій (create microdao, create node, create room, promote/revoke agent).
Надає API для:
призначення ролей,
промоції,
ревокації,
перевірки доступу.
Привʼязує всі governance-події до event_outbox для аудиту.
Створює базовий Governance UI:
City Governance Panel,
District Governance Panel,
MicroDAO Governance Panel.
Додає просту систему ескалації інцидентів (tickets + escalation flow).
Додає 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-фази¶

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

Усі ключові дії в системі підконтрольні Governance Engine.
Агенти не можуть перевищувати свої повноваження.
Є чіткі API для промоції, ревокації, призначення ролей.
Всі governance-події логуються в event_outbox.
Є UI для City/District/MicroDAO-governance.
Є Incidents/Escalation система для проблем і конфліктів.
Є 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

TASK_PHASE_GOVERNANCE_ENGINE.md¶

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

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

2. BACKEND — Governance Engine¶

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

2.2. Permission Engine¶

2.3. Governance API¶

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

3. BACKEND — Revocation Engine¶

3.1. DAIS Key Revocation¶

3.2. Agent State¶

4. BACKEND — Audit & Event Outbox¶

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

4.2. Audit API¶

5. BACKEND — Escalation System (MVP)¶

5.1. Таблиця incidents¶

5.2. API¶

6. FRONTEND — Governance UI¶

6.1. City Governance Panel¶

6.2. District Governance Panel¶

6.3. MicroDAO Governance Panel¶

7. FRONTEND — Agent Governance Views¶

8. FRONTEND — Audit Dashboard¶

9. FRONTEND — Incidents / Escalation UI¶

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

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

12. Checklist¶

Backend ✅¶

Frontend ✅¶

Tests¶

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