microdao-daarion/docs/foundation/Nodes_Interface_Architecture_UPDATE_v1.md

Nodes Interface Architecture — UPDATE v1

DAARION.city Unified Node Model
Version: 1.1

---

1. Визначення НОДИ

Нода = фізичний об'єкт + локальний обчислювальний модуль + DAIS-агент + запис у таблиці nodes.

Нода не існує "віртуально".
Вона з'являється тільки після фактичного приєднання фізичного пристрою.

---

2. Компоненти НОДИ

2.1. Фізичний об'єкт ("ресурс")

• енергетична установка,
• обчислювальний сервер,
• IoT-станція,
• мікрокомп'ютер або смартфон,
• будь-яка реальна точка у світі.

2.2. Локальний мозок

Обов'язково існує хоча б один пристрій, здатний:

• запускати агента,
• передавати телеметрію,
• встановлювати з'єднання з DAARION,
• керувати локальним обладнанням.

Це може бути:

• ноутбук,
• міні-ПК,
• сервер,
• смартфон,
• Raspberry Pi.

2.3. DAIS-агент

Кожна нода має свого:

• dais_id
• wallet
• public_key
• role: node_agent

Це і є "особистість" ноди, можливість підписувати операції.

2.4. Запис у таблиці nodes

У БД фіксується:

• node_id
• owner_microdao_id
• node_agent_id
• kind
• capabilities
• status
• registered_at

2.5. Node Profile — Core Invariants (PATCH v1)

Кожна нода в DAARION Ontology має чотири обов'язкові шари:

1. Metrics Layer — live-метрики CPU/GPU/RAM/Disk + heartbeat. Навіть якщо телеметрія частково відсутня, нода переходить у metrics_status = degraded, а не існує “порожньою”.
2. Ownership Layer — власник (MicroDAO/District) з полями owner_microdao_id, owner_microdao_slug (опційно district_id). Немає безхазяйних нод.
3. Models Layer — локальний Swapper + набір моделей (LLM, STT, vision, TTS, RAG). Dev-ноди так само мають DAGI-стек, просто з іншим складом моделей.
4. Orchestration Layer — локальний DAGI Router + агенти з home_node_id, які працюють на цій ноді.

Також кожна нода має мінімальний набір Node Core Agents:

• Node Guardian Agent — відповідає за health, безпеку, інциденти.
• Node Steward Agent — відповідає за приналежність до microDAO, профіль, онбординг.
• (опційно) Node Models/Swapper Agent — відповідає за опис і політику використання локального стека моделей.

Принцип “немає сторінки без агентів” означає, що будь-який інтерфейс Ноди (профіль, метрики, моделі, доступи) завжди “закріплений” за хоча б одним агентом, і цей агент показується в UI.

---

3. Типи НОД

3.1. Energy Node

Фізична енергетична установка з датчиками.

kind = "energy"

3.2. Compute Node

Фізичний сервер/станція для AI.

kind = "compute"

3.3. Hybrid Node

Енергія + compute.

kind = "hybrid"

3.4. IoT Gateway Node

Для сенсорних мереж.

kind = "iot_gateway"

3.5. Edge Node

Смартфон, ноутбук, міні-ПК.

kind = "edge"

3.6. Datacenter Node

Потужний серверний вузол.

kind = "datacenter"

3.7. GPU Cluster Node

Спеціалізований GPU кластер.

kind = "gpu_cluster"

---

4. Capability-профілі ("можливості")

При реєстрації ноди описуються її можливості:

Приклади:

{
  "energy": { 
    "max_kWt": 8.2, 
    "sensors": ["temp", "co2"], 
    "telemetry": "1m" 
  },
  "compute": { 
    "gpu_vram": "16GB", 
    "cpu_cores": 12, 
    "ram": "64GB",
    "storage": "2TB"
  }
}

Цей профіль створюється самим пристроєм або оператором вручну.

---

5. Правило реєстрації

Нода реєструється тільки тоді, коли фізичний пристрій реально з'єднується з DAARION і викликає /nodes/register.

Жодних автосозданих нод.
Жодних "placeholder-node".

5.1 Процес реєстрації

