docs: add ENERGYUNION District Protocol + Nodes Interface Architecture UPDATE

- ENERGYUNION: DePIN/Energy/Compute District with Helion & Energia agents
- Nodes UPDATE: Unified node model (physical object + local brain + DAIS agent)
- No auto-created nodes - all nodes registered dynamically

docs/foundation/ENERGYUNION_District_Protocol_v1.md

@@ -0,0 +1,285 @@
+# ENERGY UNION — DISTRICT PROTOCOL v1
+
+DePIN • Energy Grid • Compute Grid • AI District of DAARION.city  
+Version: 1.1  
+Status: Active  
+Lead Agent: Helion  
+Energy Agent: Energia  
+
+---
+
+# 1. МЕТА ТА МІСІЯ
+
+Energy Union — це інженерно-науковий District у DAARION.city, який об'єднує:
+
+- децентралізовані енергетичні об'єкти (зелена генерація),
+- децентралізовані обчислювальні модулі,
+- автономні AI-лабораторії,
+- climate-positive інфраструктуру.
+
+Місія District:
+
+- створення відновлюваної енергетично-обчислювальної мережі,
+- підтримка наукових AI-комп'ютинг-процесів,
+- формування DePIN-економіки участі,
+- забезпечення міста DAARION багаторівневими ресурсами.
+
+---
+
+# 2. МОДЕЛЬ ПЛАТФОРМИ (DePIN + Energy + Compute)
+
+## 2.1. Компоненти District
+
+- **Energy Grid Layer**  
+  Зелена генерація (BioMiner та інші установки), датчики, телеметрія.
+
+- **Compute Layer**  
+  Обчислювальні потужності різних учасників та AI-лабораторій.
+
+- **DePIN Layer**  
+  Фізичні ресурси, що належать учасникам і реєструються децентралізовано.
+
+- **AI Compute Layer**  
+  Три реальні лабораторії District:  
+  - PhysMath1.0 — фізика/математика;  
+  - Alatheia — аналіз знань;  
+  - DAARQode — інженерія моделей.
+
+- **Resource Sharing Layer**  
+  Спільний доступ до енергетичних та обчислювальних ресурсів.
+
+---
+
+# 3. КЛЮЧОВІ СУБ'ЄКТИ
+
+## 3.1 District Agents
+
+### Helion (District Lead)
+
+- маршрутизація запитів,
+- реєстрація нод,
+- контроль SLA та режимів.
+
+### Energia (Energy Agent)
+
+- обробка телеметрії від енергетичних вузлів,
+- аналітика потужностей,
+- координація енергетичних ресурсів.
+
+## 3.2 Participants
+
+- постачальники енергії (власники BioMiner або інших установок),
+- оператори обчислювальних модулів,
+- науково-дослідні групи,
+- сервісні агенти District,
+- користувачі AI-лабораторій.
+
+---
+
+# 4. ПРОДУКТИ ТА МОЖЛИВОСТІ DISTRICT
+
+## 4.1 Energy Module
+
+- облік енергії в одиницях **kWt**,
+- енергопрофілі,
+- telemetry stream від фізичних об'єктів.
+
+## 4.2 Compute Module
+
+- облік compute в одиницях **1T**,
+- запуск AI-процесів у PhysMath1.0, Alatheia, DAARQode.
+
+## 4.3 Climate Module
+
+- **carbon+** — одиниця кліматичної ефективності.
+
+## 4.4 Node Participation Module
+
+- реєстрація фізичних енергетичних/compute-об'єктів,
+- формування capability-профілю.
+
+## 4.5 AI Operations Module
+
+- планування обчислень,
+- маршрутизація AI-лабораторій,
+- аналіз навантаження.
+
+---
+
+# 5. DATA MODEL
+
+| Entity | Опис |
+|--------|-------|
+| EnergyUnit | kWt одиниця енергії |
+| ComputeUnit | 1T одиниця обчислень |
+| CarbonUnit | climate-positive одиниця |
+| Provider | учасник, що надає ресурс |
+| Consumer | учасник, що отримує ресурс |
+| Session | взаємодія учасника з сервісом |
+| Allocation | виділення compute/energy |
+| Job | AI/compute процес |
+| ResourceProfile | потужності ноди |
+| TelemetryRecord | телеметрія з пристрою |
+| SLA | статус доступності |
+
+---
+
+# 6. НОДА У ENERGY UNION  
+
+**(Загальний принцип — без вигаданих ID чи назв)**
+
+Нода в Energy Union =  
+**фізичний об'єкт (енергетичний або обчислювальний) + локальний комп'ютер ("мозок") + DAIS-агент + запис у таблиці `nodes`**.
+
+## 6.1. Типи нод
+
+- `energy` — енергетична установка з IoT-датчиками;  
+- `compute` — обчислювальна станція;  
+- `hybrid` — енергія + compute в одному місці;  
+- `iot_gateway` — шлюз сенсорів.
+
+## 6.2. Capability-профілі
+
+- для energy: `{ max_kWt, sensors[], telemetry_mode }`
+- для compute: `{ gpu_vram, cpu_cores, ram, storage }`
+
+## 6.3. Правило реєстрації
+
+> Нода з'являється в системі тільки після фактичного приєднання фізичного об'єкта через `/nodes/register`.
+
+---
+
+# 7. AI АГЕНТИ ENERGY UNION
+
+## 7.1 AI Energy Scheduler
+
+- оптимізація розподілу енергії,
+- обробка kWt-профілів.
+
+## 7.2 AI Compute Allocator
+
+- розподіл compute-потужностей 1T,
+- пріоритезація задач.
+
+## 7.3 AI Load Balancer
+
+- балансування навантажень,
+- контроль SLA.
+
+## 7.4 AI Monitoring Agent
+
+- контроль телеметрії,
+- anomaly detection.
+
+## 7.5 AI Failure Recovery Agent
+
+- реагування на інциденти,
+- пропозиції сценаріїв перемикання.
+
+## 7.6 AI Lab Router
+
+- маршрутизація задач PhysMath1.0, Alatheia, DAARQode.
+
+---
+
+# 8. GOVERNANCE
+
+## 8.1 Повноваження Helion
+
+- управління всіма District-процесами,
+- модерація Room Layer,
+- участь у рішенні City Governance.
+
+## 8.2 Права учасників
+
+- членство через DAIS identity,
+- доступ до District Rooms,
+- можливість запускати compute/AI задачі.
+
+## 8.3 Revocation
+
+- ноди/агенти можуть бути відключені при порушенні протоколів.
+
+---
+
+# 9. ROOM SYSTEM
+
+- `energyunion-lobby`
+- `energyunion-news`
+- `energyunion-help`
+- `energyunion-telemetry`
+- `energyunion-compute`
+- `energyunion-labs`
+- `energyunion-providers`
+- `energyunion-governance`
+
+---
+
+# 10. DISTRICT MAP
+
+Мапа містить **логічні зони** (без фізичних нод):
+
+- Energy Zone  
+- Compute Zone  
+- Labs Zone  
+- Providers Zone  
+- Telemetry Zone  
+- DAO Zone
+
+Фізичні точки з'являються тільки після реальної реєстрації нод.
+
+---
+
+# 11. SECURITY & DAIS
+
+- кожна нода має свій DAIS-агент,  
+- всі операції підписуються DAIS-ключами,  
+- повна історія в Audit Layer,  
+- інциденти обробляються AI Recovery Agent.
+
+---
+
+# 12. CITY INTEGRATION
+
+- портал у City Square,  
+- публічні Rooms,  
+- District-панель управління,  
+- інтеграція з City Governance через Helion.
+
+---
+
+# 13. MVP SCOPE
+
+## Входить до MVP:
+
+- Реєстрація District ENERGYUNION
+- Portal у City Square
+- District Rooms (8 базових)
+- Helion Agent (базова логіка)
+- Energia Agent (телеметрія)
+- Energy Module (kWt облік)
+- Compute Module (1T облік)
+- Node Participation (реєстрація)
+
+## Не входить до MVP:
+
+- Повна AI-оптимізація енергії
+- ML-балансування навантажень
+- Carbon+ токеноміка
+- Автоматичний failover
+- Multi-lab orchestration
+
+---
+
+# 14. Cross-References
+
+- **DAARION_Ontology_Core_v1.md** — базова онтологія
+- **District_Interface_Architecture_v1.md** — архітектура District UI
+- **Agent_Governance_Protocol_v1.md** — права та ролі агентів
+- **DAIS_Layer_Architecture_v1.md** — система ідентичності
+- **Nodes_Interface_Architecture_UPDATE_v1.md** — модель нод
+
+---
+
+**Document Status:** ✅ Ready for Implementation
+

docs/foundation/Nodes_Interface_Architecture_UPDATE_v1.md

@@ -0,0 +1,316 @@
+# 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`  
+
+---
+
+# 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
+