# 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-фази реалізації.