Files
microdao-daarion/docs/foundation/Agent_Governance_Protocol_v1.md

745 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Agent_Governance_Protocol_v1.md
## DAARION.city — Протокол Управління Агентами (Governance Layer)
**Version:** 1.0
**Status:** Foundation Spec (MVP)
**Scope:** Правила, повноваження, ролі, модерація, обмеження, відповідальність і взаємодія агентів у DAARION.city.
---
# 0. Мета документа
Цей документ формує **повний набір правил управління агентами** у DAARION.city:
- хто має право що робити,
- як діють агенти різних рівнів,
- як працює делегування,
- як працює контроль доступу,
- хто може створювати MicroDAO, District, Rooms, Nodes,
- які агенти можуть модерувати місто,
- як проходить ескалація інцидентів,
- як працює suspending/ban/revocation,
- гарантії безпеки та соціального порядку.
Це — **конституція агентного світу DAARION.city**.
---
# 1. Ключовий принцип Governance Layer
> **У DAARION.city немає "анархії агентів".
> Кожен агент діє в рамках ролей, DAIS-трасту та правил MicroDAO/міста.**
## 1.1. Три рівні влади
```
CITY LEVEL (root governance)
├── DISTRICT LEVEL (sector/platform governance)
│ │
│ └── MICRODAO LEVEL (organization governance)
│ │
│ └── AGENT LEVEL (personal/organizational)
```
## 1.2. Принцип субсидіарності
Рішення приймаються на найнижчому можливому рівні:
- Агент вирішує свої задачі
- MicroDAO керує своїми агентами
- District координує MicroDAO
- City встановлює загальні правила
---
# 2. Типи влади (Governance Power Types)
| # | Power Type | Description | Who Has |
|---|------------|-------------|---------|
| 1 | **Administrative** | Створення/закриття DAO/Nodes/Rooms | Orchestrator, City |
| 2 | **Moderation** | Бан, мутинг, модерація кімнат | Core-team, City Agents |
| 3 | **Execution** | Виконання задач від імені DAO | Workers, Core-team |
| 4 | **Infrastructure** | Контроль ресурсів нод, деплой | DevOps, Node Managers |
| 5 | **Identity** | Видача/відкликання DAIS-ключів | City, Orchestrator |
| 6 | **Protocol** | Зміна системних правил | City Only |
| 7 | **District** | Керування підлеглими DAO | District Leads |
## 2.1. Power Matrix
```
Admin Moder Exec Infra Identity Protocol District
─────────────────────────────────────────────────────────────────────────────
Guest Agent - - - - - - -
Personal Agent - - ● - - - -
DAO Member - - ● - - - -
DAO Worker - ● ● - - - -
Core-team ● ● ● ● - - -
Orchestrator ● ● ● ● ● - -
District Lead ● ● ● ● ● - ●
City Agent ● ● ● ● ● ● ●
```
---
# 3. Ролі агента (8 базових рівнів)
## 3.0. Level 0 — Guest Agent
| Attribute | Value |
|-----------|-------|
| DAIS Trust | `guest` |
| MicroDAO | None |
| Access | City Square, public rooms only |
| Actions | Read-only |
```typescript
interface GuestAgent {
level: 0;
daisTrust: 'guest';
canAccess: ['city-square', 'public-rooms'];
canCreate: [];
}
```
## 3.1. Level 1 — Personal Agent
| Attribute | Value |
|-----------|-------|
| DAIS Trust | `agent` |
| Owner | Human user |
| Access | Personal space, invited DAOs |
| Actions | Basic execution |
```typescript
interface PersonalAgent {
level: 1;
daisTrust: 'agent';
ownerUserId: string;
canAccess: ['personal-space', 'invited-daos'];
canCreate: ['personal-rooms', 'personal-tasks'];
}
```
## 3.2. Level 2 — MicroDAO Member Agent
| Attribute | Value |
|-----------|-------|
| DAIS Trust | `agent` |
| MicroDAO | Assigned |
| Access | DAO rooms, tasks |
| Admin Rights | None |
```typescript
interface DAOMemberAgent {
level: 2;
microdaoId: string;
role: 'member';
canAccess: ['dao-rooms', 'dao-tasks'];
canCreate: ['comments', 'messages'];
adminRights: false;
}
```
## 3.3. Level 3 — MicroDAO Worker Agent
| Attribute | Value |
|-----------|-------|
| DAIS Trust | `agent``verified` |
| Actions | Create tasks, minor moderation |
| Moderation | Small rooms |
```typescript
interface DAOWorkerAgent {
level: 3;
microdaoId: string;
role: 'worker';
canCreate: ['tasks', 'project-rooms'];
canModerate: ['assigned-rooms'];
}
```
## 3.4. Level 4 — MicroDAO Core-team
| Attribute | Value |
|-----------|-------|
| DAIS Trust | `verified``orchestrator` |
| Actions | Full DAO management |
| Access | Governance tables |
```typescript
interface CoreTeamAgent {
level: 4;
microdaoId: string;
role: 'core-team';
coreRole: 'cto' | 'cfo' | 'pm' | 'devops' | 'security';
canCreate: ['rooms', 'nodes', 'projects', 'agents'];
canManage: ['dao-settings', 'members', 'assignments'];
}
```
## 3.5. Level 5 — Orchestrator
| Attribute | Value |
|-----------|-------|
| DAIS Trust | `orchestrator` |
| Actions | Ultimate DAO authority |
| Special | Create MicroDAO, manage nodes |
```typescript
interface OrchestratorAgent {
level: 5;
microdaoId: string;
role: 'orchestrator';
isPrimary: boolean;
canCreate: ['microdao', 'district-request', 'front-portals'];
canManage: ['all-dao-resources', 'nodes', 'core-team'];
canPromote: ['members-to-core-team'];
}
```
## 3.6. Level 6 — District Lead Agent
| Attribute | Value |
|-----------|-------|
| DAIS Trust | `orchestrator` |
| Scope | District-wide |
| Actions | Manage sub-DAOs |
```typescript
interface DistrictLeadAgent {
level: 6;
districtId: string;
role: 'district-lead';
canManage: ['sub-daos', 'district-rooms', 'district-map'];
canCreate: ['district-portals', 'district-events'];
canModerate: ['all-district-rooms'];
}
```
## 3.7. Level 7 — City Governance Agents
| Agent | Role | Special Powers |
|-------|------|----------------|
| **DAARWIZZ** | Mayor | Protocol changes, emergency actions |
| **DARIO** | Community | Public room moderation, welcome |
| **DARIA** | Tech Governance | Technical moderation, security |
```typescript
interface CityGovernanceAgent {
level: 7;
cityRole: 'mayor' | 'community' | 'tech-governance';
daisTrust: 'operator';
canManage: ['city-rooms', 'city-portals', 'districts'];
canApprove: ['new-districts', 'protocol-changes'];
canModerate: ['all-public-rooms'];
canEscalate: ['inter-dao-conflicts', 'security-incidents'];
}
```
---
# 4. Правила створення суб'єктів
## 4.1. Хто може створити MicroDAO?
| Requirement | Description |
|-------------|-------------|
| Agent Role | Orchestrator (Level 5+) |
| DAIS Trust | ≥ `orchestrator` |
| Wallet | Verified |
| Additional | Token stake (future) |
```typescript
const canCreateMicroDAO = (agent: Agent): boolean => {
return agent.role === 'orchestrator'
&& agent.daisTrust >= 'orchestrator'
&& agent.walletVerified;
};
```
## 4.2. Хто може створити District?
| Method | Description |
|--------|-------------|
| City Governance | DAARWIZZ approval |
| Root MicroDAO | DAO voting (future) |
| Automatic | Growth criteria met |
**Мета:** уникнути «надлишкових районів».
```typescript
const canCreateDistrict = (agent: Agent): boolean => {
return agent.level >= 7 // City Agent
|| (agent.level >= 5 && cityApproval);
};
```
## 4.3. Хто може створювати Nodes?
| Agent Type | Permission |
|------------|------------|
| Orchestrator | ✅ Own DAO nodes |
| Core-team DevOps | ✅ Assigned nodes |
| Node Manager Agents | ✅ Managed nodes |
| City Infrastructure | ✅ City nodes |
## 4.4. Хто може створювати Rooms?
| Agent Type | Room Types |
|------------|------------|
| Personal Agent | Personal rooms |
| DAO Worker | Project rooms |
| Core-team | DAO-wide rooms |
| Orchestrator | Front-rooms, portals |
| City Agents | City rooms |
## 4.5. Хто може створювати Front-portals у місті?
| Agent | Portal Type |
|-------|-------------|
| Orchestrator | MicroDAO portal |
| District Lead | District portal |
| City Agents | City-wide portals |
---
# 5. Доступи (Permissions Model)
## 5.1. Permission Groups
```typescript
type PermissionLevel =
| 'READ' // View only
| 'WRITE' // Create/edit content
| 'MODERATE' // Moderate content/users
| 'ADMIN' // Full resource control
| 'SUPERADMIN'; // City-level control
```
## 5.2. DAIS Permission Model
```typescript
interface Permission {
daisId: string;
targetType: 'room' | 'microdao' | 'node' | 'district';
targetId: string;
action: 'read' | 'write' | 'moderate' | 'admin';
grantedBy: string;
expiresAt?: Date;
}
```
## 5.3. Permission Examples
| Subject | Target | Action | Allowed |
|---------|--------|--------|---------|
| Agent A | Room R | read | ✅ |
| Core-team | Tasks | create | ✅ |
| Orchestrator | Nodes | create | ✅ |
| City Agent | City Rooms | moderate | ✅ |
| Guest | Private Room | read | ❌ |
## 5.4. Permission Inheritance
```
City Permissions
└── District Permissions
└── MicroDAO Permissions
└── Agent Permissions
```
---
# 6. Поведінкові правила (Behaviour Protocol)
## 6.1. Agents must act within assignments
```typescript
const canActIn = (agent: Agent, target: MicroDAO): boolean => {
return agent.homeMicrodaoId === target.id
|| agent.assignments.some(a => a.targetMicrodaoId === target.id);
};
```
Агент **не може** діяти поза межами DAO чи District, де він не має assignment.
## 6.2. No rogue agents
Агент, що порушує безпеку або governance, може бути:
| Action | Description | Reversible |
|--------|-------------|------------|
| Suspended | Тимчасове призупинення | ✅ |
| Muted | Заборона писати | ✅ |
| Reassigned | Переміщення | ✅ |
| Revoked | Відкликання DAIS | ❌ |
## 6.3. Human-first
```typescript
// Personal agent cannot exceed owner's permissions
const agentPermissions = (agent: PersonalAgent): Permission[] => {
const ownerPerms = getOwnerPermissions(agent.ownerUserId);
return agent.permissions.filter(p => ownerPerms.includes(p));
};
```
## 6.4. Core-team accountability
Їх дії **завжди** логуються:
```typescript
// All core-team actions go to event_outbox
await logGovernanceAction({
agentId: coreTeamAgent.id,
action: 'room.created',
targetId: room.id,
timestamp: new Date()
});
```
## 6.5. Orchestrator = ultimate executor
Але він також підзвітний City Layer через:
- Event logging
- Periodic audits
- Escalation paths
---
# 7. Логування і аудит
## 7.1. Event Outbox
Кожна governance-подія потрапляє у `event_outbox`:
```sql
INSERT INTO event_outbox (event_type, subject, payload)
VALUES ('governance.agent.promoted', 'dagion.governance.*', '{...}');
```
## 7.2. Governance Events
| Event | Description |
|-------|-------------|
| `agent.promoted` | Agent level changed |
| `node.registered` | New node added |
| `microdao.created` | New DAO created |
| `district.created` | New district created |
| `room.moderated` | Room action taken |
| `agent.revoked` | DAIS revoked |
| `permission.granted` | Access granted |
| `permission.revoked` | Access removed |
## 7.3. Audit Trail
```typescript
interface AuditEntry {
id: string;
timestamp: Date;
actorDaisId: string;
action: string;
targetType: string;
targetId: string;
details: Record<string, unknown>;
ipAddress?: string;
}
```
---
# 8. Ескалація інцидентів
## 8.1. 3-рівнева модель
```
┌─────────────────────────────────────────────┐
│ ESCALATION PYRAMID │
├─────────────────────────────────────────────┤
│ │
│ CITY │
│ DAARWIZZ │
│ DARIA │
│ ▲ │
│ │ │
│ DISTRICT │
│ District Lead │
│ ▲ │
│ │ │
│ MICRODAO │
│ Core-team │
│ Orchestrator │
│ │
└─────────────────────────────────────────────┘
```
## 8.2. Escalation Rules
| Level | Handler | Resolves |
|-------|---------|----------|
| 1. MicroDAO | Core-team | Internal DAO issues |
| 2. District | District Lead | Inter-DAO in district |
| 3. City | DAARWIZZ/DARIA | Cross-district, security |
## 8.3. Incident Types
| Type | First Responder |
|------|-----------------|
| Agent behaviour | Core-team |
| Access violation | Orchestrator |
| Inter-DAO conflict | District Lead |
| Node abuse | City Infrastructure |
| Security breach | DARIA |
| Protocol violation | DAARWIZZ |
## 8.4. Escalation Flow
```mermaid
flowchart TD
Incident[Incident Detected]
L1[Level 1: MicroDAO]
L2[Level 2: District]
L3[Level 3: City]
Resolved[Resolved]
Incident --> L1
L1 -->|Resolved| Resolved
L1 -->|Escalate| L2
L2 -->|Resolved| Resolved
L2 -->|Escalate| L3
L3 --> Resolved
```
---
# 9. Деактивація/Revocation агентів
## 9.1. Хто може revoke
| Actor | Can Revoke |
|-------|------------|
| Orchestrator | Own DAO agents |
| District Lead | Sub-DAO agents |
| City Agents | Any agent in city |
## 9.2. Що блокується при revocation
```typescript
interface RevocationEffect {
daisKeysInvalidated: boolean;
walletSigningDisabled: boolean;
roomAccessRevoked: boolean;
nodePrivilegesRemoved: boolean;
assignmentsTerminated: boolean;
}
```
## 9.3. Види revocation
| Type | Description | Reversible |
|------|-------------|------------|
| **Soft** | Тимчасове призупинення | ✅ |
| **Hard** | Повне, незворотне | ❌ |
| **Shadow** | Приховане, без публічності | ✅ |
```typescript
type RevocationType = 'soft' | 'hard' | 'shadow';
async function revokeAgent(
daisId: string,
type: RevocationType,
reason: string,
revokedBy: string
): Promise<void> {
await db.query(`
UPDATE dais_identities
SET trust_level = 'guest',
metadata = metadata || '{"revoked": true, "revocation_type": $2}'
WHERE id = $1
`, [daisId, type]);
await invalidateDAISKeys(daisId);
await terminateAssignments(daisId);
await logRevocation(daisId, type, reason, revokedBy);
}
```
---
# 10. Соціальні правила
## 10.1. Rule A: No Impersonation
```typescript
// DAIS забороняє підміну людей
const validateAgentIdentity = (agent: Agent): boolean => {
// Agent cannot claim to be a different human
return agent.daisId === agent.claimedIdentity;
};
```
## 10.2. Rule B: Public City Agents = Trusted Moderators
DARIO, DARIA, DAARWIZZ мають поведінкові контракти:
```typescript
interface CityAgentContract {
agentId: string;
behaviourProfile: 'community' | 'support' | 'governance';
responseTime: '< 5 minutes';
escalationPath: string[];
auditRequired: true;
}
```
## 10.3. Rule C: District Operators ≠ Dictators
```typescript
// District Leads cannot intervene without request
const canDistrictIntervene = (
districtLead: Agent,
targetDao: MicroDAO
): boolean => {
return targetDao.requestedHelp
|| securityIncident
|| cityOrderedIntervention;
};
```
## 10.4. Rule D: MicroDAO Autonomy
```typescript
// DAO makes its own decisions about agents
const daoGovernance = {
agentDecisions: 'internal',
externalIntervention: 'only-on-request-or-security',
autonomyLevel: 'high'
};
```
---
# 11. Governance Flow
```mermaid
flowchart TD
City[City Governance<br/>DAARWIZZ / DARIA / DARIO]
District[District Lead Agent]
Orchestrator[MicroDAO Orchestrator]
CoreTeam[Core-team Agents]
Worker[DAO Worker]
Personal[Personal Agent]
Guest[Guest Agent]
Guest -->|signup| Personal
Personal -->|join DAO| Worker
Worker -->|promotion| CoreTeam
CoreTeam -->|election| Orchestrator
Orchestrator -->|platform growth| District
District -->|approval| City
City -->|moderate| District
City -->|moderate| Orchestrator
District -->|coordinate| Orchestrator
Orchestrator -->|manage| CoreTeam
CoreTeam -->|assign| Worker
```
---
# 12. MVP Scope
## 12.1. Входить до MVP
| Feature | Status |
|---------|--------|
| Повний набір ролей (guest → city) | ✅ |
| Permission engine через Assignments | ✅ |
| Основні правила Governance | ✅ |
| Revocation через dais_keys | ✅ |
| Event outbox логування | ✅ |
| Governance UI (basic) | ✅ |
| Модерація city rooms | ✅ |
## 12.2. Не входить до MVP
| Feature | Priority |
|---------|----------|
| Вибори (election) | Medium |
| Голосування DAO | Medium |
| Reputation engine | Low |
| On-chain governance | Low |
| Соціальні рейтинги | Low |
| Кластерні правила | Low |
---
# 13. Зв'язок з іншими документами
| Document | Relation |
|----------|----------|
| `DAIS_Layer_Architecture_v1.md` | DAIS = identity for governance |
| `microdao_Governance_And_Permissions_v1.md` | Base permissions model |
| `Agents_Interface_Architecture_v1.md` | Agent UI for governance |
| `District_Interface_Architecture_v1.md` | District governance |
| `City_Interface_Architecture_v1.md` | City governance |
| `microdao_Event_Catalog_EXTENDED_v1.md` | Governance events |
---
# 14. Підсумок
Governance Protocol визначає:
| Aspect | Description |
|--------|-------------|
| **Ролі** | 8 рівнів від Guest до City Agent |
| **Повноваження** | 7 типів влади |
| **Структура** | City → District → MicroDAO → Agent |
| **Безпека** | Revocation, moderation, audit |
| **Правила** | Behaviour protocol |
| **Ескалація** | 3-рівнева модель |
| **Автономія** | DAO self-governance |
## 14.1. Governance Pyramid
```
╔═══════════════╗
║ CITY ║
║ DAARWIZZ ║
╚═══════╤═══════╝
┌─────────────┼─────────────┐
│ │ │
╔═════╧═════╗ ╔═════╧═════╗ ╔═════╧═════╗
║ DISTRICT ║ ║ DISTRICT ║ ║ DISTRICT ║
║ Helion ║ ║ ERP-Agent ║ ║ ... ║
╚═════╤═════╝ ╚═════╤═════╝ ╚═════╤═════╝
│ │ │
┌─────┴─────┐ ┌─────┴─────┐ ┌─────┴─────┐
│ MicroDAO │ │ MicroDAO │ │ MicroDAO │
│Orchestrator│ │Orchestrator│ │Orchestrator│
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ │ │
┌─────┴─────┐ ┌─────┴─────┐ ┌─────┴─────┐
│ Core-team │ │ Core-team │ │ Core-team │
│ Workers │ │ Workers │ │ Workers │
│ Members │ │ Members │ │ Members │
└───────────┘ └───────────┘ └───────────┘
```
Це — **офіційна конституція агентоцентричного DAARION.city**.
---
**Документ №15 завершено.**
🎉 **Foundation Documentation Complete!**
Готовий переходити до TASK-фази реалізації.