microdao-daarion/docs/foundation/microdao_Data_Model_UPDATE_v1.md

# microdao_Data_Model_UPDATE_v1.md

## microDAO — Data Model Update (Foundation Layer)

**Version:** 1.0  
**Status:** Non-Breaking Schema Extension  
**Scope:** agents, microdaos, nodes, assignments, capabilities, metadata

---

# 0. Мета документа

Цей документ визначає оновлену модель даних microDAO, яка:

* формалізує онтологію DAARION (Agent → MicroDAO → Node → District),
* вводить нові інваріанти,
* додає нові сутності та поля,
* стандартизує JSON-поля `capabilities` і `metadata`,
* додає шар Assignment для агента, який працює в інших MicroDAO,
* залишається сумісною з існуючою системою (non-breaking).

---

# 1. Загальна структура моделі

Оновлена модель складається з п’яти головних сутностей:

1. `agents` (оновлено)
2. `microdaos` (оновлено)
3. `nodes` (оновлено)
4. `agent_assignments` (нова таблиця)
5. `event_log` / outbox (оновлено відповідно до подій)

Усі ці сутності підтримують фундаментальну онтологію DAARION.

---

# 2. Таблиця `agents` (оновлена)

Призначення: зберігати всіх агентів міста — персональних, сервісних, інфраструктурних, core-city, orchestrator.

## 2.1. Поля

```sql
agents (
  id text primary key,
  dais_identity_id text not null,

  -- базова приписка
  home_microdao_id text not null references microdaos(id),
  home_node_id text null references nodes(id),

  -- роль агента
  role text not null check (role in ('regular','orchestrator')),

  -- тип діяльності (розширений шар)
  service_scope text null 
    check (service_scope in ('microdao','district','city')),

  metadata jsonb not null default '{}'::jsonb,
  created_at timestamptz not null default now()
);
```

## 2.2. Опис ключових полів

* `home_microdao_id` — база агента (жорсткий інваріант).
* `home_node_id` — нода, на якій живе агент (може бути null).
* `role` — `regular` або `orchestrator`.
* `service_scope` — `microdao`, `district`, `city`.
* `metadata` — додаткові параметри (аватар, worker-конфіги, теги тощо).

---

# 3. Таблиця `microdaos` (оновлена)

Призначення: зберігати root, standard, district MicroDAO.

## 3.1. Поля

```sql
microdaos (
  id text primary key,

  type text not null
    check (type in ('root','standard','district')),

  primary_orchestrator_agent_id text not null 
    references agents(id),

  parent_microdao_id text null references microdaos(id),

  wallet_address text null,
  metadata jsonb not null default '{}'::jsonb,
  created_at timestamptz not null default now()
);
```

## 3.2. Інваріанти

* MicroDAO не може існувати без `primary_orchestrator_agent_id`.
* `type='root'` зарезервовано для DAARION.
* `type='district'` дає розширені можливості.
* МікроДАО можуть формувати дерево через `parent_microdao_id`.

---

# 4. Таблиця `nodes` (оновлена)

Призначення: зберігати фізичні / логічні вузли виконання DAGI Mesh.

## 4.1. Поля

```sql
nodes (
  id text primary key,

  microdao_id text not null references microdaos(id),

  node_kind text not null
    check (node_kind in (
      'smartphone','laptop','edge','datacenter',
      'iot','gpu-cluster'
    )),

  capabilities jsonb not null default '{}'::jsonb,

  status text not null
    check (status in ('provisioning','active','draining','retired')),

  metadata jsonb not null default '{}'::jsonb,
  created_at timestamptz not null default now()
);
```

## 4.2. Інваріанти

* Node завжди належить конкретній MicroDAO.
* Node — реальний пристрій (не абстракція).
* При створенні ноди генерується подія `node.registered`.

---

# 5. Таблиця `agent_assignments` (нова)

Призначення: описує, де агент працює (service layer), не змінюючи приписку.

## 5.1. Поля

```sql
agent_assignments (
  id uuid primary key,

  agent_id text not null references agents(id),
  target_microdao_id text not null references microdaos(id),

  scope text not null 
    check (scope in ('microdao','district','city')),

  role text not null,  -- advisor/security/mentor/ops/core-team

  start_ts timestamptz not null default now(),
  end_ts timestamptz null,

  metadata jsonb not null default '{}'::jsonb
);
```

## 5.2. Інваріанти

* Assignment не змінює `home_microdao_id`.
* DAARION108 мають assignments з `scope='city'`.
* Service/Infrastructure агенти можуть мати кілька assignments.

---

# 6. JSON-структури

## 6.1. `capabilities.json`

```json
{
  "cpu": "8 cores",
  "ram": "32GB",
  "gpu": {
    "model": "RTX 4090",
    "vram": "24GB"
  },
  "network": {
    "up": "1Gbps",
    "down": "1Gbps"
  },
  "sensors": ["camera","lidar","temperature"]
}
```

## 6.2. `metadata.json`

```json
{
  "version": "1.0.0",
  "agent_type": "service",
  "citywide": true,
  "labels": ["core","secure","production"],
  "notes": "This agent is part of DAARION108"
}
```

---

# 7. Події (пов’язані з моделлю)

* `agent.promoted_to_orchestrator`
* `microdao.created`
* `node.registered`
* `microdao.promoted_to_district`
* `agent.assignment_created`
* `agent.assignment_ended`

Їхні схеми визначені в `microdao_Event_Catalog_EXTENDED_v1.md`.

---

# 8. Міграції (чорновий план)

* додати поля до `agents`;
* додати поля до `microdaos`;
* оновити `nodes`;
* створити `agent_assignments`;
* додати enum-типи (за потреби).

---

# 9. Підсумок

Модель даних тепер повністю відповідає фундаментальній онтології DAARION.  
Усі інваріанти формалізовані, Assignment layer додано, структури capabilities/metadata стандартизовано.  
Документ готовий до реалізації міграцій та оновлень у коді.