# 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-профілі ("можливості")

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

### Приклади:

```json
{
  "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 Процес реєстрації

```mermaid
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 секунд:

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