sequenceDiagram
    participant Device as Physical Device
    participant Brain as Local Brain
    participant API as DAARION API
    participant DB as Database
    
    Device->>Brain: Boot & Initialize
    Brain->>API: POST /nodes/register
    API->>API: Validate DAIS identity
    API->>DB: INSERT INTO nodes
    DB-->>API: node_id
    API-->>Brain: { node_id, status: "registered" }
    Brain->>Device: Configure & Start Services

5.2 Required Fields

Field	Type	Required	Description
owner_microdao_id	UUID	✅	MicroDAO власник
node_agent_id	TEXT	✅	DAIS ID агента ноди
kind	ENUM	✅	Тип ноди
capabilities	JSONB	✅	Можливості
hostname	TEXT	❌	Ім'я хоста
ip_address	TEXT	❌	IP адреса

---

6. Onboarding / Offboarding

6.1 Onboarding

1. Фізичний пристрій підключається до мережі
2. Локальний мозок запускає DAIS-агента
3. Агент отримує DAIS identity (якщо ще немає)
4. Виклик /nodes/register з capability-профілем
5. Нода з'являється в системі
6. District Lead Agent підтверджує (якщо потрібно)

6.2 Offboarding

• власник може відключити ноду через /nodes/{id}/deactivate
• District Lead може заблокувати ноду при порушенні
• City Governance може ревокувати ноду при критичних інцидентах

---

7. Security

• всі операції підписані DAIS-ключами ноди
• ревокація ноди = блокування її DAIS-агента
• телеметрія може бути E2E-шифрована
• кожна нода має свій wallet для мікротранзакцій

7.1 Key Rotation

Ноди повинні періодично оновлювати ключі:

• автоматична ротація кожні 90 днів
• примусова ротація при підозрі компрометації
• старі ключі зберігаються в dais_keys з revoked = true

---

8. Інтеграція з District-протоколами

8.1 MicroDAO

Кожна нода належить певному MicroDAO:

• owner_microdao_id → FK до microdaos
• права управління нодою = права Orchestrator MicroDAO

8.2 District

District Lead (Helion, GREENFOOD ERP, інші) має право:

• реєстрації ноди всередині District
• перевірки capability-профілю
• блокування ноди в разі порушення протоколу
• налаштування SLA вимог

8.3 City

City Governance може:

• переглядати всі ноди міста з роллю city_governance
• блокувати ноди при критичних інцидентах
• встановлювати city-wide policies

---

9. Node Status Lifecycle

registered → online → busy → offline → deactivated
                ↓
            suspended (при порушенні)
                ↓
            revoked (hard block)

Status	Description
registered	Нода зареєстрована, очікує активації
online	Нода активна, готова до роботи
busy	Нода виконує задачу
offline	Нода тимчасово недоступна
suspended	Нода призупинена адміністративно
deactivated	Нода деактивована власником
revoked	Нода заблокована назавжди

---

10. Telemetry Protocol

10.1 Heartbeat

Кожна нода надсилає heartbeat кожні 60 секунд:

{
  "node_id": "...",
  "timestamp": "2025-11-30T12:00:00Z",
  "status": "online",
  "metrics": {
    "cpu_load": 0.45,
    "memory_used": 0.67,
    "disk_free": 0.82
  }
}

10.2 NATS Subjects

• nodes.heartbeat.{node_id} — heartbeat
• nodes.metrics.{node_id} — детальна телеметрія
• nodes.events.{node_id} — події ноди
• nodes.alerts.{node_id} — алерти

---

11. Сумісність

Ця модель однакова для:

• Energy Union — energy/compute/hybrid ноди
• GREENFOOD — warehouse/logistics/iot ноди
• CLAN — edge/compute ноди
• SOUL — personal/edge ноди
• DAARION root DAO — datacenter/gpu_cluster ноди

---

12. Cross-References

• DAARION_Ontology_Core_v1.md — базова онтологія
• DAIS_Layer_Architecture_v1.md — система ідентичності
• Agent_Governance_Protocol_v1.md — права агентів
• ENERGYUNION_District_Protocol_v1.md — протокол Energy Union
• GREENFOOD_District_Protocol_v1.md — протокол GREENFOOD

---

Document Status: ✅ Ready for Implementation