Files

Apple c552199eed 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

2025-11-15 04:08:35 -08:00

10 KiB

Raw Blame History

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

Основний принцип:

AI Governance Agent — це механічний виконавець волі DAO.

Він сам не генерує політик, а лише обробляє та застосовує.

3. Governance Proposal Lifecycle

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.

Приклад:

{
  "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

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.

Приклад:

min_quorum = 10% від circulating_supply
approval_required = 51%

Після дедлайну:

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

Алгоритм:

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 конфіг ентитлментів:

{
  "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 публікує:

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,
доступні для перегляду через:

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:

Increase Premium compute quotas by 25%

Operations:

[
  { "op": "increase_quota", "metric": "agent_runs_per_day", "value": 250 },
  { "op": "increase_quota", "metric": "llm_tokens_per_month", "value": 500000 }
]

Governance Agent process:

validate structure → OK
validate quotas do not exceed global max → OK
check plan hierarchy → OK
commit changes → DB updated
publish policy.updated
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

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

10 KiB Raw Blame History Unescape Escape