chore: organize documentation structure for monorepo
- Create /docs structure (microdao, daarion, agents) - Organize 61 cursor technical docs - Add README files for each category - Copy key documents to public categories - Add GitHub setup instructions and scripts
This commit is contained in:
Apple
471
docs/cursor/41_ai_governance_agent_design.md
Normal file
471
docs/cursor/41_ai_governance_agent_design.md
Normal file
@@ -0,0 +1,471 @@
|
||||
# 41 — AI Governance Agent Design (MicroDAO)
|
||||
|
||||
*Специфікація AI Governance Agent: політики, голосування, застосування правил, оновлення capability/bundle/quotas, безпека, журналювання, інтеграція з PDP та Registry*
|
||||
|
||||
---
|
||||
|
||||
## 1. Purpose & Scope
|
||||
|
||||
AI Governance Agent — це **суверенний системний агент**, який:
|
||||
|
||||
- приймає та опрацьовує governance proposals,
|
||||
- перевіряє їх коректність,
|
||||
- обчислює результати голосування,
|
||||
- застосовує зміни до Policy Registry,
|
||||
- оновлює bundles, capabilities, entitlements, stake-multipliers,
|
||||
- взаємодіє з PDP,
|
||||
- гарантує консистентність і безпеку системи.
|
||||
|
||||
Це **центральний мозок політик** DAARION.city.
|
||||
|
||||
---
|
||||
|
||||
## 2. Governance Model Overview
|
||||
|
||||
Система складається з:
|
||||
|
||||
- **Governance Token Holders (DAAR/DAARION)**
|
||||
- **AI Governance Agent**
|
||||
- **Policy Registry**
|
||||
- **Capability Registry**
|
||||
- **Quota Service**
|
||||
- **PDP**
|
||||
- **Audit Log**
|
||||
|
||||
Основний принцип:
|
||||
|
||||
```text
|
||||
AI Governance Agent — це механічний виконавець волі DAO.
|
||||
```
|
||||
|
||||
Він сам **не генерує політик**, а лише обробляє та застосовує.
|
||||
|
||||
---
|
||||
|
||||
## 3. Governance Proposal Lifecycle
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as User/Token Holder
|
||||
participant API
|
||||
participant G as Governance Agent
|
||||
participant DB as Policy Registry
|
||||
participant PDP
|
||||
|
||||
U->>API: create proposal
|
||||
API->>DB: insert proposal (pending)
|
||||
API-->>U: proposal_id
|
||||
|
||||
U->>API: submit votes
|
||||
API->>DB: update votes
|
||||
|
||||
G->>DB: check proposals for finalization
|
||||
DB-->>G: proposal ready
|
||||
|
||||
G->>G: validate proposal payload
|
||||
G->>DB: apply changes
|
||||
G->>PDP: reload capabilities/quotas
|
||||
G->>DB: mark proposal applied
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Governance Proposal Structure
|
||||
|
||||
Зберігається у таблиці `governance_policies`.
|
||||
|
||||
Приклад:
|
||||
|
||||
```json
|
||||
{
|
||||
"policy_id": "gov_0012",
|
||||
"policy_type": "plan.entitlement.update",
|
||||
"target": "plan.Premium",
|
||||
"operations": [
|
||||
{ "op": "set_quota", "metric": "llm_tokens_per_month", "value": 3500000 },
|
||||
{ "op": "increase_quota", "metric": "agent_runs_per_day", "value": 200 }
|
||||
],
|
||||
"proposed_by": "u_123",
|
||||
"voting_end": "2025-11-20T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Governance Agent Responsibilities
|
||||
|
||||
### 5.1 Validation
|
||||
|
||||
Перевіряє:
|
||||
|
||||
- формат політики,
|
||||
- чи існує bundle/cap/plan,
|
||||
- чи операції не суперечать безпековим правилам,
|
||||
- чи не роблять escalation.
|
||||
|
||||
### 5.2 Voting Finalization
|
||||
|
||||
Після дедлайну:
|
||||
|
||||
- рахує голоси,
|
||||
- перевіряє кворум,
|
||||
- визначає результат.
|
||||
|
||||
### 5.3 Applying Policy
|
||||
|
||||
Головна роль:
|
||||
|
||||
- оновити bundles/capabilities/entitlements,
|
||||
- оновити Registry,
|
||||
- створити подію `governance.policy.updated`,
|
||||
- скинути кеш PDP.
|
||||
|
||||
### 5.4 Audit
|
||||
|
||||
Записує:
|
||||
|
||||
- хто подав,
|
||||
- хто голосував,
|
||||
- коли застосовано,
|
||||
- які зміни внесено.
|
||||
|
||||
### 5.5 Failure Recovery
|
||||
|
||||
У разі помилок:
|
||||
|
||||
- застосовує rollback-strategy,
|
||||
- помічає політику як failed.
|
||||
|
||||
---
|
||||
|
||||
## 6. Governance Agent Internal Architecture
|
||||
|
||||
```text
|
||||
Governance Agent
|
||||
├── Policy Validator
|
||||
├── Voting Engine
|
||||
├── Policy Applicator
|
||||
├── Registry Updater
|
||||
├── PDP Connector
|
||||
├── Event Publisher
|
||||
└── Audit Logger
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Policy Validation Rules
|
||||
|
||||
Головний блок — **Validation Engine**.
|
||||
|
||||
### 7.1 Format validation
|
||||
|
||||
- JSON schema must match.
|
||||
- All required fields exist.
|
||||
|
||||
### 7.2 Capability rules
|
||||
|
||||
- capability must exist in `capabilities`.
|
||||
- cannot assign admin caps to visitors.
|
||||
- cannot remove baseline capabilities from Owner/Guardian.
|
||||
|
||||
### 7.3 Plan/Entitlements rules
|
||||
|
||||
- plan hierarchy is preserved.
|
||||
- quota cannot be lower than Freemium baseline.
|
||||
- cannot create infinite cost-free compute.
|
||||
|
||||
### 7.4 Stake-multiplier rules
|
||||
|
||||
- multiplier ranges must be monotonic.
|
||||
- cannot set multiplier=0 or negative.
|
||||
|
||||
### 7.5 Compute/1T rules
|
||||
|
||||
- compute costs must be >= minimum threshold.
|
||||
- cannot create zero-cost for heavy tools.
|
||||
|
||||
### 7.6 RWA policies
|
||||
|
||||
- cannot set reward rates above safety ranges.
|
||||
- cannot autogenerate rewards for unverified RWA.
|
||||
|
||||
---
|
||||
|
||||
## 8. Voting Engine
|
||||
|
||||
Перевіряє:
|
||||
|
||||
- голоси,
|
||||
- токен-вагу,
|
||||
- кворум,
|
||||
- approval threshold.
|
||||
|
||||
Приклад:
|
||||
|
||||
```text
|
||||
min_quorum = 10% від circulating_supply
|
||||
approval_required = 51%
|
||||
```
|
||||
|
||||
Після дедлайну:
|
||||
|
||||
```text
|
||||
if quorum_met && approval >= 51%:
|
||||
status = approved
|
||||
else:
|
||||
status = rejected
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Policy Applicator
|
||||
|
||||
Застосовує зміни до:
|
||||
|
||||
- bundles
|
||||
- capabilities
|
||||
- bundle_caps
|
||||
- plan entitlements
|
||||
- stake multipliers
|
||||
- compute pricing
|
||||
- RWA conversion rates
|
||||
- platform-level quotas
|
||||
|
||||
Алгоритм:
|
||||
|
||||
```python
|
||||
for op in policy.operations:
|
||||
apply(op)
|
||||
validate_consistency()
|
||||
commit()
|
||||
publish_event("governance.policy.updated")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Registry Integration
|
||||
|
||||
### 10.1 Capability Registry
|
||||
|
||||
Оновлюються:
|
||||
|
||||
- capabilities table,
|
||||
- bundles,
|
||||
- bundle_caps.
|
||||
|
||||
### 10.2 Quota Registry
|
||||
|
||||
Оновлюється JSON конфіг ентитлментів:
|
||||
|
||||
```json
|
||||
{
|
||||
"plan.Premium": {
|
||||
"llm_tokens_per_month": 3500000,
|
||||
"agent_runs_per_day": 1000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 10.3 Stake Registry
|
||||
|
||||
Оновлюються множники для RINGK.
|
||||
|
||||
### 10.4 RWA Registry
|
||||
|
||||
Оновлюються conversion rates:
|
||||
|
||||
- energy → KWT
|
||||
- water → 1T
|
||||
- food → 1T
|
||||
|
||||
---
|
||||
|
||||
## 11. PDP Integration
|
||||
|
||||
Після застосування політики Governance Agent публікує:
|
||||
|
||||
```text
|
||||
governance.policy.updated
|
||||
```
|
||||
|
||||
PDP:
|
||||
|
||||
- скидає кеш capabilities,
|
||||
- скидає кеш entitlements,
|
||||
- оновлює compute pricing,
|
||||
- оновлює stake multipliers,
|
||||
- застосовує нові access rules.
|
||||
|
||||
---
|
||||
|
||||
## 12. Security Rules (Critical)
|
||||
|
||||
### 12.1 Governance Agent cannot modify DB directly
|
||||
|
||||
Усе через:
|
||||
|
||||
- internal service keys,
|
||||
- capability: `service.governance.apply`.
|
||||
|
||||
### 12.2 Cannot bypass Validation Engine
|
||||
|
||||
Будь-яка спроба → automatic deny.
|
||||
|
||||
### 12.3 Cannot assign itself new capabilities
|
||||
|
||||
Strict no-self-escalation.
|
||||
|
||||
### 12.4 Immutable History
|
||||
|
||||
Після `applied=true` політика не може бути змінена.
|
||||
|
||||
### 12.5 Governance Agent cannot break economic model
|
||||
|
||||
Заборонено:
|
||||
|
||||
- знизити compute cost нижче min,
|
||||
- встановити reward rate за RWA > максимум.
|
||||
|
||||
---
|
||||
|
||||
## 13. Error Recovery
|
||||
|
||||
### 13.1 If validation fails
|
||||
|
||||
- політика `status=invalid`.
|
||||
|
||||
### 13.2 If apply fails
|
||||
|
||||
- rollback to pre-apply snapshot,
|
||||
- mark policy `failed`.
|
||||
|
||||
### 13.3 If PDP reload fails
|
||||
|
||||
- retry with exponential backoff,
|
||||
- system enters "safe mode".
|
||||
|
||||
---
|
||||
|
||||
## 14. Transparency & Audit
|
||||
|
||||
Усі операції Governance Agent:
|
||||
|
||||
- логуються,
|
||||
- підписуються service identity,
|
||||
- зберігаються у `audit_log`,
|
||||
- доступні для перегляду через:
|
||||
|
||||
```text
|
||||
GET /governance/policies
|
||||
GET /governance/policies/:id
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 15. Governance Agent Runtime
|
||||
|
||||
### 15.1 Frequency
|
||||
|
||||
Agent запускається:
|
||||
|
||||
- кожні 60 секунд (плановий цикл),
|
||||
- або по події «proposal.pending».
|
||||
|
||||
### 15.2 Autoscaling
|
||||
|
||||
- stateless service,
|
||||
- масштабування необмежене.
|
||||
|
||||
---
|
||||
|
||||
## 16. Example Policy Application (Full)
|
||||
|
||||
### Input proposal:
|
||||
|
||||
```text
|
||||
Increase Premium compute quotas by 25%
|
||||
```
|
||||
|
||||
### Operations:
|
||||
|
||||
```json
|
||||
[
|
||||
{ "op": "increase_quota", "metric": "agent_runs_per_day", "value": 250 },
|
||||
{ "op": "increase_quota", "metric": "llm_tokens_per_month", "value": 500000 }
|
||||
]
|
||||
```
|
||||
|
||||
### Governance Agent process:
|
||||
|
||||
1. validate structure → OK
|
||||
2. validate quotas do not exceed global max → OK
|
||||
3. check plan hierarchy → OK
|
||||
4. commit changes → DB updated
|
||||
5. publish `policy.updated`
|
||||
6. PDP reloads → new quotas active
|
||||
|
||||
---
|
||||
|
||||
## 17. Integration with Other Docs
|
||||
|
||||
Цей документ доповнює:
|
||||
|
||||
- `31_governance_policies_for_capabilities_and_quotas.md`
|
||||
- `32_policy_service_PDP_design.md`
|
||||
- `24_access_keys_capabilities_system.md`
|
||||
- `30_cost_optimization_and_token_economics_infrastructure.md`
|
||||
- `40_rwa_energy_food_water_flow_specs.md`
|
||||
|
||||
---
|
||||
|
||||
## 18. Завдання для Cursor
|
||||
|
||||
```text
|
||||
You are a senior backend engineer. Implement AI Governance Agent using:
|
||||
- 41_ai_governance_agent_design.md
|
||||
- 31_governance_policies_for_capabilities_and_quotas.md
|
||||
- 32_policy_service_PDP_design.md
|
||||
|
||||
Tasks:
|
||||
1) Create Governance Agent service architecture (Policy Validator, Voting Engine, Policy Applicator, Registry Updater, PDP Connector, Event Publisher, Audit Logger).
|
||||
2) Implement Governance Proposal Lifecycle (create, vote, finalize, apply).
|
||||
3) Create Governance Proposal Structure (JSON schema).
|
||||
4) Implement Policy Validation Rules (format, capability, plan/entitlements, stake-multiplier, compute/1T, RWA policies).
|
||||
5) Implement Voting Engine (vote counting, quorum check, approval threshold).
|
||||
6) Implement Policy Applicator (apply operations to bundles, capabilities, entitlements, quotas).
|
||||
7) Add Registry Integration (Capability Registry, Quota Registry, Stake Registry, RWA Registry).
|
||||
8) Implement PDP Integration (reload capabilities/quotas after policy update).
|
||||
9) Add Security Rules (no direct DB access, no bypass validation, no self-escalation, immutable history, economic model protection).
|
||||
10) Implement Error Recovery (validation failure, apply failure, PDP reload failure).
|
||||
11) Add Transparency & Audit (logging, service identity signing, audit_log storage).
|
||||
12) Create Governance Agent Runtime (periodic execution, event-driven triggers).
|
||||
|
||||
Output:
|
||||
- list of modified files
|
||||
- diff
|
||||
- summary
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 19. Summary
|
||||
|
||||
AI Governance Agent:
|
||||
|
||||
- керує всіма політиками DAARION.city,
|
||||
- контролює capability-набори,
|
||||
- регулює квоти та економіку,
|
||||
- гарантує безпеку та непротирічність,
|
||||
- забезпечує прозорість і аудитність,
|
||||
- інтегрується з PDP/PEP/Registry/NATS,
|
||||
- виконує волю резидентів DAO,
|
||||
- є однією з найважливіших служб у системі.
|
||||
|
||||
Це — **архітектурне серце управління DAARION OS**.
|
||||
|
||||
---
|
||||
|
||||
**Версія:** 1.0
|
||||
**Останнє оновлення:** 2024-11-14
|
||||
|
||||
|
||||
Reference in New Issue
Block a user