From c552199eeddcb25579b0d072b2ab98ad0be268c2 Mon Sep 17 00:00:00 2001 From: Apple Date: Sat, 15 Nov 2025 04:08:35 -0800 Subject: [PATCH] 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 --- .cursorrules | 17 + GITHUB_SETUP.md | 207 + GIT_PUSH_INSTRUCTIONS.md | 146 + GIT_SETUP.md | 108 + HOW_TO_REFERENCE.md | 151 + PROJECT_CONTEXT.md | 211 + PROJECT_INFO.md | 121 + QUICK_GITHUB_SETUP.md | 65 + QUICK_LINK.md | 37 + QUICK_LINK.txt | 6 + QUICK_START.md | 130 + README.md | 122 + SERVER_SETUP_INSTRUCTIONS.md | 115 + START_HERE.md | 77 + STATUS.md | 63 + docs/CONTRIBUTING_DOCS.md | 141 + docs/README.md | 85 + docs/_archive/tokenomics_legacy_v0.md | 19 + docs/agents.md | 540 ++ docs/agents/README.md | 24 + docs/api-mvp.md | 487 ++ docs/api.md | 1164 +++++ docs/core-services-mvp.md | 338 ++ docs/cursor/08_agent_first_onboarding.md | 474 ++ docs/cursor/09_evolutionary_agent.md | 550 ++ docs/cursor/10_agent_ui_system.md | 555 ++ docs/cursor/11_llm_integration.md | 646 +++ docs/cursor/12_agent_runtime_core.md | 706 +++ docs/cursor/13_agent_memory_system.md | 793 +++ docs/cursor/14_messenger_agent_module.md | 589 +++ docs/cursor/15_projects_agent_module.md | 376 ++ docs/cursor/16_followups_reminders_agent.md | 339 ++ docs/cursor/17_comemory_knowledge_space.md | 426 ++ docs/cursor/18_governance_access_agent.md | 404 ++ .../19_notifications_attention_agent.md | 335 ++ docs/cursor/20_integrations_bridges_agent.md | 346 ++ docs/cursor/21_agent_only_interface.md | 654 +++ docs/cursor/22_agent_only_interface_tasks.md | 412 ++ .../22_operator_modes_and_system_agents.md | 384 ++ docs/cursor/23_agent_cards_and_console.md | 556 ++ docs/cursor/23_domains_wallet_dao_deepdive.md | 447 ++ .../24_access_keys_capabilities_system.md | 677 +++ docs/cursor/24_agent_cards_tasks.md | 349 ++ docs/cursor/25_deployment_infrastructure.md | 480 ++ docs/cursor/26_security_audit.md | 452 ++ docs/cursor/27_database_schema_migrations.md | 496 ++ .../28_flows_wallet_embassy_energy_union.md | 356 ++ .../29_scaling_and_high_availability.md | 444 ++ ...tion_and_token_economics_infrastructure.md | 401 ++ ...ce_policies_for_capabilities_and_quotas.md | 516 ++ docs/cursor/32_policy_service_PDP_design.md | 520 ++ .../cursor/33_api_gateway_security_and_pep.md | 537 ++ .../34_internal_services_architecture.md | 679 +++ .../cursor/35_microdao_service_mesh_design.md | 517 ++ ..._agent_runtime_isolation_and_sandboxing.md | 500 ++ ...7_agent_tools_and_plugins_specification.md | 458 ++ ...private_agents_lifecycle_and_management.md | 486 ++ ...e_agent_templates_and_behavior_profiles.md | 482 ++ .../40_rwa_energy_food_water_flow_specs.md | 458 ++ docs/cursor/41_ai_governance_agent_design.md | 471 ++ ...42_nats_event_streams_and_event_catalog.md | 608 +++ .../43_database_events_outbox_design.md | 407 ++ .../44_usage_accounting_and_quota_engine.md | 510 ++ .../45_llm_proxy_and_multimodel_routing.md | 506 ++ docs/cursor/46_router_orchestrator_design.md | 452 ++ ...7_messaging_channels_and_privacy_layers.md | 436 ++ ...ms_access_control_and_confidential_mode.md | 409 ++ docs/cursor/49_wallet_rwa_payouts_claims.md | 395 ++ .../50_daarion_city_website_integration.md | 596 +++ docs/cursor/DAARION_city_integration.md | 403 ++ docs/cursor/DAARION_city_platforms_catalog.md | 397 ++ docs/cursor/DOCX_UPDATE_INSTRUCTIONS.md | 247 + docs/cursor/MISSING_DOCS_ANALYSIS.md | 178 + docs/cursor/MVP_VERTICAL_SLICE.md | 537 ++ docs/cursor/PLAN_MODULES.md | 85 + docs/cursor/README.md | 307 +- docs/daarion/README.md | 25 + docs/daarion/integration-microdao.md | 403 ++ docs/daarion/platforms-catalog.md | 397 ++ docs/daarion/tokenomics-city.md | 393 ++ docs/integration-daarion.md | 358 ++ docs/microdao-admin-console.md | 331 ++ docs/microdao/README.md | 25 + docs/microdao/access-keys-capabilities.md | 677 +++ docs/microdao/architecture.md | 33 + docs/microdao/rbac.md | 409 ++ docs/microdao_project_notes.ipynb | 181 + docs/superdao-federation.md | 299 ++ docs/tokenomics/city-tokenomics.md | 393 ++ index.html | 14 + package-lock.json | 4524 +++++++++++++++++ package.json | 34 + postcss.config.js | 7 + push-to-github.sh | 77 + src/App.tsx | 15 + src/README.md | 96 +- src/api/http/agents.routes.ts | 53 + src/api/http/dao.routes.ts | 78 + src/api/http/pdp.routes.ts | 38 + src/api/http/platforms.routes.ts | 48 + src/api/http/vendor.routes.ts | 52 + src/api/http/wallet.routes.ts | 72 + src/api/middleware/auth.middleware.ts | 39 + src/api/middleware/context.middleware.ts | 18 + src/app.ts | 45 + src/domain/dao/dao.logic.ts | 30 + src/domain/dao/types.ts | 37 + src/domain/pdp/policy.model.ts | 38 + src/domain/user/types.ts | 14 + src/domain/wallet/types.ts | 27 + src/index.css | 24 + src/infra/config/env.ts | 21 + src/infra/db/client.ts | 20 + src/infra/db/dao.repository.ts | 44 + src/infra/logger/logger.ts | 27 + src/main.tsx | 14 + .../dao-factory/dao-factory.service.ts | 109 + src/services/pdp/pdp.service.ts | 100 + src/services/pdp/policies.config.ts | 76 + src/services/registry/registry.service.ts | 47 + src/services/wallet/wallet.adapter.ts | 36 + src/services/wallet/wallet.interface.ts | 15 + src/services/wallet/wallet.service.ts | 61 + supabase/migrations/000001_init.sql | 24 + supabase/migrations/000002_microdao_core.sql | 75 + supabase/migrations/000003_projects_tasks.sql | 37 + supabase/migrations/000004_agents.sql | 34 + .../000005_wallet_staking_payouts.sql | 40 + supabase/migrations/000006_rwa.sql | 18 + supabase/migrations/000007_embassy.sql | 48 + .../000008_access_keys_capabilities.sql | 58 + supabase/migrations/000009_audit_outbox.sql | 32 + supabase/migrations/README.md | 89 + supabase/migrations/seeds.sql | 147 + tailwind.config.js | 18 + tsconfig.json | 30 + tsconfig.node.json | 11 + vite.config.ts | 11 + 138 files changed, 39624 insertions(+), 40 deletions(-) create mode 100644 .cursorrules create mode 100644 GITHUB_SETUP.md create mode 100644 GIT_PUSH_INSTRUCTIONS.md create mode 100644 GIT_SETUP.md create mode 100644 HOW_TO_REFERENCE.md create mode 100644 PROJECT_CONTEXT.md create mode 100644 PROJECT_INFO.md create mode 100644 QUICK_GITHUB_SETUP.md create mode 100644 QUICK_LINK.md create mode 100644 QUICK_LINK.txt create mode 100644 QUICK_START.md create mode 100644 README.md create mode 100644 SERVER_SETUP_INSTRUCTIONS.md create mode 100644 START_HERE.md create mode 100644 STATUS.md create mode 100644 docs/CONTRIBUTING_DOCS.md create mode 100644 docs/README.md create mode 100644 docs/_archive/tokenomics_legacy_v0.md create mode 100644 docs/agents.md create mode 100644 docs/agents/README.md create mode 100644 docs/api-mvp.md create mode 100644 docs/api.md create mode 100644 docs/core-services-mvp.md create mode 100644 docs/cursor/08_agent_first_onboarding.md create mode 100644 docs/cursor/09_evolutionary_agent.md create mode 100644 docs/cursor/10_agent_ui_system.md create mode 100644 docs/cursor/11_llm_integration.md create mode 100644 docs/cursor/12_agent_runtime_core.md create mode 100644 docs/cursor/13_agent_memory_system.md create mode 100644 docs/cursor/14_messenger_agent_module.md create mode 100644 docs/cursor/15_projects_agent_module.md create mode 100644 docs/cursor/16_followups_reminders_agent.md create mode 100644 docs/cursor/17_comemory_knowledge_space.md create mode 100644 docs/cursor/18_governance_access_agent.md create mode 100644 docs/cursor/19_notifications_attention_agent.md create mode 100644 docs/cursor/20_integrations_bridges_agent.md create mode 100644 docs/cursor/21_agent_only_interface.md create mode 100644 docs/cursor/22_agent_only_interface_tasks.md create mode 100644 docs/cursor/22_operator_modes_and_system_agents.md create mode 100644 docs/cursor/23_agent_cards_and_console.md create mode 100644 docs/cursor/23_domains_wallet_dao_deepdive.md create mode 100644 docs/cursor/24_access_keys_capabilities_system.md create mode 100644 docs/cursor/24_agent_cards_tasks.md create mode 100644 docs/cursor/25_deployment_infrastructure.md create mode 100644 docs/cursor/26_security_audit.md create mode 100644 docs/cursor/27_database_schema_migrations.md create mode 100644 docs/cursor/28_flows_wallet_embassy_energy_union.md create mode 100644 docs/cursor/29_scaling_and_high_availability.md create mode 100644 docs/cursor/30_cost_optimization_and_token_economics_infrastructure.md create mode 100644 docs/cursor/31_governance_policies_for_capabilities_and_quotas.md create mode 100644 docs/cursor/32_policy_service_PDP_design.md create mode 100644 docs/cursor/33_api_gateway_security_and_pep.md create mode 100644 docs/cursor/34_internal_services_architecture.md create mode 100644 docs/cursor/35_microdao_service_mesh_design.md create mode 100644 docs/cursor/36_agent_runtime_isolation_and_sandboxing.md create mode 100644 docs/cursor/37_agent_tools_and_plugins_specification.md create mode 100644 docs/cursor/38_private_agents_lifecycle_and_management.md create mode 100644 docs/cursor/39_private_agent_templates_and_behavior_profiles.md create mode 100644 docs/cursor/40_rwa_energy_food_water_flow_specs.md create mode 100644 docs/cursor/41_ai_governance_agent_design.md create mode 100644 docs/cursor/42_nats_event_streams_and_event_catalog.md create mode 100644 docs/cursor/43_database_events_outbox_design.md create mode 100644 docs/cursor/44_usage_accounting_and_quota_engine.md create mode 100644 docs/cursor/45_llm_proxy_and_multimodel_routing.md create mode 100644 docs/cursor/46_router_orchestrator_design.md create mode 100644 docs/cursor/47_messaging_channels_and_privacy_layers.md create mode 100644 docs/cursor/48_teams_access_control_and_confidential_mode.md create mode 100644 docs/cursor/49_wallet_rwa_payouts_claims.md create mode 100644 docs/cursor/50_daarion_city_website_integration.md create mode 100644 docs/cursor/DAARION_city_integration.md create mode 100644 docs/cursor/DAARION_city_platforms_catalog.md create mode 100644 docs/cursor/DOCX_UPDATE_INSTRUCTIONS.md create mode 100644 docs/cursor/MISSING_DOCS_ANALYSIS.md create mode 100644 docs/cursor/MVP_VERTICAL_SLICE.md create mode 100644 docs/cursor/PLAN_MODULES.md create mode 100644 docs/daarion/README.md create mode 100644 docs/daarion/integration-microdao.md create mode 100644 docs/daarion/platforms-catalog.md create mode 100644 docs/daarion/tokenomics-city.md create mode 100644 docs/integration-daarion.md create mode 100644 docs/microdao-admin-console.md create mode 100644 docs/microdao/README.md create mode 100644 docs/microdao/access-keys-capabilities.md create mode 100644 docs/microdao/architecture.md create mode 100644 docs/microdao/rbac.md create mode 100644 docs/microdao_project_notes.ipynb create mode 100644 docs/superdao-federation.md create mode 100644 docs/tokenomics/city-tokenomics.md create mode 100644 index.html create mode 100644 package-lock.json create mode 100644 package.json create mode 100644 postcss.config.js create mode 100755 push-to-github.sh create mode 100644 src/App.tsx create mode 100644 src/api/http/agents.routes.ts create mode 100644 src/api/http/dao.routes.ts create mode 100644 src/api/http/pdp.routes.ts create mode 100644 src/api/http/platforms.routes.ts create mode 100644 src/api/http/vendor.routes.ts create mode 100644 src/api/http/wallet.routes.ts create mode 100644 src/api/middleware/auth.middleware.ts create mode 100644 src/api/middleware/context.middleware.ts create mode 100644 src/app.ts create mode 100644 src/domain/dao/dao.logic.ts create mode 100644 src/domain/dao/types.ts create mode 100644 src/domain/pdp/policy.model.ts create mode 100644 src/domain/user/types.ts create mode 100644 src/domain/wallet/types.ts create mode 100644 src/index.css create mode 100644 src/infra/config/env.ts create mode 100644 src/infra/db/client.ts create mode 100644 src/infra/db/dao.repository.ts create mode 100644 src/infra/logger/logger.ts create mode 100644 src/main.tsx create mode 100644 src/services/dao-factory/dao-factory.service.ts create mode 100644 src/services/pdp/pdp.service.ts create mode 100644 src/services/pdp/policies.config.ts create mode 100644 src/services/registry/registry.service.ts create mode 100644 src/services/wallet/wallet.adapter.ts create mode 100644 src/services/wallet/wallet.interface.ts create mode 100644 src/services/wallet/wallet.service.ts create mode 100644 supabase/migrations/000001_init.sql create mode 100644 supabase/migrations/000002_microdao_core.sql create mode 100644 supabase/migrations/000003_projects_tasks.sql create mode 100644 supabase/migrations/000004_agents.sql create mode 100644 supabase/migrations/000005_wallet_staking_payouts.sql create mode 100644 supabase/migrations/000006_rwa.sql create mode 100644 supabase/migrations/000007_embassy.sql create mode 100644 supabase/migrations/000008_access_keys_capabilities.sql create mode 100644 supabase/migrations/000009_audit_outbox.sql create mode 100644 supabase/migrations/README.md create mode 100644 supabase/migrations/seeds.sql create mode 100644 tailwind.config.js create mode 100644 tsconfig.json create mode 100644 tsconfig.node.json create mode 100644 vite.config.ts diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 00000000..6edd5faf --- /dev/null +++ b/.cursorrules @@ -0,0 +1,17 @@ +# MicroDAO MVP - Cursor Rules + +## Проєкт +- Шлях: /Users/apple/Desktop/MicroDAO/MicroDAO 3 +- Документація: docs/cursor/ +- Швидкий контекст: PROJECT_CONTEXT.md + +## Стандарти +- Дотримуватися docs/cursor/05_coding_standards.md +- Використовувати типи з docs/cursor/03_api_core_snapshot.md +- UI тексти з docs/cursor/04_ui_ux_onboarding_chat.md + +## Структура +- React 18 + TypeScript + Vite +- Tailwind CSS для стилів +- React Query для state +- API: https://api.microdao.xyz/v1 diff --git a/GITHUB_SETUP.md b/GITHUB_SETUP.md new file mode 100644 index 00000000..a02dd73c --- /dev/null +++ b/GITHUB_SETUP.md @@ -0,0 +1,207 @@ +# Налаштування GitHub для автоматичної роботи + +Цей документ описує, як налаштувати доступ до GitHub, щоб Cursor AI міг працювати з твоїми репозиторіями. + +## Варіант 1: SSH ключі (рекомендовано) + +### Крок 1: Перевірка наявних SSH ключів + +```bash +ls -la ~/.ssh +``` + +Шукай файли `id_rsa`, `id_ed25519` або подібні. + +### Крок 2: Створення нового SSH ключа (якщо немає) + +```bash +ssh-keygen -t ed25519 -C "your_email@example.com" +``` + +Натисни Enter для використання стандартного шляху (`~/.ssh/id_ed25519`). +Можеш ввести пароль або залишити порожнім (менш безпечно, але зручніше). + +### Крок 3: Додавання SSH ключа до ssh-agent + +```bash +eval "$(ssh-agent -s)" +ssh-add ~/.ssh/id_ed25519 +``` + +### Крок 4: Копіювання публічного ключа + +```bash +cat ~/.ssh/id_ed25519.pub +``` + +Скопіюй весь вивід (починається з `ssh-ed25519 ...`). + +### Крок 5: Додавання ключа на GitHub + +1. Відкрий https://github.com/settings/keys +2. Натисни **"New SSH key"** +3. **Title:** наприклад, "MacBook Pro - Cursor AI" +4. **Key:** встав скопійований публічний ключ +5. Натисни **"Add SSH key"** + +### Крок 6: Перевірка підключення + +```bash +ssh -T git@github.com +``` + +Маєш побачити: +``` +Hi username! You've successfully authenticated, but GitHub does not provide shell access. +``` + +--- + +## Варіант 2: Personal Access Token (альтернатива) + +Якщо SSH не працює, використовуй HTTPS з токеном. + +### Крок 1: Створення Personal Access Token + +1. Відкрий https://github.com/settings/tokens +2. Натисни **"Generate new token"** → **"Generate new token (classic)"** +3. **Note:** "Cursor AI - MicroDAO Project" +4. **Expiration:** вибери термін (або "No expiration" для постійного доступу) +5. **Scopes:** обери: + - ✅ `repo` (повний доступ до репозиторіїв) + - ✅ `workflow` (якщо потрібні GitHub Actions) +6. Натисни **"Generate token"** +7. **ВАЖЛИВО:** Скопіюй токен одразу (він показується тільки один раз!) + +### Крок 2: Збереження токену + +```bash +# Додай токен до git config (локально для цього проєкту) +cd "/Users/apple/Desktop/MicroDAO/MicroDAO 3" +git config credential.helper store +``` + +При першому `git push` введи: +- **Username:** твій GitHub username +- **Password:** встав токен (не пароль!) + +Або створи файл `~/.git-credentials`: +``` +https://YOUR_TOKEN@github.com +``` + +--- + +## Створення репозиторію на GitHub + +### Варіант A: Через веб-інтерфейс (найпростіше) + +1. Відкрий https://github.com/new +2. **Repository name:** `microdao-daarion` або `dagi-stack` +3. **Description:** "MicroDAO & DAARION.city - Agent-based community platform" +4. **Visibility:** Private або Public (на твій вибір) +5. **НЕ** стави галочки на "Initialize with README" (у нас вже є файли) +6. Натисни **"Create repository"** + +### Варіант B: Через GitHub CLI (якщо встановлено) + +```bash +gh repo create microdao-daarion --private --source=. --remote=origin --push +``` + +--- + +## Підготовка проєкту до push + +### Крок 1: Додавання всіх файлів + +```bash +cd "/Users/apple/Desktop/MicroDAO/MicroDAO 3" +git add . +``` + +### Крок 2: Коміт + +```bash +git commit -m "chore: organize documentation and prepare for GitHub + +- Create /docs structure (microdao, daarion, agents) +- Organize 61 cursor docs +- Add README files for each category +- Copy key documents to public categories +- Add setup instructions" +``` + +### Крок 3: Додавання remote + +**Для SSH:** +```bash +git remote add origin git@github.com:YOUR_USERNAME/microdao-daarion.git +``` + +**Для HTTPS:** +```bash +git remote add origin https://github.com/YOUR_USERNAME/microdao-daarion.git +``` + +### Крок 4: Push + +```bash +git branch -M main +git push -u origin main +``` + +--- + +## Автоматизація для Cursor AI + +Після налаштування SSH або токену, я зможу: + +1. ✅ Клонувати репозиторії +2. ✅ Створювати нові гілки +3. ✅ Робити коміти та push +4. ✅ Створювати pull requests (через GitHub CLI або API) + +### Перевірка доступу + +Після налаштування, я можу виконати: + +```bash +git remote -v # перевірити remote +git push origin main # протестувати push +``` + +--- + +## Troubleshooting + +### Помилка: "Permission denied (publickey)" + +1. Перевір, чи додано ключ на GitHub +2. Перевір, чи ключ додано до ssh-agent: + ```bash + ssh-add -l + ``` +3. Якщо немає, додай: + ```bash + ssh-add ~/.ssh/id_ed25519 + ``` + +### Помилка: "remote origin already exists" + +```bash +git remote remove origin +git remote add origin git@github.com:YOUR_USERNAME/microdao-daarion.git +``` + +### Помилка: "failed to push some refs" + +```bash +git pull origin main --allow-unrelated-histories +git push -u origin main +``` + +--- + +**Останнє оновлення:** 2024-11-14 + diff --git a/GIT_PUSH_INSTRUCTIONS.md b/GIT_PUSH_INSTRUCTIONS.md new file mode 100644 index 00000000..2ce33e57 --- /dev/null +++ b/GIT_PUSH_INSTRUCTIONS.md @@ -0,0 +1,146 @@ +# Інструкції для Git Push + +Цей документ описує, як завантажити документацію та код у GitHub репозиторій. + +## Передумови + +1. GitHub репозиторій створено (наприклад: `daarion/dagi-stack` або `daarion/microdao-daarion-docs`) +2. SSH ключ налаштовано для GitHub (або використовуєш HTTPS з токеном) + +## Крок 1: Перевірка поточного стану + +```bash +cd "/Users/apple/Desktop/MicroDAO/MicroDAO 3" +git status +``` + +## Крок 2: Додавання файлів + +### Варіант A: Додати все (рекомендовано для першого коміту) + +```bash +git add . +``` + +### Варіант B: Додати тільки документацію + +```bash +git add docs/ +git add .gitignore +git add README.md +git add PROJECT_CONTEXT.md +``` + +## Крок 3: Коміт + +```bash +git commit -m "chore: organize documentation structure for monorepo + +- Create /docs structure (microdao, daarion, agents) +- Organize 61 cursor docs +- Add README files for each category +- Copy key documents to public categories" +``` + +## Крок 4: Налаштування remote (якщо ще не налаштовано) + +### Для SSH: +```bash +git remote add origin git@github.com:daarion/dagi-stack.git +``` + +### Для HTTPS: +```bash +git remote add origin https://github.com/daarion/dagi-stack.git +``` + +### Перевірка remote: +```bash +git remote -v +``` + +## Крок 5: Push у GitHub + +```bash +git branch -M main +git push -u origin main +``` + +Якщо виникають конфлікти або remote вже існує: +```bash +git pull origin main --allow-unrelated-histories +git push -u origin main +``` + +## Структура після push + +``` +daarion/dagi-stack/ +├── docs/ +│ ├── microdao/ # MicroDAO документація +│ │ ├── README.md +│ │ ├── architecture.md +│ │ ├── rbac.md +│ │ └── access-keys-capabilities.md +│ ├── daarion/ # DAARION.city документація +│ │ ├── README.md +│ │ ├── integration-microdao.md +│ │ ├── platforms-catalog.md +│ │ └── tokenomics-city.md +│ ├── agents/ # Агентська система +│ │ └── README.md +│ ├── cursor/ # Технічна документація (61 документ) +│ │ └── [61 файлів] +│ ├── tokenomics/ # Токеноміка +│ └── README.md # Головний README +├── src/ # Код проєкту +├── package.json +└── README.md +``` + +## Наступні кроки + +### На сервері (після push у GitHub) + +```bash +cd /opt +sudo git clone git@github.com:daarion/dagi-stack.git +# або +sudo git clone https://github.com/daarion/dagi-stack.git + +cd dagi-stack +``` + +### Оновлення на сервері (коли є нові зміни) + +```bash +cd /opt/dagi-stack +sudo git pull origin main +``` + +## Troubleshooting + +### Помилка: "remote origin already exists" +```bash +git remote remove origin +git remote add origin git@github.com:daarion/dagi-stack.git +``` + +### Помилка: "failed to push some refs" +```bash +git pull origin main --rebase +git push -u origin main +``` + +### Помилка: "permission denied" +Перевір SSH ключ: +```bash +ssh -T git@github.com +``` + +Або використовуй HTTPS з Personal Access Token. + +--- + +**Останнє оновлення:** 2024-11-14 + diff --git a/GIT_SETUP.md b/GIT_SETUP.md new file mode 100644 index 00000000..3c4774f5 --- /dev/null +++ b/GIT_SETUP.md @@ -0,0 +1,108 @@ +# Налаштування Git для MicroDAO + +## ✅ Що вже зроблено + +- ✅ Git репозиторій ініціалізовано +- ✅ `.gitignore` створено +- ✅ Перший коміт зроблено (58 файлів) + +## 📤 Підключення до віддаленого репозиторію + +### Варіант 1: GitHub + +1. Створіть новий репозиторій на GitHub (https://github.com/new) + - Назва: `microdao-mvp` (або інша) + - Тип: Private або Public + - НЕ створюйте README, .gitignore або license (вони вже є) + +2. Підключіть віддалений репозиторій: + +```bash +cd "/Users/apple/Desktop/MicroDAO/MicroDAO 3" + +# Додайте віддалений репозиторій (замініть YOUR_USERNAME та REPO_NAME) +git remote add origin https://github.com/YOUR_USERNAME/REPO_NAME.git + +# Або через SSH (якщо налаштовано): +# git remote add origin git@github.com:YOUR_USERNAME/REPO_NAME.git + +# Перевірте підключення: +git remote -v + +# Відправте код: +git push -u origin main +``` + +### Варіант 2: GitLab + +```bash +cd "/Users/apple/Desktop/MicroDAO/MicroDAO 3" + +git remote add origin https://gitlab.com/YOUR_USERNAME/REPO_NAME.git +git push -u origin main +``` + +### Варіант 3: Інший Git сервер + +```bash +cd "/Users/apple/Desktop/MicroDAO/MicroDAO 3" + +git remote add origin YOUR_GIT_URL +git push -u origin main +``` + +## 🔐 Автентифікація + +### Для HTTPS: +- GitHub: використовуйте Personal Access Token замість пароля +- GitLab: використовуйте Personal Access Token + +### Для SSH: +Переконайтеся, що ваш SSH ключ додано до GitHub/GitLab: +```bash +# Перевірка SSH ключа +ssh -T git@github.com +# або +ssh -T git@gitlab.com +``` + +## 📝 Налаштування Git (якщо потрібно) + +```bash +# Встановіть ваше ім'я та email +git config --global user.name "Ваше Ім'я" +git config --global user.email "your.email@example.com" +``` + +## 🔄 Подальші коміти + +Після підключення до віддаленого репозиторію: + +```bash +# Додати зміни +git add . + +# Зробити коміт +git commit -m "Опис змін" + +# Відправити на сервер +git push +``` + +## 📊 Перевірка статусу + +```bash +# Статус репозиторію +git status + +# Історія комітів +git log --oneline + +# Віддалені репозиторії +git remote -v +``` + +--- + +**Примітка:** Я не можу виконувати `git push` безпосередньо, оскільки для цього потрібна ваша автентифікація. Виконайте команди вище вручну після створення репозиторію на GitHub/GitLab. + diff --git a/HOW_TO_REFERENCE.md b/HOW_TO_REFERENCE.md new file mode 100644 index 00000000..4dad0b25 --- /dev/null +++ b/HOW_TO_REFERENCE.md @@ -0,0 +1,151 @@ +# 🔗 Як посилатись на проєкт microDAO2 + +**Швидкий гайд для посилань в чатах та Cursor** + +--- + +## 📍 Швидке посилання (копіюй це) + +### Для Cursor / AI чатів + +``` +Проєкт: microDAO2 +Шлях: /Users/apple/Desktop/MicroDAO/MicroDAO 3 +Документація: docs/cursor/ (31 документ) +``` + +### Коротка версія + +``` +microDAO2: /Users/apple/Desktop/MicroDAO/MicroDAO 3 +``` + +--- + +## 🎯 Що завжди вказувати + +### 1. Повний шлях до проєкту +``` +/Users/apple/Desktop/MicroDAO/MicroDAO 3 +``` + +### 2. Де документація +``` +docs/cursor/ - 17+ документів для Cursor +``` + +### 3. Ключові файли +``` +PROJECT_CONTEXT.md - швидкий контекст +README.md - головний README +docs/cursor/README.md - навігація по документації +``` + +--- + +## 💬 Приклади використання в чатах + +### Приклад 1: Швидке посилання +``` +Працюю над проєктом microDAO2: +/Users/apple/Desktop/MicroDAO/MicroDAO 3 + +Документація: docs/cursor/ (31 документ) +``` + +### Приклад 2: З контекстом +``` +Проєкт: microDAO2 +Локація: /Users/apple/Desktop/MicroDAO/MicroDAO 3 +Документація: docs/cursor/ (31 документ) +Статус: Документація готова, починаємо реалізацію MVP +``` + +### Приклад 3: Для Cursor +``` +Додай в контекст: +/Users/apple/Desktop/MicroDAO/MicroDAO 3/docs/cursor/ + +Або конкретний файл: +/Users/apple/Desktop/MicroDAO/MicroDAO 3/docs/cursor/21_agent_only_interface.md +``` + +--- + +## 📂 Структура для швидкого доступу + +### Ключові папки +``` +/Users/apple/Desktop/MicroDAO/MicroDAO 3/ +├── docs/cursor/ # ← Документація для Cursor +├── src/ # ← Код проєкту +└── PROJECT_CONTEXT.md # ← Швидкий контекст +``` + +### Ключові файли +- `PROJECT_CONTEXT.md` - швидкий доступ до всього +- `README.md` - головний README +- `docs/cursor/README.md` - навігація по документації +- `22_agent_only_interface_tasks.md` - поточні задачі + +--- + +## 🚀 Рекомендований порядок роботи + +### Варіант 1: Спочатку документація (рекомендовано) +1. ✅ Завершити всі документи (14-20 з плану) +2. ⏳ Потім почати реалізацію +3. ✅ Переваги: повне розуміння, менше переробок + +### Варіант 2: Паралельно +1. ✅ Базові документи (01-13) - готові +2. ⏳ Реалізувати базові компоненти +3. ⏳ Паралельно додавати документи 14-20 +4. ✅ Переваги: швидший старт, ітеративний підхід + +**Рекомендація:** Варіант 1 - спочатку завершити документацію, потім реалізація. + +--- + +## 📋 Чеклист для нового чату + +Коли починаєш новий чат з Cursor або AI: + +- [ ] Вказати повний шлях: `/Users/apple/Desktop/MicroDAO/MicroDAO 3` +- [ ] Згадати про документацію: `docs/cursor/` +- [ ] Вказати конкретну задачу або документ (якщо є) +- [ ] Додати `PROJECT_CONTEXT.md` в контекст (якщо потрібно) + +--- + +## 🎯 Шаблони промптів + +### Шаблон 1: Загальна задача +``` +Проєкт: /Users/apple/Desktop/MicroDAO/MicroDAO 3 +Документація: docs/cursor/ + +Задача: [опиши задачу] +``` + +### Шаблон 2: Конкретний документ +``` +Використовуй документацію: +/Users/apple/Desktop/MicroDAO/MicroDAO 3/docs/cursor/21_agent_only_interface.md + +Задача: [опиши задачу] +``` + +### Шаблон 3: З контекстом +``` +Проєкт: /Users/apple/Desktop/MicroDAO/MicroDAO 3 +Контекст: PROJECT_CONTEXT.md +Документація: docs/cursor/ + +Задача: [опиши задачу] +``` + +--- + +**Готово!** Тепер ти можеш легко посилатись на проєкт в будь-якому чаті. + diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md new file mode 100644 index 00000000..150142a2 --- /dev/null +++ b/PROJECT_CONTEXT.md @@ -0,0 +1,211 @@ +# 🚀 microDAO2 — Швидкий контекст проєкту + +**Для швидкого посилання в чатах та Cursor** + +--- + +## 📍 Де знаходиться проєкт + +**Повний шлях:** +``` +/Users/apple/Desktop/MicroDAO/MicroDAO 3 +``` + +**Швидкий доступ:** +- Символічне посилання: `~/Desktop/MicroDAO-QuickAccess` +- Spotlight: `⌘ + Space` → "MicroDAO 3" + +--- + +## 📚 Документація для Cursor + +**Основна папка:** +``` +docs/cursor/ +``` + +**Ключові документи:** + +### Фундамент (01-13) +- `00_overview_microdao.md` — Загальний огляд +- `01_product_brief_mvp.md` — Product requirements +- `02_architecture_basics.md` — Технічна архітектура +- `03_api_core_snapshot.md` — API контракти +- `04_ui_ux_onboarding_chat.md` — UI/UX специфікація +- `05_coding_standards.md` — Стандарти кодування +- `06_tasks_onboarding_mvp.md` — Технічні задачі +- `07_testing_checklist_mvp.md` — Тестовий чеклист + +### Агентська система (08-13) +- `08_agent_first_onboarding.md` — Агентський онбординг +- `09_evolutionary_agent.md` — Еволюційний агент +- `10_agent_ui_system.md` — Агентський UI +- `11_llm_integration.md` — Інтеграція LLM +- `12_agent_runtime_core.md` — Agent Runtime Core +- `13_agent_memory_system.md` — Система пам'яті агентів + +### Модулі та інтерфейс (14-24) +- `14_messenger_agent_module.md` — Агент-месенджер +- `15_projects_agent_module.md` — Агент-проєктний менеджер +- `16_followups_reminders_agent.md` — Агент нагадувань та фоллоуапів +- `17_comemory_knowledge_space.md` — Co-Memory та Knowledge Space +- `18_governance_access_agent.md` — Governance & Access Agent +- `19_notifications_attention_agent.md` — Notifications & Attention Agent +- `20_integrations_bridges_agent.md` — Integrations & Bridges Agent +- `21_agent_only_interface.md` — Agent-Only Interface +- `22_operator_modes_and_system_agents.md` — Operator Modes & System Agents +- `22_agent_only_interface_tasks.md` — Задачі для Agent-Only Interface +- `23_domains_wallet_dao_deepdive.md` — Domains, Wallet & DAO Deep Dive +- `23_agent_cards_and_console.md` — Живі картки агентів та Console +- `24_agent_cards_tasks.md` — Задачі для Agent Cards +- `24_access_keys_capabilities_system.md` — Access Keys & Capabilities System + +### DAARION.city та платформи +- `DAARION_city_integration.md` — Інтеграція DAARION.city +- `DAARION_city_platforms_catalog.md` — Каталог платформ DAARION.city + +### Deployment, Infrastructure та Database +- `25_deployment_infrastructure.md` — Deployment процес, середовища, CI/CD, моніторинг +- `26_security_audit.md` — Безпековий чеклист для аудитування +- `27_database_schema_migrations.md` — Повна схема БД та міграції +- `28_flows_wallet_embassy_energy_union.md` — Sequence-діаграми критичних потоків +- `29_scaling_and_high_availability.md` — Масштабування та висока доступність +- `30_cost_optimization_and_token_economics_infrastructure.md` — Оптимізація витрат та токеноміка +- `31_governance_policies_for_capabilities_and_quotas.md` — Політики DAO для управління доступами та квотами +- `32_policy_service_PDP_design.md` — Архітектура Policy Decision Point +- `33_api_gateway_security_and_pep.md` — API Gateway Architecture та Policy Enforcement Point +- `34_internal_services_architecture.md` — Архітектура внутрішніх сервісів (17 сервісів) +- `35_microdao_service_mesh_design.md` — MicroDAO Service Mesh (zero-trust, mTLS, observability) +- `36_agent_runtime_isolation_and_sandboxing.md` — Безпечна ізоляція агентів та sandbox-модель +- `37_agent_tools_and_plugins_specification.md` — Специфікація інструментів та плагінів агентів +- `38_private_agents_lifecycle_and_management.md` — Життєвий цикл приватних агентів +- `39_private_agent_templates_and_behavior_profiles.md` — Шаблони агентів та поведінкові профілі +- `40_rwa_energy_food_water_flow_specs.md` — Потоки RWA (енергія, їжа, вода) +- `41_ai_governance_agent_design.md` — AI Governance Agent (політики, голосування, застосування правил) +- `42_nats_event_streams_and_event_catalog.md` — NATS Event Streams та Event Catalog +- `43_database_events_outbox_design.md` — Outbox Pattern (транзакційна доставка подій) +- `44_usage_accounting_and_quota_engine.md` — Usage Accounting & Quota Engine +- `45_llm_proxy_and_multimodel_routing.md` — LLM Proxy & Multi-Model Routing +- `46_router_orchestrator_design.md` — Router Orchestrator Design +- `47_messaging_channels_and_privacy_layers.md` — Messaging Channels & Privacy Layers +- `48_teams_access_control_and_confidential_mode.md` — Teams Access Control & Confidential Mode +- `49_wallet_rwa_payouts_claims.md` — Wallet, RWA, Payouts & Claims +- `50_daarion_city_website_integration.md` — DAARION.city Website Integration +- `docs/tokenomics/README.md` — Unified Tokenomics for DAARION.city & MicroDAO +- `docs/tokenomics/city-tokenomics.md` — City Tokenomics — DAARION.city +- `docs/integration-daarion.md` — Integration Guide: MicroDAO → DAARION.city +- `docs/agents.md` — Agents Map — DAARION.city (A1-A4 hierarchy) +- `docs/api.md` — API Reference — DAARION.city & MicroDAO (MVP endpoints) + +**Повний список:** `docs/cursor/README.md` + +--- + +## 🗂️ Структура проєкту + +``` +MicroDAO 3/ +├── docs/ +│ ├── cursor/ # Документація для Cursor (17+ документів) +│ └── microdao_project_notes.ipynb # Jupyter ноутбук +├── src/ +│ ├── api/ # API клієнти +│ ├── components/ # React компоненти +│ │ └── onboarding/ # Компоненти онбордингу +│ ├── hooks/ # React hooks +│ ├── pages/ # Сторінки +│ └── types/ # TypeScript типи +├── package.json +├── vite.config.ts +└── PROJECT_CONTEXT.md # Цей файл +``` + +--- + +## 🎯 Поточний статус + +### ✅ Завершено +- Документація для Cursor (17 документів) +- Онбординг компоненти (6 кроків) +- API клієнти (teams, channels, agents, auth) +- Git репозиторій ініціалізовано +- Dev server налаштовано + +### ⏳ В процесі +- Реалізація Agent-Only Interface (4 задачі) +- Інтеграція LLM +- Система пам'яті агентів + +### 📋 Заплановано +- Projects Agent Module (15) +- Follow-ups Agent (16) +- Co-Memory Agent (17) +- Governance Agent (18) +- Notifications Agent (19) +- Integrations Agent (20) + +--- + +## 🔗 Швидкі посилання + +### Для Cursor +``` +Додай в контекст: /Users/apple/Desktop/MicroDAO/MicroDAO 3/docs/cursor/ +``` + +### Для розробки +```bash +cd "/Users/apple/Desktop/MicroDAO/MicroDAO 3" +npm install +npm run dev +``` + +### Відкрити в браузері +- Головна: http://localhost:3000 +- Онбординг: http://localhost:3000/onboarding + +--- + +## 📝 Як посилатись на проєкт + +### В чатах з Cursor / AI +Просто скопіюй: +``` +Проєкт: microDAO2 +Шлях: /Users/apple/Desktop/MicroDAO/MicroDAO 3 +Документація: docs/cursor/ (31 документ) +``` + +Або коротко: +``` +microDAO2: /Users/apple/Desktop/MicroDAO/MicroDAO 3 +``` + +### Для швидкого старту +``` +Використовуй: PROJECT_CONTEXT.md в корені проєкту +``` + +--- + +## 🛠️ Технології + +- **Frontend:** React 18, TypeScript, Vite, Tailwind CSS +- **Backend:** API Gateway `https://api.microdao.xyz/v1` +- **State:** React Query, Zustand/Context +- **LLM:** OpenAI (інтеграція через backend) + +--- + +## 📖 Корисні файли + +- `QUICK_START.md` — Швидкий старт +- `PROJECT_INFO.md` — Інформація про проєкт +- `GIT_SETUP.md` — Налаштування Git +- `STATUS.md` — Статус проєкту +- `docs/cursor/README.md` — Навігація по документації + +--- + +**Останнє оновлення:** 2024-11-13 + diff --git a/PROJECT_INFO.md b/PROJECT_INFO.md new file mode 100644 index 00000000..69444186 --- /dev/null +++ b/PROJECT_INFO.md @@ -0,0 +1,121 @@ +# 📍 Інформація про проєкт MicroDAO + +## 🗂️ Де зберігається проєкт + +### Локальне зберігання +``` +/Users/apple/Desktop/MicroDAO/MicroDAO 3 +``` + +### Швидкий доступ +- **Символічне посилання:** `~/Desktop/MicroDAO-QuickAccess` +- **В Finder:** `⌘ + Shift + G` → вставити шлях вище +- **В Terminal:** `cd "/Users/apple/Desktop/MicroDAO/MicroDAO 3"` + +## 💾 Continue / Pieces — що це? + +**Continue** та **Pieces** — це розширення для IDE (Cursor/VS Code), які: + +### Що вони роблять: +- ✅ Зберігають **історію розмов** з AI локально +- ✅ Запам'ятовують **контекст проєкту** для кращої роботи Cursor +- ✅ Дозволяють **швидко знаходити** попередні розмови + +### Що вони НЕ роблять: +- ❌ НЕ зберігають сам проєкт (він на вашому диску) +- ❌ НЕ є хмарним сховищем +- ❌ НЕ синхронізують код між пристроями + +### Де знаходиться історія Continue/Pieces: +- **Continue:** `~/.continue/` (прихована папка) +- **Pieces:** залежить від налаштувань, зазвичай в `~/Library/Application Support/` + +**Ваш проєкт завжди на:** `/Users/apple/Desktop/MicroDAO/MicroDAO 3` + +## 📓 Jupyter Notebook + +### Чи можна зберігати проєкт в Jupyter? + +**Jupyter Notebook** підходить для: +- ✅ Документації та аналізу даних +- ✅ Python скриптів та експериментів +- ✅ Візуалізацій та нотаток +- ❌ **НЕ** для React/TypeScript проєктів + +### Якщо хочете використати Jupyter: + +Можна створити окремі ноутбуки для: +- `docs/analysis.ipynb` — аналіз даних проєкту +- `docs/notes.ipynb` — нотатки та ідеї +- `docs/api_examples.ipynb` — приклади використання API + +**Але основний код React залишається в `src/`** + +## 🌐 Canvas Browser + +### Чи можу я запустити проєкт в Canvas? + +**Canvas Browser** — це інструмент для перегляду веб-сторінок, але: + +1. **Я не можу безпосередньо запустити** React проєкт в Canvas +2. **Але можу допомогти:** + - Налаштувати проєкт для запуску + - Запустити dev server локально + - Відкрити браузер на `localhost:3000` + - Показати скріншот через Canvas + +### Як запустити проєкт: + +```bash +# 1. Встановити залежності (один раз) +cd "/Users/apple/Desktop/MicroDAO/MicroDAO 3" +npm install + +# 2. Запустити dev server +npm run dev + +# 3. Відкрити в браузері +# Автоматично відкриється http://localhost:3000 +# Або відкрийте вручну: http://localhost:3000/onboarding +``` + +## 🔍 Швидкий пошук проєкту + +### Варіант 1: Spotlight (macOS) +Натисніть `⌘ + Space` і введіть: `MicroDAO 3` + +### Варіант 2: Terminal alias +Додайте в `~/.zshrc`: +```bash +alias microdao='cd "/Users/apple/Desktop/MicroDAO/MicroDAO 3"' +``` + +### Варіант 3: Символічне посилання +Вже створено: `~/Desktop/MicroDAO-QuickAccess` + +## 📊 Структура проєкту + +``` +MicroDAO 3/ +├── docs/cursor/ # Документація для Cursor +├── src/ # React код +│ ├── api/ # API клієнти +│ ├── components/ # React компоненти +│ ├── pages/ # Сторінки +│ └── types/ # TypeScript типи +├── package.json # Залежності +├── vite.config.ts # Vite конфігурація +└── QUICK_START.md # Інструкції запуску +``` + +## 🚀 Наступні кроки + +1. **Встановити залежності:** `npm install` +2. **Запустити проєкт:** `npm run dev` +3. **Відкрити онбординг:** `http://localhost:3000/onboarding` +4. **Підключити Git:** див. `GIT_SETUP.md` + +--- + +**Важливо:** Проєкт зберігається локально на вашому комп'ютері. Continue/Pieces лише допомагають Cursor згадувати контекст, але не зберігають сам код. + diff --git a/QUICK_GITHUB_SETUP.md b/QUICK_GITHUB_SETUP.md new file mode 100644 index 00000000..72e508ef --- /dev/null +++ b/QUICK_GITHUB_SETUP.md @@ -0,0 +1,65 @@ +# 🚀 Швидке налаштування GitHub (5 хвилин) + +## Крок 1: Додай SSH ключ на GitHub + +Твій публічний SSH ключ: +``` +ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOsHg+L0tRWlNfiJLIsHXdUarfjx65CavasAZfA/a+1M daarion@gex44 +``` + +**Що робити:** +1. Скопіюй ключ вище +2. Відкрий https://github.com/settings/keys +3. Натисни **"New SSH key"** +4. Встав ключ +5. Натисни **"Add SSH key"** + +## Крок 2: Створи репозиторій на GitHub + +1. Відкрий https://github.com/new +2. **Repository name:** `microdao-daarion` (або інша назва) +3. **Description:** "MicroDAO & DAARION.city - Agent-based community platform" +4. **Visibility:** Private або Public +5. **НЕ** стави галочку "Initialize with README" +6. Натисни **"Create repository"** + +## Крок 3: Підготуй проєкт + +Я вже підготував проєкт. Тепер виконай: + +```bash +cd "/Users/apple/Desktop/MicroDAO/MicroDAO 3" + +# Додай remote (заміни YOUR_USERNAME на свій GitHub username) +git remote add origin git@github.com:YOUR_USERNAME/microdao-daarion.git + +# Або якщо репозиторій вже створено, перевір: +git remote -v +``` + +## Крок 4: Push на GitHub + +```bash +# Переконайся, що всі файли додані +git add . + +# Зроби коміт +git commit -m "chore: initial commit - MicroDAO & DAARION.city documentation and code" + +# Push +git branch -M main +git push -u origin main +``` + +## Готово! 🎉 + +Після цього я зможу: +- ✅ Клонувати репозиторії +- ✅ Робити коміти та push +- ✅ Створювати гілки +- ✅ Працювати з твоїми репозиторіями + +--- + +**Детальні інструкції:** `GITHUB_SETUP.md` + diff --git a/QUICK_LINK.md b/QUICK_LINK.md new file mode 100644 index 00000000..44556c74 --- /dev/null +++ b/QUICK_LINK.md @@ -0,0 +1,37 @@ +# 🔗 Швидке посилання на проєкт microDAO2 + +**Скопіюй це посилання для інших чатів:** + +``` +Проєкт: microDAO2 +Шлях: /Users/apple/Desktop/MicroDAO/MicroDAO 3 +Документація: docs/cursor/ (31 документ) +Контекст: PROJECT_CONTEXT.md +``` + +--- + +## 📋 Повна інформація для AI + +``` +Проєкт: microDAO2 (MicroDAO MVP) +Шлях: /Users/apple/Desktop/MicroDAO/MicroDAO 3 +Документація: docs/cursor/ (31 документ, 412KB) +Ключові файли: +- PROJECT_CONTEXT.md - швидкий контекст +- MVP_VERTICAL_SLICE.md - план реалізації MVP +- docs/cursor/README.md - навігація по документації +``` + +--- + +## 🎯 Для швидкого старту + +Просто скопіюй це: + +``` +microDAO2: /Users/apple/Desktop/MicroDAO/MicroDAO 3 +Документація: docs/cursor/ +``` + + diff --git a/QUICK_LINK.txt b/QUICK_LINK.txt new file mode 100644 index 00000000..1d1fe519 --- /dev/null +++ b/QUICK_LINK.txt @@ -0,0 +1,6 @@ +🔗 Швидке посилання на microDAO2 + +Скопіюй це для інших чатів: + +microDAO2: /Users/apple/Desktop/MicroDAO/MicroDAO 3 +Документація: docs/cursor/ (31 документ) diff --git a/QUICK_START.md b/QUICK_START.md new file mode 100644 index 00000000..814dc71c --- /dev/null +++ b/QUICK_START.md @@ -0,0 +1,130 @@ +# 🚀 Швидкий старт MicroDAO MVP + +## 📍 Де знаходиться проєкт + +**Повний шлях:** +``` +/Users/apple/Desktop/MicroDAO/MicroDAO 3 +``` + +**Швидкий доступ:** +- Відкрити в Finder: `⌘ + Shift + G` → вставити шлях вище +- Відкрити в Terminal: `cd "/Users/apple/Desktop/MicroDAO/MicroDAO 3"` +- Створити символічне посилання (див. нижче) + +## 🔧 Перший запуск + +### 1. Встановити залежності + +```bash +cd "/Users/apple/Desktop/MicroDAO/MicroDAO 3" +npm install +``` + +### 2. Запустити dev server + +```bash +npm run dev +``` + +Проєкт відкриється автоматично на `http://localhost:3000` + +### 3. Відкрити онбординг + +Перейдіть на: `http://localhost:3000/onboarding` + +## 📂 Створення швидкого доступу + +### Варіант 1: Символічне посилання на робочому столі + +```bash +ln -s "/Users/apple/Desktop/MicroDAO/MicroDAO 3" ~/Desktop/MicroDAO-Link +``` + +### Варіант 2: Додати в обрані (Finder) + +1. Відкрити Finder +2. Перейти до `/Users/apple/Desktop/MicroDAO/MicroDAO 3` +3. Перетягнути папку в бічну панель (Sidebar) + +### Варіант 3: Створити alias в Terminal + +Додайте в `~/.zshrc` або `~/.bash_profile`: + +```bash +alias microdao='cd "/Users/apple/Desktop/MicroDAO/MicroDAO 3"' +``` + +Потім: +```bash +source ~/.zshrc +microdao # Швидкий перехід до проєкту +``` + +## 🗂️ Про Continue / Pieces + +**Continue** та **Pieces** — це IDE розширення, які: +- Зберігають контекст розмови локально +- Не зберігають сам проєкт (він на диску) +- Допомагають Cursor/VS Code згадувати попередні розмови + +**Ваш проєкт зберігається:** +- Локально: `/Users/apple/Desktop/MicroDAO/MicroDAO 3` +- В Git: після підключення до GitHub/GitLab + +## 📓 Jupyter Notebook + +Jupyter Notebook підходить для: +- ✅ Документації та аналізу +- ✅ Python скриптів +- ❌ НЕ для React проєктів + +**Можна створити:** +- `docs/analysis.ipynb` — для аналізу даних +- `docs/notes.ipynb` — для нотаток + +## 🌐 Canvas Browser + +**Я не можу безпосередньо запустити проєкт в Canvas browser**, але можу: + +1. ✅ Запустити dev server локально +2. ✅ Відкрити браузер на `localhost:3000` +3. ✅ Показати скріншот через Canvas + +**Щоб запустити:** +```bash +npm install +npm run dev +``` + +Потім відкрийте `http://localhost:3000` в браузері. + +## 📝 Корисні команди + +```bash +# Перейти до проєкту +cd "/Users/apple/Desktop/MicroDAO/MicroDAO 3" + +# Встановити залежності +npm install + +# Запустити dev server +npm run dev + +# Збілдити для продакшн +npm run build + +# Перевірити Git статус +git status + +# Зробити коміт +git add . +git commit -m "Опис змін" +``` + +## 🔗 Корисні посилання + +- Документація для Cursor: `docs/cursor/README.md` +- Налаштування Git: `GIT_SETUP.md` +- Структура проєкту: `src/README.md` + diff --git a/README.md b/README.md new file mode 100644 index 00000000..fc8b3365 --- /dev/null +++ b/README.md @@ -0,0 +1,122 @@ +# MicroDAO MVP + +Приватна мережа ШІ-агентів для малих спільнот (5-50 членів) + +--- + +## 🚀 Швидкий старт + +```bash +# Встановити залежності +npm install + +# Запустити dev server +npm run dev + +# Відкрити в браузері +http://localhost:3000/onboarding +``` + +--- + +## 📍 Де знаходиться проєкт + +**Повний шлях:** +``` +/Users/apple/Desktop/MicroDAO/MicroDAO 3 +``` + +**Швидкий доступ:** +- Символічне посилання: `~/Desktop/MicroDAO-QuickAccess` +- Spotlight: `⌘ + Space` → "MicroDAO 3" + +**Для посилань в чатах:** +``` +Проєкт: /Users/apple/Desktop/MicroDAO/MicroDAO 3 +Документація: docs/cursor/ +``` + +--- + +## 📚 Документація + +### Для Cursor AI +Повна документація знаходиться в `docs/cursor/` (17+ документів): + +- **Фундамент:** 00-07 (overview, product, architecture, API, UI/UX, standards, tasks, tests) +- **Агентська система:** 08-13 (onboarding, evolution, UI, LLM, runtime, memory) +- **Модулі:** 14, 21-22 (messenger, interface, tasks) + +**Навігація:** `docs/cursor/README.md` + +### Швидкий контекст +- `PROJECT_CONTEXT.md` — Швидкий доступ до ключових інформацій +- `QUICK_START.md` — Інструкції запуску +- `PROJECT_INFO.md` — Детальна інформація про проєкт + +--- + +## 🗂️ Структура + +``` +MicroDAO 3/ +├── docs/ +│ ├── cursor/ # Документація для Cursor +│ └── microdao_project_notes.ipynb +├── src/ +│ ├── api/ # API клієнти +│ ├── components/ # React компоненти +│ ├── hooks/ # React hooks +│ ├── pages/ # Сторінки +│ └── types/ # TypeScript типи +├── package.json +└── vite.config.ts +``` + +--- + +## 🎯 Статус проєкту + +### ✅ Завершено +- Документація для Cursor (17 документів) +- Онбординг (6 кроків) +- API інтеграція +- Git репозиторій + +### ⏳ В процесі +- Agent-Only Interface +- LLM інтеграція +- Система пам'яті + +### 📋 Заплановано +- Projects Agent (15) +- Follow-ups Agent (16) +- Co-Memory Agent (17) +- Governance Agent (18) +- Notifications Agent (19) +- Integrations Agent (20) + +--- + +## 🛠️ Технології + +- **Frontend:** React 18, TypeScript, Vite, Tailwind CSS +- **Backend:** API Gateway `https://api.microdao.xyz/v1` +- **State:** React Query, Zustand/Context +- **LLM:** OpenAI (через backend) + +--- + +## 📖 Корисні посилання + +- [Документація для Cursor](docs/cursor/README.md) +- [Швидкий старт](QUICK_START.md) +- [Контекст проєкту](PROJECT_CONTEXT.md) +- [Налаштування Git](GIT_SETUP.md) + +--- + +**Версія:** MVP v1.0 +**Останнє оновлення:** 2024-11-13 + + diff --git a/SERVER_SETUP_INSTRUCTIONS.md b/SERVER_SETUP_INSTRUCTIONS.md new file mode 100644 index 00000000..8f86a161 --- /dev/null +++ b/SERVER_SETUP_INSTRUCTIONS.md @@ -0,0 +1,115 @@ +# Інструкції для налаштування на сервері + +Цей документ описує, як завантажити та налаштувати проєкт на сервері після push у GitHub. + +## Передумови + +1. GitHub репозиторій вже містить код та документацію +2. На сервері встановлено Git +3. SSH доступ до сервера налаштовано + +## Крок 1: Клонування репозиторію + +```bash +cd /opt +sudo git clone git@github.com:daarion/dagi-stack.git +# або для HTTPS: +sudo git clone https://github.com/daarion/dagi-stack.git +``` + +## Крок 2: Перевірка структури + +```bash +cd /opt/dagi-stack +ls -la +tree docs/ # якщо встановлено tree +``` + +Очікувана структура: +``` +/opt/dagi-stack/ +├── docs/ +│ ├── microdao/ +│ ├── daarion/ +│ ├── agents/ +│ └── cursor/ +├── src/ +└── package.json +``` + +## Крок 3: Оновлення (коли є нові зміни) + +```bash +cd /opt/dagi-stack +sudo git pull origin main +``` + +## Крок 4: Використання документації + +### Для DAGI Router +Документація знаходиться в `/opt/dagi-stack/docs/` — можна використовувати як джерело знань. + +### Для microDAO RBAC +Використовуй документи з `/opt/dagi-stack/docs/microdao/`: +- `rbac.md` — система ролей та доступів +- `access-keys-capabilities.md` — ключі доступу + +### Для DAARION.city +Використовуй документи з `/opt/dagi-stack/docs/daarion/`: +- `tokenomics-city.md` — токеноміка +- `platforms-catalog.md` — каталог платформ +- `integration-microdao.md` — інтеграція + +## Крок 5: Інтеграція з Docusaurus/MkDocs (опціонально) + +Якщо хочеш публічну документацію: + +```bash +cd /opt/dagi-stack +npm install # якщо є package.json з Docusaurus +npm run build +``` + +Або з MkDocs: +```bash +pip install mkdocs mkdocs-material +mkdocs build +``` + +## Автоматичне оновлення (опціонально) + +Створи cron job для автоматичного оновлення: + +```bash +sudo crontab -e +``` + +Додай: +``` +0 2 * * * cd /opt/dagi-stack && git pull origin main > /dev/null 2>&1 +``` + +Це оновлюватиме репозиторій щодня о 2:00 ночі. + +## Troubleshooting + +### Помилка: "Permission denied" +```bash +sudo chown -R $USER:$USER /opt/dagi-stack +``` + +### Помилка: "git pull requires authentication" +Налаштуй SSH ключ на сервері або використовуй HTTPS з токеном: +```bash +git config --global credential.helper store +``` + +### Помилка: "detached HEAD" +```bash +git checkout main +``` + +--- + +**Останнє оновлення:** 2024-11-14 + diff --git a/START_HERE.md b/START_HERE.md new file mode 100644 index 00000000..c07d9944 --- /dev/null +++ b/START_HERE.md @@ -0,0 +1,77 @@ +# 🚀 microDAO2 — Початок роботи + +**Якщо ти в новому чаті з Cursor/AI — скопіюй це:** + +``` +Проєкт: microDAO2 +Шлях: /Users/apple/Desktop/MicroDAO/MicroDAO 3 +Документація: docs/cursor/ (31 документ) +``` + +--- + +## ⚠️ Важливо + +Я (AI) **не маю автоматичної пам'яті між різними чатами**. + +Кожен новий чат — це нова сесія, тому: + +✅ **ПРАВИЛЬНО:** +``` +microDAO2: /Users/apple/Desktop/MicroDAO/MicroDAO 3 +``` + +❌ **НЕ ПРАЦЮЄ:** +``` +Просто "microDAO" без шляху +``` + +--- + +## 📋 Що завжди вказувати + +1. **Шлях до проєкту:** + ``` + /Users/apple/Desktop/MicroDAO/MicroDAO 3 + ``` + +2. **Назва проєкту:** + ``` + microDAO2 + ``` + +3. **Де документація:** + ``` + docs/cursor/ + ``` + +--- + +## 🎯 Швидкий старт для нового чату + +Скопіюй це повідомлення: + +``` +Працюю над проєктом microDAO2. + +Шлях: /Users/apple/Desktop/MicroDAO/MicroDAO 3 +Документація: docs/cursor/ (31 документ) +Контекст: PROJECT_CONTEXT.md + +Почни з: MVP_VERTICAL_SLICE.md +``` + +--- + +## 📂 Ключові файли + +- `PROJECT_CONTEXT.md` — швидкий контекст +- `MVP_VERTICAL_SLICE.md` — план реалізації MVP +- `QUICK_LINK.md` — швидке посилання +- `docs/cursor/README.md` — навігація по документації + +--- + +**Завжди вказуй шлях — тоді я зможу знайти проєкт!** 🎯 + + diff --git a/STATUS.md b/STATUS.md new file mode 100644 index 00000000..2a6845f2 --- /dev/null +++ b/STATUS.md @@ -0,0 +1,63 @@ +# ✅ Статус проєкту MicroDAO MVP + +## 🎉 Проєкт успішно запущено! + +**Дата:** $(date) + +### ✅ Що працює: + +1. **Node.js та npm** встановлені + - Node.js: v22.20.0 + - npm: 10.9.3 + +2. **Залежності встановлено** + - 279 пакетів встановлено + - React, TypeScript, Vite, Tailwind CSS готові + +3. **Dev server запущено** + - URL: `http://localhost:3000` + - Онбординг: `http://localhost:3000/onboarding` + - Статус: ✅ Працює + +### 📍 Де знаходиться проєкт: + +``` +/Users/apple/Desktop/MicroDAO/MicroDAO 3 +``` + +**Швидкий доступ:** +- Символічне посилання: `~/Desktop/MicroDAO-QuickAccess` +- Spotlight: `⌘ + Space` → "MicroDAO 3" + +### 🚀 Команди для роботи: + +```bash +# Перейти до проєкту +cd "/Users/apple/Desktop/MicroDAO/MicroDAO 3" + +# Запустити dev server (якщо не запущений) +npm run dev + +# Зупинити сервер +# Натисніть Ctrl+C в терміналі + +# Збілдити для продакшн +npm run build +``` + +### 🌐 Відкрити в браузері: + +- Головна: http://localhost:3000 +- Онбординг: http://localhost:3000/onboarding + +### 📝 Наступні кроки: + +1. ✅ Проєкт запущено +2. ⏳ Підключити до Git (див. `GIT_SETUP.md`) +3. ⏳ Реалізувати решту компонентів (див. `docs/cursor/06_tasks_onboarding_mvp.md`) +4. ⏳ Налаштувати API інтеграцію + +--- + +**Примітка:** Dev server запущено в фоні. Щоб зупинити, знайдіть процес або перезапустіть термінал. + diff --git a/docs/CONTRIBUTING_DOCS.md b/docs/CONTRIBUTING_DOCS.md new file mode 100644 index 00000000..fe1ab899 --- /dev/null +++ b/docs/CONTRIBUTING_DOCS.md @@ -0,0 +1,141 @@ +# Contributing to Documentation + +Правила роботи з документацією проєкту MicroDAO / DAARION.city. + +--- + +## Документація: джерела правди + +### Токеноміка + +- **Актуальна токеноміка міста:** `docs/tokenomics/city-tokenomics.md` +- Усі файли з токеноміки в `docs/_archive/` є застарілими і використовуються лише як історичні чернетки. +- При будь-яких змінах токеноміки редагуємо тільки `city-tokenomics.md` і оновлюємо версію у frontmatter. + +### Архітектура + +- **Основна архітектура:** `docs/cursor/02_architecture_basics.md` +- **Внутрішні сервіси:** `docs/cursor/34_internal_services_architecture.md` +- **Service Mesh:** `docs/cursor/35_microdao_service_mesh_design.md` + +### API + +- **API контракти:** `docs/cursor/03_api_core_snapshot.md` + +### Агенти + +- **Agent Runtime Core:** `docs/cursor/12_agent_runtime_core.md` +- **Agent Memory System:** `docs/cursor/13_agent_memory_system.md` +- **Private Agents Lifecycle:** `docs/cursor/38_private_agents_lifecycle_and_management.md` + +### Інтеграція + +- **DAARION.city Integration:** `docs/cursor/DAARION_city_integration.md` +- **Website Integration:** `docs/cursor/50_daarion_city_website_integration.md` +- **Integration Guide:** `docs/integration-daarion.md` + +--- + +## Правила версіонування + +### Канонічні документи + +Канонічні документи мають frontmatter з версією: + +```yaml +--- +title: Document Title +version: 1.0.0 +status: canonical +last_updated: 2024-11-14 +--- +``` + +### Оновлення документів + +1. Редагуєш **той самий** файл (не створюєш новий). +2. Змінюєш версію й дату у frontmatter: + ```yaml + version: 1.1.0 + last_updated: 2024-12-01 + ``` +3. Додаєш запис у секцію Changelog внизу документа. + +### Legacy документи + +- Старі версії документів переносяться в `docs/_archive/`. +- На початку legacy файлу додається помітка: + ```markdown + > **LEGACY:** Цей документ застарів. Актуальна версія: `docs/path/to/canonical.md`. + ``` + +--- + +## Структура документації + +``` +docs/ +├── cursor/ # Детальні технічні специфікації +├── tokenomics/ # Токеноміка (канонічний: city-tokenomics.md) +├── _archive/ # Застарілі документи +├── integration-daarion.md # Консолідований гайд інтеграції +├── CONTRIBUTING_DOCS.md # Цей файл +└── README.md # Загальний огляд документації +``` + +--- + +## Як працювати з Cursor + +### При створенні промптів + +Завжди вказуй канонічні документи: + +> Використовуй `docs/tokenomics/city-tokenomics.md` як єдине актуальне джерело токеноміки. + +> Використовуй `docs/cursor/50_daarion_city_website_integration.md` для інтеграції з сайтом. + +### При оновленні документації + +1. Знайди канонічний документ (перевір frontmatter на `status: canonical`). +2. Онови версію у frontmatter. +3. Додай запис у Changelog. +4. Якщо є legacy версії — перенеси їх в `_archive/`. + +--- + +## Приклади + +### Правильно + +```markdown +# Оновлення токеноміки +- Редагуємо `docs/tokenomics/city-tokenomics.md` +- Оновлюємо версію: 1.0.0 → 1.1.0 +- Додаємо запис у Changelog +``` + +### Неправильно + +```markdown +# Створення нового файлу +- ❌ НЕ створюємо `city-tokenomics-v2.md` +- ❌ НЕ створюємо `city-tokenomics-updated.md` +- ✅ Редагуємо існуючий `city-tokenomics.md` +``` + +--- + +## Питання? + +Якщо не впевнений, який документ є канонічним: + +1. Перевір frontmatter на `status: canonical`. +2. Перевір `docs/README.md` — там вказані канонічні документи. +3. Перевір `docs/CONTRIBUTING_DOCS.md` (цей файл). + +--- + +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..f5808e74 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,85 @@ +# Документація MicroDAO & DAARION.city + +Ця папка містить всю документацію проєкту, організовану за категоріями. + +## 📁 Структура документації + +### `/microdao/` — Документація MicroDAO +Архітектура, RBAC, токеноміка, технічні специфікації MicroDAO. + +**Ключові документи:** +- `architecture.md` — загальна архітектура системи +- `rbac.md` — система ролей та доступів (RBAC, Confidential Mode) +- `access-keys-capabilities.md` — система ключів доступу та capabilities + +**Детальна технічна документація:** `/cursor/` (61 документ для розробників) + +### `/daarion/` — Документація DAARION.city +Roadmap, governance, токеноміка міста, інтеграція з MicroDAO. + +**Ключові документи:** +- `integration-microdao.md` — інтеграція DAARION.city з MicroDAO +- `platforms-catalog.md` — каталог платформ (GREENFOOD, EnergyUnion, WaterUnion) +- `tokenomics-city.md` — токеноміка міста (DAAR, DAARION) + +### `/agents/` — Документація агентської системи +DAGI Router, DevTools Agent, CrewAI Orchestrator. + +**Структура:** +- `dagi-router.md` — архітектура DAGI Router +- `devtools-agent.md` — DevTools Agent +- `crewai-orchestrator.md` — CrewAI інтеграція + +### `/cursor/` — Технічна документація для розробки +61 документ з детальними специфікаціями для Cursor AI та розробників. + +**Категорії:** +- **00-07:** Фундамент (overview, product brief, architecture, API, UI/UX, coding standards, tasks, testing) +- **08-13:** Агентська система (onboarding, evolutionary agent, UI, LLM, runtime core, memory) +- **14-24:** Модулі та інтерфейс (messenger, projects, follow-ups, co-memory, governance, notifications, integrations, agent-only interface, operator modes, domains/wallet/DAO, agent cards) +- **24-50:** Інфраструктура та сервіси (access keys, deployment, security, database, flows, scaling, cost optimization, governance policies, PDP, API Gateway, service mesh, agent isolation, tools, lifecycle, templates, RWA, AI governance, NATS, outbox, usage, LLM proxy, router, messaging, teams, wallet, website integration) + +**Детальний опис:** `/cursor/README.md` + +## 🚀 Швидкий старт + +### Для розробників +1. Почни з `/cursor/00_overview_microdao.md` — загальний огляд +2. Вивчи `/cursor/01_product_brief_mvp.md` — product requirements +3. Переглянь `/cursor/03_api_core_snapshot.md` — API контракти +4. Дотримуйся `/cursor/05_coding_standards.md` — стандарти кодування + +### Для архітекторів +1. `/microdao/architecture.md` — архітектура MicroDAO +2. `/microdao/rbac.md` — система доступів +3. `/daarion/integration-microdao.md` — інтеграція з DAARION.city +4. `/cursor/34_internal_services_architecture.md` — архітектура сервісів + +### Для product/growth +1. `/daarion/tokenomics-city.md` — токеноміка міста +2. `/daarion/platforms-catalog.md` — каталог платформ +3. `/cursor/MVP_VERTICAL_SLICE.md` — план MVP + +## 📚 Посилання на повну документацію + +- [MicroDAO документація](./microdao/README.md) +- [DAARION.city документація](./daarion/README.md) +- [Агентська система](./agents/README.md) +- [Технічна документація для розробки](./cursor/README.md) + +## 🔄 Версіонування + +Вся документація зберігається в Git репозиторії. Для оновлення: + +```bash +git pull origin main +``` + +## 📝 Внесок у документацію + +Див. [CONTRIBUTING_DOCS.md](./CONTRIBUTING_DOCS.md) для інструкцій з оновлення документації. + +--- + +**Останнє оновлення:** 2024-11-14 +**Версія:** 1.0.0 diff --git a/docs/_archive/tokenomics_legacy_v0.md b/docs/_archive/tokenomics_legacy_v0.md new file mode 100644 index 00000000..674560c5 --- /dev/null +++ b/docs/_archive/tokenomics_legacy_v0.md @@ -0,0 +1,19 @@ +> **LEGACY:** Цей документ застарів. Актуальна версія токеноміки: `docs/tokenomics/city-tokenomics.md`. + +--- + +# Unified Tokenomics for DAARION.city & MicroDAO (Integration-Ready) + +*Version: 1.0 — production-ready (LEGACY)* + +--- + +## ⚠️ УВАГА: Цей документ застарів + +**Актуальна версія токеноміки:** `docs/tokenomics/city-tokenomics.md` + +Цей файл зберігається лише як історична чернетка. Вся актуальна інформація перенесена в канонічний документ `city-tokenomics.md`. + +--- + +*[Оригінальний вміст зберігається нижче для історичної довідки]* diff --git a/docs/agents.md b/docs/agents.md new file mode 100644 index 00000000..4116b8e1 --- /dev/null +++ b/docs/agents.md @@ -0,0 +1,540 @@ +--- +title: Agents Map — DAARION.city +version: 1.0.0 +status: canonical +last_updated: 2024-11-14 +--- + +> **Цей документ є актуальною картою всіх агентів у DAARION.city.** +> Інтегрується з `microdao-architecture.md` та ієрархією A1-A4. + +# Agents Map — DAARION.city + +*Консолідована карта всіх агентів екосистеми DAARION.city з ієрархією A1-A4* + +--- + +## 1. Overview + +DAARION.city працює на **багаторівневій системі агентів**, організованих за ієрархією MicroDAO: + +- **A1** — DAARION.city (системні агенти, DAARWIZZ) +- **A2** — Міські платформи (платформні агенти) +- **A3** — Публічні MicroDAO (DAO-агенти) +- **A4** — Приватні MicroDAO (приватні агенти) + +Кожен рівень має своїх агентів з відповідними правами, пам'яттю та інтеграціями. + +--- + +## 2. A1 — DAARION.city (Root Level Agents) + +### 2.1 DAARWIZZ — System Orchestrator Agent + +**Роль:** Головний системний агент міста, маршрутизатор та планувальник Swarm-OS + +**Призначення:** +- Оркестрація DAGI (Distributed AI Grid) +- Роутинг запитів між моделями та агентами +- Multi-agent сценарії та планування +- Телеметрія та моніторинг якості + +**Агентські модулі:** +- **Router Agent** — розподіляє запити між моделями та агентами +- **Planner Agent** — декомпозує задачі, запускає ланцюжки інструментів +- **Observer/Telemetry Agent** — відстежує якість, латентність, бюджет + +**Capabilities:** +- `router.invoke` +- `router.plan.run` +- `router.tool.call` +- `telemetry.events.write` +- `telemetry.events.read:aggregate` + +**Доступ:** +- Користувацькі microDAO отримують DAARWIZZ-keys через: + - Wallet Agent (оплата DAAR / 1T) + - План Platformium + +--- + +### 2.2 City-Level Agents + +**City Governance Agent** +- Міські правила, дух міста +- Governance proposals, voting, policies +- Інтеграція з AI Governance Agent (`41_ai_governance_agent_design.md`) + +**City Registry Agent** +- Реєстр мешканців, громадянство +- Управління citizenship, рівнями доступу +- DAARION-статус та права + +**City Bridges Agent** +- Зв'язки між city ↔ платформи ↔ microDAO +- Синхронізація подій між рівнями +- City events broadcast + +**City Co-Memory Agent** +- Загальноміський простір знань +- City Knowledge Spaces (City.Ecology, City.Energy, City.Food, City.Governance) +- Публікація фактів від платформ у City Co-Memory + +**Second Me Agent** +- Персональний цифровий двійник резидента +- Особистий контекст та пам'ять + +**Citizenship Agent** +- Керує резидентством, рівнями доступу, DAARION-статусом +- Capabilities: `citizenship.status.view`, `citizenship.level.upgrade` + +**Gift Fabric Agent** +- Відстежує акти взаємодії й відгук міста (MJD) +- Capabilities: `gift.act.register` + +--- + +## 3. A2 — Platform Agents (Міські платформи) + +Кожна платформа має власних агентів, які працюють на рівні платформи. + +### 3.1 GREENFOOD Platform Agents + +**Warehouse Agent** +- Облік партій/залишків +- Capabilities: `platform.greenfood.inventory.view/update` + +**Logistics Agent** +- Маршрути та хаби +- Capabilities: `platform.greenfood.shipment.create` + +**Accounting Agent** +- Автоматичні нарахування/розподіл по кооперативу +- Capabilities: `platform.greenfood.coop.balance.view` + +**Sales Agent** +- Інтеграція з маркетплейсами +- Capabilities: `platform.greenfood.member.register` + +**Community Coordinator Agent** +- Координація між учасниками спільноти + +**Embassy Integration:** +- `rwa.claim` (сертифікати продуктів) +- `rwa.stock.update` (запаси на складах) + +--- + +### 3.2 Energy Union Platform Agents + +**Metering Agent** +- Читає лічильники генерації/споживання +- Capabilities: `energy.meter.read` + +**Oracle Agent** +- Агрегує дані, формує виплати KWT/1T +- Capabilities: `energy.payout.compute` + +**Facility Agent** +- Агент об'єкта (сонячна станція, дата-центр) +- Capabilities: `energy.asset.read` + +**Energy Market Agent** +- Узгоджує акти енергетичного дарообміну +- Capabilities: `wallet.payout.view/claim` + +**Embassy Integration:** +- `embassy.energy.update` +- `embassy.rwa.claim` (сертифікати енергетичних часток) + +--- + +### 3.3 Water Union Platform Agents + +**Sensor Agent** +- Збір даних з сенсорів (якість/об'єм води) +- Capabilities: `water.sensor.read`, `water.sensor.update` + +**Infrastructure Agent** +- Стан насосів, резервуарів +- Capabilities: `water.infrastructure.view` + +**Community Water Agent** +- Координація доступу громад, планування ремонтів + +**Water RWA Agent** +- Сертифікати дару на водні ініціативи +- Capabilities: `rwa.water.claim` + +--- + +### 3.4 Essence Stream Platform Agents + +**Curator Agent** +- Формує програми, добирає контент +- Capabilities: `essence.event.publish` + +**Event Agent** +- Події, квитки (як сертифікати дару) +- Capabilities: `essence.event.register` + +**Mentor Agent** +- Персоналізовані навчальні траєкторії +- Capabilities: `essence.course.view` + +**Quest Agent** +- Квести/ігрові сценарії в DAARION.city +- Capabilities: `essence.quest.progress.update` + +--- + +### 3.5 Helion Platform Agents + +**Energy Production Agent** +- Управління енергетичними об'єктами +- Моніторинг генерації + +**Energy Distribution Agent** +- Розподіл енергії між споживачами +- Балансування навантаження + +--- + +### 3.6 Soul Platform Agents + +**Social Graph Agent** +- Управління соціальними зв'язками +- Рекомендації та мережі + +**Community Builder Agent** +- Створення та координація спільнот +- Інтеграція з microDAO + +--- + +### 3.7 Dario Platform Agents + +**City Services Agent** +- Управління міськими сервісами +- Координація з міською інфраструктурою + +--- + +### 3.8 Nutra Platform Agents + +**Health & Nutrition Agent** +- Управління здоров'ям та нутрицією +- Персоналізовані рекомендації + +--- + +## 4. A3 — Public MicroDAO Agents + +Публічні MicroDAO мають стандартний набір агентів, доступних для всіх резидентів. + +### 4.1 Team Assistant (Core Agent) + +**Призначення:** +- Основний помічник команди +- Відповіді у спільних чатах +- Автоматичні підсумки +- Створення follow-ups +- Пропозиції задач + +**Capabilities:** +- `agent.run.invoke` +- `chat.message.send` +- `project.task.create` +- `followup.create` + +--- + +### 4.2 Messenger Agent + +**Призначення:** +- Управління чатами та каналами +- Фільтрація та пошук повідомлень +- Розумні папки та огляди + +**Capabilities:** +- `chat.message.read` +- `chat.message.send` +- `channel.manage` + +--- + +### 4.3 Projects Agent + +**Призначення:** +- Управління проєктами та задачами +- Канбан-дошки +- Авто-генерація тасок з діалогів + +**Capabilities:** +- `project.create` +- `project.manage` +- `task.create` +- `task.manage` + +--- + +### 4.4 Follow-ups & Reminders Agent + +**Призначення:** +- Перетворення повідомлень на задачі +- Планування часу +- Нагадування + +**Capabilities:** +- `followup.create` +- `followup.remind` + +--- + +### 4.5 Co-Memory & Knowledge Space Agent + +**Призначення:** +- Документи, wiki, нотатки +- RAG по документах та пам'яті +- Інтерфейс "покажи, що ми вже знаємо про X" + +**Capabilities:** +- `comemory.item.read` +- `comemory.item.write` + +--- + +### 4.6 Governance & Access Agent + +**Призначення:** +- Голосування, пропозиції, кворум +- Зв'язок з 1T / RINGK / іншими токенами +- Train-to-Earn з точки зору агента + +**Capabilities:** +- `governance.proposal.create` +- `governance.vote.cast` +- `governance.policy.manage` + +--- + +### 4.7 Notifications & Attention Agent + +**Призначення:** +- Які події важливі, які — ні +- Digest-и, дайджести, персональні огляди дня/тижня + +**Capabilities:** +- `notification.send` +- `attention.prioritize` + +--- + +### 4.8 Integrations & Bridges Agent + +**Призначення:** +- Telegram / WhatsApp / email / календар +- Як мости працюють через агентську логіку +- Маршрутизація повідомлень і контексту + +**Capabilities:** +- `integration.bridge.create` +- `integration.message.route` + +--- + +## 5. A4 — Private MicroDAO Agents + +Приватні MicroDAO мають повну автономію та можуть мати власних агентів. + +### 5.1 Personal Agents + +**Призначення:** +- Особистий супутник користувача +- Особистий контекст та пам'ять +- Приватні нотатки, документи, нагадування +- Приватний інтерфейс до DAGI + +**Права:** +- Тільки `personal_space` +- Немає доступу до командних просторів без спеціального дозволу + +**Operator Mode:** +- Може працювати як оператор лише в особистому просторі +- Обмежені інструменти: `create_personal_note`, `create_personal_task`, `personal_digest` + +--- + +### 5.2 Private Team Agents + +**Призначення:** +- Аналогічні до A3 агентів, але з обмеженим доступом +- Працюють тільки в межах приватного MicroDAO +- Не мають доступу до публічних даних + +**Особливості:** +- Confidential mode за замовчуванням +- Обмежений доступ до LLM Proxy (тільки summary/embeddings) +- Немає публічного індексування + +--- + +## 6. Agent Hierarchy & Integration + +### 6.1 Hierarchy Flow + +```text +A1: DAARION.city + ├── DAARWIZZ (System Orchestrator) + ├── City Governance Agent + ├── City Registry Agent + ├── City Bridges Agent + └── City Co-Memory Agent + │ + ├── A2: Platforms + │ ├── GREENFOOD Agents + │ ├── Energy Union Agents + │ ├── Water Union Agents + │ └── Essence Stream Agents + │ + ├── A3: Public MicroDAO + │ ├── Team Assistant + │ ├── Messenger Agent + │ ├── Projects Agent + │ └── ... (standard agents) + │ + └── A4: Private MicroDAO + ├── Personal Agents + └── Private Team Agents +``` + +### 6.2 Integration Points + +**DAARWIZZ Integration:** +- Всі агенти можуть використовувати DAARWIZZ для роутингу та планування +- Доступ через DAAR/1T оплату або Platformium план + +**PDP Integration:** +- Всі агенти перевіряються через PDP для доступу до ресурсів +- Capability-based access control + +**Wallet Integration:** +- Агенти можуть працювати з UTIL токенами +- Не можуть змінювати баланси DAAR/DAARION + +**Embassy Integration:** +- Платформні агенти (A2) мають доступ до Embassy для RWA +- City-level агенти мають обмежений доступ до Embassy + +--- + +## 7. Agent Memory & Context + +### 7.1 Memory Scopes + +**A1 Agents:** +- City-level memory (загальноміський контекст) +- Доступ до всіх платформ та публічних MicroDAO + +**A2 Agents:** +- Platform-level memory (контекст платформи) +- Доступ до City Co-Memory для публікації фактів + +**A3 Agents:** +- Team-level memory (контекст команди) +- Обмежений доступ до City Co-Memory + +**A4 Agents:** +- Personal/Private memory (особистий/приватний контекст) +- Немає доступу до City Co-Memory + +### 7.2 Confidential Mode + +**A4 Agents (Private MicroDAO):** +- Confidential mode за замовчуванням +- LLM Proxy отримує тільки summary/embeddings +- Немає публічного індексування + +**A3 Agents (Public MicroDAO):** +- Можуть мати confidential канали +- Обмежений доступ до plaintext у confidential каналах + +--- + +## 8. Agent Capabilities Matrix + +| Agent Type | Router Access | Wallet Access | Embassy Access | City Co-Memory | +|------------|---------------|---------------|----------------|----------------| +| DAARWIZZ | ✅ Full | ❌ No | ❌ No | ✅ Read/Write | +| City Agents | ✅ Via DAARWIZZ | ❌ No | ⚠️ Limited | ✅ Read/Write | +| Platform Agents | ✅ Via DAARWIZZ | ⚠️ UTIL only | ✅ Full | ✅ Publish | +| A3 Agents | ✅ Via DAARWIZZ | ⚠️ UTIL only | ❌ No | ⚠️ Read only | +| A4 Agents | ✅ Via DAARWIZZ | ⚠️ UTIL only | ❌ No | ❌ No | + +--- + +## 9. Agent Lifecycle + +### 9.1 Creation + +**A1 Agents:** +- Створюються при ініціалізації DAARION.city +- Системні агенти, не можуть бути видалені + +**A2 Agents:** +- Створюються при реєстрації платформи +- Управляються платформою + +**A3/A4 Agents:** +- Створюються через DAOFactory (1 DAAR або 0.01 DAARION) +- Управляються власниками MicroDAO + +### 9.2 Configuration + +Всі агенти налаштовуються через: +- Agent Config (роль, системний промпт, пам'ять) +- Capabilities (доступ до інструментів) +- Memory Scope (channel, team, global) + +### 9.3 Updates + +- Агенти можуть оновлюватися через Governance +- Еволюційні агенти можуть самонавчатися (з дозволу користувача) + +--- + +## 10. Integration with Other Docs + +Цей документ інтегрується з: + +- `microdao-architecture.md` — архітектура MicroDAO (A1-A4) +- `tokenomics/city-tokenomics.md` — токеноміка та доступ +- `cursor/12_agent_runtime_core.md` — Agent Runtime Core +- `cursor/13_agent_memory_system.md` — Agent Memory System +- `cursor/22_operator_modes_and_system_agents.md` — System Agents +- `cursor/38_private_agents_lifecycle_and_management.md` — Private Agents +- `cursor/41_ai_governance_agent_design.md` — AI Governance Agent +- `cursor/46_router_orchestrator_design.md` — Router/Orchestrator +- `DAARION_city_platforms_catalog.md` — Платформи та їх агенти + +--- + +## 11. Changelog + +### v1.0.0 — 2024-11-14 +- Початкова версія карти агентів +- Додано DAARWIZZ як системний агент A1 +- Додано City-level агенти +- Додано Platform Agents (A2) +- Додано Public MicroDAO Agents (A3) +- Додано Private MicroDAO Agents (A4) +- Додано Agent Hierarchy & Integration +- Додано Agent Capabilities Matrix + +--- + +**Версія:** 1.0.0 +**Останнє оновлення:** 2024-11-14 +*Документ готовий до інтеграції у Cursor, GitHub або будь-який інший проект.* + + diff --git a/docs/agents/README.md b/docs/agents/README.md new file mode 100644 index 00000000..693bd705 --- /dev/null +++ b/docs/agents/README.md @@ -0,0 +1,24 @@ +# Агентська система — Документація + +Ця папка містить документацію про агентську систему: DAGI Router, DevTools Agent, CrewAI Orchestrator. + +## Структура + +### DAGI Router +- `dagi-router.md` — архітектура та специфікація DAGI Router +- `dagi-router-setup.md` — інструкції з налаштування + +### DevTools Agent +- `devtools-agent.md` — опис DevTools Agent +- `devtools-setup.md` — налаштування DevTools + +### CrewAI Orchestrator +- `crewai-orchestrator.md` — архітектура CrewAI +- `crewai-integration.md` — інтеграція з системою + +## Посилання + +- [MicroDAO документація](../microdao/README.md) +- [DAARION.city документація](../daarion/README.md) +- [Технічна документація для розробки](../cursor/README.md) + diff --git a/docs/api-mvp.md b/docs/api-mvp.md new file mode 100644 index 00000000..c5d15981 --- /dev/null +++ b/docs/api-mvp.md @@ -0,0 +1,487 @@ +--- +title: API Specification (MVP) — DAARION.city & MicroDAO +version: 1.0.0 +status: canonical +last_updated: 2024-11-14 +--- + +# API Specification (MVP) — DAARION.city & MicroDAO + +**Документ описує мінімальний набір API-ендпоінтів для запуску MVP-версії MicroDAO, інтегрованої з DAARION.city.** + +Фокус: + +* створення та реєстрація MicroDAO +* робота з реєстром DAO та платформ +* базові операції Wallet (DAAR/DAARION) +* реєстрація вендорів та створення платформ +* PDP-перевірки +* базові Agent / Router виклики (stub-рівень) + +--- + +# 1. Загальні принципи + +* Транспорт: **HTTPS / JSON** +* Auth: **Bearer Token (user / service token)** +* Стиль: REST-like з чіткими ресурсами +* Усі критичні операції проходять через PDP +* Ідентифікатори DAO/платформ/користувачів — `UUID` / `string` (визначається реалізацією) + +Базовий префікс: + +```text +/api/v1 +``` + +--- + +# 2. Auth & Context + +Контекст користувача / сервісу визначається: + +* токеном авторизації (user/service) +* DAO-контекстом (якщо вказано `X-DAO-ID` у заголовках) + +Приклад заголовків: + +```http +Authorization: Bearer +X-DAO-ID: # опційно, якщо дія виконується в межах конкретного DAO +``` + +--- + +# 3. DAOFactory API + +## 3.1 Створення MicroDAO + +**POST** `/api/v1/dao` + +Створює новий MicroDAO (A3 або A4). + +### Умови + +* PDP: `policy.dao.create` +* токен користувача + +### Request + +```json +{ + "name": "string", + "description": "string", + "type": "public | private", + "level": "A3 | A4", + "settings": { + "visibility": "catalog | invite-only" + } +} +``` + +### Response + +```json +{ + "dao_id": "string", + "level": "A3 | A4", + "name": "string", + "parent_dao_id": null, + "federation_mode": "none", + "created_at": "2025-..." +} +``` + +--- + +## 3.2 Отримати DAO за id + +**GET** `/api/v1/dao/{dao_id}` + +### Response + +```json +{ + "dao_id": "string", + "name": "string", + "description": "string", + "level": "A1 | A2 | A3 | A4", + "type": "platform | public | private", + "parent_dao_id": "string | null", + "federation_mode": "none | member | superdao", + "settings": { ... } +} +``` + +--- + +## 3.3 Список DAO (каталог) + +**GET** `/api/v1/dao` + +Параметри: + +* `level` (опційно): `A1|A2|A3|A4` +* `type` (опційно): `platform|public|private` + +### Response + +```json +{ + "items": [ + { + "dao_id": "string", + "name": "string", + "level": "A2", + "type": "platform" + } + ] +} +``` + +--- + +# 4. Registry API (DAO & Platforms) + +## 4.1 Реєстр платформ (тільки A2) + +**GET** `/api/v1/platforms` + +### Response + +```json +{ + "items": [ + { + "dao_id": "string", + "name": "Helion", + "slug": "helion", + "description": "Energy platform", + "level": "A2" + } + ] +} +``` + +--- + +# 5. Wallet API (DAAR / DAARION) + +## 5.1 Отримати баланс користувача + +**GET** `/api/v1/wallet/me` + +### Response + +```json +{ + "user_id": "string", + "balances": [ + { "symbol": "DAAR", "amount": "123.45" }, + { "symbol": "DAARION", "amount": "0.50" } + ] +} +``` + +--- + +## 5.2 Перевірка базових прав доступу (допоміжний метод) + +**POST** `/api/v1/wallet/check-access` + +Перевіряє, чи достатньо токенів для певної дії (корисно для UI). + +### Request + +```json +{ + "check": "dao.create | vendor.register | platform.create" +} +``` + +### Response + +```json +{ + "allowed": true, + "reason": null +} +``` + +або + +```json +{ + "allowed": false, + "reason": "INSUFFICIENT_DAARION_BALANCE" +} +``` + +--- + +# 6. Vendor & Platform API + +## 6.1 Реєстрація вендора на платформі + +**POST** `/api/v1/platforms/{platform_id}/vendors` + +### Умови + +* PDP: `policy.vendor.register` (мінімум 0.01 DAARION у стейкінгу) + +### Request + +```json +{ + "display_name": "GreenFarm UA", + "contact": { + "email": "owner@example.com" + } +} +``` + +### Response + +```json +{ + "vendor_id": "string", + "platform_id": "string", + "status": "approved | pending" +} +``` + +--- + +## 6.2 Створення платформи (A2) + +**POST** `/api/v1/platforms` + +### Умови + +* PDP: `policy.platform.create` (мінімум 1 DAARION у стейкінгу) + +### Request + +```json +{ + "name": "Helion", + "slug": "helion", + "description": "Energy platform", + "domain": "energy" +} +``` + +### Response + +```json +{ + "dao_id": "string", + "name": "Helion", + "level": "A2", + "type": "platform" +} +``` + +--- + +# 7. PDP API + +## 7.1 Перевірка політики + +**POST** `/api/v1/pdp/check` + +### Request + +```json +{ + "policy": "policy.dao.create", + "resource": { + "type": "dao", + "id": null + }, + "context": { + "dao_level": "A3", + "user_id": "string" + } +} +``` + +### Response + +```json +{ + "decision": "allow | deny | require-elevation", + "reason": "string | null" +} +``` + +> У продакшн-коді сервіси зазвичай викликають PDP напряму, а не через публічний API. Ендпоінт може використовуватись для діагностики, дебагу або внутрішніх адміністративних інструментів. + +--- + +# 8. Agents & Router API (MVP Stub) + +## 8.1 Запуск агента в DAO (simple invoke) + +**POST** `/api/v1/dao/{dao_id}/agents/{agent_id}/invoke` + +### Умови + +* PDP: `policy.agent.run` + +### Request + +```json +{ + "input": "string", + "metadata": { + "origin": "admin-console | user-chat | system" + } +} +``` + +### Response + +```json +{ + "run_id": "string", + "status": "queued | running | completed | failed", + "output": "string | null" +} +``` + +--- + +## 8.2 Створення Router flow (спрощено) + +**POST** `/api/v1/router/flows` + +### Request + +```json +{ + "dao_id": "string", + "name": "Onboard new member", + "steps": [ + { "type": "agent", "agent_id": "welcome-agent" }, + { "type": "agent", "agent_id": "policy-explainer" } + ] +} +``` + +### Response + +```json +{ + "flow_id": "string", + "status": "created" +} +``` + +--- + +# 9. Events (System → Clients) + +Події можуть відправлятися через Webhook / WebSocket / NATS (деталі реалізації залежать від інфраструктури). + +Мінімальний набір подій: + +* `dao.created` +* `platform.created` +* `vendor.registered` +* `agent.run.completed` + +Приклад payload: + +```json +{ + "event": "dao.created", + "data": { + "dao_id": "string", + "name": "string", + "level": "A3", + "created_by": "user_id" + }, + "ts": "2025-..." +} +``` + +--- + +# 10. Статуси та помилки + +## 10.1 HTTP-статуси + +* `200 OK` — успішний запит +* `201 Created` — ресурс створено +* `400 Bad Request` — некоректні дані +* `401 Unauthorized` — відсутня/некоректна авторизація +* `403 Forbidden` — PDP = deny +* `404 Not Found` — ресурс не знайдено +* `409 Conflict` — конфлікт станів +* `500 Internal Server Error` — внутрішня помилка + +## 10.2 Приклад помилки + +```json +{ + "error": "ACCESS_DENIED", + "message": "PDP denied action 'platform.create' for this user.", + "details": { + "policy": "policy.platform.create" + } +} +``` + +--- + +# 11. Подальший розвиток API + +Цей документ описує **MVP-шар**. Надалі можливі розширення: + +* детальний Wallet API (транзакції, стейкінг, payout-и) +* повна OpenAPI-специфікація +* окремий Agent Runtime API (streams, tools, multi-step flows) +* Notification API (email / push / in-app) + +На рівні MVP цього набору достатньо, щоб: + +* створювати DAO +* реєструвати платформи +* реєструвати вендорів +* керувати базовими правами доступу +* запускати прості агенти та оркестраційні флоу. + +--- + +## 12. Integration with Other Docs + +Цей документ інтегрується з: + +- `api.md` — повна API специфікація (розширена версія) +- `core-services-mvp.md` — реалізація core-сервісів (Wallet, DAOFactory, Registry, PDP) +- `pdp_access.md` — PDP та система доступів +- `microdao-architecture.md` — архітектура A1-A4 +- `superdao-federation.md` — SuperDAO та федерації +- `tokenomics/city-tokenomics.md` — токеноміка + +--- + +## 13. Changelog + +### v1.0.0 — 2024-11-14 +- Початкова версія MVP API специфікації +- Додано DAOFactory API (створення, отримання, список DAO) +- Додано Registry API (реєстр платформ) +- Додано Wallet API (баланси, перевірка доступу) +- Додано Vendor & Platform API (реєстрація вендорів, створення платформ) +- Додано PDP API (перевірка політик) +- Додано Agents & Router API (stub-рівень) +- Додано Events (системні події) + +--- + +**Версія:** 1.0.0 +**Останнє оновлення:** 2024-11-14 +*Документ готовий до інтеграції у Cursor, GitHub або будь-який інший проект.* + diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 00000000..6a254baa --- /dev/null +++ b/docs/api.md @@ -0,0 +1,1164 @@ +--- +title: API Reference — DAARION.city & MicroDAO +version: 1.1.0 +status: canonical +last_updated: 2024-11-14 +--- + +> **Цей документ є актуальною API специфікацією для DAARION.city & MicroDAO.** +> Повна версія API з усіма ендпоінтами. Для MVP-версії див. `api-mvp.md`. + +# API Reference — DAARION.city & MicroDAO + +*Мінімальний набір MVP-ендпоінтів для інтеграції з DAARION.city* + +--- + +## 1. Overview + +Цей документ описує мінімальний набір API endpoints для: + +- **Wallet Service** — баланси, транзакції, staking, payouts +- **DAOFactory** — створення MicroDAO, емісія GOV/UTIL/REP +- **Registry** — реєстрація DAO, агентів, платформ +- **Vendor/Platform Registration** — реєстрація вендорів та платформ +- **Token-Gated Access** — перевірки DAAR/DAARION +- **Public Channel** — для інтеграції з сайтом +- **PDP Check** — Policy Decision Point endpoint +- **Agent Runtime / Router** — запуск агентів та роутера +- **System Events** — WebSocket підписка на події + +**Base URL:** `https://api.microdao.xyz/v1` + +**Authentication:** Bearer Token (JWT) + +--- + +## 2. Wallet API + +### 2.1 Get Balances + +```http +GET /wallet/balances +Authorization: Bearer {token} +``` + +**Response 200:** +```json +{ + "balances": [ + { + "symbol": "DAAR", + "balance": "100.50", + "staked": "50.00" + }, + { + "symbol": "DAARION", + "balance": "2.5", + "staked": "1.0" + }, + { + "symbol": "RINGK", + "balance": "0", + "staked": "0" + } + ] +} +``` + +--- + +### 2.2 Check Token Eligibility + +```http +GET /wallet/eligibility?action={action} +Authorization: Bearer {token} +``` + +**Query Parameters:** +- `action`: `dao.create` | `vendor.register` | `platform.create` + +**Response 200:** +```json +{ + "eligible": true, + "reason": "balance(DAAR) >= 1.00", + "required": { + "DAAR": 1.0, + "DAARION": 0.01 + }, + "current": { + "DAAR": 100.50, + "DAARION": 2.5 + } +} +``` + +--- + +### 2.3 Stake Tokens + +```http +POST /wallet/stake +Authorization: Bearer {token} +Content-Type: application/json + +{ + "symbol": "DAARION", + "amount": "1.0" +} +``` + +**Response 200:** +```json +{ + "success": true, + "transaction_id": "tx_123", + "staked": { + "symbol": "DAARION", + "amount": "1.0", + "total_staked": "2.0" + } +} +``` + +--- + +### 2.4 Get Payouts + +```http +GET /wallet/payouts?status={status} +Authorization: Bearer {token} +``` + +**Query Parameters:** +- `status`: `generated` | `claimed` | `failed` + +**Response 200:** +```json +{ + "payouts": [ + { + "id": "p_123", + "symbol": "KWT", + "amount": "250.00", + "rwa_ref": "rwa_456", + "status": "generated", + "created_at": "2024-11-14T10:00:00Z" + } + ] +} +``` + +--- + +### 2.5 Claim Payout + +```http +POST /wallet/payouts/{payoutId}/claim +Authorization: Bearer {token} +``` + +**Response 200:** +```json +{ + "success": true, + "payout_id": "p_123", + "claimed_at": "2024-11-14T10:05:00Z", + "new_balance": { + "symbol": "KWT", + "balance": "250.00" + } +} +``` + +--- + +## 3. DAOFactory API + +### 3.1 Create MicroDAO + +```http +POST /dao/create +Authorization: Bearer {token} +Content-Type: application/json + +{ + "name": "My MicroDAO", + "type": "community", // community | personal + "mode": "public", // public | confidential + "payment_token": "DAAR" // DAAR | DAARION +} +``` + +**PDP Check:** +- Перевіряє `balance(DAAR) >= 1.00` або `balance(DAARION) >= 0.01` +- Списує 1 DAAR (або еквівалент в DAARION) + +**Response 201:** +```json +{ + "dao_id": "dao_123", + "name": "My MicroDAO", + "slug": "my-microdao", + "type": "community", + "level": "A3", // A3 (public) or A4 (private) + "mode": "public", + "created_at": "2024-11-14T10:00:00Z" +} +``` + +--- + +### 3.2 Mint GOV Token + +```http +POST /dao/{daoId}/tokens/mint +Authorization: Bearer {token} +Content-Type: application/json + +{ + "token_type": "GOV", + "amount": "1000" +} +``` + +**PDP Check:** +- Перевіряє `balance(DAAR) >= 1.00` +- Списує 1 DAAR + +**Response 200:** +```json +{ + "success": true, + "token_type": "GOV", + "amount": "1000", + "transaction_id": "tx_456" +} +``` + +--- + +### 3.3 Mint UTIL Token + +```http +POST /dao/{daoId}/tokens/mint +Authorization: Bearer {token} +Content-Type: application/json + +{ + "token_type": "UTIL", + "amount": "5000" +} +``` + +**PDP Check:** +- Перевіряє `balance(DAAR) >= 1.00` +- Списує 1 DAAR + +**Response 200:** +```json +{ + "success": true, + "token_type": "UTIL", + "amount": "5000", + "transaction_id": "tx_789" +} +``` + +--- + +### 3.4 Mint REP Token + +```http +POST /dao/{daoId}/tokens/mint +Authorization: Bearer {token} +Content-Type: application/json + +{ + "token_type": "REP", + "amount": "1", + "recipient_id": "u_123" +} +``` + +**PDP Check:** +- Перевіряє `balance(DAAR) >= 1.00` +- Списує 1 DAAR + +**Response 200:** +```json +{ + "success": true, + "token_type": "REP", + "amount": "1", + "recipient_id": "u_123", + "transaction_id": "tx_012" +} +``` + +--- + +## 4. Registry API + +### 4.1 Register DAO in Registry + +```http +POST /registry/dao/register +Authorization: Bearer {token} +Content-Type: application/json + +{ + "dao_id": "dao_123", + "name": "My MicroDAO", + "type": "community", + "level": "A3", + "metadata": { + "description": "Description of DAO", + "tags": ["tech", "community"] + } +} +``` + +**Response 201:** +```json +{ + "success": true, + "registry_id": "reg_123", + "dao_id": "dao_123", + "registered_at": "2024-11-14T10:00:00Z" +} +``` + +--- + +### 4.2 Register Agent + +```http +POST /registry/agent/register +Authorization: Bearer {token} +Content-Type: application/json + +{ + "agent_id": "agent_123", + "dao_id": "dao_123", + "name": "Team Assistant", + "role": "team_assistant", + "capabilities": [ + "agent.run.invoke", + "chat.message.send", + "project.task.create" + ] +} +``` + +**Response 201:** +```json +{ + "success": true, + "registry_id": "reg_456", + "agent_id": "agent_123", + "registered_at": "2024-11-14T10:00:00Z" +} +``` + +--- + +### 4.3 Register Platform (A2) + +```http +POST /registry/platform/register +Authorization: Bearer {token} +Content-Type: application/json + +{ + "platform_code": "greenfood", + "name": "GREENFOOD", + "dao_id": "dao_789", + "level": "A2", + "metadata": { + "domain": "агро/харчові продукти", + "owner": "GREENFOOD microDAO" + } +} +``` + +**PDP Check:** +- Перевіряє `staked(DAARION) >= 1.00` +- Перевіряє роль Owner або Guardian + +**Response 201:** +```json +{ + "success": true, + "registry_id": "reg_789", + "platform_code": "greenfood", + "dao_id": "dao_789", + "registered_at": "2024-11-14T10:00:00Z" +} +``` + +--- + +## 5. Vendor/Platform Registration API + +### 5.1 Register Vendor + +```http +POST /platforms/{platformCode}/vendors/register +Authorization: Bearer {token} +Content-Type: application/json + +{ + "vendor_name": "My Farm", + "vendor_type": "producer" +} +``` + +**PDP Check:** +- Перевіряє `staked(DAARION) >= 0.01` +- Перевіряє доступ до платформи + +**Response 201:** +```json +{ + "success": true, + "vendor_id": "vendor_123", + "platform_code": "greenfood", + "registered_at": "2024-11-14T10:00:00Z" +} +``` + +--- + +### 5.2 Get Platform Info + +```http +GET /platforms/{platformCode} +``` + +**Response 200:** +```json +{ + "platform_code": "greenfood", + "name": "GREENFOOD", + "dao_id": "dao_789", + "level": "A2", + "status": "active", + "metadata": { + "domain": "агро/харчові продукти", + "owner": "GREENFOOD microDAO" + } +} +``` + +--- + +## 6. Token-Gated Access API + +### 6.1 Check Access + +```http +POST /access/check +Authorization: Bearer {token} +Content-Type: application/json + +{ + "action": "dao.create", + "resource": "dao", + "context": { + "dao_level": "A3" + } +} +``` + +**Response 200:** +```json +{ + "allow": true, + "reason": "balance(DAAR) >= 1.00", + "checked_at": "2024-11-14T10:00:00Z" +} +``` + +**Response 403:** +```json +{ + "allow": false, + "reason": "insufficient_balance", + "required": { + "DAAR": 1.0, + "DAARION": 0.01 + }, + "current": { + "DAAR": 0.5, + "DAARION": 0.005 + } +} +``` + +--- + +## 7. Public Channel API + +### 7.1 Get Public Channel Info + +```http +GET /channels/{slug}/public +``` + +**Response 200:** +```json +{ + "id": "daarion-city-general", + "team_id": "daarion-city", + "title": "Загальний канал міста", + "slug": "general", + "description": "Публічний канал для обговорення міських питань", + "message_count": 1234, + "member_count": 567, + "is_public": true, + "team": { + "id": "daarion-city", + "name": "DAARION.city", + "slug": "daarion" + } +} +``` + +--- + +### 7.2 Get Public Messages + +```http +GET /channels/{slug}/public/messages?limit=50&before={message_id} +``` + +**Response 200:** +```json +{ + "messages": [ + { + "id": "msg_123", + "sender": { + "id": "user_456", + "name": "Олександр", + "avatar_url": "https://..." + }, + "body": "Привіт, місто!", + "created_at": "2024-11-14T10:00:00Z", + "reactions": [] + } + ], + "pagination": { + "has_more": true, + "next_cursor": "msg_124" + } +} +``` + +--- + +### 7.3 Post Message (Authenticated) + +```http +POST /channels/{slug}/public/messages +Authorization: Bearer {token} +Content-Type: application/json + +{ + "body": "Повідомлення від користувача" +} +``` + +**Response 201:** +```json +{ + "id": "msg_125", + "sender": { + "id": "user_789", + "name": "Марія" + }, + "body": "Повідомлення від користувача", + "created_at": "2024-11-14T10:05:00Z" +} +``` + +--- + +### 7.4 Join Public Channel + +```http +POST /channels/{slug}/public/join +Content-Type: application/json + +{ + "email": "user@example.com", + "name": "Ім'я Користувача", + "viewer_type": "member" // member | visitor +} +``` + +**Response 200:** +```json +{ + "user_id": "user_789", + "access_token": "jwt-token", + "membership": { + "role": "member", + "viewer_type": "member" + } +} +``` + +--- + +## 8. TokenBridge API + +### 8.1 Exchange UTIL → DAAR + +```http +POST /bridge/exchange +Authorization: Bearer {token} +Content-Type: application/json + +{ + "from_token": "UTIL", + "to_token": "DAAR", + "amount": "100", + "dao_id": "dao_123" +} +``` + +**Response 200:** +```json +{ + "success": true, + "exchange_rate": 0.85, + "from": { + "token": "UTIL", + "amount": "100" + }, + "to": { + "token": "DAAR", + "amount": "85" + }, + "transaction_id": "tx_345" +} +``` + +--- + +## 9. DAARsales / DAARIONsales API + +### 9.1 Buy DAAR + +```http +POST /sales/daar/buy +Authorization: Bearer {token} +Content-Type: application/json + +{ + "amount_usdt": "100", + "payment_method": "USDT" // USDT | POL +} +``` + +**Response 200:** +```json +{ + "success": true, + "daar_received": "100", + "transaction_id": "tx_678", + "new_balance": { + "DAAR": "200.50" + } +} +``` + +--- + +### 9.2 Exchange DAAR → DAARION + +```http +POST /sales/daarion/exchange +Authorization: Bearer {token} +Content-Type: application/json + +{ + "daar_amount": "100" +} +``` + +**Response 200:** +```json +{ + "success": true, + "daarion_received": "1", + "exchange_rate": 100, + "transaction_id": "tx_901", + "new_balance": { + "DAARION": "3.5" + } +} +``` + +--- + +## 10. PDP Check API + +### 10.1 Check Access (PDP) + +```http +POST /pdp/check +Authorization: Bearer {token} +Content-Type: application/json + +{ + "subject": { + "id": "u_123", + "type": "user" // user | agent | integration | embassy + }, + "team_id": "t_456", + "action": "dao.create", + "resource": { + "id": "dao_001", + "team_id": "t_456", + "mode": "public" + }, + "key_id": "ak_789", + "context": { + "ip": "1.2.3.4", + "ua": "Mozilla/5.0", + "timestamp": 1700000000 + } +} +``` + +**Response 200:** +```json +{ + "allow": true, + "reason": "ok", + "checked_at": "2024-11-14T10:00:00Z" +} +``` + +**Response 403:** +```json +{ + "allow": false, + "reason": "insufficient_balance", + "details": { + "required": { + "DAAR": 1.0, + "DAARION": 0.01 + }, + "current": { + "DAAR": 0.5, + "DAARION": 0.005 + } + } +} +``` + +--- + +## 11. Agent Runtime / Router API + +### 11.1 Run Agent + +```http +POST /agent/run +Authorization: Bearer {token} +Content-Type: application/json + +{ + "agent_id": "agent_123", + "input": "Створи задачу з обговорення в каналі #general", + "context": { + "team_id": "t_456", + "channel_id": "c_789", + "confidential": false + } +} +``` + +**Response 200:** +```json +{ + "run_id": "run_123", + "agent_id": "agent_123", + "status": "running", + "created_at": "2024-11-14T10:00:00Z" +} +``` + +--- + +### 11.2 Get Agent Run Status + +```http +GET /agent/run/{runId}/status +Authorization: Bearer {token} +``` + +**Response 200:** +```json +{ + "run_id": "run_123", + "status": "completed", + "result": { + "task_id": "task_456", + "message": "Задачу створено успішно" + }, + "created_at": "2024-11-14T10:00:00Z", + "completed_at": "2024-11-14T10:00:05Z" +} +``` + +--- + +### 11.3 Router Invoke (DAARWIZZ) + +```http +POST /router/invoke +Authorization: Bearer {token} +Content-Type: application/json + +{ + "input": "Підготуй звіт по проєкту за останній місяць", + "goal": "Generate monthly project report", + "constraints": { + "max_cost": "10.0", + "max_steps": 10 + }, + "context": { + "team_id": "t_456", + "agent_run_id": "ar_777", + "confidential": false + }, + "mode": "auto", // auto | structured | hybrid + "tools": ["math", "project", "llm"] +} +``` + +**Response 200:** +```json +{ + "run_id": "router_123", + "status": "planning", + "plan": [ + { + "step": 1, + "tool": "project", + "action": "get_project_summary", + "args": { + "project_id": "p_001" + } + }, + { + "step": 2, + "tool": "llm", + "action": "generate_report", + "args": { + "template": "monthly_report" + } + } + ], + "created_at": "2024-11-14T10:00:00Z" +} +``` + +--- + +### 11.4 Get Router Run Status + +```http +GET /router/run/{runId}/status +Authorization: Bearer {token} +``` + +**Response 200:** +```json +{ + "run_id": "router_123", + "status": "done", + "result": { + "report_url": "https://...", + "steps_completed": 2, + "cost": "8.5" + }, + "created_at": "2024-11-14T10:00:00Z", + "completed_at": "2024-11-14T10:00:15Z" +} +``` + +--- + +## 12. System Events API + +### 12.1 Subscribe to Events (WebSocket) + +```http +GET /events/subscribe?streams={streams} +Authorization: Bearer {token} +Upgrade: websocket +``` + +**Query Parameters:** +- `streams`: Comma-separated list of streams (e.g., `dao,wallet,agent`) + +**WebSocket Messages:** + +**Event: `dao.created`** +```json +{ + "event_id": "evt_123", + "ts": "2024-11-14T10:00:00Z", + "domain": "dao", + "type": "dao.created", + "version": 1, + "actor": { + "id": "u_123", + "kind": "user" + }, + "payload": { + "dao_id": "dao_456", + "name": "My MicroDAO", + "type": "community", + "level": "A3", + "mode": "public" + }, + "meta": { + "team_id": "dao_456", + "trace_id": "trace_abc" + } +} +``` + +**Event: `vendor.registered`** +```json +{ + "event_id": "evt_124", + "ts": "2024-11-14T10:05:00Z", + "domain": "platform", + "type": "vendor.registered", + "version": 1, + "actor": { + "id": "u_123", + "kind": "user" + }, + "payload": { + "vendor_id": "vendor_789", + "platform_code": "greenfood", + "vendor_name": "My Farm", + "vendor_type": "producer" + }, + "meta": { + "platform_code": "greenfood", + "trace_id": "trace_def" + } +} +``` + +**Event: `platform.created`** +```json +{ + "event_id": "evt_125", + "ts": "2024-11-14T10:10:00Z", + "domain": "platform", + "type": "platform.created", + "version": 1, + "actor": { + "id": "u_123", + "kind": "user" + }, + "payload": { + "platform_code": "greenfood", + "name": "GREENFOOD", + "dao_id": "dao_789", + "level": "A2" + }, + "meta": { + "platform_code": "greenfood", + "trace_id": "trace_ghi" + } +} +``` + +**Event: `agent.run.started`** +```json +{ + "event_id": "evt_126", + "ts": "2024-11-14T10:15:00Z", + "domain": "agent", + "type": "agent.run.started", + "version": 1, + "actor": { + "id": "agent_123", + "kind": "agent" + }, + "payload": { + "run_id": "run_123", + "agent_id": "agent_123", + "input": "Створи задачу", + "context": { + "team_id": "t_456", + "channel_id": "c_789" + } + }, + "meta": { + "team_id": "t_456", + "trace_id": "trace_jkl" + } +} +``` + +**Event: `wallet.payout.generated`** +```json +{ + "event_id": "evt_127", + "ts": "2024-11-14T10:20:00Z", + "domain": "wallet", + "type": "wallet.payout.generated", + "version": 1, + "actor": { + "id": "system", + "kind": "service" + }, + "payload": { + "payout_id": "p_123", + "team_id": "t_456", + "symbol": "KWT", + "amount": "250.00", + "rwa_ref": "rwa_789" + }, + "meta": { + "team_id": "t_456", + "trace_id": "trace_mno" + } +} +``` + +--- + +### 12.2 Get Event History + +```http +GET /events/history?stream={stream}&limit=50&before={event_id} +Authorization: Bearer {token} +``` + +**Query Parameters:** +- `stream`: Event stream name (e.g., `dao`, `wallet`, `agent`) +- `limit`: Number of events to return (default: 50) +- `before`: Event ID to start from (cursor pagination) + +**Response 200:** +```json +{ + "events": [ + { + "event_id": "evt_123", + "ts": "2024-11-14T10:00:00Z", + "type": "dao.created", + "payload": { ... } + } + ], + "pagination": { + "has_more": true, + "next_cursor": "evt_124" + } +} +``` + +--- + +## 13. Error Responses + +### Standard Error Format + +```json +{ + "error": { + "code": "insufficient_balance", + "message": "Insufficient DAAR balance. Required: 1.00, Current: 0.50", + "details": { + "required": { + "DAAR": 1.0 + }, + "current": { + "DAAR": 0.5 + } + } + } +} +``` + +### Common Error Codes + +- `insufficient_balance` — недостатній баланс токенів +- `access_denied` — доступ заборонено (PDP) +- `invalid_token` — невалідний токен +- `quota_exceeded` — перевищено квоту +- `resource_not_found` — ресурс не знайдено +- `rate_limit_exceeded` — перевищено rate limit + +--- + +## 14. Rate Limiting + +### Global Limits + +- **Guest (read-only):** 100 requests/minute +- **Authenticated (write):** 30 requests/minute +- **Join requests:** 5 requests/hour per IP + +### Per-Endpoint Limits + +- **Wallet operations:** 10 requests/minute +- **DAOFactory:** 5 requests/hour +- **Registry:** 20 requests/minute + +--- + +## 15. Integration with Other Docs + +Цей документ інтегрується з: + +- `pdp_access.md` — PDP та система доступів +- `tokenomics/city-tokenomics.md` — токеноміка та правила +- `agents.md` — агенти та їх права +- `microdao-architecture.md` — архітектура A1-A4 +- `microdao-admin-console.md` — адмін-панель для всіх MicroDAO +- `superdao-federation.md` — SuperDAO та федерації +- `integration-daarion.md` — інтеграція з сайтом + +--- + +## 16. Changelog + +### v1.1.0 — 2024-11-14 +- Додано PDP Check API +- Додано Agent Runtime / Router API (stub) +- Додано System Events API (WebSocket subscribe, event history) +- Додано події: dao.created, vendor.registered, platform.created, agent.run.started, wallet.payout.generated + +### v1.0.0 — 2024-11-14 +- Початкова версія API специфікації +- Додано Wallet API (баланси, staking, payouts) +- Додано DAOFactory API (створення DAO, емісія GOV/UTIL/REP) +- Додано Registry API (реєстрація DAO, агентів, платформ) +- Додано Vendor/Platform Registration API +- Додано Token-Gated Access API +- Додано Public Channel API +- Додано TokenBridge API +- Додано DAARsales/DAARIONsales API + +--- + +**Версія:** 1.1.0 +**Останнє оновлення:** 2024-11-14 +*Документ готовий до інтеграції у Cursor, GitHub або будь-який інший проект.* + diff --git a/docs/core-services-mvp.md b/docs/core-services-mvp.md new file mode 100644 index 00000000..65c1fd0e --- /dev/null +++ b/docs/core-services-mvp.md @@ -0,0 +1,338 @@ +--- +title: Core Services (MVP) — Wallet, DAOFactory, Registry, PDP +version: 1.0.0 +status: canonical +last_updated: 2024-11-14 +--- + +# Core Services (MVP) — Wallet, DAOFactory, Registry, PDP + +**Мета цього документа — формалізувати мінімальний набір core-сервісів для MVP MicroDAO / DAARION.city.** + +Ці сервіси є "хребтом" системи: + +* **Wallet Service** — токени DAAR / DAARION, базові перевірки доступу. +* **DAOFactory Service** — створення MicroDAO та платформ. +* **Registry Service** — каталог DAO і платформ. +* **PDP Service** — єдина точка прийняття рішень по доступу. + +Документ повʼязує високорівневі документи (`overview.md`, `microdao-architecture.md`, `pdp_access.md`, `api.md`) з конкретними сервісами, які треба реалізувати в коді. + +--- + +# 1. Загальна картина + +MVP передбачає роботу чотирьох базових сервісів: + +1. **Wallet Service** + + * читає баланси DAAR / DAARION + * надає util-методи для перевірки доступу (balance/stake) + +2. **DAOFactory Service** + + * створює MicroDAO (A3/A4) + * створює платформи (A2) + * ініціалізує базові метадані DAO + +3. **Registry Service** + + * зберігає всі DAO + * зберігає всі платформи (позначені як A2) + * надає публічний каталог DAO/платформ + +4. **PDP Service** + + * приймає рішення, чи дозволена дія (`allow/deny/require-elevation`) + * використовується Wallet, DAOFactory, Registry та іншими модулями + +--- + +# 2. Wallet Service (MVP) + +## 2.1 Відповідальність + +* зчитування балансів DAAR / DAARION користувача +* зчитування стейкінгу DAARION (для доступу до платформ/ролей) +* надання простих helper-функцій типу: + + * `hasEnoughForDaoCreate(user)` + * `hasEnoughForVendorRegister(user)` + * `hasEnoughForPlatformCreate(user)` + +Фінансові транзакції, стейкінг, payout-и **не входять у MVP** (можуть бути заглушені або відкладені). + +## 2.2 Інтерфейс (логічний) + +```ts +type TokenSymbol = 'DAAR' | 'DAARION'; + +interface WalletService { + getBalances(userId: string): Promise>; + + hasEnoughForDaoCreate(userId: string): Promise; + hasEnoughForVendorRegister(userId: string): Promise; + hasEnoughForPlatformCreate(userId: string): Promise; +} +``` + +## 2.3 Інтеграція з API + +Мапінг на `api.md`: + +* `GET /api/v1/wallet/me` → `getBalances` +* `POST /api/v1/wallet/check-access` → використовує `hasEnough*`-методи + +## 2.4 Залежності + +* зовнішній або внутрішній модуль для читання ончейн-даних (або stub) +* PDP (на наступних фазах, якщо будуть складніші правила) + +--- + +# 3. DAOFactory Service (MVP) + +## 3.1 Відповідальність + +* створення нових DAO (A3/A4) +* створення платформ (A2) — з маркуванням рівня та типу +* валідація вхідних параметрів +* виклик PDP для перевірки прав +* запис DAO у Registry + +## 3.2 Інтерфейс (логічний) + +```ts +interface CreateDaoInput { + name: string; + description?: string; + type: 'public' | 'private'; + level: 'A3' | 'A4'; + settings?: Record; +} + +interface CreatePlatformInput { + name: string; + slug: string; + description?: string; + domain?: string; // 'energy' | 'food' | 'water' | ... +} + +interface DaoFactoryService { + createDao(userId: string, input: CreateDaoInput): Promise<{ daoId: string }>; + createPlatform(userId: string, input: CreatePlatformInput): Promise<{ daoId: string }>; +} +``` + +## 3.3 Інтеграція з API + +Мапінг на `api.md`: + +* `POST /api/v1/dao` → `createDao` +* `POST /api/v1/platforms` → `createPlatform` + +## 3.4 Залежності + +* **Wallet Service** — перевірка наявності DAAR/DAARION +* **PDP Service** — `policy.dao.create`, `policy.platform.create` +* **Registry Service** — запис нового DAO / платформи + +--- + +# 4. Registry Service (MVP) + +## 4.1 Відповідальність + +* зберігання інформації про всі DAO +* маркування DAO як платформи (A2) або MicroDAO (A3/A4) +* надання публічного каталогу DAO/платформ + +## 4.2 Мінімальна модель DAO + +```ts +interface DaoRecord { + daoId: string; + name: string; + description?: string; + level: 'A1' | 'A2' | 'A3' | 'A4'; + type: 'platform' | 'public' | 'private'; + parentDaoId?: string | null; + federationMode: 'none' | 'member' | 'superdao'; + createdAt: string; +} +``` + +## 4.3 Інтерфейс (логічний) + +```ts +interface RegistryService { + saveDao(record: DaoRecord): Promise; + + getDaoById(daoId: string): Promise; + + listDaos(filter?: { level?: string; type?: string }): Promise; + + listPlatforms(): Promise; // level A2, type = 'platform' +} +``` + +## 4.4 Інтеграція з API + +Мапінг на `api.md`: + +* `GET /api/v1/dao/{dao_id}` → `getDaoById` +* `GET /api/v1/dao` → `listDaos` +* `GET /api/v1/platforms` → `listPlatforms` + +## 4.5 Залежності + +* немає критичних зовнішніх залежностей (простий сервіс над БД) +* може використовувати PDP для фільтрації приватних DAO + +--- + +# 5. PDP Service (MVP) + +## 5.1 Відповідальність + +* централізоване прийняття рішень про доступ +* інтерпретація політик із `pdp_access.md` +* надання простого API для інших сервісів + +## 5.2 Основний інтерфейс + +```ts +export type Decision = 'allow' | 'deny' | 'require-elevation'; + +interface PdpContext { + userId?: string; + daoId?: string; + daoLevel?: 'A1' | 'A2' | 'A3' | 'A4'; + // додатковий контекст: ролі, баланси, стейкінг тощо +} + +interface PdpService { + check(policyId: string, resource: Record, context: PdpContext): Promise<{ + decision: Decision; + reason?: string; + }>; +} +``` + +## 5.3 Приклади використання + +### 5.3.1 DAOFactory → створення DAO + +```ts +const res = await pdp.check('policy.dao.create', { type: 'dao' }, { userId, daoLevel: 'A3' }); +if (res.decision !== 'allow') throw new Error('ACCESS_DENIED'); +``` + +### 5.3.2 Vendor → реєстрація на платформі + +```ts +const res = await pdp.check('policy.vendor.register', { platformId }, { userId, daoId: platformDaoId, daoLevel: 'A2' }); +``` + +## 5.4 Інтеграція з API + +Мапінг на `api.md`: + +* `POST /api/v1/pdp/check` → обгортка над `PdpService.check` (діагностика/адмінки) + +## 5.5 Залежності + +* **Wallet Service** — для перевірки балансів +* **Registry Service** — для визначення рівня DAO +* джерело політик (конфіги/БД) + +--- + +# 6. Потоки взаємодії (MVP) + +## 6.1 Створення DAO (користувач → MicroDAO) + +1. Frontend → `POST /api/v1/dao` +2. API → DAOFactory Service +3. DAOFactory → WalletService (`hasEnoughForDaoCreate`) +4. DAOFactory → PDP Service (`policy.dao.create`) +5. DAOFactory → Registry (`saveDao`) +6. Повернення `dao_id` користувачу + +## 6.2 Створення платформи + +1. Frontend → `POST /api/v1/platforms` +2. DAOFactory → WalletService (`hasEnoughForPlatformCreate`) +3. DAOFactory → PDP (`policy.platform.create`) +4. DAOFactory → Registry (`saveDao` із level=A2, type=platform) + +## 6.3 Реєстрація вендора + +1. Frontend → `POST /api/v1/platforms/{id}/vendors` +2. Service → PDP (`policy.vendor.register`) +3. Якщо `allow` → запис у БД + +--- + +# 7. MVP Scope vs. Future Scope + +## 7.1 Входить у MVP + +* Wallet Service: лише читання балансів + прості перевірки +* DAOFactory: створення DAO/платформ +* Registry: читання/запис DAO, список платформ +* PDP: базові політики (див. `pdp_access.md`) + +## 7.2 Поза рамками MVP (може бути додано пізніше) + +* повні транзакції DAAR/DAARION +* стейкінг (on-chain інтеграція) +* payout-и й автоматичний розподіл винагород +* розширені політики PDP (rate-limits, time-based rules) +* audit trails на рівні подій (окремий сервіс) + +--- + +# 8. Використання цього документа + +Цей документ служить + +* **для бекенд-розробників** — як точний опис того, які сервіси реалізувати й які інтерфейси їм дати; +* **для архітекторів** — як карта залежностей між Wallet, DAOFactory, Registry, PDP; +* **для фронтенду** — як звʼязок між API (`api.md`) і внутрішньою логікою. + +Наступний крок після цього документа — створення каркасів сервісів у коді (наприклад, у `/services/wallet`, `/services/dao-factory`, `/services/registry`, `/services/pdp`). + +--- + +## 9. Integration with Other Docs + +Цей документ інтегрується з: + +- `overview.md` — загальний огляд системи +- `microdao-architecture.md` — архітектура A1-A4 +- `pdp_access.md` — PDP та система доступів +- `api.md` / `api-mvp.md` — API специфікації +- `superdao-federation.md` — SuperDAO та федерації +- `tokenomics/city-tokenomics.md` — токеноміка + +--- + +## 10. Changelog + +### v1.0.0 — 2024-11-14 +- Початкова версія специфікації Core Services (MVP) +- Додано Wallet Service (читання балансів, перевірки доступу) +- Додано DAOFactory Service (створення DAO та платформ) +- Додано Registry Service (каталог DAO та платформ) +- Додано PDP Service (централізоване прийняття рішень) +- Додано потоки взаємодії між сервісами +- Додано розмежування MVP vs Future Scope + +--- + +**Версія:** 1.0.0 +**Останнє оновлення:** 2024-11-14 +*Документ готовий до інтеграції у Cursor, GitHub або будь-який інший проект.* + + diff --git a/docs/cursor/08_agent_first_onboarding.md b/docs/cursor/08_agent_first_onboarding.md new file mode 100644 index 00000000..0a6cf651 --- /dev/null +++ b/docs/cursor/08_agent_first_onboarding.md @@ -0,0 +1,474 @@ +# 08 — Agent-First Onboarding Specification (MicroDAO) + +Цей документ описує нову модель онбордингу MicroDAO: +**користувач входить у чат з агентом-провідником, який крок за кроком створює спільноту, канал і налаштовує агента.** + +Весь процес — діалоговий. +Усі API-виклики — ті самі, що в 03_api_core_snapshot.md. + +--- + +# 1. Мета + +Замінити класичні форми/кроки онбордингу повністю **агентським інтерфейсом**. +Увесь onboarding виконується через `AgentOnboardingChat`, який: + +- говорить з користувачем живою мовою, +- ставить запитання, +- парсить відповіді, +- викликає API, +- підтверджує успішні кроки, +- веде користувача до створення першої microDAO, +- налаштовує приватного агента, +- завершує онбординг фразою та редіректом. + +--- + +# 2. Загальна архітектура + +Усі дії будуються на: + +- **state-machine** (опис нижче), +- **Chat UI** (аналог звичайного чату), +- **репліках агента** (скрипт), +- **розпізнаванні наміру користувача** (regex / LLM / кнопки), +- **викликах API** (з 03_api_core_snapshot.md). + +Компоненти: + +``` +src/features/onboarding-agent/ + AgentOnboardingChat.tsx + useOnboardingState.ts + scripts/ + script.json + parser.ts + transitions.ts +``` + +--- + +# 3. State Machine + +```ts +type OnboardingStep = + | "greet" + | "ask_profile" + | "ask_team_name" + | "ask_team_desc" + | "ask_mode" + | "ask_channel_name" + | "ask_channel_type" + | "ask_agent_enable" + | "ask_agent_prefs" + | "ask_invites" + | "done"; +``` + +Перехід між кроками базується на: + +* відповіді користувача, +* успішності API-виклику. + +--- + +# 4. Повний сценарій діалогу (репліки агента) + +Нижче — готовий сценарій, який можна покласти в JSON або хардкод. + +## 4.1. greet + +**Агент:** + +> Привіт! Я — агент-провідник MicroDAO. +> Зараз ми разом створимо твою першу спільноту та особистого помічника. +> Як до тебе звертатися? + +Після відповіді → `ask_profile`. + +--- + +## 4.2. ask_profile + +**Агент:** + +> Приємно познайомитися, {name}. +> Якою мовою хочеш працювати — українською чи англійською? + +Після відповіді — зберегти `locale` → `ask_team_name`. + +--- + +## 4.3. ask_team_name + +**Агент:** + +> Як назвемо твою майбутню microDAO? +> Наприклад: "Креативна Майстерня", "AI-Команда Альфа", "Моя Спільнота". + +Читаємо будь-який текст → `POST /teams` → `ask_team_desc`. + +--- + +## 4.4. ask_team_desc + +**Агент:** + +> Класно. А як би ти описав спільноту одним реченням? +> (Не обов'язково, можеш написати "пропустити".) + +Зберегти опис → `ask_mode`. + +--- + +## 4.5. ask_mode + +**Агент:** + +> Обери режим для твоєї microDAO: +> **1)** Відкрита — є публічний канал, гості можуть читати. +> **2)** Приватна — тільки запрошені, чати зашифровані. +> Напиши `1` або `2`. + +Після відповіді: + +* map → `"public"` / `"confidential"` +* `PATCH /teams/{teamId}` + → `ask_channel_name`. + +--- + +## 4.6. ask_channel_name + +**Агент:** + +> Давай створимо перший канал. +> Як би ти хотів його назвати? (`general`, `core`, `support`) + +Після відповіді → `ask_channel_type`. + +--- + +## 4.7. ask_channel_type + +**Агент:** + +> Це буде публічний канал чи приватна кімната? +> Напиши: **public** або **private**. + +Mapping: + +* `public` → `type: "public"` +* `private` → `type: "group"` + +API: +`POST /channels` + +Після успіху → `ask_agent_enable`. + +--- + +## 4.8. ask_agent_enable + +**Агент:** + +> У MicroDAO кожна спільнота має власного ШІ-агента, який памʼятає контекст і самонавчається. +> Хочеш одразу створити командного агента? + +Очікувані відповіді: так / ні. + +* Якщо «ні» → `ask_invites` +* Якщо «так» → `ask_agent_prefs` + +--- + +## 4.9. ask_agent_prefs + +**Агент:** + +> Добре. Налаштуємо агента. +> Якою мовою він має відповідати? + +Після відповіді → + +**Агент:** + +> Який у нього фокус? +> Вибери одне: **general**, **business**, **technical**, **creative**. + +Після відповіді → + +**Агент:** + +> Що він має памʼятати? +> +> 1. Лише цей канал +> 2. Усі канали спільноти + +Після відповіді: + +Викликаємо: +`POST /agents` + +Потім → `ask_invites`. + +--- + +## 4.10. ask_invites + +**Агент:** + +> Все готово! +> Хочеш зараз запросити людей до своєї microDAO? +> Я підготую посилання, яке можна надіслати будь-кому. + +Після відповіді — показати UI-елемент з інвайт-лінком. + +→ `done`. + +--- + +## 4.11. done + +**Агент:** + +> Вітаю! +> Твоя microDAO **{team.name}** створена. +> Я створив канал **#{channel.title}** і готовий допомагати. +> Можеш почати працювати або поставити мені питання: +> "Що ти вмієш?" / "Як користуватися каналами?" / "Як запросити команду?" + +redirect → `/t/:teamId/c/:channelId`. + +--- + +# 5. Intent Parser (як агент розуміє відповіді) + +Мінімальний підхід (regex): + +```ts +function parseMode(input: string) { + if (input.match(/1|пуб/i)) return "public"; + if (input.match(/2|прив/i)) return "confidential"; +} +``` + +```ts +function parseYesNo(input: string) { + if (input.match(/^так|yes|y$/i)) return true; + if (input.match(/^ні|no|n$/i)) return false; +} +``` + +Або гібридний: + +* парсимо regex, +* якщо незрозуміло → питаємо LLM: + *"Чи відповідь користувача означає Так/Ні/Інше?"* + +--- + +# 6. Компонент `AgentOnboardingChat.tsx` + +### Мінімальна структура: + +```tsx +export function AgentOnboardingChat() { + const { step, setStep, state, updateState } = useOnboardingState(); + + const handleUserMessage = async (text: string) => { + addMessage({ author: "user", text }); + + switch (step) { + case "greet": + updateState({ name: text }); + addAgent("Приємно познайомитися, " + text + "..."); + setStep("ask_profile"); + break; + + case "ask_profile": + updateState({ locale: detectLocale(text) }); + addAgent("Як назвемо твою microDAO?"); + setStep("ask_team_name"); + break; + + case "ask_team_name": + const team = await api.post("/teams", { name: text }); + updateState({ teamId: team.id }); + addAgent("А як би ти описав спільноту?"); + setStep("ask_team_desc"); + break; + + // ... і так далі для кожного step. + } + }; + + return ( + + ); +} +``` + +--- + +# 7. Acceptance Criteria (як перевіряти) + +* `/onboarding` відкривається як чат. +* Користувач спілкується з агентом. +* На кожному кроці агент відповідає правильно. +* Усі API виклики працюють: + + * `/teams` + * `/teams/{id}` + * `/channels` + * `/agents` +* Після завершення → redirect. +* UX: користувач не бачить жодної форми. Все — діалог. + +--- + +# 8. Для Cursor + +Коли ти даси йому задачу, використовуй цей формат: + +``` +You are a senior React/TS engineer. + +Implement the Agent-first onboarding at `/onboarding` using the specification in: +- 08_agent_first_onboarding.md +- 03_api_core_snapshot.md +- 05_coding_standards.md + +Create the component `AgentOnboardingChat.tsx` and supporting files. + +Output: +- list of modified files +- diff +- summary +``` + +--- + +# 9. Інтеграція з існуючим кодом + +## 9.1. Заміна класичного онбордингу + +Існуючий `OnboardingPage.tsx` можна: +- залишити як fallback для користувачів, які не хочуть агентський онбординг, +- або повністю замінити на `AgentOnboardingChat`. + +## 9.2. Використання API клієнтів + +Використовувати існуючі API клієнти з `src/api/`: +- `teams.ts` — для створення команди +- `channels.ts` — для створення каналу +- `agents.ts` — для створення агента +- `auth.ts` — для автентифікації + +## 9.3. State Management + +Використовувати `useOnboardingState` hook або розширити існуючий `useOnboarding.ts` для агентського онбордингу. + +--- + +# 10. UI/UX Вимоги + +## 10.1. Chat Interface + +- Повідомлення агента з аватаром +- Повідомлення користувача справа +- Індикатор набору тексту (typing indicator) під час обробки +- Кнопки швидких відповідей (опціонально) +- Плавні анімації появи повідомлень + +## 10.2. Візуальні елементи + +- Аватар агента (іконка або зображення) +- Індикатор прогресу онбордингу (опціонально) +- Підказки для користувача +- Обробка помилок з дружніми повідомленнями + +## 10.3. Мобільна адаптація + +- Адаптивний дизайн для мобільних пристроїв +- Зручний ввід тексту на мобільних +- Оптимізація для маленьких екранів + +--- + +# 11. Обробка помилок + +## 11.1. Помилки API + +Якщо API виклик не вдався: +- Показати дружнє повідомлення від агента +- Запропонувати спробувати ще раз +- Зберегти стан, щоб не втратити прогрес + +## 11.2. Незрозумілі відповіді + +Якщо агент не розуміє відповідь: +- Задати уточнююче питання +- Показати приклади правильних відповідей +- Запропонувати кнопки з варіантами + +## 11.3. Таймаути + +- Обробка повільних API викликів +- Показ індикатора завантаження +- Повідомлення про затримку + +--- + +# 12. Тестування + +## 12.1. Unit Tests + +- Тести для `parser.ts` (розпізнавання намірів) +- Тести для `transitions.ts` (переходи між станами) +- Тести для компонента `AgentOnboardingChat` + +## 12.2. Integration Tests + +- Тестування повного flow онбордингу +- Тестування API інтеграції +- Тестування обробки помилок + +## 12.3. E2E Tests + +- Повний сценарій онбордингу від початку до кінця +- Різні варіанти відповідей користувача +- Перевірка редіректу після завершення + +--- + +# 13. Майбутні покращення + +## 13.1. LLM Integration + +- Використання LLM для розпізнавання намірів +- Більш природна мова агента +- Контекстне розуміння відповідей + +## 13.2. Персоналізація + +- Адаптація мови агента під користувача +- Запам'ятовування попередніх відповідей +- Рекомендації на основі профілю + +## 13.3. Мультимовність + +- Підтримка багатьох мов +- Автоматичне визначення мови +- Перемикання мови під час онбордингу + +--- + +**Готово.** +Це **повна специфікація агентського онбордингу**, готова до використання в Cursor. + + diff --git a/docs/cursor/09_evolutionary_agent.md b/docs/cursor/09_evolutionary_agent.md new file mode 100644 index 00000000..8acca8fb --- /dev/null +++ b/docs/cursor/09_evolutionary_agent.md @@ -0,0 +1,550 @@ +# 09 — Evolutionary Agent (Self-Improving AI) for MicroDAO + +Цей документ описує архітектуру та принципи роботи самонавчального агента MicroDAO. +Агент вміє: + +- аналізувати свої відповіді, +- виявляти помилки і прогалини, +- створювати пропозиції покращень, +- еволюціонувати через зміни правил, FAQ, мікро-навичок, +- вчитись на поведінці клієнтів та спільноти, +- надавати журнали змін (версії), +- взаємодіяти з DAGI через анонімізований Train-to-Earn. + +--- + +# 1. Мета + +Створити **особистого eволюційного агента** для кожної microDAO: + +- приватного, +- адаптивного, +- підконтрольного користувачу, +- який стає розумнішим з часом, +- але не змінює глобальну LLM-модель, +- а накопичує *власний досвід*: правила, пам'ять, патерни, мікро-навички. + +Це перетворює microDAO на **живий цифровий організм**, який виростає з досвіду команди. + +--- + +# 2. Архітектура (3 рівні мозку) + +Еволюційний агент складається з трьох шарів. + +## 2.1. Рівень 0 — Базова LLM (Frozen Model) + +- GPT/Claude/локальна модель. +- Не модифікується. +- Відповідає за мовні і логічні здібності. + +## 2.2. Рівень 1 — Пам'ять та контекст + +- Контекст сесій. +- Векторна пам'ять (Co-Memory microDAO). +- Профіль агента (тон, роль, лексика, мова). +- Налаштування приватності та доступу. + +Працює як «довгострокова кора». + +## 2.3. Рівень 2 — Meta-Agent (Self-Improvement Layer) + +Це ядро еволюції. + +Включає: + +- аналіз діалогів, +- фідбеки користувачів, +- пошук недоліків, +- генерацію покращень, +- контроль застосування, +- трекінг версій. + +--- + +# 3. Компоненти Meta-Agent + +## 3.1. Feedback Collector + +Збирає сигнали якості: + +1. 👍 / 👎 + +2. Правки користувача (коли людина переписує відповідь) + +3. Маркери: + + - «не по темі» + - «неправильна відповідь» + - «занадто загально» + - «довго» + +4. Explicit Correction + Користувач каже: + > «Замість цього говори так…» + +Усе це зберігається як *мета-телеметрія*. + +--- + +## 3.2. Pattern Analyzer + +Раз на N діалогів/годин agent запускає self-review job. + +Він виявляє: + +- повторювані типи питань, +- категорії помилок, +- патерни, де агент слабкий, +- пропущені інструкції. + +--- + +## 3.3. Improvement Generator + +Генерує пропозиції змін: + +Типи змін: + +1. Нове правило (instruction) + +2. Новий шаблон відповіді + +3. FAQ-елементи + +4. Новий «skill» + (регулярний патерн → мікро-інструмент / chain) + +5. Мета-тести + (питання, з якими агент має справлятися) + +Приклади: + +- «Додавати приклади у відповідях команді design.» +- «Уникай надто формального тону в каналi #marketing.» +- «Коли питають про дедлайни — уточнюй контекст.» + +--- + +## 3.4. User Approval Layer (Manual Control) + +Агент НІКОЛИ не застосовує зміни сам. + +Формує список пропозицій у вигляді: + +``` +• Пропозиція №17 +Тип: Нове правило +Текст: "Якщо user → українська, відповідай українською." +Джерело: 13 подібних ситуацій. +[Прийняти] [Відхилити] [Редагувати] +``` + +Це ключова відмінність MicroDAO від централізованих систем: + +**користувач контролює еволюцію інтелекту.** + +--- + +## 3.5. Versioning Engine + +Веде історію еволюції: + +- v0 — чистий агент +- v1 — після перших 20 діалогів +- v2 — після 100 діалогів +- … + +Кожна версія містить: + +- список правил, +- diff памʼяті, +- список навичок, +- історію змін. + +UI показує «дерево еволюції». + +--- + +# 4. UI/UX модуля "Еволюція агента" + +## 4.1. Вкладка 1 — Огляд + +Показує: + +- версію агента, +- скільки правил застосовано, +- скільки покращень очікує. + +--- + +## 4.2. Вкладка 2 — Памʼять + +Показує: + +- які факти агент зберіг, +- що він знає про команду, +- ключові поняття та терміни. + +Кнопка: + +- «Очистити коротку пам'ять» +- «Показати довгострокові факти» + +--- + +## 4.3. Вкладка 3 — Самонавчання + +Перемикачі: + +- `[x] Самонавчання увімкнено` +- Рівень: + - `Базовий` + - `Розширений` +- Джерела: + - `[x] Діалоги в цій спільноті` + - `[ ] Всі мої microDAO` + - `[ ] Анонімізований внесок у DAGI (Train-to-Earn)` + +--- + +## 4.4. Вкладка 4 — Пропозиції покращень (Actionable Insights) + +Список: + +``` +• Пропозиція №23 +Тип: FAQ +Тема: «Як додати нового учасника?» +Згенеровано: Meta-Agent +→ [Прийняти] [Відхилити] [Редагувати] +``` + +--- + +## 4.5. Вкладка 5 — Журнал Еволюції (Versions) + +Хронологічне дерево змін. + +--- + +# 5. Логіка самонавчання (алгоритм) + +## 5.1. Тригер self-review + +Self-review запускається коли: + +- кожні 50 повідомлень, +- або щогодини, +- або вручну. + +## 5.2. Self-review pipeline + +1. витягує останні діалоги +2. фільтрує по негативних сигналах +3. кластеризує помилки +4. генерує пропозиції +5. оцінює важливість +6. показує користувачу для схвалення + +--- + +# 6. API для еволюційного агента + +Додаємо нові ендпоїнти: + +### GET /agents/{id}/evolution + +Історія еволюції. + +### GET /agents/{id}/suggestions + +Список пропозицій meta-agent. + +### POST /agents/{id}/suggestions/{sid}/accept + +Застосувати пропозицію. + +### POST /agents/{id}/suggestions/{sid}/reject + +Відхилити. + +### POST /agents/{id}/suggestions/{sid}/edit + +Внести зміну вручну. + +### POST /agents/{id}/memory/update + +Оновити довгострокову памʼять агента. + +--- + +# 7. Як працює Train-to-Earn + +Коли користувач вмикає цю опцію: + +- meta-agent генерує анонімізовані патерни +- агрегує їх (без текстів, без персональних даних) +- відправляє в DAGI +- DAGI оцінює їхню цінність +- видає винагороду у вигляді 1T або іншого токена +- microDAO отримує reward + +Користувач бачить: + +``` +Ми використали 3 нові патерни вашої спільноти. +Винагорода: +17 1T +``` + +--- + +# 8. MVP того, що реально зробити зараз + +### MVP-версія: + +- збір фідбеків (👍/👎), +- ручний запуск self-review, +- генерація 1–3 пропозицій правил, +- вручну додане рев'ю у UI, +- зберігання версій у JSON. + +### Наступні етапи: + +- кластеризація помилок, +- автоматичні тест-кейси, +- DAGI-підключення, +- мікромоделі LoRA. + +--- + +# 9. Завдання для Cursor (шаблон) + +``` +You are a senior React/TS and backend engineer. + +Implement the Self-Improving Agent module using: + +* 09_evolutionary_agent.md +* 03_api_core_snapshot.md +* 05_coding_standards.md + +Tasks: + +1. Create UI: Agent → Evolution tab. +2. Show suggestions list (stub data). +3. Implement actions: accept/reject/edit (client-only). +4. Add version history (client-only). +5. Add feedback buttons 👍/👎 to agent messages. + +Output: + +* list of files +* diff +* summary +``` + +--- + +# 10. Інтеграція з існуючим кодом + +## 10.1. Використання API клієнтів + +Розширити існуючий `src/api/agents.ts` для підтримки нових ендпоїнтів: + +```ts +// Додати до agents.ts +export async function getAgentEvolution(agentId: string) { + return apiClient.get(`/agents/${agentId}/evolution`); +} + +export async function getAgentSuggestions(agentId: string) { + return apiClient.get(`/agents/${agentId}/suggestions`); +} + +export async function acceptSuggestion(agentId: string, suggestionId: string) { + return apiClient.post(`/agents/${agentId}/suggestions/${suggestionId}/accept`); +} +``` + +## 10.2. Компоненти UI + +Створити нову структуру: + +``` +src/features/agent-evolution/ + AgentEvolutionTab.tsx + SuggestionsList.tsx + VersionHistory.tsx + MemoryView.tsx + FeedbackButtons.tsx + hooks/ + useAgentEvolution.ts + useSuggestions.ts +``` + +## 10.3. State Management + +Використовувати React Query для кешування та синхронізації: + +```ts +const { data: suggestions } = useQuery({ + queryKey: ['agent-suggestions', agentId], + queryFn: () => getAgentSuggestions(agentId), +}); +``` + +--- + +# 11. Типи даних + +## 11.1. Suggestion + +```ts +interface Suggestion { + id: string; + type: 'rule' | 'faq' | 'skill' | 'template'; + title: string; + description: string; + source: { + type: 'feedback' | 'pattern' | 'explicit'; + count: number; + examples: string[]; + }; + status: 'pending' | 'accepted' | 'rejected' | 'edited'; + createdAt: string; +} +``` + +## 11.2. AgentVersion + +```ts +interface AgentVersion { + version: string; + createdAt: string; + rules: Rule[]; + skills: Skill[]; + memoryDiff: MemoryDiff; + changes: Change[]; +} +``` + +## 11.3. Feedback + +```ts +interface Feedback { + id: string; + messageId: string; + type: 'positive' | 'negative' | 'correction'; + content?: string; // для explicit correction + createdAt: string; +} +``` + +--- + +# 12. Тестування + +## 12.1. Unit Tests + +- Тести для `FeedbackCollector` +- Тести для `PatternAnalyzer` +- Тести для `ImprovementGenerator` +- Тести для парсингу фідбеків + +## 12.2. Integration Tests + +- Тестування повного циклу: фідбек → аналіз → пропозиція → застосування +- Тестування версіонування +- Тестування API інтеграції + +## 12.3. E2E Tests + +- Користувач ставить 👍 → з'являється пропозиція → приймає → агент оновлюється +- Перевірка відображення історії версій +- Перевірка UI вкладок еволюції + +--- + +# 13. Безпека та приватність + +## 13.1. Контроль доступу + +- Тільки власник/адміністратор microDAO може застосовувати зміни +- Фідбек може залишати будь-який учасник +- Історія еволюції доступна тільки для адмінів + +## 13.2. Анонімізація для DAGI + +Перед відправкою в DAGI: + +- Видаляти персональні дані +- Видаляти конкретні тексти діалогів +- Залишати тільки патерни та структури +- Агрегувати дані + +## 13.3. Валідація змін + +- Перевірка на шкідливий контент +- Перевірка на порушення правил спільноти +- Модерація перед застосуванням + +--- + +# 14. Продуктивність + +## 14.1. Оптимізація self-review + +- Запускати в фоні +- Кешувати результати аналізу +- Обмежувати кількість одночасних аналізів + +## 14.2. Оптимізація пам'яті + +- Архівувати старі версії +- Стискати дані +- Використовувати векторні БД для ефективного пошуку + +--- + +# 15. Майбутні покращення + +## 15.1. Розширений аналіз + +- Використання LLM для кластеризації помилок +- Автоматичне виявлення патернів +- Предиктивне покращення + +## 15.2. LoRA Fine-tuning + +- Створення мікромоделей для конкретних спільнот +- Локальне навчання без зміни базової моделі +- Персоналізація на рівні моделі + +## 15.3. Спільне навчання + +- Обмін анонімізованими патернами між microDAO +- Колективна еволюція +- Рейтинг найкращих практик + +--- + +# 16. Результат + +Еволюційний агент стає серцем MicroDAO: +він вчиться, адаптується, росте — і належить спільноті. + +Кожна microDAO отримує унікального інтелектуального помічника, який: + +- розуміє контекст спільноти, +- адаптується до стилю комунікації, +- покращується з часом, +- залишається під повним контролем користувача, +- може співпрацювати з глобальною мережею через DAGI. + +--- + +**Готово.** +Це **повна специфікація еволюційного агента**, готова до використання в Cursor. + + diff --git a/docs/cursor/10_agent_ui_system.md b/docs/cursor/10_agent_ui_system.md new file mode 100644 index 00000000..b7a1a0f6 --- /dev/null +++ b/docs/cursor/10_agent_ui_system.md @@ -0,0 +1,555 @@ +# 10 — Agent UI System (MicroDAO) + +Повна специфікація агентського інтерфейсу + +Цей документ описує, як агент стає першим інтерфейсом взаємодії в MicroDAO. +Уся взаємодія — чатова. +Агент — навігатор, помічник, аналітик та еволюційна сутність. + +--- + +# 1. Мета + +Зробити агента центральною точкою взаємодії користувача зі спільнотою. + +У результаті: + +- новачок спілкується з агентом для створення microDAO; + +- учасник команди — взаємодіє з агентом через командний чат; + +- агент сам ініціює корисні дії; + +- агент має власний чат, власну панель еволюції і власну пам'ять; + +- агент виконує функції внутрішнього інтелекту команди. + +--- + +# 2. Типи агентів у UI + +## 2.1. Guide Agent (провідник) + +Працює в онбордингу. + +Показує: + +- підказки, + +- кроки, + +- питання, + +- підтверджує створення команд/каналів. + +## 2.2. Team Assistant (внутрішній агент) + +Доступний всередині кожної microDAO. + +Основні функції: + +- відповіді у спільних чатах, + +- автоматичні підсумки, + +- створення follow-ups, + +- пропозиції задач, + +- аналіз документації, + +- self-improvement. + +## 2.3. Personal Agent (опція 2025+) + +Асистент конкретного користувача. + +--- + +# 3. Компоненти Agent UI + +## 3.1. Agent Bubble + +Маленький фіксований аватар агента у нижньому правому куті (як у Copilot / ChatGPT): + +- натискаєш → відкривається Agent Chat; + +- агент може блиматиме (notifying) при певних подіях. + +## 3.2. Agent Chat Window + +Окремий чат у форматі інтерфейсу: + +``` +--- +| Team Assistant (ім'я агента) | +| Chat messages | +| Input field | +``` + +Функції: + +- ставити питання агенту; + +- отримувати аналіз; + +- генерувати документи (MVP — текст); + +- зворотній зв'язок 👍/👎; + +- self-review автозапуск. + +## 3.3. Inline Agent Messages у каналах + +Агент може писати в каналі: + +Способи: + +- коли його тегнули: @assistant + +- коли користувач попросив: "Підсумуй останнє" + +- коли канал просить допомогу (опційно) + +- коли тригери (як у Slack bots) + +Повідомлення агента виглядають так: + +- інший фон, + +- аватар агента, + +- дрібний значок "AI". + +--- + +# 4. Sidebar інтеграція + +У лівому меню зʼявляється новий розділ: + +``` +Агенти +• Team Assistant +• (у майбутньому: Personal Agent) +``` + +При натисканні → сторінка агента. + +--- + +# 5. Сторінка агента + +### Розташування: + +`/t/:teamId/agent/:agentId` + +Складається з 4 вкладок: + +## 5.1. "Чат" + +Центральне місце взаємодії з агентом. + +Вигляд: стандартний чат + тред з агентом. + +## 5.2. "Памʼять" + +Показує: + +- довгострокові факти, + +- короткострокові факти, + +- терміни, + +- ключові меседжі. + +Кнопки: + +- «Очистити коротку» + +- «Очистити довгострокову» + +- «Експорт памʼяті» + +## 5.3. "Самонавчання" + +(інтегровано з документом 09) + +Поля: + +- toggle: self-improvement ON/OFF + +- рівень: basic / extended + +- джерела: канал / вся microDAO / DAGI + +- статус останнього review: + + - дата + + - кількість знайдених помилок + + - кількість пропозицій + +Кнопка: + +- «Запустити self-review зараз» + +## 5.4. "Еволюція" + +Показує: + +- список пропозицій, + +- версії агента, + +- детальні diffs, + +- кнопки accept/reject/edit. + +UI приклад: + +``` +Версія: v4.2 +Запропоновано 2 покращення: + +[1] Нове правило: "Відповідати українською, якщо канал український." [Прийняти] [Відхилити] + +[2] FAQ: "Як додати учасника до команди?" [Прийняти] [Редагувати] +``` + +--- + +# 6. Взаємодія агента з подіями + +## 6.1. У каналі + +Тригери для агента: + +- `@assistant` — пряме звернення. + +- Фрази: + + - "Підсумуй будь ласка" + + - "Що сталося?" + + - "Створи таску з цього" + + - "Які наступні кроки?" + +- Коли новий учасник приєднався: + + - агент робить welcome-репліку. + +--- + +# 7. Взаємодія агента з Follow-Ups & Projects + +### 7.1. Follow-ups + +Агент може: + +- створювати follow-up автоматично, + +- пропонувати: "Хочеш я створю задачу з цього?", + +- групувати follow-ups. + +### 7.2. Projects + +Агент може: + +- пропонувати задачі, + +- заповнювати опис задач, + +- будувати мінімальні roadmaps, + +- робити автоматичні щоденні підсумки по проєкту (summary). + +--- + +# 8. Notification Logic + +Агент sparingly надсилає нотифікації: + +Типи: + +- завершений self-review, + +- знайдені проблеми, + +- нові пропозиції змін, + +- нагадування про follow-ups, + +- важливі зміни у спільноті. + +UI: + +- Badge на іконці агента, + +- "пульсація" Agent Bubble, + +- push (на майбутнє). + +--- + +# 9. Анімації та UX-поведінка + +- Аватар агента реагує на події (мʼяка анімована "пульсація"). + +- У чаті агент не відповідає миттєво (0.3–0.7s delay). + +- Пише «…друкую» (typing indicator). + +- Помилки агента обробляються як звичайні системні помилки. + +--- + +# 10. Інтеграція з Agent-First Onboarding + +Після онбордингу: + +- той самий агент-провідник стає Team Assistant + +- або передає користувача "головному" агенту команди + +Після завершення онбордингу агент каже: + +> "Якщо хочеш, я можу показати тобі, як працює ваша молоденька microDAO." + +--- + +# 11. Завдання для Cursor + +``` +You are a senior React/TS engineer. + +Implement Agent UI System using: + +* 10_agent_ui_system.md +* 08_agent_first_onboarding.md +* 03_api_core_snapshot.md +* 05_coding_standards.md + +Deliverables: + +1. AgentBubble component +2. AgentChatWindow component +3. Agent page with tabs: Chat / Memory / Learning / Evolution +4. Inline agent messages in channels +5. Hook: useAgentActions() + +Output: + +* list of modified files +* diff +* summary +``` + +--- + +# 12. Компоненти та структура файлів + +## 12.1. Компоненти UI + +``` +src/components/agent/ + AgentBubble.tsx # Фіксований аватар у правому нижньому куті + AgentChatWindow.tsx # Окно чату з агентом + AgentMessage.tsx # Повідомлення агента в каналах + AgentAvatar.tsx # Аватар агента з анімаціями + AgentTypingIndicator.tsx # Індикатор набору тексту +``` + +## 12.2. Сторінки + +``` +src/pages/ + AgentPage.tsx # Головна сторінка агента з вкладками + AgentChatTab.tsx # Вкладка чату + AgentMemoryTab.tsx # Вкладка пам'яті + AgentLearningTab.tsx # Вкладка самонавчання + AgentEvolutionTab.tsx # Вкладка еволюції +``` + +## 12.3. Hooks + +``` +src/hooks/ + useAgentActions.ts # Дії агента (відповіді, аналіз) + useAgentNotifications.ts # Нотифікації від агента + useAgentMemory.ts # Робота з пам'яттю агента + useAgentEvolution.ts # Еволюція агента (з 09_evolutionary_agent.md) +``` + +## 12.4. Типи + +``` +src/types/ + agent.ts # Типи для агентів + - Agent + - AgentMessage + - AgentSuggestion + - AgentVersion + - AgentMemory +``` + +--- + +# 13. Інтеграція з каналами + +## 13.1. Відображення повідомлень агента + +Повідомлення агента в каналі мають: + +- Спеціальний фон (наприклад, світло-синій) +- Аватар агента з іконкою AI +- Індикатор "AI" біля імені +- Кнопки фідбеку 👍/👎 (опціонально) + +## 13.2. Тригери для агента + +Система розпізнає наступні тригери: + +- `@assistant` або `@agent` — пряме звернення +- Фрази-команди: + - "Підсумуй" + - "Створи задачу" + - "Що сталося?" + - "Які наступні кроки?" + - "Допоможи з..." + +## 13.3. Автоматичні дії + +Агент може автоматично: + +- Привітати нового учасника +- Підсумувати довгі обговорення +- Запропонувати створити задачу з важливого повідомлення +- Нагадати про дедлайни + +--- + +# 14. API інтеграція + +## 14.1. Отримання відповіді від агента + +```ts +POST /agents/{agentId}/chat +{ + "message": "Підсумуй останні повідомлення", + "context": { + "channelId": "channel-123", + "threadId": "thread-456" + } +} +``` + +## 14.2. Отримання пам'яті агента + +```ts +GET /agents/{agentId}/memory +``` + +## 14.3. Оновлення налаштувань самонавчання + +```ts +PATCH /agents/{agentId}/learning +{ + "enabled": true, + "level": "extended", + "sources": ["channel", "team"] +} +``` + +--- + +# 15. UX деталі + +## 15.1. Agent Bubble + +- Розмір: 56x56px +- Позиція: fixed, bottom-right, 24px від країв +- Z-index: 1000 +- Анімація: м'яка пульсація при нових нотифікаціях +- Badge: червоний кружечок з кількістю нових подій + +## 15.2. Agent Chat Window + +- Розмір: 400x600px (desktop), fullscreen (mobile) +- Позиція: fixed, bottom-right, над Agent Bubble +- Анімація відкриття: slide-up з fade +- Закриття: кнопка X або клік поза вікном + +## 15.3. Typing Indicator + +- Показується під час генерації відповіді +- Анімація: три точки, що пульсують +- Текст: "Агент друкує..." + +--- + +# 16. Обробка помилок + +## 16.1. Помилки API + +Якщо агент не може відповісти: + +- Показати дружнє повідомлення: "Вибач, зараз не можу відповісти. Спробуй пізніше." +- Запропонувати альтернативу +- Логувати помилку для аналізу + +## 16.2. Таймаути + +Якщо відповідь занадто довга: + +- Показати індикатор завантаження +- Запропонувати скасувати +- Після 30 секунд — показати попередження + +--- + +# 17. Тестування + +## 17.1. Unit Tests + +- Тести для `AgentBubble` +- Тести для `AgentChatWindow` +- Тести для `useAgentActions` +- Тести для розпізнавання тригерів + +## 17.2. Integration Tests + +- Тестування повного flow: питання → відповідь → фідбек +- Тестування інтеграції з каналами +- Тестування нотифікацій + +## 17.3. E2E Tests + +- Користувач відкриває Agent Chat → ставить питання → отримує відповідь +- Користувач тегує агента в каналі → агент відповідає +- Користувач приймає пропозицію еволюції → агент оновлюється + +--- + +# 18. Результат + +MicroDAO стає не месенджером з агентами, а **агентською операційною системою спільнот**, де ШІ — активний навігатор, який еволюціонує та живе поруч з людьми. + +Агент: + +- є першим інтерфейсом для нових користувачів, +- допомагає у щоденній роботі команди, +- еволюціонує разом зі спільнотою, +- залишається під повним контролем користувачів, +- інтегрується з усіма функціями MicroDAO. + +--- + +**Готово.** +Це **повна специфікація агентського UI системи**, готова до використання в Cursor. + + diff --git a/docs/cursor/11_llm_integration.md b/docs/cursor/11_llm_integration.md new file mode 100644 index 00000000..fe05d173 --- /dev/null +++ b/docs/cursor/11_llm_integration.md @@ -0,0 +1,646 @@ +# 11 — LLM Integration Guide (MicroDAO) + +Інтеграція ChatGPT / OpenAI / інших моделей у агентську систему MicroDAO + +Цей документ описує: + +- де і як підключити LLM, + +- як організувати backend-виклики, + +- як звʼязати агента з моделлю, + +- як працює agent-first онбординг, + +- як працює агентський чат, + +- як працює еволюційна модель на основі LLM. + +Документ орієнтований на Cursor + Node/TS backend. + +--- + +# 1. Принцип інтеграції + +Усі виклики до LLM здійснюються **на бекенді**, не з фронтенду. + +Причини: + +- безпека (ключ не світиться), + +- стабільність, + +- контроль ціни, + +- можливість додавати кэшинг, rate-limits, + +- можливість підміняти провайдерів (OpenAI → Anthropic → локальні моделі). + +--- + +# 2. Високорівнева архітектура + +``` +Frontend (React SPA) +| +| POST /agents/{id}/chat +↓ +Backend +├── agentsController.ts +├── llm/ +│ ├── openaiClient.ts +│ ├── modelRouter.ts +│ └── prompts/ +│ ├── system_agent.txt +│ └── system_onboarding.txt +| +↓ +OpenAI API (або інша модель) +``` + +--- + +# 3. Структура директорій для LLM + +Додайте на бекенд: + +``` +src/ +llm/ +openaiClient.ts +modelRouter.ts +prompts/ +system_agent.txt +system_onboarding.txt +system_evolution.txt +``` + +- `openaiClient.ts` — клієнт OpenAI / GPT. + +- `modelRouter.ts` — місце, де ти можеш вирішити, яку модель використовувати (gpt-4.1-mini, o3, claude тощо). + +- `prompts/*.txt` — системні промпти для: + + - Agent Chat + + - Onboarding Guide Agent + + - Evolution Meta-Agent + +--- + +# 4. Реалізація базового клієнта OpenAI + +**Файл: `src/llm/openaiClient.ts`** + +```ts +import OpenAI from "openai"; + +export const openai = new OpenAI({ + apiKey: process.env.OPENAI_API_KEY!, +}); + +export async function callLLM(messages: any[], model = "gpt-4.1-mini") { + const res = await openai.chat.completions.create({ + model, + messages, + temperature: 0.2, + }); + + return res.choices[0]?.message?.content ?? ""; +} +``` + +--- + +# 5. Model Router + +**Файл: `src/llm/modelRouter.ts`** + +```ts +export function pickModel(agentProfile: string) { + switch (agentProfile) { + case "technical": + return "gpt-4.1"; + case "business": + return "gpt-4.1-mini"; + case "creative": + return "gpt-4o-mini"; + default: + return "gpt-4.1-mini"; + } +} +``` + +У майбутньому це місце для: + +* локальних моделей (Ollama, vLLM), +* кластеру DAGI, +* автоматичного підбору моделі. + +--- + +# 6. Запит до LLM для агентського чату + +**Файл: `src/controllers/agentsController.ts`** + +```ts +import { callLLM } from "../llm/openaiClient"; +import { pickModel } from "../llm/modelRouter"; +import systemAgent from "../llm/prompts/system_agent.txt"; + +export async function chatWithAgent(req, res) { + const { agentId } = req.params; + const { messages } = req.body; + + const agent = await db.agent.find(agentId); + + const model = pickModel(agent.role); + + const llmMessages = [ + { role: "system", content: systemAgent }, + ...messages + ]; + + const reply = await callLLM(llmMessages, model); + + // зберегти останнє повідомлення як agent message + await db.agentMessages.insert({ + agent_id: agentId, + role: "assistant", + body: reply + }); + + res.json({ reply }); +} +``` + +--- + +# 7. Інтеграція з Agent Chat у фронтенді + +**Файл: `api/agents.ts`** + +```ts +export async function agentChat(agentId: string, messages: ChatMessage[]) { + return api.post(`/agents/${agentId}/chat`, { messages }); +} +``` + +**У `AgentChatWindow.tsx`:** + +```ts +const onSend = async (text: string) => { + addMessage({ role: "user", content: text }); + + const response = await agentChat(agentId, [ + ...history, + { role: "user", content: text } + ]); + + addMessage({ role: "assistant", content: response.reply }); +}; +``` + +--- + +# 8. Agent-First Onboarding Integration + +Використовує той самий LLM-клієнт, але з іншим системним промптом: + +**`prompts/system_onboarding.txt`:** + +``` +You are MicroDAO Guide Agent. + +Your job is to ask the user questions one-by-one to configure their microDAO. + +NEVER skip steps. NEVER jump too far. + +Be friendly, minimalistic and precise. +``` + +У онбордингу: + +```ts +const reply = await callLLM([ + { role: "system", content: onboardingSystemPrompt }, + ...conversation +]); +``` + +Але state-machine керує реальними діями (API), LLM — тільки текстом. + +--- + +# 9. Integration with Evolutionary Agent (09_evolutionary_agent.md) + +Meta-Agent (self-review) використовує **ще один промпт**: + +`prompts/system_evolution.txt`: + +``` +You are Meta-Agent responsible for analyzing logs of conversations. + +Find mistakes, weak answers, missing rules, and propose improvements. + +Always output JSON with `["type", "value", "explanation"]`. +``` + +Self-review: + +```ts +const improvements = await callLLM([ + { role: "system", content: evolutionPrompt }, + { role: "user", content: JSON.stringify(conversationLog) } +]); +``` + +--- + +# 10. Як передавати пам'ять агента в LLM + +У LLM-запит можна додати: + +* `short-term memory` (останні X повідомлень) + +* `long-term memory` (витяг з Co-Memory) + +* `agent profile` + +* інструкції агента (структура з DB) + +Приклад у messages: + +```ts +const llmMessages = [ + { role: "system", content: systemPrompt }, + { role: "assistant", content: "AGENT_PROFILE:" + JSON.stringify(agentProfile) }, + { role: "assistant", content: "MEMORY:" + JSON.stringify(memories) }, + ...history, + { role: "user", content: question } +]; +``` + +--- + +# 11. Безпека + +* API key зберігати у `.env` на сервері. + +* Ніколи не відправляти ключ у фронтенд. + +* Додавати rate limit. + +* Додавати аудит використання агента. + +--- + +# 12. Кешування та оптимізація + +## 12.1. Кешування відповідей + +Для однакових запитів можна кешувати відповіді: + +```ts +const cacheKey = hash(messages); +const cached = await cache.get(cacheKey); +if (cached) return cached; + +const reply = await callLLM(messages); +await cache.set(cacheKey, reply, { ttl: 3600 }); +return reply; +``` + +## 12.2. Streaming відповідей + +Для кращого UX можна використовувати streaming: + +```ts +const stream = await openai.chat.completions.create({ + model, + messages, + stream: true, +}); + +for await (const chunk of stream) { + const content = chunk.choices[0]?.delta?.content; + if (content) { + res.write(content); + } +} +``` + +## 12.3. Rate Limiting + +Обмеження кількості запитів: + +```ts +import rateLimit from "express-rate-limit"; + +const agentLimiter = rateLimit({ + windowMs: 60 * 1000, // 1 хвилина + max: 10, // 10 запитів на хвилину + keyGenerator: (req) => req.user.id, +}); +``` + +--- + +# 13. Альтернативні провайдери + +## 13.1. Anthropic Claude + +```ts +import Anthropic from "@anthropic-ai/sdk"; + +const anthropic = new Anthropic({ + apiKey: process.env.ANTHROPIC_API_KEY!, +}); + +export async function callClaude(messages: any[]) { + const response = await anthropic.messages.create({ + model: "claude-3-5-sonnet-20241022", + max_tokens: 1024, + messages, + }); + + return response.content[0].text; +} +``` + +## 13.2. Локальні моделі (Ollama) + +```ts +export async function callOllama(messages: any[], model = "llama2") { + const response = await fetch("http://localhost:11434/api/chat", { + method: "POST", + body: JSON.stringify({ + model, + messages, + }), + }); + + const data = await response.json(); + return data.message.content; +} +``` + +## 13.3. Уніфікований інтерфейс + +```ts +interface LLMProvider { + call(messages: any[], options?: any): Promise; +} + +class OpenAIProvider implements LLMProvider { + async call(messages: any[], options?: any) { + return callLLM(messages, options?.model); + } +} + +class AnthropicProvider implements LLMProvider { + async call(messages: any[], options?: any) { + return callClaude(messages); + } +} + +export function getLLMProvider(provider: string): LLMProvider { + switch (provider) { + case "openai": + return new OpenAIProvider(); + case "anthropic": + return new AnthropicProvider(); + case "ollama": + return new OllamaProvider(); + default: + return new OpenAIProvider(); + } +} +``` + +--- + +# 14. Обробка помилок + +## 14.1. Retry Logic + +```ts +async function callLLMWithRetry( + messages: any[], + model: string, + maxRetries = 3 +): Promise { + for (let i = 0; i < maxRetries; i++) { + try { + return await callLLM(messages, model); + } catch (error) { + if (i === maxRetries - 1) throw error; + await sleep(1000 * (i + 1)); // exponential backoff + } + } + throw new Error("LLM call failed after retries"); +} +``` + +## 14.2. Fallback моделі + +```ts +async function callLLMWithFallback(messages: any[], primaryModel: string) { + try { + return await callLLM(messages, primaryModel); + } catch (error) { + console.warn(`Primary model failed, using fallback`); + return await callLLM(messages, "gpt-3.5-turbo"); + } +} +``` + +--- + +# 15. Моніторинг та логування + +## 15.1. Логування викликів + +```ts +async function callLLM(messages: any[], model: string) { + const startTime = Date.now(); + + try { + const reply = await openai.chat.completions.create({ + model, + messages, + temperature: 0.2, + }); + + const duration = Date.now() - startTime; + const tokens = reply.usage?.total_tokens || 0; + + logger.info("LLM call", { + model, + duration, + tokens, + cost: calculateCost(model, tokens), + }); + + return reply.choices[0]?.message?.content ?? ""; + } catch (error) { + logger.error("LLM call failed", { model, error }); + throw error; + } +} +``` + +## 15.2. Метрики + +Відстежувати: + +- кількість викликів на агента +- середній час відповіді +- витрати на токени +- частота помилок +- популярні моделі + +--- + +# 16. Завдання для Cursor + +``` +You are a senior backend + frontend engineer. + +Integrate OpenAI LLM into the MicroDAO Agents system using: + +- 11_llm_integration.md +- 03_api_core_snapshot.md +- 05_coding_standards.md + +Tasks: + +1. Create openaiClient.ts +2. Create modelRouter.ts +3. Add AgentChat endpoint +4. Connect AgentChatWindow to backend +5. Add LLM to AgentOnboardingChat +6. Add LLM to EvolutionMetaAgent (stub) + +Output: + +- list of modified files +- diff +- summary +``` + +--- + +# 17. Типи та інтерфейси + +## 17.1. ChatMessage + +```ts +interface ChatMessage { + role: "system" | "user" | "assistant"; + content: string; + timestamp?: string; +} +``` + +## 17.2. LLMResponse + +```ts +interface LLMResponse { + content: string; + model: string; + tokens?: { + prompt: number; + completion: number; + total: number; + }; + finishReason?: string; +} +``` + +## 17.3. AgentChatRequest + +```ts +interface AgentChatRequest { + messages: ChatMessage[]; + context?: { + channelId?: string; + threadId?: string; + userId?: string; + }; + options?: { + temperature?: number; + maxTokens?: number; + stream?: boolean; + }; +} +``` + +--- + +# 18. Тестування + +## 18.1. Unit Tests + +```ts +describe("openaiClient", () => { + it("should call LLM with correct messages", async () => { + const messages = [ + { role: "system", content: "You are a helpful assistant" }, + { role: "user", content: "Hello" }, + ]; + + const response = await callLLM(messages); + expect(response).toBeDefined(); + expect(typeof response).toBe("string"); + }); +}); +``` + +## 18.2. Integration Tests + +```ts +describe("Agent Chat Integration", () => { + it("should handle full chat flow", async () => { + const agentId = "test-agent"; + const messages = [ + { role: "user", content: "Hello" }, + ]; + + const response = await agentChat(agentId, messages); + expect(response.reply).toBeDefined(); + }); +}); +``` + +--- + +# 19. Результат + +Після інтеграції: + +* будь-який агент microDAO працює на GPT/LLM, +* онбординг веде агент-гіда, +* Team Assistant відповідає у чаті, +* Meta-Agent генерує покращення, +* вся система стає справжньою OS на базі ШІ. + +--- + +# 20. Наступні кроки + +Після базової інтеграції можна додати: + +- Streaming відповідей для кращого UX +- Кешування для оптимізації витрат +- Підтримку альтернативних провайдерів +- Fine-tuning моделей для конкретних спільнот +- Інтеграцію з DAGI для колективного навчання + +--- + +**Готово.** +Це **повна специфікація інтеграції LLM**, готова до використання в Cursor. + + diff --git a/docs/cursor/12_agent_runtime_core.md b/docs/cursor/12_agent_runtime_core.md new file mode 100644 index 00000000..34525d2d --- /dev/null +++ b/docs/cursor/12_agent_runtime_core.md @@ -0,0 +1,706 @@ +# 12 — Agent Runtime Core (MicroDAO) + +Цей документ визначає, **як саме агент реалізований у коді** MicroDAO: + +- які інтерфейси має, + +- як виглядає життєвий цикл одного кроку, + +- як інтегрується пам'ять, + +- як інтегрується LLM, + +- як у майбутньому додати SML / локальні моделі. + +Це "контракт" для всіх агентів: Guide, Team Assistant, Meta-Agent. + +--- + +# 1. Базові принципи + +1. Агент — це **чиста функція + конфіг**. + +2. Агент **не знає** про HTTP / UI — він працює з: + + - історією повідомлень, + + - пам'яттю, + + - інструментами (tools), + + - LLM-інтерфейсом. + +3. Кожен агент має: + + - `config` (роль, системний промт, пам'ять), + + - `runtime` (функції: runStep, useTools, updateMemory). + +--- + +# 2. Інтерфейси агента + +```ts +export type AgentRole = + | "guide" // онбординг + | "team_assistant" // основний помічник команди + | "meta_evolution" // еволюційний агент + | "custom"; + +export type MemoryScope = "channel" | "team" | "global"; + +export interface AgentConfig { + id: string; + teamId: string; + name: string; + role: AgentRole; + systemPrompt: string; + memoryScope: MemoryScope; + modelHint?: string; // підказка для modelRouter + tools?: string[]; // назви інструментів, які дозволені +} +``` + +Повідомлення: + +```ts +export type AgentMsgRole = "user" | "assistant" | "system" | "tool"; + +export interface AgentMessage { + role: AgentMsgRole; + content: string; + toolName?: string; // якщо role === "tool" + ts?: string; +} +``` + +--- + +# 3. Runtime-контекст агента + +```ts +export interface AgentContext { + agent: AgentConfig; + teamId: string; + channelId?: string; + userId: string; + + // дані ззовні: + history: AgentMessage[]; // діалог user ↔ agent (локальний) + input: string; // останнє повідомлення user + + // сервіси: + tools: ToolRegistry; + memory: AgentMemoryAdapter; + llm: AgentLLMAdapter; +} +``` + +--- + +# 4. Інтерфейси Memory та LLM + +## 4.1. AgentMemoryAdapter + +```ts +export interface AgentMemoryAdapter { + loadShortTerm(ctx: AgentContext): Promise; + loadLongTerm(ctx: AgentContext): Promise; // факти / ноти + saveTurn(ctx: AgentContext, turn: AgentMessage): Promise; + appendFact(ctx: AgentContext, fact: string): Promise; +} +``` + +* `short-term` — останні N ходів діалогу; + +* `long-term` — узагальнені знання про команду/проект. + +## 4.2. AgentLLMAdapter + +```ts +export interface AgentLLMAdapter { + complete( + ctx: AgentContext, + messages: AgentMessage[], + options?: { modelHint?: string } + ): Promise; +} +``` + +Фактична реалізація використовує `openaiClient` + `modelRouter` з `11_llm_integration.md`. + +--- + +# 5. Інструменти (Tools) + +```ts +export type ToolFn = (ctx: AgentContext, args: any) => Promise; + +export interface ToolRegistry { + [name: string]: ToolFn; +} +``` + +Приклади tools: + +* `create_followup` + +* `create_task` + +* `get_project_summary` + +* `get_channel_history` + +Інструменти не викликаються напряму з UI, тільки через агентський runtime. + +--- + +# 6. Головна функція: runAgentTurn + +```ts +export interface AgentTurnResult { + reply: AgentMessage; + toolCalls?: { name: string; args: any; result?: any }[]; +} + +export async function runAgentTurn(ctx: AgentContext): Promise { + // 1. Завантажуємо памʼять + const shortTerm = await ctx.memory.loadShortTerm(ctx); + const longTerm = await ctx.memory.loadLongTerm(ctx); + + // 2. Готуємо повідомлення для LLM + const messages = buildLLMMessages(ctx, shortTerm, longTerm); + + // 3. Викликаємо LLM + const replyText = await ctx.llm.complete(ctx, messages, { + modelHint: ctx.agent.modelHint, + }); + + const reply: AgentMessage = { + role: "assistant", + content: replyText, + ts: new Date().toISOString(), + }; + + // 4. Зберігаємо хід в памʼяті + await ctx.memory.saveTurn(ctx, { role: "user", content: ctx.input }); + await ctx.memory.saveTurn(ctx, reply); + + // 5. (опційно) витягуємо структуровані інструкції для tools / еволюції + const toolCalls = parseToolCalls(replyText); + + // 6. Виконання tools (якщо дозволено) + if (toolCalls.length > 0) { + for (const call of toolCalls) { + const tool = ctx.tools[call.name]; + if (!tool) continue; + + const result = await tool(ctx, call.args); + call.result = result; + + // Можемо зберегти це як tool-message + await ctx.memory.saveTurn(ctx, { + role: "tool", + toolName: call.name, + content: JSON.stringify(result), + }); + } + } + + return { reply, toolCalls }; +} +``` + +--- + +# 7. buildLLMMessages: як формується промпт + +```ts +function buildLLMMessages( + ctx: AgentContext, + shortTerm: AgentMessage[], + longTerm: string[], +): AgentMessage[] { + const system: AgentMessage = { + role: "system", + content: ctx.agent.systemPrompt, + }; + + const memoryMsg: AgentMessage = { + role: "system", + content: + "LONG_TERM_MEMORY:\n" + + longTerm.map((f, i) => `- ${f}`).join("\n"), + }; + + const userInput: AgentMessage = { + role: "user", + content: ctx.input, + }; + + return [system, memoryMsg, ...shortTerm, userInput]; +} +``` + +Надалі: + +* можна додати Co-Memory / RAG (витягнути релевантні факти з векторної БД); + +* можна додати структуровані інструкції для tools. + +--- + +# 8. Життєвий цикл одного запиту агента (end-to-end) + +1. UI (`AgentChatWindow` або `AgentOnboardingChat`) відправляє `/agents/{id}/chat`: + + * `agentId`, + + * `channelId`, + + * `userId`, + + * `input` (текст користувача). + +2. Backend: + + * дістає `AgentConfig` з БД; + + * формує `AgentContext`: + + * agent, teamId, channelId, userId, + + * history (опційно), + + * memory adapter, + + * llm adapter, + + * tools. + +3. Викликає `runAgentTurn(ctx)`. + +4. Отримує `reply` + `toolCalls`. + +5. Повертає `reply` у UI. + +6. UI показує відповідь агента, додає фідбек (👍/👎). + +--- + +# 9. Інтеграція з SML / локальними моделями + +У майбутньому: + +* `AgentLLMAdapter.complete` може: + + * для простих задач (класифікація, короткі відповіді) викликати локальний SML, + + * для складних — OpenAI/велику LLM. + +Псевдокод: + +```ts +export async function complete(ctx, messages, options) { + if (isSimpleTask(messages)) { + return callLocalSML(messages); + } else { + return callLLM(messages, pickModel(ctx.agent.role)); + } +} +``` + +--- + +# 10. Використання для різних типів агентів + +### Guide Agent (онбординг) + +* той самий runtime, + +* інший `systemPrompt`, + +* інший набір tools: + + * `create_team` + + * `update_team_mode` + + * `create_channel` + + * `create_agent` + +### Team Assistant + +* general-purpose агент, + +* має tools: + + * `create_followup` + + * `create_task` + + * `get_summary` + + * `search_memory` + +### Evolution Meta-Agent + +* використовує: + + * `conversation_log` як input, + + * інший systemPrompt, + + * tools: + + * `create_improvement_proposal` + + * `update_agent_rules` + +--- + +# 11. Структура файлів + +## 11.1. Core Runtime + +``` +src/agent-runtime/ + core/ + types.ts # AgentConfig, AgentContext, AgentMessage + runAgentTurn.ts # Головна функція + buildLLMMessages.ts # Формування промпту + parseToolCalls.ts # Парсинг викликів інструментів + adapters/ + memoryAdapter.ts # Реалізація AgentMemoryAdapter + llmAdapter.ts # Реалізація AgentLLMAdapter + tools/ + registry.ts # Реєстр інструментів + createFollowup.ts # Інструмент створення follow-up + createTask.ts # Інструмент створення задачі + getSummary.ts # Інструмент отримання підсумку +``` + +## 11.2. Контролери + +``` +src/controllers/ + agentsController.ts # HTTP endpoint /agents/{id}/chat +``` + +--- + +# 12. Реалізація адаптерів + +## 12.1. Memory Adapter + +```ts +export class DatabaseMemoryAdapter implements AgentMemoryAdapter { + async loadShortTerm(ctx: AgentContext): Promise { + // Завантажити останні N повідомлень з БД + const messages = await db.agentMessages.findMany({ + where: { + agentId: ctx.agent.id, + channelId: ctx.channelId, + }, + orderBy: { ts: "desc" }, + take: 20, + }); + return messages.reverse(); + } + + async loadLongTerm(ctx: AgentContext): Promise { + // Завантажити довгострокові факти з Co-Memory + const facts = await db.agentMemory.findMany({ + where: { + agentId: ctx.agent.id, + teamId: ctx.teamId, + type: "fact", + }, + }); + return facts.map(f => f.content); + } + + async saveTurn(ctx: AgentContext, turn: AgentMessage): Promise { + await db.agentMessages.create({ + data: { + agentId: ctx.agent.id, + channelId: ctx.channelId, + teamId: ctx.teamId, + userId: ctx.userId, + role: turn.role, + content: turn.content, + toolName: turn.toolName, + ts: turn.ts || new Date().toISOString(), + }, + }); + } + + async appendFact(ctx: AgentContext, fact: string): Promise { + await db.agentMemory.create({ + data: { + agentId: ctx.agent.id, + teamId: ctx.teamId, + type: "fact", + content: fact, + }, + }); + } +} +``` + +## 12.2. LLM Adapter + +```ts +import { callLLM } from "../llm/openaiClient"; +import { pickModel } from "../llm/modelRouter"; + +export class OpenAILLMAdapter implements AgentLLMAdapter { + async complete( + ctx: AgentContext, + messages: AgentMessage[], + options?: { modelHint?: string } + ): Promise { + const model = options?.modelHint || + pickModel(ctx.agent.role) || + "gpt-4.1-mini"; + + // Конвертувати AgentMessage[] в формат OpenAI + const openaiMessages = messages.map(msg => ({ + role: msg.role, + content: msg.content, + })); + + return await callLLM(openaiMessages, model); + } +} +``` + +--- + +# 13. Реєстр інструментів + +```ts +import { ToolRegistry, ToolFn } from "./types"; +import { createFollowup } from "./tools/createFollowup"; +import { createTask } from "./tools/createTask"; +import { getSummary } from "./tools/getSummary"; + +export const defaultToolRegistry: ToolRegistry = { + create_followup: createFollowup, + create_task: createTask, + get_summary: getSummary, +}; + +// Фільтрація інструментів на основі конфігурації агента +export function getAvailableTools(agent: AgentConfig): ToolRegistry { + if (!agent.tools || agent.tools.length === 0) { + return {}; + } + + const registry: ToolRegistry = {}; + for (const toolName of agent.tools) { + if (defaultToolRegistry[toolName]) { + registry[toolName] = defaultToolRegistry[toolName]; + } + } + return registry; +} +``` + +--- + +# 14. Парсинг викликів інструментів + +```ts +export function parseToolCalls(replyText: string): Array<{ name: string; args: any }> { + // Простий парсер для формату: args + const toolCallRegex = /(.*?)<\/tool>/gs; + const calls: Array<{ name: string; args: any }> = []; + + let match; + while ((match = toolCallRegex.exec(replyText)) !== null) { + const name = match[1]; + const argsStr = match[2]; + + try { + const args = JSON.parse(argsStr); + calls.push({ name, args }); + } catch (e) { + console.warn(`Failed to parse tool args for ${name}:`, e); + } + } + + return calls; +} +``` + +Альтернативно, можна використовувати structured outputs або function calling API OpenAI. + +--- + +# 15. HTTP Endpoint + +```ts +import { Request, Response } from "express"; +import { runAgentTurn } from "../agent-runtime/core/runAgentTurn"; +import { DatabaseMemoryAdapter } from "../agent-runtime/adapters/memoryAdapter"; +import { OpenAILLMAdapter } from "../agent-runtime/adapters/llmAdapter"; +import { getAvailableTools } from "../agent-runtime/tools/registry"; + +export async function chatWithAgent(req: Request, res: Response) { + const { agentId } = req.params; + const { input, channelId, userId } = req.body; + + // Завантажити конфігурацію агента + const agent = await db.agent.findUnique({ + where: { id: agentId }, + }); + + if (!agent) { + return res.status(404).json({ error: "Agent not found" }); + } + + // Завантажити історію (опціонально) + const history = await db.agentMessages.findMany({ + where: { + agentId, + channelId, + }, + orderBy: { ts: "asc" }, + take: 50, + }); + + // Створити контекст + const ctx: AgentContext = { + agent: { + id: agent.id, + teamId: agent.teamId, + name: agent.name, + role: agent.role as AgentRole, + systemPrompt: agent.systemPrompt, + memoryScope: agent.memoryScope as MemoryScope, + modelHint: agent.modelHint, + tools: agent.tools as string[], + }, + teamId: agent.teamId, + channelId, + userId, + history: history.map(msg => ({ + role: msg.role as AgentMsgRole, + content: msg.content, + toolName: msg.toolName, + ts: msg.ts, + })), + input, + tools: getAvailableTools(agent), + memory: new DatabaseMemoryAdapter(), + llm: new OpenAILLMAdapter(), + }; + + // Виконати хід агента + try { + const result = await runAgentTurn(ctx); + res.json({ + reply: result.reply, + toolCalls: result.toolCalls, + }); + } catch (error) { + console.error("Agent turn failed:", error); + res.status(500).json({ error: "Agent failed to respond" }); + } +} +``` + +--- + +# 16. Тестування + +## 16.1. Unit Tests + +```ts +describe("runAgentTurn", () => { + it("should generate reply from LLM", async () => { + const mockLLM = { + complete: jest.fn().mockResolvedValue("Test reply"), + }; + + const mockMemory = { + loadShortTerm: jest.fn().mockResolvedValue([]), + loadLongTerm: jest.fn().mockResolvedValue([]), + saveTurn: jest.fn().mockResolvedValue(undefined), + }; + + const ctx: AgentContext = { + agent: mockAgentConfig, + teamId: "team-1", + userId: "user-1", + history: [], + input: "Hello", + tools: {}, + memory: mockMemory, + llm: mockLLM, + }; + + const result = await runAgentTurn(ctx); + + expect(result.reply.content).toBe("Test reply"); + expect(mockLLM.complete).toHaveBeenCalled(); + }); +}); +``` + +--- + +# 17. Завдання для Cursor + +Приклад промта: + +``` +You are a senior backend engineer. + +Implement the Agent Runtime Core for MicroDAO using: + +- 12_agent_runtime_core.md +- 11_llm_integration.md +- 09_evolutionary_agent.md +- 03_api_core_snapshot.md +- 05_coding_standards.md + +Tasks: + +1) Define core interfaces: AgentConfig, AgentContext, AgentMemoryAdapter, AgentLLMAdapter. + +2) Implement runAgentTurn() with memory + LLM + optional tools. + +3) Wire /agents/{id}/chat endpoint to runAgentTurn(). + +4) Update AgentChatWindow to use the new endpoint. + +Output: + +- list of modified files +- diff +- summary +``` + +--- + +# 18. Результат + +Після впровадження цього ядра: + +* усі агенти MicroDAO працюють через єдиний runtime; + +* легко додавати нові типи агентів; + +* пам'ять, LLM і tools чітко відокремлені; + +* інтеграція з SML і DAGI стає питанням конфігурації, а не переписування коду. + +--- + +**Готово.** +Це **повна специфікація Agent Runtime Core**, готова до використання в Cursor. + + diff --git a/docs/cursor/13_agent_memory_system.md b/docs/cursor/13_agent_memory_system.md new file mode 100644 index 00000000..3ddaf70a --- /dev/null +++ b/docs/cursor/13_agent_memory_system.md @@ -0,0 +1,793 @@ +# 13 — Agent Memory System (MicroDAO) + +Цей документ описує архітектуру памʼяті агентів у MicroDAO: + +- short-term, mid-term, long-term; + +- персональна / командна / глобальна памʼять; + +- Co-Memory та RAG; + +- як памʼять інтегрується з Agent Runtime Core (12); + +- як це використовувати для еволюційного агента (09). + +--- + +# 1. Цілі системи памʼяті + +1. Зробити агентів **контекстними**: вони памʼятають діалоги, рішення, факти. + +2. Розділити памʼять за часом і рівнем узагальнення: + + - short-term → останні репліки; + + - mid-term → сесії / таски / важливі обговорення; + + - long-term → узагальнені знання про команду/проєкт. + +3. Дати можливість: + + - переглядати памʼять, + + - очищати її, + + - контролювати, що саме зберігається. + +4. Готувати основу для DAGI та Train-to-Earn (агрегована колективна памʼять). + +--- + +# 2. Рівні памʼяті + +## 2.1. Short-Term Memory (STM) + +- Останні N повідомлень (user ↔ агент) в поточному контексті (канал / чат). + +- Зберігається як `AgentMessage` (див. 12_agent_runtime_core.md). + +- Використовується **в кожному запиті до LLM**. + +Приклад: + +- останні 20–50 повідомлень у каналі; + +- спеціальні system-репліки (актуальні інструкції). + +## 2.2. Mid-Term Memory (MTM) + +- Важливі фрагменти діалогів, завдання, рішення, які стосуються: + + - конкретних тасок, + + - спринтів, + + - обговорень проєктів. + +- Може бути збережена як: + + - підсумки сесій, + + - «замітки агента», + + - структуровані записи (JSON). + +Використання: + +- контекст для агентських звітів, + +- нагадування про те, що команда домовилася зробити. + +## 2.3. Long-Term Memory (LTM) + +- Узагальнені факти про: + + - команду, + + - проєкти, + + - стилі роботи, + + - правила, + + - терміни та словник. + +Формат: + +- списки фактів (текстові), + +- векторні ембедінги (для RAG). + +Приклади фактів: + +- «Наш основний продукт — MicroDAO, ми фокусуємося на невеликих спільнотах.» + +- «Для терміну "DAGI" ми маємо окремий опис, який завжди треба враховувати.» + +--- + +# 3. Простір памʼяті (Scopes) + +Памʼять розділяється за обсягом: + +1. **Personal** + + - пов'язана з конкретним користувачем (Personal Agent). + +2. **Channel** + + - стосується конкретного каналу, де агент працює. + +3. **Team (microDAO)** + + - загальна памʼять всієї спільноти. + +4. **Global / DAGI** + + - узагальнені патерни, які можуть бути анонімізовано експортовані. + +--- + +# 4. Модель даних + +### Таблиці (логічно): + +- `agent_memory_events` + + - id + + - agent_id + + - team_id + + - channel_id (optional) + + - user_id (optional) + + - scope: `short_term | mid_term | long_term` + + - kind: `message | fact | summary | note` + + - body: text/json + + - created_at + +- `agent_memory_facts_vector` + + - id + + - team_id + + - agent_id + + - fact_text + + - embedding (vector) + + - metadata (json) + +- `agent_memory_snapshots` (опціонально) + + - агреговані snapshot-и стану памʼяті. + +--- + +# 5. AgentMemoryAdapter (деталізація) + +Посилання на 12_agent_runtime_core.md: + +```ts +export interface AgentMemoryAdapter { + loadShortTerm(ctx: AgentContext): Promise; + loadLongTerm(ctx: AgentContext): Promise; + saveTurn(ctx: AgentContext, turn: AgentMessage): Promise; + appendFact(ctx: AgentContext, fact: string): Promise; +} +``` + +### 5.1. loadShortTerm + +* Витягує останні `N` подій типу `kind = 'message'` зі scope `short_term` для: + + * `agent_id`, + + * `team_id`, + + * `channel_id` (якщо є). + +### 5.2. loadLongTerm + +* Витягує список текстових фактів зі scope `long_term` (через `agent_memory_events` з `kind = 'fact'`). + +### 5.3. saveTurn + +* Записує повідомлення user/assistant як `message` (short-term). + +* Якщо увімкнено автоматичне ущільнення памʼяті — може переносити деякі фрагменти в mid-term. + +### 5.4. appendFact + +* Додає факт у long-term (як `kind = 'fact'`). + +* Додатково: + + * рахує ембедінг (через окремий LLM/embedding API), + + * зберігає в `agent_memory_facts_vector`. + +--- + +# 6. RAG (Retrieval-Augmented Generation) + +### 6.1. Retrieval + +Коли агент отримує новий запит, перед викликом LLM: + +1. Формує пошуковий запит (query) з тексту user. + +2. Шукає релевантні факти у: + + * `agent_memory_facts_vector`, + + * (опційно) Co-Memory документів (файли, wiki). + +3. Обмежує контекст, наприклад Top-K = 5–10 фактів. + +### 6.2. Включення в промпт + +Факти додаються в `LONG_TERM_MEMORY` (див. 12_agent_runtime_core.md): + +```ts +const memoryMsg: AgentMessage = { + role: "system", + content: + "LONG_TERM_MEMORY:\n" + + retrievedFacts.map((f, i) => `- ${f.text}`).join("\n"), +}; +``` + +--- + +# 7. Перетікання памʼяті (compression / distillation) + +Щоб памʼять не перетворювалась на хаос, потрібні періодичні "distillation jobs". + +### 7.1. Distillation Job + +Раз на N повідомлень або раз на день для команди: + +1. Беремо всі short-term повідомлення за певний період. + +2. Feed-имо їх у Meta-Agent (див. 09_evolutionary_agent.md). + +3. Отримуємо: + + * конспект (summary), + + * витяг корисних фактів, + + * пропозиції правил. + +4. Записуємо: + + * summary → mid-term, + + * факти → long-term (appendFact), + + * пропозиції → evolution suggestions. + +### 7.2. Видалення шуму + +Після успішної дистиляції: + +* можна частину короткої памʼяті чистити; + +* можна перевести непотрібні `message` у архів. + +--- + +# 8. Контроль з боку користувача + +У UI потрібно дати користувачу можливість: + +1. Переглядати памʼять (принаймні long-term): + + * список фактів, + + * розділений по каналах / темах. + +2. Видаляти факти: + + * для конфіденційних даних, + + * при помилках. + +3. Вимикати зберігання: + + * «Не зберігати DM-переписку з агентом у довгострокову памʼять». + +4. Експортувати памʼять: + + * для аудиту / переносу. + +--- + +# 9. Memory Scopes vs Agent Roles + +### Guide Agent (онбординг) + +* short-term: поточна сесія онбордингу; + +* long-term: факти про те, як виглядає створена команда (не обовʼязково). + +### Team Assistant + +* short-term: останні діалоги в конкретному каналі; + +* mid-term: summaries мітингів / сесій; + +* long-term: знання про команду, процеси, словник. + +### Meta-Agent + +* працює на mid-/long-term даних: + + * аналізує їх, + + * пропонує зміни в правилах, + + * оновлює памʼять. + +--- + +# 10. Псевдокод реалізації Adapter'а + +```ts +export class PgAgentMemoryAdapter implements AgentMemoryAdapter { + async loadShortTerm(ctx: AgentContext): Promise { + const rows = await db.agent_memory_events.findMany({ + where: { + agent_id: ctx.agent.id, + team_id: ctx.teamId, + channel_id: ctx.channelId ?? null, + scope: "short_term", + kind: "message", + }, + orderBy: { created_at: "desc" }, + limit: 50, + }); + + return rows.reverse().map(rowToMessage); + } + + async loadLongTerm(ctx: AgentContext): Promise { + const rows = await db.agent_memory_events.findMany({ + where: { + agent_id: ctx.agent.id, + team_id: ctx.teamId, + scope: "long_term", + kind: "fact", + }, + orderBy: { created_at: "desc" }, + limit: 100, + }); + + return rows.map(r => r.body_text); + } + + async saveTurn(ctx: AgentContext, turn: AgentMessage): Promise { + await db.agent_memory_events.insert({ + agent_id: ctx.agent.id, + team_id: ctx.teamId, + channel_id: ctx.channelId ?? null, + scope: "short_term", + kind: "message", + body_json: turn, + }); + } + + async appendFact(ctx: AgentContext, fact: string): Promise { + await db.agent_memory_events.insert({ + agent_id: ctx.agent.id, + team_id: ctx.teamId, + scope: "long_term", + kind: "fact", + body_text: fact, + }); + + // TODO: обчислити embedding та зберегти у agent_memory_facts_vector + } +} +``` + +--- + +# 11. RAG Implementation + +## 11.1. Embedding Generation + +```ts +import { OpenAIEmbeddings } from "langchain/embeddings/openai"; + +const embeddings = new OpenAIEmbeddings({ + openAIApiKey: process.env.OPENAI_API_KEY, +}); + +export async function generateEmbedding(text: string): Promise { + const result = await embeddings.embedQuery(text); + return result; +} +``` + +## 11.2. Vector Search + +```ts +export async function searchRelevantFacts( + query: string, + agentId: string, + teamId: string, + topK: number = 5 +): Promise> { + // Генеруємо embedding для запиту + const queryEmbedding = await generateEmbedding(query); + + // Шукаємо найближчі вектори (cosine similarity) + const results = await db.$queryRaw` + SELECT + fact_text, + 1 - (embedding <=> ${queryEmbedding}::vector) as similarity + FROM agent_memory_facts_vector + WHERE agent_id = ${agentId} + AND team_id = ${teamId} + ORDER BY similarity DESC + LIMIT ${topK} + `; + + return results.map(r => ({ + text: r.fact_text, + score: r.similarity, + })); +} +``` + +## 11.3. Integration with runAgentTurn + +```ts +export async function runAgentTurn(ctx: AgentContext): Promise { + // 1. Завантажуємо short-term пам'ять + const shortTerm = await ctx.memory.loadShortTerm(ctx); + + // 2. RAG: шукаємо релевантні факти + const relevantFacts = await searchRelevantFacts( + ctx.input, + ctx.agent.id, + ctx.teamId, + 5 + ); + + // 3. Завантажуємо long-term (статичні факти) + const longTerm = await ctx.memory.loadLongTerm(ctx); + + // 4. Об'єднуємо RAG-результати з long-term + const allFacts = [ + ...relevantFacts.map(f => f.text), + ...longTerm, + ]; + + // 5. Готуємо повідомлення для LLM + const messages = buildLLMMessages(ctx, shortTerm, allFacts); + + // ... решта логіки +} +``` + +--- + +# 12. Distillation Job Implementation + +```ts +export async function runDistillationJob( + agentId: string, + teamId: string, + period: { from: Date; to: Date } +): Promise { + // 1. Збираємо всі short-term повідомлення за період + const messages = await db.agent_memory_events.findMany({ + where: { + agent_id: agentId, + team_id: teamId, + scope: "short_term", + kind: "message", + created_at: { + gte: period.from, + lte: period.to, + }, + }, + orderBy: { created_at: "asc" }, + }); + + // 2. Формуємо контекст для Meta-Agent + const conversationLog = messages.map(m => ({ + role: m.body_json.role, + content: m.body_json.content, + timestamp: m.created_at, + })); + + // 3. Викликаємо Meta-Agent для аналізу + const metaAgent = await getMetaAgent(agentId); + const analysis = await metaAgent.analyze(conversationLog); + + // 4. Зберігаємо результати + if (analysis.summary) { + await db.agent_memory_events.create({ + data: { + agent_id: agentId, + team_id: teamId, + scope: "mid_term", + kind: "summary", + body_text: analysis.summary, + }, + }); + } + + if (analysis.facts && analysis.facts.length > 0) { + for (const fact of analysis.facts) { + await db.agent_memory_events.create({ + data: { + agent_id: agentId, + team_id: teamId, + scope: "long_term", + kind: "fact", + body_text: fact, + }, + }); + + // Генеруємо embedding та зберігаємо + const embedding = await generateEmbedding(fact); + await db.agent_memory_facts_vector.create({ + data: { + agent_id: agentId, + team_id: teamId, + fact_text: fact, + embedding: embedding, + }, + }); + } + } + + // 5. Очищаємо оброблені short-term повідомлення + await db.agent_memory_events.deleteMany({ + where: { + agent_id: agentId, + team_id: teamId, + scope: "short_term", + kind: "message", + created_at: { + gte: period.from, + lte: period.to, + }, + }, + }); +} +``` + +--- + +# 13. Database Schema + +## 13.1. agent_memory_events + +```sql +CREATE TABLE agent_memory_events ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + agent_id UUID NOT NULL REFERENCES agents(id), + team_id UUID NOT NULL REFERENCES teams(id), + channel_id UUID REFERENCES channels(id), + user_id UUID REFERENCES users(id), + scope TEXT NOT NULL CHECK (scope IN ('short_term', 'mid_term', 'long_term')), + kind TEXT NOT NULL CHECK (kind IN ('message', 'fact', 'summary', 'note')), + body_text TEXT, + body_json JSONB, + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + + INDEX idx_agent_team_scope (agent_id, team_id, scope), + INDEX idx_agent_channel (agent_id, channel_id), + INDEX idx_created_at (created_at) +); +``` + +## 13.2. agent_memory_facts_vector + +```sql +CREATE EXTENSION IF NOT EXISTS vector; + +CREATE TABLE agent_memory_facts_vector ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + agent_id UUID NOT NULL REFERENCES agents(id), + team_id UUID NOT NULL REFERENCES teams(id), + fact_text TEXT NOT NULL, + embedding vector(1536), -- OpenAI ada-002 embedding size + metadata JSONB, + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + + INDEX idx_agent_team (agent_id, team_id), + INDEX idx_embedding USING ivfflat (embedding vector_cosine_ops) +); +``` + +--- + +# 14. API Endpoints + +## 14.1. GET /agents/{id}/memory + +```ts +export async function getAgentMemory(req: Request, res: Response) { + const { agentId } = req.params; + const { scope, limit = 50 } = req.query; + + const memory = await db.agent_memory_events.findMany({ + where: { + agent_id: agentId, + scope: scope as string, + }, + orderBy: { created_at: "desc" }, + take: parseInt(limit as string), + }); + + res.json({ + scope, + items: memory, + }); +} +``` + +## 14.2. DELETE /agents/{id}/memory/{memoryId} + +```ts +export async function deleteMemoryItem(req: Request, res: Response) { + const { agentId, memoryId } = req.params; + + await db.agent_memory_events.delete({ + where: { + id: memoryId, + agent_id: agentId, + }, + }); + + res.json({ success: true }); +} +``` + +## 14.3. POST /agents/{id}/memory/distill + +```ts +export async function triggerDistillation(req: Request, res: Response) { + const { agentId } = req.params; + const { days = 7 } = req.body; + + const from = new Date(); + from.setDate(from.getDate() - days); + + await runDistillationJob(agentId, req.teamId, { + from, + to: new Date(), + }); + + res.json({ success: true }); +} +``` + +--- + +# 15. Інтеграція з еволюційним агентом (09) + +Еволюційний агент: + +* читає `agent_memory_events` (особливо з негативним фідбеком), + +* агрегує логи, + +* робить distillation, + +* створює пропозиції покращень. + +Memory System → джерело для: + +* аналізу діалогів, + +* виявлення патернів, + +* побудови Train-to-Earn. + +--- + +# 16. Тестування + +## 16.1. Unit Tests + +```ts +describe("PgAgentMemoryAdapter", () => { + it("should load short-term memory", async () => { + const adapter = new PgAgentMemoryAdapter(); + const ctx = createMockContext(); + + const messages = await adapter.loadShortTerm(ctx); + expect(messages).toBeInstanceOf(Array); + expect(messages.length).toBeLessThanOrEqual(50); + }); + + it("should save turn to memory", async () => { + const adapter = new PgAgentMemoryAdapter(); + const ctx = createMockContext(); + const turn: AgentMessage = { + role: "user", + content: "Test message", + }; + + await adapter.saveTurn(ctx, turn); + + const messages = await adapter.loadShortTerm(ctx); + expect(messages).toContainEqual( + expect.objectContaining({ content: "Test message" }) + ); + }); +}); +``` + +--- + +# 17. Завдання для Cursor + +Приклад промта: + +``` +You are a senior backend engineer. + +Implement the Agent Memory System for MicroDAO using: + +- 13_agent_memory_system.md +- 12_agent_runtime_core.md +- 11_llm_integration.md +- 09_evolutionary_agent.md +- 05_coding_standards.md + +Tasks: + +1) Create tables: agent_memory_events, agent_memory_facts_vector. + +2) Implement PgAgentMemoryAdapter with short-term + long-term. + +3) Wire PgAgentMemoryAdapter into Agent Runtime Core. + +4) Add a simple RAG retrieval step using facts. + +5) Expose a debug endpoint to inspect agent memory (GET /agents/{id}/memory). + +Output: + +- list of modified files +- diff +- summary +``` + +--- + +# 18. Результат + +Після впровадження цієї системи: + +* агенти MicroDAO мають справжню багаторівневу памʼять; + +* можна керувати тим, що саме вони памʼятають; + +* можна будувати RAG, еволюційний аналіз, Train-to-Earn; + +* перехід до DAGI стає природним — через спільну колективну памʼять агентів. + +--- + +**Готово.** +Це **повна специфікація системи пам'яті агентів**, готова до використання в Cursor. + + diff --git a/docs/cursor/14_messenger_agent_module.md b/docs/cursor/14_messenger_agent_module.md new file mode 100644 index 00000000..5499a79a --- /dev/null +++ b/docs/cursor/14_messenger_agent_module.md @@ -0,0 +1,589 @@ +# 14 — Messenger Agent Module (MicroDAO) + +Агентське переосмислення месенджера + +Цей документ описує, як класичний "месенджер" (Telegram/WhatsApp-подібний інтерфейс) реалізований у MicroDAO як **агент-модуль**, а не просто список чатів. + +--- + +# 1. Ідея + +Замість "голої" стрічки чатів у MicroDAO є: + +- **Agent Messenger** — підагент всередині microDAO, який: + + - знає про всі чати, канали, DM; + + - вміє показувати потрібні розмови за запитом користувача; + + - вміє сам пропонувати релевантні чати; + + - інтегрований з памʼяттю (13) і runtime (12); + + - може працювати як "голосовий/текстовий UI" поверх звичайного месенджера. + +Класичні фічі месенджера (чати, канали, DM, статуси, непрочитані, пошук) — описані як **спроможності агента**, а не просто як UI. + +--- + +# 2. Ролі агентів у модулі месенджера + +## 2.1. Messenger Agent (core) + +Роль: `"messenger_core"` (може бути профіль Team Assistant або окремий агент). + +Він: + +- знає структуру: + + - `teams` (microDAO), + + - `channels` (публічні/приватні), + + - `direct messages`, + + - `threads` (якщо ввімкнено), + +- має доступ до: + + - списку чатів, + + - їхнього стану (непрочитані, muted, pinned), + + - історії повідомлень (через Messaging Service / Memory). + +## 2.2. User-Facing Agent (асистент користувача) + +Користувач взаємодіє не з "меню чатів", а з агентом: + +- "Покажи мені всі непрочитані по проекту X" + +- "Знайди переписку, де ми обговорювали токеноміку" + +- "Підготуй резюме сьогоднішнього дня по всіх каналах" + +User-facing агент делегує запити Messenger Agent'у. + +--- + +# 3. Функціональні спроможності Messenger Agent + +## 3.1. Базові (класичний месенджер) + +Під капотом елевантні фічі: + +- Список каналів і чатів: + + - публічні канали, + + - приватні канали, + + - особисті чати (DM), + + - системні / службові. + +- Стани: + + - `unread_count`, + + - `muted`, + + - `pinned`, + + - `last_message` + `last_activity_at`. + +- Повідомлення: + + - текст, + + - посилання, + + - (пізніше) вкладення, + + - реакції (on/off для MVP). + +- Системні події: + + - додавання/видалення учасників, + + - зміна назви/іконки, + + - інвайти. + +Це реалізується Messaging Service (див. 02/03/04), але доступно агенту як "інструменти". + +## 3.2. Розширені (агентські) + +Messenger Agent вміє: + +1. **Фільтрувати чати:** + + - за проектом, + + - за учасником, + + - за темою (через пошук + RAG). + +2. **Будувати "розумні папки":** + + - "Сьогоднішні важливі розмови", + + - "Все, де тебе тегнули", + + - "Все, що стосується токеноміки/DAO". + +3. **Проводити огляди:** + + - "Зроби щоденний дайджест по всіх каналах", + + - "Поясни, що змінилось з учора". + +4. **Автоматично створювати follow-ups / задачі:** + + - над певними патернами (наприклад, "зробимо", "потрібно", "до пʼятниці"). + +--- + +# 4. Інтерфейс з точки зору користувача + +### 4.1. Класичний UI (sidebar + список чатів) + +Звичайний sidebar: + +- Канали, + +- DM, + +- Папки/фільтри (Unread, Mentions, Starred). + +Але поверх нього — **агентське поле запиту**: + +> "Напиши, що ти хочеш побачити" +> (input зверху або окремий Agent Chat). + +Приклади: + +- "Покажи тільки непрочитані в робочих каналах" + +- "Відфільтруй чати, де обговорюється MicroDAO MVP" + +- "Покажи останні 10 повідомлень від Марії" + +Агент відповідає: + +- або у вигляді пояснювальної репліки; + +- або оновлює UI (відкриває/фільтрує потрібні чати). + +### 4.2. Повністю агентський режим + +У майбутньому можливо: + +- взагалі без списку чатів; + +- користувач спілкується з агентом: + + > "Що важливого в команді за сьогодні?" + > "Покажи діалог з Ігорем, де ми обговорювали бюджети." + > "Знайди канал, де ми домовлялись про токеноміку." + +--- + +# 5. Інтеграція з Agent Runtime Core (12) + +Messenger Agent описується як звичайний агент: + +```ts +const messengerAgentConfig: AgentConfig = { + id: "ag_messenger_core", + teamId: "t_...", + name: "Messenger Core", + role: "team_assistant", + systemPrompt: systemMessengerPrompt, + memoryScope: "team", + tools: [ + "list_channels", + "list_unread", + "search_messages", + "open_channel", + "get_daily_digest", + "create_followup_from_message" + ], +}; +``` + +Tools реалізуються через Messaging Service: + +```ts +const tools: ToolRegistry = { + async list_channels(ctx, args) { ... }, + async list_unread(ctx, args) { ... }, + async search_messages(ctx, args) { ... }, + async open_channel(ctx, args) { ... }, // повертає метаданні каналу + async get_daily_digest(ctx, args) { ... }, +}; +``` + +Агент runtime (`runAgentTurn`) вирішує: + +* чи просто відповісти текстом, + +* чи викликати tools, + +* чи комбінувати. + +--- + +# 6. Інтеграція з памʼяттю (13) + +Messenger Agent: + +* **Short-term** — поточний контекст каналу/діалогу. + +* **Long-term** — факти: + + * які канали важливі для яких людей, + + * які теми зʼявляються часто, + + * які теги/поняття повʼязані з якими чатами. + +Приклад фактів: + +* "Канал #governance використовується для голосувань DAO." + +* "Канал #dev-mvp обговорює реалізацію MVP MicroDAO." + +Це дозволяє агенту: + +* відповідати на питання типу: + + * "Де обговорювати зміни в governance?" + +* пропонувати: + + * "Здається, обговорення токеноміки краще перенести в #tokenomics." + +--- + +# 7. Типові сценарії використання + +### Сценарій 1 — Новий учасник + +Новачок пише агенту: + +> "Я щойно приєднався. Де мені почитати, що тут відбувається?" + +Messenger Agent: + +* знаходить 2–3 ключові канали, + +* дає короткі описи, + +* пропонує їх відкрити. + +### Сценарій 2 — Щоденний огляд + +> "Сформуй підсумок за день." + +Messenger Agent: + +* використовує `get_daily_digest` tool, + +* збирає важливі повідомлення/канали, + +* створює summary (через LLM), + +* відправляє повідомлення у спеціальний канал або в DM. + +### Сценарій 3 — Пошук контексту + +> "Знайди, де ми домовлялись про дедлайн запуску DAGI." + +Messenger Agent: + +* шукає в повідомленнях (Meilisearch + RAG), + +* показує релевантні уривки, + +* пропонує створити follow-up або задачу. + +--- + +# 8. Взаємодія з іншими агентами + +* **Team Assistant** може делегувати складні запити Messenger Agent'у. + +* **Evolution Meta-Agent** аналізує: + + * які канали важливі; + + * які патерни запитів до Messenger Agent'а повторюються; + + * які нові "розумні фільтри" варто запропонувати. + +--- + +# 9. Реалізація Tools + +## 9.1. list_channels + +```ts +async function list_channels( + ctx: AgentContext, + args: { filter?: "public" | "private" | "all"; projectId?: string } +): Promise { + const channels = await db.channels.findMany({ + where: { + teamId: ctx.teamId, + ...(args.filter === "public" && { type: "public" }), + ...(args.filter === "private" && { type: "group" }), + ...(args.projectId && { projectId: args.projectId }), + }, + include: { + _count: { + select: { messages: true }, + }, + }, + }); + + return channels.map(ch => ({ + id: ch.id, + name: ch.name, + type: ch.type, + description: ch.description, + messageCount: ch._count.messages, + })); +} +``` + +## 9.2. list_unread + +```ts +async function list_unread( + ctx: AgentContext, + args: { userId?: string } +): Promise> { + const userId = args.userId || ctx.userId; + + const unread = await db.userChannelStates.findMany({ + where: { + userId, + teamId: ctx.teamId, + unreadCount: { gt: 0 }, + }, + include: { + channel: true, + }, + }); + + return unread.map(u => ({ + channelId: u.channelId, + channelName: u.channel.name, + unreadCount: u.unreadCount, + lastMessageAt: u.lastReadAt, + })); +} +``` + +## 9.3. search_messages + +```ts +async function search_messages( + ctx: AgentContext, + args: { query: string; channelId?: string; limit?: number } +): Promise { + // Використовуємо Meilisearch для пошуку + const results = await meilisearchClient + .index("messages") + .search(args.query, { + filter: [ + `teamId = ${ctx.teamId}`, + ...(args.channelId ? [`channelId = ${args.channelId}`] : []), + ], + limit: args.limit || 10, + }); + + return results.hits.map(hit => ({ + id: hit.id, + channelId: hit.channelId, + content: hit.content, + authorId: hit.authorId, + createdAt: hit.createdAt, + })); +} +``` + +## 9.4. get_daily_digest + +```ts +async function get_daily_digest( + ctx: AgentContext, + args: { date?: string; channels?: string[] } +): Promise { + const date = args.date || new Date().toISOString().split("T")[0]; + const startOfDay = new Date(date + "T00:00:00Z"); + const endOfDay = new Date(date + "T23:59:59Z"); + + // Збираємо важливі повідомлення за день + const messages = await db.messages.findMany({ + where: { + teamId: ctx.teamId, + createdAt: { + gte: startOfDay, + lte: endOfDay, + }, + ...(args.channels && { channelId: { in: args.channels } }), + }, + include: { + author: true, + channel: true, + }, + orderBy: { createdAt: "desc" }, + take: 100, + }); + + // Формуємо контекст для LLM + const context = messages.map(m => ({ + channel: m.channel.name, + author: m.author.name, + content: m.content, + time: m.createdAt, + })); + + // Викликаємо LLM для створення дайджесту + const digest = await ctx.llm.complete(ctx, [ + { + role: "system", + content: "You are a summarizer. Create a concise daily digest of team communications.", + }, + { + role: "user", + content: JSON.stringify(context), + }, + ]); + + return digest; +} +``` + +--- + +# 10. System Prompt для Messenger Agent + +```txt +You are the Messenger Agent for MicroDAO. + +Your role is to help users navigate and interact with channels, messages, and conversations. + +You can: +- List and filter channels +- Search for messages and conversations +- Show unread messages +- Create daily digests +- Suggest relevant channels based on topics + +Always be concise and helpful. When a user asks to see something, use the appropriate tools to fetch the data and present it clearly. + +If you don't understand a request, ask for clarification. +``` + +--- + +# 11. UI Integration + +## 11.1. Agent Query Input + +Додати поле вводу над списком каналів: + +```tsx + { + const response = await agentChat(messengerAgentId, [ + { role: "user", content: query }, + ]); + + // Відобразити відповідь або оновити UI + if (response.action === "filter_channels") { + setFilteredChannels(response.channels); + } else { + showAgentResponse(response.reply); + } + }} +/> +``` + +## 11.2. Smart Filters + +Агент може створювати динамічні фільтри: + +```tsx + { + const result = await agentChat(messengerAgentId, [ + { role: "user", content: "Покажи канали з непрочитаними повідомленнями за сьогодні" }, + ]); + applyFilter(result.channels); + }} +/> +``` + +--- + +# 12. Завдання для Cursor + +Приклад промта: + +``` +You are a senior full-stack engineer. + +Implement the Messenger Agent module using: + +- 14_messenger_agent_module.md +- 12_agent_runtime_core.md +- 13_agent_memory_system.md +- 03_api_core_snapshot.md +- 05_coding_standards.md + +Tasks: + +1) Define messengerAgentConfig and register it in the Agents system. + +2) Implement tools: + - list_channels + - list_unread + - search_messages + - get_daily_digest (stub) + +3) Add Messenger Agent entrypoint in the UI (e.g. "Ask Messenger" input above channel list). + +4) Wire user queries from this input to /agents/{id}/chat using messengerAgentConfig. + +Output: + +- list of modified files +- diff +- summary +``` + +--- + +# 13. Результат + +Після впровадження Messenger Agent: + +* MicroDAO перестає бути "ще одним месенджером"; + +* користувач взаємодіє з агентом, а не просто з переліком чатів; + +* всі класичні можливості месенджера залишаються, але стають **інструментами** всередині агентської ОС. + +--- + +**Готово.** +Це **повна специфікація Messenger Agent модуля**, готова до використання в Cursor. + + diff --git a/docs/cursor/15_projects_agent_module.md b/docs/cursor/15_projects_agent_module.md new file mode 100644 index 00000000..c179d4bd --- /dev/null +++ b/docs/cursor/15_projects_agent_module.md @@ -0,0 +1,376 @@ +# 15 — Projects Agent Module (MicroDAO) + +Агент-проєктний менеджер для команд і спільнот + +Цей документ описує агентський модуль "Проєкти" у MicroDAO — систему управління роботою, яка повністю працює через агентів. Проєкти, задачі, дедлайни, фоллоуапи та прогрес — це не просто дані, а живий простір, у якому взаємодіють люди та агенти microDAO. + +--- + +# 1. Ідея + +Проєкт у MicroDAO — це: + +- спільний простір роботи, +- де активні ролі мають люди та агенти, +- де задачі створюються й координуються автоматично, +- де агент проектів (Projects Agent) виступає координатором, навігатором і аналітиком. + +Проєкт не існує як "сторінка". Він існує як **розмова**, **контекст**, **граф подій**, яким володіє Projects Agent. + +--- + +# 2. Ролі агентів у модулі + +## 2.1. Projects Agent (основний) + +Роль: `"projects_core"` + +Відповідає за: + +- створення, оновлення, завершення задач; +- синхронізацію задач з каналами/чатами; +- календар дедлайнів; +- AI-саммарі проєкту; +- глибоку інтеграцію з памʼяттю для пріоритизації. + +## 2.2. Task Agent + +Роль: `"task_unit"` + +- Опікується конкретними задачами. +- Може вести діалог про задачу у власному треді. +- Має памʼять щодо історії виконання конкретної задачі. + +## 2.3. Planning Agent (опційний) + +Роль: `"planning"` + +- Створює дорожні карти (roadmaps), +- Пропонує структурування задач, +- Формує спринти, +- Аналізує історичні патерни роботи в microDAO. + +--- + +# 3. Структура проєкту + +Проєкт складається з: + +- **Мета** (опис/маніфест), +- **Учасники** (люди й агенти), +- **Задачі**: + + - backlog, + - активні, + - завершені. + +- **Knowledge Space** (повʼязані документи/факти), +- **Проєктний контекст у памʼяті**: + + - важливі рішення, + - визначення, + - стандарти/узгодження, + +- **Канали спілкування**: + + - основний канал проєкту, + - треди задач. + +Проєкт і канал — різні речі, але проєкт зазвичай має прив'язаний канал для комунікації. + +--- + +# 4. Модель задачі + +Задача (`task`) має: + +- `id` +- `project_id` +- `title` +- `description` +- `status`: `"new" | "in_progress" | "blocked" | "done"` +- `priority`: `"low" | "medium" | "high" | "critical"` +- `assignees`: перелік людей/агентів +- `due_at` (необовʼязково) +- `created_by` (людина або агент) +- `created_at`, `updated_at` +- `memory_thread_id` (для диалогу з Task Agent) +- `tags` (опційно) + +Задача може мати чат-тред, пов'язаний з Task Agent. + +--- + +# 5. Основні спроможності Projects Agent + +## 5.1. Авто-створення задач з діалогів + +Якщо в чаті зʼявляється фраза: + +- "Треба зробити…" +- "Хочу щоб агент підготував…" +- "До кінця тижня потрібно…" +- "Це треба виправити." + +Projects Agent може запропонувати: + +> "Створити задачу для цього?" + +Або може створити самостійно, якщо це дозволено правами контексту. + +## 5.2. Автоматичні фоллоуапи + +Projects Agent: + +- відстежує дедлайни, +- нагадує виконавцю, +- пропонує оновлення статусу, +- створює автосаммарі тижня/дня. + +## 5.3. Розумні саммарі проєкту + +Команда може попросити: + +- "Покажи прогрес по проєкту." +- "Що зроблено за останні 3 дні?" +- "Які блокери є зараз?" + +Projects Agent формує відповіді через LLM + памʼять + RAG. + +## 5.4. Привʼязка до каналів + +Кожен проєкт має: + +- основний канал, +- треди задач. + +Projects Agent синхронізує зміни задач у чаті: + +- статуси, +- дедлайни, +- призначення. + +## 5.5. Планування і пріоритети + +Projects Agent може: + +- групувати задачі в спринти, +- пропонувати чергу виконання, +- аналізувати історію виконання. + +--- + +# 6. Tools для Projects Agent + +У форматі, що сумісний з Runtime Core (12). + +### 6.1. Створення задач + +`create_task(title, description, priority?, due_at?, assignees?)` + +### 6.2. Оновлення задач + +`update_task(id, fields)` + +### 6.3. Призначення виконавців + +`assign_task(id, assignees)` + +### 6.4. Пошук задач + +`search_tasks(query)` + +### 6.5. Показати прогрес проєкту + +`summarize_project(project_id)` + +### 6.6. Створення спринтів + +`create_sprint(name, tasks)` + +### 6.7. Авто-фоллоуап + +`auto_followup(task_id)` + +--- + +# 7. Інтеграція з Runtime Core (12) + +Projects Agent — звичайний агент: + +```ts +const projectsAgentConfig: AgentConfig = { + id: "ag_projects_core", + teamId: "t_...", + name: "Projects Agent", + role: "projects_core", + systemPrompt: systemProjectsPrompt, + memoryScope: "team", + tools: [ + "create_task", + "update_task", + "assign_task", + "search_tasks", + "summarize_project", + "auto_followup" + ], +}; +``` + +Projects Agent працює з: + +* памʼяттю (13), +* каналами (14), +* еволюційним агентом (09), +* LLM (11). + +--- + +# 8. Інтеграція з памʼяттю (13) + +Projects Agent використовує: + +### 8.1. Short-Term Memory + +* поточні обговорення задач у каналі проєкту. + +### 8.2. Long-Term Memory + +* ключові рішення команди, +* визначення задач і стандартів, +* історія пріоритетів. + +### 8.3. Mid-Term Memory + +* summary спринтів, +* переліки завершених задач, +* звіти про прогрес. + +Projects Agent додає факти в памʼять: + +* "Задачу X завершено 12 жовтня." +* "Проєкт переходить до етапу тестування." + +--- + +# 9. Інтеграція з Messenger Agent (14) + +Messenger Agent допомагає Projects Agent: + +* показувати списки задач у чатах, +* формувати треди для задач, +* робити дайджести по каналах. + +Projects Agent може викликати Messenger Agent через tools або через делегацію. + +--- + +# 10. API для проєктів та задач + +### 10.1. Projects + +`GET /projects?team_id=...` +`POST /projects` +`GET /projects/:id` +`PATCH /projects/:id` + +### 10.2. Tasks + +`GET /projects/:id/tasks` +`POST /tasks` +`PATCH /tasks/:id` +`GET /tasks/:id` + +Модель задачі повинна бути сумісною з Task Agent. + +--- + +# 11. UI інтеграція + +## 11.1. Sidebar → Projects + +У лівому сайдбарі в блоці "Простори" відображаються: + +* список проєктів, +* кнопка "Створити проєкт". + +## 11.2. Right Sidebar → Project Context + +Коли користувач знаходиться у каналі проєкту: + +* правий сайдбар показує: + + * назву проєкту, + * короткий опис, + * задачі по статусам, + * кнопку "Нова задача". + +## 11.3. Task Panel + +Клік по задачі відкриває: + +* повну картку задачі, +* чат-тред задачі, +* дії: + + * змінити статус, + * призначити, + * додати опис, + * переглянути памʼять. + +--- + +# 12. Інструкції для Cursor + +Приклад промта: + +``` +Implement the Projects Agent module using: + +- 15_projects_agent_module.md +- 12_agent_runtime_core.md +- 13_agent_memory_system.md +- 14_messenger_agent_module.md +- 10_agent_ui_system.md +- 05_coding_standards.md + +Tasks: + +1) Create models for Project and Task in backend. + +2) Implement basic API: GET/POST/PATCH for projects and tasks. + +3) Register Projects Agent with tools: create_task, update_task, search_tasks, summarize_project. + +4) Implement UI: + + - Projects list in sidebar. + + - Project context panel in right sidebar. + + - Modal for creating tasks. + + - Basic task list with statuses. + +5) Integrate task creation with agent chat (Projects Agent intercepts messages with "треба зробити"). + +Output: + +- list of changed files +- diff +- summary +``` + +--- + +# 13. Результат + +Після впровадження цього модуля: + +* MicroDAO отримує повноцінний агентський менеджмент проєктів; +* задачі створюються з діалогів, а не через форму; +* агенти синхронізують роботу між каналами й людьми; +* зʼявляється можливість планувати спринти, отримувати прогрес і формувати дайджести; +* Projects Agent стає центральним "організатором роботи" у кожному microDAO. + + diff --git a/docs/cursor/16_followups_reminders_agent.md b/docs/cursor/16_followups_reminders_agent.md new file mode 100644 index 00000000..79ddbd5c --- /dev/null +++ b/docs/cursor/16_followups_reminders_agent.md @@ -0,0 +1,339 @@ +# 16 — Follow-ups & Reminders Agent (MicroDAO) + +Агент-нагадувань, ритму та повторних дій у MicroDAO + +Агент Follow-ups & Reminders (далі — Followup Agent) відповідає за ритм роботи, дисципліну задач, таймінг і "догляд" за станом спільноти та проєктів. Він є природним продовженням Projects Agent і Messenger Agent, але має власну функціональність і власну памʼять. + +--- + +# 1. Ідея + +Followup Agent — це: + +- памʼять про обіцянки, завдання та домовленості, +- внутрішній таймер microDAO, +- особистий асистент кожного учасника, +- координатор "ритму" в команді, +- агент, який не дозволяє задачам загубитися. + +Його головна функція — **перетворювати хаотичний чат → впорядкований потік дій**. + +--- + +# 2. Ролі агентів у модулі + +### 2.1. Followup Agent (основний) + +Роль: `"followups_core"` + +Він: + +- відстежує дедлайни, +- нагадує виконавцям, +- створює follow-ups із діалогів, +- пропонує зміни статусів задач, +- робить щоденні/тижневі огляди. + +### 2.2. Personal Reminder Agent (опційний) + +Роль: `"personal_reminder"` + +- створює персональні нагадування для людей, +- вміє працювати в PRIV/DM режимі, +- зберігає приватні повідомлення у локальному особистому просторі користувача. + +--- + +# 3. Документи, які породжує Followup Agent + +Цей агент може автоматично створювати: + +1. **Follow-up** — коротка дія: + + - "З'ясувати статус задачі X" + - "Перевірити, чи готовий документ" + - "Написати у канал #design про оновлення макету" + +2. **Нагадування**: + + - одноразові, + - повторні (щодня/щотижня). + +3. **Запити до виконавців**: + + - "Чи потрібна допомога зі задачею?" + - "Статус задачі лишається незмінним уже 3 дні." + +4. **Огляди стану**: + + - щоденний digest, + - тижневий огляд, + - огляд ризиків. + +--- + +# 4. Logics — коли агент активується + +### 4.1. Фрази-тригери в чатах + +Якщо хтось пише: + +- "Нагадай мені завтра…" +- "Скажи через два дні…" +- "Через годину пінгани мене…" +- "Слухай, перевір статус задачі…" +- "Хай мені хтось нагадає про це в понеділок." + +Followup Agent: + +- перехоплює, +- уточнює (якщо потрібно), +- створює нагадування або follow-up. + +### 4.2. Активність задач + +Followup Agent постійно моніторить: + +- задачі без оновлень (X днів), +- задачі з дедлайнами, +- блокери, +- задачі без призначених виконавців. + +### 4.3. Розмови у каналах + +Якщо в чаті виникає невирішеність: + +- "Хтось має уточнити це у дизайну." +- "Хто відповідає за цей файл?" +- "Було б добре перепровірити після дзвінка." + +Agent пропонує: + +> "Створити follow-up для цього?" + +--- + +# 5. Інтеграція з Projects Agent + +Followup Agent працює разом з Projects Agent: + +- Якщо створюється задача → Followup Agent аналізує дедлайн і встановлює ритм нагадувань. +- Projects Agent створює структуру задач → Followup Agent тримає їхній статус живим. +- Projects Agent відповідає за створення задач → Followup Agent відповідає за виконання, контроль і ритм. + +--- + +# 6. Tools (для інтеграції з Runtime Core) + +Список інструментів, які Followup Agent використовує у форматі 12_agent_runtime_core.md: + +### 6.1. create_followup + +``` +create_followup({ +project_id?, +task_id?, +user_id?, +message, +schedule // "in 1 hour", "tomorrow 09:00", CRON-like +}) +``` + +### 6.2. create_reminder + +``` +create_reminder({ +user_id, +message, +schedule +}) +``` + +### 6.3. check_task_status + +``` +check_task_status(task_id) +``` + +### 6.4. ask_for_update + +``` +ask_for_update(task_id, assignee) +``` + +### 6.5. daily_digest + +``` +daily_digest(project_id | team_id) +``` + +### 6.6. weekly_review + +``` +weekly_review(project_id | team_id) +``` + +--- + +# 7. Memory інтеграція (13) + +Followup Agent активно використовує памʼять: + +### Short-Term Memory + +- контекст діалогу, де користувач дає інструкцію. + +### Mid-Term Memory + +- записи про: + + - виконання/невиконання нагадувань, + - найбільш часті follow-up патерни, + - типові проблеми. + +### Long-Term Memory + +- факти, як от: + + - "Команда працює в ритмі щоденних коротких оглядів." + - "Треба нагадувати за 24 години до дедлайну." + +--- + +# 8. UI інтеграція + +## 8.1. Sidebar / Панель фоллоуапів + +- Список активних нагадувань. +- Список активних follow-ups. +- Кнопка "Створити нагадування". + +## 8.2. Створення нагадування + +- Модалка: + + - "Кому нагадати?" → Людина або собі. + - "Про що?" + - "Коли?" + + - natural language ("завтра о 10") + - або формальні параметри. + +## 8.3. Стрічка подій у правій панелі + +Followup Agent постійно додає записи: + +- "Нагадування заплановано…" +- "Буде перевірено статус задачі…" +- "Follow-up створено…" + +## 8.4. Взаємодія через чат агентів + +Користувач може написати: + +- "Зроби мені кілька нагадувань." +- "Хочу огляд дня." +- "Оціні чи є блокери в цьому проєкті." + +--- + +# 9. API + +### 9.1. Follow-ups + +`GET /followups?team_id` +`POST /followups` +`PATCH /followups/:id` + +### 9.2. Reminders + +`GET /reminders?user_id` +`POST /reminders` +`DELETE /reminders/:id` + +### 9.3. Digest & Reviews + +`POST /digests/daily` +`POST /digests/weekly` + +--- + +# 10. Agent конфіг у Runtime Core + +```ts +const followupAgentConfig: AgentConfig = { + id: "ag_followups_core", + teamId: "...", + name: "Follow-up Agent", + role: "followups_core", + systemPrompt: systemFollowupPrompt, + memoryScope: "team", + tools: [ + "create_followup", + "create_reminder", + "ask_for_update", + "check_task_status", + "daily_digest", + "weekly_review" + ] +}; +``` + +--- + +# 11. Інструкції для Cursor + +Приклад промта: + +``` +Implement the Follow-ups & Reminders Agent using: + +- 16_followups_reminders_agent.md +- 12_agent_runtime_core.md +- 13_agent_memory_system.md +- 15_projects_agent_module.md +- 14_messenger_agent_module.md +- 10_agent_ui_system.md +- 05_coding_standards.md + +Tasks: + +1) Create data models for followups and reminders. + +2) Implement basic API: GET/POST/PATCH for followups and reminders. + +3) Register Followup Agent with tools (create_followup, create_reminder, ask_for_update…). + +4) Create UI: + + - sidebar list of active reminders, + + - modal for creating reminders, + + - follow-up events in right sidebar. + +5) Integrate chat triggers: + + - detect "нагадати", "через", "завтра", "перевір статус" phrases. + + - forward to Followup Agent. + +Output: + +- files list +- diff +- summary +``` + +--- + +# 12. Результат + +Після впровадження Followup Agent: + +* microDAO має власного "агента-організатора ритму", +* задачі й домовленості ніколи не губляться, +* наявна здатність до самодисципліни та самонагляду, +* spільнота працює природно, без формальних таблиць чи менеджерів. + + diff --git a/docs/cursor/17_comemory_knowledge_space.md b/docs/cursor/17_comemory_knowledge_space.md new file mode 100644 index 00000000..2c938c55 --- /dev/null +++ b/docs/cursor/17_comemory_knowledge_space.md @@ -0,0 +1,426 @@ +# 17 — Co-Memory & Knowledge Space (MicroDAO) + +Простір знань і колективна памʼять спільноти + +Co-Memory — це "мозок спільноти". +Це місце, де зберігаються документи, факти, концепти, визначення, історія, рішення, правила й контексти. + +Knowledge Space — це структурована навігація по цій памʼяті, яку розуміють і люди, і агенти. + +Разом вони формують фундамент DAGI — децентралізованого емерджентного інтелекту. + +--- + +# 1. Призначення + +Co-Memory вирішує три завдання: + +1. **Колективні знання** + + - Документи, файли, бази знань. + - Значущі фрагменти (факти, визначення, домовленості). + +2. **Структура знань** + + - Простори (knowledge spaces), + - Теги, + - Категорії, + - RAG-індекси, + - Семантичні групи. + +3. **Інструменти розуміння** + + - RAG-пошук, + - оновлення знань агентами, + - генерація summary, + - інференс подій, + - пропозиції покращення. + +Knowledge Space — це не "Google Drive". +Це **агентський, самооновлюваний простір**, де знання постійно оновлюються через взаємодію спільноти та агентів. + +--- + +# 2. Що таке Knowledge Space + +Knowledge Space — це: + +- "папка", але з контекстом, +- простір, який може містити: + + - документи, + - файли, + - нотатки, + - факти, + - ключові поняття, + +- власну багаторівневу памʼять, +- власних агентів-кураторів знань. + +Кожен Knowledge Space існує як **контекст**, у якому можуть взаємодіяти: + +- люди, +- агент знань, +- інші агенти, +- Projects Agent, +- Followup Agent. + +--- + +# 3. Структура Co-Memory + +Co-Memory складається з: + +### 3.1. Documents (Документи) + +- PDF, MD, DOCX +- структури текстів +- автоматично створювані summary + +### 3.2. Notes (Нотатки) + +- короткі фрагменти, +- конспекти, +- витяги агентів. + +### 3.3. Facts (Факти) + +- короткі текстові знання: + + - "Проєкт MicroDAO запускається в три етапи." + - "Кожен агент має власну пам'ять і колективну памʼять." + +### 3.4. Definitions (Визначення) + +- ключові поняття: + + - "DAGI", + - "Team Agent", + - "1T як одиниця досвіду". + +### 3.5. Threads Memory + +- памʼять дискусій, +- важливі моменти взаємодій у каналах. + +### 3.6. Semantic Embeddings + +- ембедінги документів, нотаток, фактів. + +### 3.7. Metadata & Relations + +- посилання між документами, +- причинно-наслідкові звʼязки, +- залежності між поняттями. + +--- + +# 4. Агенти, пов'язані з Co-Memory + +## 4.1. Memory Agent (основний) + +Роль: `"memory_core"` + +Відповідає за: + +- додавання фактів, +- витяг релевантних знань, +- формування рішень, +- оновлення довгострокової памʼяті агента, +- RAG-індексацію. + +## 4.2. Knowledge Curator Agent + +Роль: `"knowledge_curator"` + +- створює структуру знань, +- перевіряє старі факти, +- пропонує очистку або об'єднання документів, +- формує "канон" спільноти. + +## 4.3. Knowledge Guide Agent + +Роль: `"knowledge_guide"` + +- відповідає на питання: + + - "Що ми знаємо про MicroDAO?" + - "Поясни концепцію DAGI." + - "Покажи документи про governance." + +- виконує RAG-пошук, +- створює підбірки знань. + +--- + +# 5. Життєвий цикл знань + +### Етап 1: Створення + +- документ завантажують, +- агент додає summary, +- Knowledge Space оновлюється. + +### Етап 2: Дистиляція + +- Memory Agent аналізує обговорення, +- створює факти / визначення, +- додає їх у long-term. + +### Етап 3: Об'єднання + +- Curator Agent: + + - виявляє дублікати, + - обʼєднує схожі документи, + - оптимізує структуру. + +### Етап 4: RAG-індексація + +- ембедінги документів, +- векторні індекси, +- контекст для всіх агентів. + +### Етап 5: Використання + +- пошук, +- відповіді на запити, +- автоматичні звіти, +- аналіз проєктів. + +--- + +# 6. Структура даних + +## 6.1. Таблиця `knowledge_spaces` + +- id +- team_id +- name +- description +- created_by +- created_at + +## 6.2. Таблиця `knowledge_documents` + +- id +- space_id +- title +- content_text +- file_url? +- summary +- embedding_vector +- created_at +- updated_at + +## 6.3. Таблиця `knowledge_facts` + +- id +- space_id +- fact_text +- embedding_vector +- created_by +- created_at + +## 6.4. Таблиця `knowledge_relations` + +- id +- from_id +- to_id +- relation_type ("defines", "depends_on", "explains", "references") +- created_by +- created_at + +--- + +# 7. Tools (сумісні з Runtime Core) + +### 7.1. add_document + +Додає документ у Knowledge Space. + +### 7.2. add_fact + +Додає факт у LTM та індексує його. + +### 7.3. get_relevant_knowledge + +RAG-пошук: + +- слова → факти → документи → summary. + +### 7.4. summarize_space + +Створює огляд усього Knowledge Space. + +### 7.5. explain_concept + +Пояснює концепт на основі фактів, визначень, документів. + +### 7.6. link_knowledge + +Створює звʼязки між фактами/документами. + +--- + +# 8. Інтеграція з Runtime Core (12) + +Memory Agent підключається як: + +```ts +const memoryAgentConfig: AgentConfig = { + id: "ag_memory_core", + teamId: "...", + name: "Memory Agent", + role: "memory_core", + systemPrompt: systemMemoryPrompt, + memoryScope: "team", + tools: [ + "add_document", + "add_fact", + "get_relevant_knowledge", + "summarize_space", + "explain_concept", + "link_knowledge" + ] +}; +``` + +--- + +# 9. Інтеграція з Projects, Messenger, Followups + +### Projects Agent + +* додає факти про проєкт у Knowledge Space проєкту. + +### Messenger Agent + +* зберігає важливі уривки обговорень. + +### Followups Agent + +* формує історію ритму та задач у вигляді нотаток. + +--- + +# 10. UI + +## 10.1. Sidebar → Knowledge + +* Список Knowledge Spaces. +* Кнопка "Створити новий простір знань". + +## 10.2. Основний екран Knowledge Space + +* Заголовок. +* Опис. +* Documents. +* Facts. +* Relations. +* Кнопка "Додати документ". +* Кнопка "Додати факт". + +## 10.3. Правий сайдбар Knowledge + +* Рекомендації від агентів. +* Семантичні групи. +* Контекстні звʼязки. + +## 10.4. Чат взаємодії з Knowledge Guide + +* "Поясни мені цей документ…" +* "Що ми знаємо про governance?" +* "Покажи всі визначення, повʼязані з DAGI." + +--- + +# 11. API + +### 11.1. Knowledge Spaces + +`GET /knowledge_spaces?team_id` +`POST /knowledge_spaces` + +### 11.2. Documents + +`GET /knowledge_spaces/:id/documents` +`POST /documents` +`PATCH /documents/:id` + +### 11.3. Facts + +`GET /knowledge_spaces/:id/facts` +`POST /facts` + +### 11.4. Search & RAG + +`POST /knowledge/search` + +→ повертає релевантні факти, документи, summary. + +--- + +# 12. Інструкції для Cursor + +``` +Implement the Co-Memory & Knowledge Space module using: + +- 17_comemory_knowledge_space.md +- 12_agent_runtime_core.md +- 13_agent_memory_system.md +- 14_messenger_agent_module.md +- 15_projects_agent_module.md +- 10_agent_ui_system.md +- 05_coding_standards.md + +Tasks: + +1) Create backend models: + + - knowledge_spaces + - knowledge_documents + - knowledge_facts + - knowledge_relations + +2) Implement API for documents, facts, spaces, relations. + +3) Register Memory Agent and Knowledge Guide Agent with tools: + + - add_document + - add_fact + - get_relevant_knowledge + - explain_concept + - summarize_space + +4) Create UI: + + - Knowledge Spaces list in sidebar + - Knowledge Space page (documents, facts, relations) + - modal for uploading documents + - chat with Knowledge Guide Agent + +5) Integrate RAG search: + + - based on documents + facts + +Output: + +- list of changed files +- diff +- summary +``` + +--- + +# 13. Результат + +Після впровадження цього модуля: + +* кожне microDAO отримує повноцінну еволюційну памʼять, +* агенти знають, що створює спільнота, +* знання не губляться в чатах — вони структуруються, +* DAGI отримує основу для глибинного reasoning, +* MicroDAO перетворюється на справжній "живий простір розуму". + + diff --git a/docs/cursor/18_governance_access_agent.md b/docs/cursor/18_governance_access_agent.md new file mode 100644 index 00000000..ab214de4 --- /dev/null +++ b/docs/cursor/18_governance_access_agent.md @@ -0,0 +1,404 @@ +# 18 — Governance & Access Agent (MicroDAO) + +Агент правил, доступів, ритуалів та духу спільноти + +Цей модуль визначає, як спільнота microDAO керує собою: +правила, права доступу, колективні рішення, символічні ключі, ритуали довіри та механізми узгодження. + +Це НЕ фінансова система. +Це **етико-організаційна інфраструктура**, яка тримає єдність духу спільноти. + +--- + +# 1. Призначення + +Governance & Access Agent відповідає за: + +- **правила спільноти** (policies), +- **роли й дозволи** (RBAC + entitlements), +- **символічні ключі доступу** (soulbound / capability keys), +- **ритуали узгодження** (голосування, сигнали підтримки, консенсус), +- **індекс довіри та реноме** (не фінансовий), +- **координацію взаємодії між агентами та людьми**. + +Все це забезпечує гармонію всередині microDAO. + +--- + +# 2. Ключові концепти + +## 2.1. "Ключі спільноти" (Community Keys) + +Це не монети чи валюта. +Це **символічні доступи**, які визначають: + +- членство, +- рівень участі, +- довіру, +- право вводити/виводити агентів у простір. + +Кожен ключ може бути: + +- **особистим** (soulbound), +- **командним** (для проєкту), +- **контекстним** (для певного простору знань чи каналу). + +## 2.2. "Ритуали узгодження" + +Замість слова "голосування" можна використовувати: + +- "колективний сигнал підтримки", +- "колективна згода", +- "ритуал затвердження". + +Це спрощений процес, який може включати: + +- варіанти "підтримую / не підтримую", +- коментарі, +- пропозиції поправок, +- участь агентів. + +## 2.3. "Індекс довіри" + +Нефінансова, духовна метрика участі: + +- внесок у спільноту, +- кількість створених фактів, +- допомога іншим, +- активність в agent-based просторах, +- прийняті пропозиції. + +--- + +# 3. Роль Governance Agent + +Роль агента: `"governance_core"` + +Він: + +- стежить за правилами, +- пропонує, коли потрібно затвердити зміни, +- забезпечує правильне застосування доступів, +- координує "ритуали узгодження", +- захищає конфіденційні простори, +- видає/анулює символічні ключі. + +--- + +# 4. Ролі Access Agent + +Роль: `"access_keeper"` + +Він: + +- керує entitlements (доступами), +- створює capability-доступи для: + + - людей, + - агентів, + - просторів, + +- гарантує, що агенти не виходять за межі своїх прав. + +--- + +# 5. Структура правил + +## 5.1. Рівні правил + +Правила діляться на 3 рівні: + +1. **Простору (microDAO)** + + - загальні принципи, + - стилістика взаємодії, + - етичні правила. + +2. **Проєкту** + + - специфічні для конкретної роботи, + - права агентів у межах проєкту, + - ритуали перевірки прогресу. + +3. **Контексту / каналу** + + - прості локальні правила. + +## 5.2. Формат зберігання правил + +Таблиця `governance_policies`: + +- id +- team_id +- title +- body_text +- created_by +- scope (`team`, `project`, `channel`) +- created_at + +--- + +# 6. Інтеграція з RBAC та Entitlements + +Використовується модуль `microdao — RBAC and Entitlements (MVP)`. + +Governance Agent: + +- створює entitlements, +- оновлює/анулює доступи, +- пропонує оновлення прав агентів, +- захищає конфіденційні зони. + +Доступ може бути: + +- `read`, +- `write`, +- `tasks`, +- `knowledge`, +- `presence`. + +Ключі можуть бути soulbound, або привʼязані до ролей. + +--- + +# 7. Ритуали узгодження + +## 7.1. Створення ритуалу + +Через чат агентів: + +> "Запропонуй зміни в правилах." +> "Проведи ритуал узгодження щодо нового документа." +> "Чи підтримує спільнота цей простір знань?" + +## 7.2. Модель ритуалу + +`governance_rituals`: + +- id +- team_id +- title +- description +- options (наприклад: підтримую / не підтримую) +- created_by +- closes_at +- status + +## 7.3. Перебіг + +Governance Agent: + +1. Створює ритуал. +2. Повідомляє всіх учасників. +3. Збирає сигнали підтримки у чатах і через агентів. +4. Формує summary. +5. Оновлює правила/доступи або пропонує зміни. + +--- + +# 8. Символічні ключі (Soulbound Keys) + +Це: + +- особисті ключі для членів microDAO, +- ключі проєктів, +- ключі агентів, +- ключі доступу до конфіденційних просторів. + +Дані зберігаються в `governance_keys`: + +- id +- team_id +- owner_kind (`user` | `agent`) +- owner_id +- scope (`team`, `project`, `channel`) +- permissions (json array) +- created_at + +--- + +# 9. Інтеграція з агентами інших модулів + +### Messenger Agent + +- отримує сповіщення про зміни доступів, +- не допускає агентів у заборонені канали. + +### Projects Agent + +- отримує дозволи на створення/оновлення задач у контекстах. + +### Memory Agent + +- додає факти: "Правило X затверджено", "Ритуал Y завершено". + +### Agent Hub + +- показує короткі огляди активних ритуалів і важливих рішень. + +--- + +# 10. UI + +## 10.1. Sidebar → Правила + +- Кнопка "Правила спільноти" +- Кнопка "Символічні ключі" + +## 10.2. Сторінка правил + +- Список правил +- Фільтри: team / project / channel +- Кнопка "Запропонувати зміну" + +## 10.3. Сторінка символічних ключів + +- Список ключів: + + - належать користувачу, + - належать агентам користувача, + +- Контекст доступів. + +## 10.4. Ритуали узгодження + +- Список активних ритуалів. +- Оголошення: + + - "Потрібна увага спільноти." + +- Кнопка "Підтримати" чи "Не підтримую". + +--- + +# 11. Tools (сумісно з Runtime Core) + +### 11.1. create_policy + +Створює нове правило. + +### 11.2. update_policy + +Оновлює існуюче правило. + +### 11.3. create_key + +Створює символічний ключ доступу. + +### 11.4. revoke_key + +Анулює ключ. + +### 11.5. create_ritual + +Створює ритуал узгодження. + +### 11.6. collect_support + +Збирає сигнали підтримки. + +### 11.7. finalize_ritual + +Підсумок ритуалу: + +- оновити правила, +- або передати у Memory Agent для аналізу. + +--- + +# 12. Конфіг агента (Runtime Core) + +```ts +const governanceAgentConfig: AgentConfig = { + id: "ag_governance_core", + teamId: "...", + name: "Governance Agent", + role: "governance_core", + systemPrompt: systemGovernancePrompt, + memoryScope: "team", + tools: [ + "create_policy", + "update_policy", + "create_key", + "revoke_key", + "create_ritual", + "collect_support", + "finalize_ritual" + ] +}; +``` + +--- + +# 13. API + +### Policies + +`GET /governance/policies?team_id` +`POST /governance/policies` +`PATCH /governance/policies/:id` + +### Keys + +`GET /governance/keys?team_id` +`POST /governance/keys` +`DELETE /governance/keys/:id` + +### Rituals + +`GET /governance/rituals?team_id` +`POST /governance/rituals` +`PATCH /governance/rituals/:id` + +--- + +# 14. Інструкції для Cursor + +``` +Implement the Governance & Access Agent using: + +- 18_governance_access_agent.md +- microdao — RBAC and Entitlements (MVP) +- 12_agent_runtime_core.md +- 13_agent_memory_system.md +- 10_agent_ui_system.md +- 05_coding_standards.md + +Tasks: + +1) Create models for governance_policies, governance_keys, governance_rituals. + +2) Implement API for policies, keys, and rituals. + +3) Register Governance Agent with tools. + +4) Create UI: + + - Policies page + - Symbolic Keys page + - Rituals page + +5) Integrate with Agent Hub: show active rituals and key policy changes. + +6) Ensure no financial vocabulary is used anywhere. + +Output: + +- list of changed files +- diff +- summary +``` + +--- + +# 15. Результат + +Після впровадження цього модуля: + +* кожне microDAO отримує свою "конституцію", +* доступи стають функцією духу спільноти, а не технічних ролей, +* символічні ключі формують систему довіри, +* ритуали узгодження стають живою формою колективного рішення, +* Governance Agent забезпечує гармонію роботи людей і агентів. + + diff --git a/docs/cursor/19_notifications_attention_agent.md b/docs/cursor/19_notifications_attention_agent.md new file mode 100644 index 00000000..e5c8dfa8 --- /dev/null +++ b/docs/cursor/19_notifications_attention_agent.md @@ -0,0 +1,335 @@ +# 19 — Notifications & Attention Agent (MicroDAO) + +Агент уваги, тиші та інформаційного ритму + +Notifications & Attention Agent (далі — Attention Agent) відповідає за *ритм сповіщень* та *інформаційну гігієну* в microDAO. +Його мета — захистити учасників від шуму та втоми, залишивши лише важливе. + +Це не "push-нотифікації". +Це **агент управління увагою** — частина "нервової системи" microDAO. + +--- + +# 1. Призначення + +Attention Agent: + +- фільтрує події, +- визначає важливість, +- блокує шум, +- формує дайджести, +- підсилює справді важливе, +- узгоджує ритм взаємодії між людьми та агентами. + +Він — аналог "ретикулярної формації" спільноти. + +--- + +# 2. Проблеми, які він вирішує + +- надлишок сповіщень, +- інформаційне перевантаження, +- пропущені важливі оновлення, +- хаос у каналах, +- дублювання повідомлень, +- невчасні сигнали, +- втому від постійного ping. + +--- + +# 3. Види уваги + +Attention Agent працює з трьома видами уваги: + +1. **Миттєва увага** + Події, які вимагають негайної реакції. + (блокер задачі, критична дія в governance, тривожний сигнал у роботах) + +2. **Периферійна увага** + Події, важливі, але не термінові. + (новий документ, оновлення задачі, рішення ритуалу узгодження) + +3. **Глибинна увага** + Знання, що варто прочитати, але не зараз. + (аналітика, звіти, огляди, Co-Memory оновлення) + +--- + +# 4. Модель даних (log of events) + +Attention Agent працює поверх подій (`events`): + +``` +event: { +id, +team_id, +type, // message, task_update, followup, governance, knowledge_update... +source, // messenger, tasks, governance, agents... +payload, // JSON +ts +} +``` + +Він визначає важливість і формує *streams of attention*. + +--- + +# 5. Потоки уваги (Attention Streams) + +### 5.1. High-Attention Stream + +- критичні події, +- прямі звернення до користувача, +- блокери. + +### 5.2. Normal Stream + +- звичайні робочі оновлення. + +### 5.3. Low-Attention Stream + +- знання, аналітика, нові документи, +- загальні події. + +--- + +# 6. Attention Agent — спроможності + +## 6.1. Фільтрація шуму + +Він аналізує: + +- дублікати, +- непотрібні @mention, +- спам дій від агентів, +- повторювані нагадування. + +Шум приглушується або згруповується. + +## 6.2. Ранжування важливості + +Залежно від: + +- ролі користувача, +- поточного контексту, +- активного проєкту, +- ритуалів узгодження, +- стану задач. + +## 6.3. Дайджести + +Формує: + +- огляд дня, +- огляд тижня, +- огляд проєкту, +- огляд каналу. + +## 6.4. Інтелектуальні сигнали + +Наприклад: + +- "Схоже, це важливо саме для тебе". +- "Цей документ стосується твого проєкту." +- "Тут задача, яку ти раніше коментував." + +## 6.5. Таймінг + +Обирає правильний момент: + +- не вночі, +- не в момент великого потоку, +- між подіями. + +## 6.6. Підсилення важливого + +Якщо подія має високу важливість: + +- підсвічується, +- виноситься у top stream, +- дублюється одноразово. + +--- + +# 7. Інтеграція з агентами інших модулів + +### Messenger Agent + +- аналізує повідомлення, +- визначає важливі ключові слова. + +### Projects Agent + +- сигналить про дедлайни, блокери. + +### Followups Agent + +- генерує ритм. + +### Governance Agent + +- підсвічує ритуали узгодження. + +### Memory Agent + +- працює з подіями знань. + +--- + +# 8. Tools (для Runtime Core) + +### 8.1. classify_event + +Визначає важливість події. + +### 8.2. filter_noise + +Зменшує шум, об'єднує дублікати. + +### 8.3. build_digest + +Створює дайджест з групи подій. + +### 8.4. get_user_attention_stream + +Повертає важливі події для конкретної людини. + +### 8.5. suggest_timing + +Підбирає оптимальний час для сповіщення. + +### 8.6. highlight_critical + +Позначає критичні події. + +--- + +# 9. Інтеграція з Runtime Core (12) + +```ts +const attentionAgentConfig: AgentConfig = { + id: "ag_attention_core", + teamId: "...", + name: "Attention Agent", + role: "attention_core", + systemPrompt: systemAttentionPrompt, + memoryScope: "team", + tools: [ + "classify_event", + "filter_noise", + "build_digest", + "get_user_attention_stream", + "suggest_timing", + "highlight_critical" + ] +}; +``` + +--- + +# 10. UI — візуалізація уваги + +## 10.1. Панель уваги (Attention Panel) + +Правий сайдбар у будь-якому контексті: + +* топ важливих подій, +* пропущені сигнали, +* критичні оновлення. + +## 10.2. Центр уваги (Attention Hub) + +Окремий екран: + +* `/t/:teamId/attention` + +Тут користувач бачить: + +* "Важливе за сьогодні", +* "Критичне зараз", +* "Рекомендоване до перегляду". + +## 10.3. Дайджести + +* кнопка "Огляд дня", +* кнопка "Огляд тижня". + +## 10.4. Налаштування уваги + +Користувач може обрати: + +* рівень чутливості, +* типи подій, +* тихі години. + +--- + +# 11. API + +### Події + +`GET /events?team_id` +`POST /events` + +### Attention Streams + +`GET /attention/stream?user_id` +`POST /attention/digest_daily` +`POST /attention/digest_weekly` + +--- + +# 12. Інструкції для Cursor + +``` +Implement the Notifications & Attention Agent using: + +- 19_notifications_attention_agent.md +- 12_agent_runtime_core.md +- 13_agent_memory_system.md +- 14_messenger_agent_module.md +- 15_projects_agent_module.md +- 16_followups_reminders_agent.md +- 10_agent_ui_system.md +- 05_coding_standards.md + +Tasks: + +1) Create backend models for events and attention streams. + +2) Implement API for events (recording) and attention streams (filtering, ranking). + +3) Register Attention Agent and its tools. + +4) Create UI: + + - Right sidebar "Attention Panel" showing prioritized events. + + - `/t/:teamId/attention` page (Attention Hub). + + - Configuration modal for attention levels. + +5) Integrate with Messenger, Projects, Followups, and Governance Agents. + +6) Implement basic digest generation (daily/weekly). + +Output: + +- file list +- diff +- summary +``` + +--- + +# 13. Результат + +Після впровадження цього модуля: + +* спільнота перестає тонути в шумі, +* виникає природна структура уваги, +* критичні події не губляться, +* люди й агенти діють у правильному ритмі, +* інформаційне навантаження стає здоровим і екологічним. + + diff --git a/docs/cursor/20_integrations_bridges_agent.md b/docs/cursor/20_integrations_bridges_agent.md new file mode 100644 index 00000000..d8a1a653 --- /dev/null +++ b/docs/cursor/20_integrations_bridges_agent.md @@ -0,0 +1,346 @@ +# 20 — Integrations & Bridges Agent (MicroDAO) + +Агент мостів, міжпросторових зв'язків та зовнішньої взаємодії + +Integrations & Bridges Agent — це модуль, який забезпечує обмін інформацією між microDAO та зовнішнім світом: +іншими платформами, месенджерами, інструментами, сервісами, даними та іншими агентськими екосистемами. + +Це "протокольний шар" агентської ОС DAARION.city. + +--- + +# 1. Призначення + +Bridges Agent виконує функції: + +- інтеграції із зовнішніми платформами, +- маршрутизації даних, +- синхронізації контекстів, +- взаємодії між різними агентськими системами, +- побудови міжпросторових каналів (cross-microDAO), +- підключення до сторонніх інструментів (пошта, календар, API), +- реалізації безпечних каналів входу/виходу з екосистеми. + +Основна ідея — **microDAO не живе в ізоляції, а існує у зв'язку зі світом**. + +--- + +# 2. Види інтеграцій + +### 2.1. Месенджери та комунікаційні сервіси + +- Telegram (вхідні повідомлення, вихідні, канали, боти) +- WhatsApp / Signal (через API-адаптери) +- Email +- SMS (опційно) + +### 2.2. Робочі інструменти + +- Google Calendar / iCal +- Google Drive / Dropbox (для файлів) +- GitHub (issues, PRs, CI) +- Notion / Confluence (документи) + +### 2.3. API зовнішніх сервісів + +- Webhooks +- REST / GraphQL +- OAuth2 інтеграції + +### 2.4. Cross-microDAO зв'язки + +- "міст" між microDAO для: + + - спільних агентів, + - спільних проєктів, + - спільної пам'яті, + +- міжміські зв'язки DAARION.city. + +### 2.5. Web3-протоколи + +- підписані повідомлення, +- capability-токени доступу, +- безпечна автентифікація. + +--- + +# 3. Агенти інтеграцій + +Модуль складається із під-агентів: + +## 3.1. Bridges Agent (основний) + +Роль: `"bridges_core"` + +Він: + +- керує списком інтеграцій, +- маршрутизує дані між контекстами, +- керує підключенням зовнішніх API. + +## 3.2. Connector Agents (адаптери) + +Ролі: `"telegram_connector"`, `"email_connector"`, `"calendar_connector"`, `"github_connector"` тощо. + +Кожен Connector: + +- має свої ключі/аутентифікацію, +- вміє читати/писати події, +- перетворює зовнішній формат → внутрішній формат events у microDAO. + +## 3.3. CrossDAO Agent + +Роль: `"crossdao_bridge"` + +Відповідає за: + +- між-microDAO синхронізацію, +- передачу фактів/документів, +- спільних агентів, +- правила та ритуали між DAO. + +--- + +# 4. Модель інтеграції + +### 4.1. Таблиця інтеграцій + +`integrations`: + +- id +- team_id +- type (`telegram`, `email`, `calendar`, `github`, …) +- config_json +- status (`active`, `disabled`) +- created_at + +### 4.2. Модель подій + +Всі зовнішні події конвертуються у універсальний формат: + +``` +event: { +id, +team_id, +source, // telegram | email | github | ... +type, // message | file | issue | event | calendar_update ... +payload, // JSON +ts +} +``` + +Цей формат потім обробляється: + +- Messenger Agent, +- Projects Agent, +- Followups Agent, +- Attention Agent, +- Memory Agent. + +--- + +# 5. Основні сценарії + +### 5.1. Telegram → microDAO + +- повідомлення з каналу/групи → вхідний event, +- Bridges Agent передає їх Messenger Agent'у, +- агент може відповідати назад у Telegram (якщо дозволено). + +### 5.2. microDAO → Email + +- агент може відправити email через Email Connector: + + "Сформуй лист-запит у партнерську організацію." + +### 5.3. GitHub → Projects Agent + +- issue → створення задачі, +- PR → оновлення статусів, +- label changes → пріоритизація. + +### 5.4. Calendar → Followups Agent + +- події календаря → нагадування, +- синхронізація дедлайнів. + +### 5.5. Cross-microDAO + +- передача фактів між двома DAO: + + "Поділись цим визначенням з іншим microDAO". + +- спільна робота агента у двох DAO. + +--- + +# 6. Інтеграція з Runtime Core (12) + +Основний агент: + +```ts +const bridgesAgentConfig: AgentConfig = { + id: "ag_bridges_core", + teamId: "...", + name: "Bridges Agent", + role: "bridges_core", + systemPrompt: systemBridgesPrompt, + memoryScope: "team", + tools: [ + "sync_event", + "push_notification", + "pull_updates", + "register_integration", + "update_integration", + "disable_integration" + ] +}; +``` + +Адаптери — це окремі агенти з вузькими tools. + +--- + +# 7. Tools (для Runtime Core) + +### 7.1. register_integration + +Реєструє інтеграцію (тип, ключі доступу, конфіг). + +### 7.2. update_integration + +Оновлює конфіг інтеграції. + +### 7.3. disable_integration + +Вимикає інтеграцію. + +### 7.4. sync_event + +Приймає подію від зовнішнього джерела і конвертує у внутрішню подію. + +### 7.5. push_notification + +Відправляє повідомлення у зовнішній світ (Telegram, Email тощо). + +### 7.6. pull_updates + +Регулярно опитує зовнішній сервіс (GitHub, Calendar). + +--- + +# 8. UI + +## 8.1. Sidebar → Інтеграції + +* список інтеграцій, +* кнопка "Підключити інтеграцію". + +## 8.2. Модалка підключення інтеграції + +* вибір сервісу: Telegram / Email / Calendar / GitHub / Custom API, +* ввод даних підключення, +* тестування підключення, +* збереження. + +## 8.3. Профіль інтеграції + +* історія подій, +* статус, +* налаштування, +* кнопка "Вимкнути". + +## 8.4. Cross-microDAO панель + +* список підключених DAO, +* права та контексти, +* статуси синхронізації. + +--- + +# 9. API + +### Інтеграції + +`GET /integrations?team_id` +`POST /integrations` +`PATCH /integrations/:id` +`DELETE /integrations/:id` + +### Події + +`POST /integrations/events` +`GET /events?team_id&type=external` + +### Cross-DAO + +`POST /crossdao/share_fact` +`POST /crossdao/share_document` + +--- + +# 10. Інструкції для Cursor + +``` +Implement the Integrations & Bridges Agent using: + +- 20_integrations_bridges_agent.md +- 12_agent_runtime_core.md +- 13_agent_memory_system.md +- 14_messenger_agent_module.md +- 15_projects_agent_module.md +- 16_followups_reminders_agent.md +- 17_comemory_knowledge_space.md +- 18_governance_access_agent.md +- 10_agent_ui_system.md +- 05_coding_standards.md + +Tasks: + +1) Create backend models for integrations and external events. + +2) Implement API for listing, creating, updating, disabling integrations. + +3) Register Bridges Agent and connector agents. + +4) Implement adapters: + + - Telegram (stub) + + - Email (stub) + + - Calendar (stub) + + - GitHub (stub) + +5) Create UI: + + - Integrations list in sidebar + + - Integration setup modal + + - Integration profile page + +6) Implement event syncing logic (sync_event tool → Messenger/Projects/Followups/Attention Agents) + +Output: + +- list of modified files +- diff +- summary +``` + +--- + +# 11. Результат + +Після впровадження: + +* microDAO стає мережевим вузлом, +* агенти можуть діяти в кількох просторах, +* знання й події можуть перетікати між DAO, +* зовнішні інструменти інтегруються легко та безпечно, +* DAARION.city отримує основу для єдиного агентського всесвіту. + + diff --git a/docs/cursor/21_agent_only_interface.md b/docs/cursor/21_agent_only_interface.md new file mode 100644 index 00000000..d225f746 --- /dev/null +++ b/docs/cursor/21_agent_only_interface.md @@ -0,0 +1,654 @@ +# 21 — Agent-Only Interface (MicroDAO) + +Агентська операційна система замість класичного застосунку + +Цей документ описує цільовий інтерфейс MicroDAO, де: + +- немає класичного "меню функцій"; + +- все представлено як **учасники**: Люди, Агенти, Роботи; + +- чати, проєкти, бази знань і доступи — це **ресурси**, якими керують агенти; + +- інвайти, шеринги, права і токени виконуються через агентські дії (з web3-фіксацією, де потрібно). + +Це візійний, але достатньо конкретний документ для Cursor: + +- UX-специфікація; + +- структура layout; + +- сценарії; + +- задачі для реалізації перших версій. + +--- + +# 1. Мета + +Перетворити MicroDAO на **агентську ОС спільнот**, де: + +- користувач взаємодіє насамперед з агентами, а не з "екранами"; + +- кожен контекст (канал, проєкт, база даних, DAO-голосування) — це простір, де присутні: + + - Люди, + + - Агенти, + + - (у майбутньому) Роботи; + +- запрошення, шеринги, доступи — це: + + - діалог з агентом, + + - + технічні дії (RBAC, entitlements, web3-транзакції). + +--- + +# 2. Загальний layout агентської ОС + +## 2.1. Лівий сайдбар — Простори та Учасники + +Структура: + +1. **Мої простори (microDAO)** + + - `[DAARION Core]` + + - `[GreenFood DAO]` + + - `[Personal Lab]` + +2. **Учасники** + + - **Люди** + + - **Агенти** + + - **Роботи** (поки пусто, плейсхолдер) + +3. **Активний контекст** + + Підсвічений простір + "поточний стіл": + + - Канал: `#dev-mvp` + + - Проєкт: `MicroDAO MVP` + + - Простір знань: `Tokenomics` + +Сайдбар показує **структуру світу**, але основні дії йдуть через агентів. + +## 2.2. Центр — Діалоговий простір + +Центральна колонка завжди є **чатом**: + +- Це може бути: + + - канал (`#dev-mvp`), + + - група (мультичат), + + - DM з людиною, + + - або "Agent Hub" (чат з головним агентом). + +У заголовку: + +- Назва контексту (наприклад, `#dev-mvp`). + +- Список учасників (аватари): + + - Люди: 2–5 + + - Агенти: Team Assistant, Messenger Agent, Projects Agent, Governance Agent + + - (Роботи, якщо є) + +Звідси: + +- пишуть люди, + +- відповідають агенти, + +- запускаються операції над ресурсами (проєктами, БД, токенами). + +## 2.3. Правий сайдбар — Контекст і Ресурси + +Праворуч: + +1. **Контекст**: + + - Активний простір (microDAO) + + - Поточний канал/проєкт + + - Які агенти мають доступ + +2. **Ресурси**: + + - Проєкти + + - Бази даних / таблиці + + - Простори знань (Co-Memory) + + - Повʼязані гаманці / токени + +3. **Права та ключі**: + + - Список людей та агентів з доступами (read/write/admin/use-in-prompts) + + - Кнопка "Керувати доступами" + + - Інформація про web3-стан (якщо є on-chain записи) + +--- + +# 3. Панель "Люди / Агенти / Роботи" + +## 3.1. Люди + +Елементи списку: + +- Аватар + +- Імʼя + +- Статус (online/offline/busy) + +- Ролі в microDAO (Member, Guardian, Investor…) + +Клік по людині: + +- відкриває: + + - DM-чат з цією людиною, + + - або розширений профіль (у майбутньому): + + - в яких проєктах, + + - з якими агентами працює. + +## 3.2. Агенти + +Групи: + +- **Системні агенти**: + + - Team Assistant + + - Messenger Agent + + - Projects Agent + + - Memory/Knowledge Agent + + - Governance/Tokenomics Agent + + - Bridge/Integrations Agent + +- **Користувацькі агенти**: + + - спеціалізовані боти, створені командою. + +- **Зовнішні агенти (маркетплейс)**: + + - агенти з інших microDAO або від сторонніх розробників. + +Клік по агенту: + +- відкриває **сторінку агента**: + + - вкладка "Чат", + + - вкладка "Памʼять", + + - вкладка "Самонавчання/Еволюція", + + - вкладка "Доступи та ресурси" (які проєкти/БД він бачить). + +## 3.3. Роботи + +Поки може бути просто секція "Роботи (скоро)". + +Модель на майбутнє: + +- Привʼязані до фізичних пристроїв (робот, сенсор, енергоблок). + +- Участь у чатах як окремі "учасники". + +- Окремі права на дії у фізичному світі. + +--- + +# 4. Запрошення агентів до каналів/чатів + +## 4.1. UX-флоу + +У будь-якому чаті/каналі: + +- кнопка **"Додати учасника"**. + +При натисканні: + +1. Модалка: + + - таби: `Люди | Агенти | Роботи` + + - поле пошуку + +2. Вибір Агента: + + - список агентів, + + - короткий опис (роль, профіль, що вміє). + +3. Налаштування прав: + + - чекбокси / селект: + + - `Читати цей канал` + + - `Писати в цей канал` + + - `Створювати задачі / follow-ups` + + - `Доступ до проєктів цього контексту` + + - `Доступ до баз знань цього контексту` + +4. Підтвердження: + + - кнопка **"Запросити агента"** + +Після цього: + +- у header чату зʼявляється новий агент; + +- агент отримує повідомлення (system DM): + + > "Тебе додали до каналу #dev-mvp з правами: читати, писати, створювати задачі." + +## 4.2. Backend/протоколно + +Під капотом: + +- створюється entitlement для `agent_id` з: + + - `resource_kind`: `channel` / `project` / `knowledge_space`, + + - `resource_id`, + + - `scopes`: `[read, write, tasks, knowledge]`. + +- (optionally) запускається web3-транзакція: + + - видача capability-токена / NFT-доступу, + + - запис в on-chain реєстр (аудит, DAO-гарантія). + +--- + +# 5. Обмін проєктами / базами даних між людьми та агентами + +## 5.1. Поняття "Ресурсу" + +Ресурс — це будь-що, до чого можна дати/забрати доступ: + +- Проєкт (`project_id`) + +- Таблиця / БД (`dataset_id`, `table_id`) + +- Простір знань (`knowledge_space_id`) + +- Набір подій (`events_stream_id`) + +- Гаманець / смарт-контракт (`wallet_id`, `contract_id`) + +У правому сайдбарі поточного контексту: + +- "Ресурси цього контексту" + +- Кожен ресурс має меню: + + - "Поділитися…" + + - "Показати, хто має доступ" + +## 5.2. UX шерингу + +У правій панелі користувач: + +1. Обирає ресурс → "Поділитися". + +2. Відкривається модалка: + + - таби: `Люди | Агенти | MicroDAO` + +3. Вибирає: + + - одного або кількох адресатів. + +4. Вказує права: + + - `read` / `write` / `admin` / `use_in_prompts_only`. + +5. Підтверджує. + +Після цього: + +- Governance/Tokenomics Agent: + + - оформлює web3-операцію (за потреби), + + - оновлює entitlements, + + - лог у audit/journal. + +- Memory/Knowledge Agent: + + - оновлює карту знань (хто/що бачить), + + - може пропонувати нові рекомендації (наприклад, Projects Agent тепер бачить дані продажів). + +--- + +# 6. "Agent Hub" — стартовий екран без меню + +Замість класичного "Home": + +- при вході в MicroDAO користувач потрапляє в чат з головним агентом (**Team Assistant / OS Agent**). + +Верхня частина: + +- "Привіт, це твоя microDAO: [Назва]" + +- Короткі блоки: + + - "Учасники" (скільки людей, скільки агентів) + + - "Проєкти" (активні) + + - "Сигнали" (важливі нотифікації) + +Основний елемент — чат, де користувач може написати будь-що: + +Приклади: + +- "Покажи, хто зараз працює над MVP." + +- "Створи новий проєкт для інтеграції DAGI." + +- "Запроси Projects Agent і Governance Agent в цей проєкт." + +- "Поділись базою `sales_events` з Projects Agent тільки для читання." + +Агент: + +- ставить уточнюючі питання (якщо потрібно), + +- викликає внутрішні агенти: + + - Messenger Agent → створити/налаштувати канал + + - Projects Agent → створити проєкт/таски + + - Governance Agent → оформити доступи й web3-запис + + - Knowledge Agent → підключити Co-Memory + +Усе це відображається як: + +- ланцюжок дій у чаті, + +- результати в структурі UI (нові канали / проєкти / ресурси). + +--- + +# 7. Мінімальний MVP цієї парадигми + +Для першої реалізації (без надроздуття): + +1. **Лівий сайдбар:** + + - блок "Учасники": `Люди`, `Агенти` (Роботи — плейсхолдер). + + - кліки відкривають DM / сторінку агента. + +2. **Agent Hub як Home:** + + - `/t/:teamId/home` → чат з Team Assistant. + + - кнопка "Домашня" у сайдбарі → туди. + +3. **Модалка "Додати учасника" для каналів:** + + - можливість додати агента, + + - налаштувати права (на поки що хоча б `read/write`). + +4. **Модалка "Поділитися ресурсом":** + + - для проєктів (Projects Agent вже буде з 15-го документа), + + - базові права `read/write`. + +5. **Без web3 на першому етапі:** + + - тільки модель прав у БД (RBAC + entitlements), + + - web3-интеграція — stub/плейсхолдер (логіка в Governance Agent). + +--- + +# 8. Компоненти та структура + +## 8.1. Layout Components + +``` +src/layouts/ + AgentOSLayout.tsx # Головний layout з 3 колонками + LeftSidebar.tsx # Простори + Учасники + ParticipantsPanel.tsx # Панель Люди/Агенти/Роботи + RightSidebar.tsx # Контекст + Ресурси + ContextPanel.tsx # Панель контексту + ResourcesPanel.tsx # Панель ресурсів +``` + +## 8.2. Pages + +``` +src/pages/ + AgentHubPage.tsx # /t/:teamId/home - стартовий екран + ParticipantPage.tsx # Сторінка учасника (людина/агент) +``` + +## 8.3. Modals + +``` +src/components/modals/ + AddParticipantModal.tsx # Додати учасника до каналу/чату + ShareResourceModal.tsx # Поділитися ресурсом + ManageAccessModal.tsx # Керування доступами +``` + +## 8.4. Types + +```ts +interface Participant { + id: string; + type: "human" | "agent" | "robot"; + name: string; + avatar?: string; + status?: "online" | "offline" | "busy"; + roles?: string[]; +} + +interface Resource { + id: string; + type: "project" | "dataset" | "knowledge_space" | "wallet" | "contract"; + name: string; + description?: string; + accessLevel?: "read" | "write" | "admin" | "use_in_prompts_only"; +} + +interface Entitlement { + participantId: string; + resourceKind: string; + resourceId: string; + scopes: string[]; +} +``` + +--- + +# 9. API Endpoints + +## 9.1. Participants + +```ts +GET /teams/{teamId}/participants +// Повертає список учасників (люди + агенти) + +GET /teams/{teamId}/participants/{id} +// Деталі учасника + +POST /channels/{channelId}/participants +// Додати учасника до каналу +{ + participantId: string; + participantType: "human" | "agent"; + scopes: string[]; +} +``` + +## 9.2. Resources + +```ts +GET /teams/{teamId}/resources +// Список ресурсів у контексті + +POST /resources/{resourceId}/share +// Поділитися ресурсом +{ + participantIds: string[]; + scopes: string[]; +} +``` + +## 9.3. Entitlements + +```ts +GET /entitlements +// Список прав поточного користувача/агента + +POST /entitlements +// Створити entitlement +{ + participantId: string; + resourceKind: string; + resourceId: string; + scopes: string[]; +} +``` + +--- + +# 10. Інтеграція з існуючими модулями + +## 10.1. Messenger Agent (14) + +Messenger Agent може: + +- показувати список каналів з учасниками +- фільтрувати канали за наявністю агентів +- пропонувати додати агента до каналу + +## 10.2. Projects Agent (15) + +Projects Agent може: + +- показувати проєкти як ресурси +- керувати доступами до проєктів +- пропонувати поділитися проєктом з іншими агентами + +## 10.3. Governance Agent (18) + +Governance Agent: + +- оформлює web3-транзакції для доступу +- веде audit log всіх змін прав +- керує токеномікою доступів + +--- + +# 11. Завдання для Cursor + +Приклад промта: + +``` +You are a senior React/TS engineer. + +Implement the Agent-Only Interface shell using: + +- 21_agent_only_interface.md +- 10_agent_ui_system.md +- 14_messenger_agent_module.md +- 03_api_core_snapshot.md +- 05_coding_standards.md + +Tasks: + +1) Update the main layout: + - Left sidebar: Spaces + Participants (People, Agents, Robots placeholder). + - Center: Dialog area (chat for current context). + - Right sidebar: Context & Resources panel (stub data). + +2) Create "Agent Hub" route `/t/:teamId/home`: + - Chat with Team Assistant as the main entry point. + +3) Add "Add participant" flow for channels: + - Modal with tabs: People / Agents. + - For Agents: basic permissions (read / write) stored in entitlements (stub). + +4) Add "Share resource" flow in the right sidebar: + - For now: projects only (resource type stub). + - Modal to grant read/write access to People or Agents (no web3 yet). + +5) Ensure navigation: + - Clicking on a Person/Agent in the sidebar opens the appropriate chat/page. + +Output: + +- list of modified files +- diff +- summary +``` + +--- + +# 12. Результат + +Після впровадження цього модуля: + +* MicroDAO отримує "агентський" каркас інтерфейсу: + + * вхід через Agent Hub, + + * центральна роль агентів, + + * простий механізм запрошення агентів, + + * базові flows шерингу ресурсів; + +* класичний месенджер (документ 14) стає лише однією з "здібностей" всередині агентської ОС, а не центром продукту. + +--- + +**Готово.** +Це **повна специфікація Agent-Only Interface**, готова до використання в Cursor. + + diff --git a/docs/cursor/22_agent_only_interface_tasks.md b/docs/cursor/22_agent_only_interface_tasks.md new file mode 100644 index 00000000..cd349ff9 --- /dev/null +++ b/docs/cursor/22_agent_only_interface_tasks.md @@ -0,0 +1,412 @@ +# 22 — Agent-Only Interface Tasks (MicroDAO) + +Структурований список задач для реалізації Agent-Only Interface + +Цей документ містить детальні технічні задачі для поетапної реалізації агентського інтерфейсу MicroDAO. Кожну задачу можна давати Cursor окремо для поступової розробки. + +**Базовий документ:** `21_agent_only_interface.md` + +--- + +# Task 1 — UI-Agents-List (People / Agents / Robots панель) + +## Мета + +Зробити лівий блок "Учасники", де видно Людей, Агентів і (поки що) плейсхолдер Роботів. Клік по елементу відкриває відповідний чат/сторінку. + +## Специфікація + +### 1. Розташування + +* Лівий сайдбар, нижче/поруч з блоком "Простори (microDAO)". +* Заголовок: `Учасники`. +* Вкладки або груповані секції: + + * `Люди` + * `Агенти` + * `Роботи` (поки список порожній, з текстом "Скоро"). + +### 2. Дані + +* People: + + * `id`, `display_name`, `avatar_url`, `online_status`. + +* Agents: + + * `id`, `name`, `role`, `avatar`, maybe `type` (system/custom). + +* Robots: + + * поки просто статичний текст: "Роботи поки не під'єднані". + +На бекенді: можна зробити: + +* `GET /participants?team_id=...` → `{ people: [...], agents: [...] }` + або окремі запити `GET /members`, `GET /agents`. + +### 3. UI-поведінка + +* Клік по Людині: + + * відкриває DM-чат `/t/:teamId/dm/:userId`. + +* Клік по Агенту: + + * відкриває сторінку агента `/t/:teamId/agent/:agentId` + або агент-чат. + +* Список скролиться, якщо елементів багато. + +### 4. Інтеграція з існуючим кодом + +* Використати загальні компоненти `Sidebar`, `Avatar`, `ListItem`. +* Типи/інтерфейси привести до стандартів з `05_coding_standards.md`. + +## Acceptance Criteria + +* У лівому сайдбарі є блок "Учасники" з секціями `Люди`, `Агенти`, `Роботи`. +* Для `Людей` і `Агентів` рендеряться реальні дані з API (або mock, якщо API ще нема). +* Клік по Людині відкриває приватний чат (навіть якщо поки stub). +* Клік по Агенту відкриває сторінку/чат агента. +* "Роботи" відображаються як порожній список з плейсхолдером. + +## Приклад промта для Cursor + +``` +Implement the Participants panel (People / Agents / Robots) in the left sidebar using: + +- 21_agent_only_interface.md +- 10_agent_ui_system.md +- 03_api_core_snapshot.md +- 05_coding_standards.md + +Deliverables: + +- Sidebar section "Учасники" with groups: Люди, Агенти, Роботи. +- Click on a Person opens DM route `/t/:teamId/dm/:userId` (stub if needed). +- Click on an Agent opens `/t/:teamId/agent/:agentId`. + +Output: list of files + diff + summary. +``` + +--- + +# Task 2 — Invite-Agent-Flow (модалка прав + web3-тригери) + +## Мета + +Дати можливість додавати агентів до каналів/чатів з налаштуванням прав. Web3 — на першому етапі Stub (просто підготувати місце для виклику Governance/Web3-агента). + +## Специфікація + +### 1. Де викликається + +* У header каналу/чату — кнопка `+ Додати учасника`. +* Доступна тільки для користувача з правами `admin`/`owner` (поки можна не перевіряти, просто буде кнопка). + +### 2. Модалка + +* Заголовок: "Додати учасника". +* Tabs: + + * `Люди` + * `Агенти` +* Із них нас цікавить вкладка `Агенти`. + +### 3. Вкладка "Агенти" + +* Список доступних агентів з пошуком. +* По кліку на агента або чекбоксом обираємо 1–N агентів. + +### 4. Налаштування прав + +* Секція "Права в цьому каналі": + + * `[ ] Читати` + * `[ ] Писати` + * `[ ] Створювати задачі / follow-ups` +* За замовчуванням: `Читати` увімкнено, інші вимкнено. + +### 5. API / Entitlements + +* On Submit: + + * `POST /entitlements` (або аналог) із даними: + + * `agent_id` + * `resource_kind: "channel"` + * `resource_id: channelId` + * `scopes: ["read", "write", "tasks"]` (залежить від чекбоксів) + +* Web3 Stub: + + * В коді робимо виклик функції `governance.issueAccessToken(...)` або логування TODO; + * Реальної транзакції поки не робимо. + +### 6. UX + +* Після успіху модалка закривається. +* У хедері каналу в списку учасників зʼявляється новий агент. + +## Acceptance Criteria + +* У кожному каналі/чаті є кнопка "Додати учасника". +* В модалці є вкладка "Агенти" зі списком наявних агентів. +* Можна обрати агента, налаштувати права, натиснути "Запросити". +* На бекенді зберігаються entitlements (навіть якщо прості JSON у БД). +* Після додавання агент показується як учасник каналу. +* В коді є очевидний Stub для майбутньої web3 інтеграції. + +## Приклад промта для Cursor + +``` +Implement the "Invite Agent" flow for channels using: + +- 21_agent_only_interface.md +- microdao — RBAC and Entitlements (MVP) +- 10_agent_ui_system.md +- 05_coding_standards.md + +Deliverables: + +1) "Add participant" button in channel header. +2) Modal with tabs People / Agents, focusing on Agents tab. +3) Permissions UI for agent (read / write / tasks). +4) POST entitlements call to store agent-channel permissions (web3 as stub hook). + +Output: list of files + diff + summary. +``` + +--- + +# Task 3 — Share-Resource-Flow (проєкт / БД / knowledge space) + +## Мета + +Реалізувати базову можливість "поділитися ресурсом" (спочатку — Проєктом), з видачею прав людям/агентам. БД / knowledge space можна підключати далі за тим самим патерном. + +## Специфікація + +### 1. Ресурси для MVP + +* Почати з `Проєктів` (Projects Agent з документу 15). +* Інтерфейс у правому сайдбарі для активного контексту: + + * розділ "Проєкти цього контексту", + * кожен проєкт має кнопку `⋯` → `Поділитися`. + +### 2. Модалка "Поділитися проєктом" + +* Заголовок: "Поділитися проєктом". +* Tabs: + + * `Люди` + * `Агенти` +* Список одержувачів з пошуком. + +### 3. Права доступу + +* Радіо-кнопки або чекбокси: + + * `Тільки читати` + * `Читати і оновлювати задачі` + * `Адмініструвати проєкт` +* Для MVP: + + * мапимо на `["read"]`, `["read","write"]`, `["admin"]`. + +### 4. API / Entitlements + +* `POST /entitlements`: + + * `resource_kind: "project"` + * `resource_id: projectId` + * `subject_kind: "user" | "agent"` + * `subject_id: ...` + * `scopes: [...]` + +* Web3 Stub: + + * так само, як у Task 2 — залишити хук/функцію для майбутньої транзакції. + +### 5. Відображення + +* У правому сайдбарі для вибраного проєкту: + + * короткий список: хто має доступ (іконки + тип: людина/агент). + * посилання "Керувати доступами" (можна виводити ту ж саму модалку). + +## Acceptance Criteria + +* У правому сайдбарі є список проєктів для контексту (навіть якщо один). +* Для кожного проєкту доступна дія "Поділитися". +* Модалка дозволяє вибрати людей/агентів і рівень доступу. +* Після підтвердження зʼявляються записи entitlements. +* У правій панелі видно, що проєкт поділено з конкретними субʼєктами. + +## Приклад промта для Cursor + +``` +Implement the "Share Project" flow as the first Resource Sharing feature using: + +- 21_agent_only_interface.md +- 15_projects_agent_module.md (if present) +- microdao — RBAC and Entitlements (MVP) +- 05_coding_standards.md + +Deliverables: + +1) In the right sidebar, show list of projects for the current context. +2) Add "Share" action for a project → opens modal. +3) Modal lets the user pick People or Agents and assign access level (read / read+write / admin). +4) POST entitlements to persist access. +5) Show who has access in the sidebar (avatars + type). + +Output: list of files + diff + summary. +``` + +--- + +# Task 4 — Agent-Hub-Home (стартовий екран "все через агента") + +## Мета + +Зробити "Agent Hub" як домашню точку входу в microDAO: користувач відкриває `/t/:teamId/home` і бачить чат з головним агентом + базові віджети стану. + +## Специфікація + +### 1. Новий маршрут + +* `GET /t/:teamId/home` (frontend route). +* Відображає `AgentHubPage`. + +### 2. AgentHubPage структура + +* Верх: + + * заголовок: `microDAO: {team.name}` + * короткі віджети (можуть бути stub): + + * "Учасники: X людей, Y агентів" + * "Активні проєкти: N" + +* Центр: + + * чат з головним агентом (Team Assistant або спеціальний OS Agent): + + * використовує вже існуючий `AgentChatWindow`. + * агент_id береться з конфіг (наприклад, "team_assistant" для цієї команди). + +* Праворуч: + + * контекст (список проєктів / каналів / ресурсів — поки можна stub). + +### 3. Поведінка чату + +* Перший запуск: + + * агент вітається, якщо немає історії: + + > "Привіт, це твій Agent Hub. Я допоможу керувати твоєю microDAO." + +* Далі: + + * користувач може написати запит, наприклад: + + * "Покажи активні проєкти" + * "Відкрий канал #dev-mvp" + * "Хочу створити новий проєкт" + * Поки що можна зробити stub-відповіді, якщо Projects/Messenger Agents ще не реалізовані. + +### 4. Навігація + +* Кнопка/посилання "Головна" у лівому сайдбарі веде на `/t/:teamId/home`. +* Після успішного онбордингу (з `08_agent_first_onboarding.md`) редірект також може йти на Agent Hub. + +## Acceptance Criteria + +* Існує маршрут `/t/:teamId/home`, який рендерить Agent Hub. +* У центрі — робочий чат з Team Assistant (через `/agents/{id}/chat` endpoint). +* У сайдбарі є посилання "Головна" / "Agent Hub", що веде на цей екран. +* Якщо історії немає — агент показує вітальний меседж. +* Екран виглядає як "головна консоль" microDAO, а не просто черговий канал. + +## Приклад промта для Cursor + +``` +Implement the Agent Hub Home screen using: + +- 21_agent_only_interface.md +- 10_agent_ui_system.md +- 11_llm_integration.md +- 12_agent_runtime_core.md +- 05_coding_standards.md + +Deliverables: + +1) New route `/t/:teamId/home` rendering AgentHubPage. +2) AgentHubPage: + - header with team name and basic stats (stub). + - central chat with Team Assistant agent (AgentChatWindow). + - optional right sidebar context (stub). +3) "Home / Agent Hub" entry in left sidebar that routes to `/t/:teamId/home`. + +Output: list of files + diff + summary. +``` + +--- + +# Порядок виконання задач + +Рекомендований порядок реалізації: + +1. **Task 1** — UI-Agents-List (базова структура учасників) +2. **Task 4** — Agent-Hub-Home (стартовий екран) +3. **Task 2** — Invite-Agent-Flow (додавання агентів до каналів) +4. **Task 3** — Share-Resource-Flow (поділ ресурсів) + +Альтернативний порядок (якщо потрібно спочатку базовий функціонал): + +1. **Task 4** — Agent-Hub-Home +2. **Task 1** — UI-Agents-List +3. **Task 2** — Invite-Agent-Flow +4. **Task 3** — Share-Resource-Flow + +--- + +# Залежності між задачами + +- **Task 1** не залежить від інших +- **Task 4** може використовувати компоненти з Task 1 +- **Task 2** потребує Task 1 (список агентів) +- **Task 3** потребує Task 2 (механізм entitlements) + +--- + +# Загальні вимоги для всіх задач + +## Технічні вимоги + +- Дотримуватися `05_coding_standards.md` +- Використовувати типи з `03_api_core_snapshot.md` +- Інтегрувати з існуючими компонентами з `10_agent_ui_system.md` +- Дотримуватися UI/UX з `04_ui_ux_onboarding_chat.md` + +## Тестування + +- Кожна задача має мінімальні unit tests +- Перевірити наявність помилок TypeScript +- Перевірити відповідність acceptance criteria + +## Документація + +- Оновити `src/README.md` з описом нових компонентів +- Додати коментарі до складних частин коду + +--- + +**Готово.** +Це **структурований список задач для Agent-Only Interface**, готовий до використання в Cursor. + + diff --git a/docs/cursor/22_operator_modes_and_system_agents.md b/docs/cursor/22_operator_modes_and_system_agents.md new file mode 100644 index 00000000..9242e29e --- /dev/null +++ b/docs/cursor/22_operator_modes_and_system_agents.md @@ -0,0 +1,384 @@ +# 22 — Operator Modes & System Agents (MicroDAO) + +Приватні агенти, агент-спільноти, операторські режими, агент DAO і агент-гаманець + +Цей документ визначає системну архітектуру внутрішніх агентів MicroDAO, їхні операторські режими, взаємодію з доступами, правилами, ключами та внутрішньою криптографією спільноти. + +Документ узгоджений із попередніми специфікаціями (12–20). + +--- + +# 1. Основні типи системних агентів + +MicroDAO має три фундаментальні типи агентів: + +- **особисті агенти** (Personal Agents), +- **агенти спільноти** (Team Agents / Shared Agents), +- **агенти-протоколісти** (System Protocol Agents): + DAO Agent, Wallet Agent, Bridges Agent, Governance Agent тощо. + +Кожен тип має свою власну памʼять, права доступу та операторські можливості. + +--- + +# 2. Особистий агент (Personal Agent) + +### 2.1. Призначення +Особистий агент — це "внутрішній супутник" людини в екосистемі microDAO: + +- знає особистий контекст, +- веде особистий Co-Memory простір, +- допомагає у приватних нотатках, документах, нагадуваннях, +- працює як приватний інтерфейс до DAGI, +- не має доступу до командних просторів, якщо не надано спеціальний дозвіл. + +### 2.2. Права +Особистий агент оперує винятково у: + +- `personal_space`, +- особистих документах, +- особистих навчальних даних, +- особистих локальних задачах. + +Доступи до спільних проектів даються явно через Governance/Access Agent у вигляді entitlements. + +### 2.3. Операторський режим +Особистий агент може бути оператором **лише в особистому просторі**: + +```ts +operatorMode: { + enabled: true, + scopes: ["personal"], + allowedTools: [ + "create_personal_note", + "create_personal_task", + "personal_digest", + "organize_notes" + ], + schedule: "*/20 * * * *", // кожні 20 хвилин (приклад) + maxActionsPerHour: 10 +} +``` + +--- + +# 3. Спільний агент (Team/Shared Agent) + +### 3.1. Призначення + +Це агенти: + +* Team Assistant, +* Messenger Agent, +* Projects Agent, +* Followups Agent, +* Memory Agent, +* Attention Agent, +* Knowledge Guide, +* Bridges Agent, +* Governance Agent. + +Вони працюють на рівні microDAO (колективний простір). + +### 3.2. Права + +Спільні агенти можуть отримувати доступ до: + +* каналів, +* проектів, +* документів Knowledge Space, +* ритуалів узгодження, +* Co-Memory microDAO. + +Доступи обмежуються entitlements — кожен агент бачить лише те, що дозволено. + +### 3.3. Операторські повноваження + +Командні агенти можуть працювати як "оператори" на рівні спільноти: + +```ts +operatorMode: { + enabled: true, + scopes: ["team","project","channel"], + allowedTools: [ + "summarize_project", + "daily_digest", + "check_task_status", + "highlight_critical", + "sync_event" + ], + schedule: "0 * * * *", // щогодини + maxActionsPerHour: 30 +} +``` + +Операторські дії **завжди логуються** в Co-Memory. + +--- + +# 4. Protocol Agents: DAO Agent і Wallet Agent + +Ці агенти не є "учасниками" в комунікації, а швидше **протокольними модулями**. + +--- + +# 4.1. DAO Agent + +Роль: `"dao_protocol_agent"` + +### Призначення + +DAO Agent відповідає за: + +* зв'язок із зовнішнім DAO-протоколом (якщо microDAO його має), +* синхронізацію правил із контрактами, +* оновлення локальних правил на основі зовнішніх церемоній, +* відправку ритуалів узгодження в DAO-контракт (якщо дозволено). + +### Інтерфейс (tools) + +```ts +tools: [ + "sync_policies_onchain", + "fetch_dao_proposals", + "submit_ritual_to_dao", + "resolve_dao_result" +] +``` + +### Оператор-режим + +DAO Agent завжди працює **строго у командному масштабі** і лише за дозволами Governance Agent. + +--- + +# 4.2. Wallet Agent + +Роль: `"wallet_interface_agent"` + +### Призначення + +Wallet Agent — це **інтерфейс** між microDAO/агентами та: + +* криптографічним підписом, +* зовнішніми гаманцями користувачів, +* фізичними ключами (Tangem-подібні), +* системою capability-доступів. + +Wallet Agent **не зберігає приватні ключі**. + +Він: + +* формує пояснення: + + * "що саме підписується", + * "чому це потрібно", + * "які наслідки"; + +* відправляє payload на зовнішній Signer; +* отримує підписаний результат і повертає агенту, що ініціював дію. + +### Tools + +```ts +tools: [ + "prepare_signature_payload", + "request_signature", + "verify_signature", + "get_wallet_state" +] +``` + +--- + +# 5. Модель operatorMode + +Операторський режим є **частиною конфігурації кожного агента**. + +```ts +interface OperatorModeConfig { + enabled: boolean; + scopes: ("personal" | "team" | "project" | "channel")[]; + allowedTools: string[]; + schedule?: string; // CRON або natural language + maxActionsPerHour?: number; +} +``` + +У `AgentConfig`: + +```ts +interface AgentConfig { + ... + operatorMode?: OperatorModeConfig; +} +``` + +### 5.1. Scopes + +* `"personal"` — особистий простір користувача; +* `"team"` — командний рівень microDAO; +* `"project"` — окремий проєкт; +* `"channel"` — конкретний канал/чат. + +### 5.2. Режими + +Типовий розподіл: + +| Тип агента | operatorMode | +| ---------------- | ------------------------ | +| Personal Agent | personal | +| Team Assistant | team | +| Projects Agent | team,project | +| Followups Agent | team,project | +| Memory Agent | team | +| Attention Agent | team | +| Governance Agent | team | +| Wallet Agent | team (тільки з дозволом) | +| DAO Agent | team (тільки з дозволом) | + +### 5.3. Принципи безпеки operatorMode + +1. **Усі операторські дії логуються**. +2. **Жоден агент не може діяти поза своїми scopes**. +3. **Усі небезпечні дії потребують підтвердження Governance Agent**. +4. **Wallet Agent не може діяти без підтвердження людини**. +5. **OperatorMode можна вимкнути** для будь-якого агента в налаштуваннях microDAO. + +--- + +# 6. Модель системних агентів у БД + +### Таблиця `system_agents` + +* id +* team_id +* type (`personal`, `team`, `protocol`) +* role +* operator_enabled +* config_json (включає operatorMode) +* created_at + +### Таблиця `agent_permissions` + +* id +* agent_id +* resource_kind +* resource_id +* scopes (json array) +* created_at + +### Таблиця `operator_logs` + +* id +* agent_id +* action +* payload_json +* context +* created_at + +--- + +# 7. Інтеграція з доступами та ключами (Governance Agent) + +OperatorMode завжди працює у звʼязці з: + +* entitlements, +* symbolic keys, +* governance_policies. + +Наприклад: + +* Personal Agent має ключ рівня `personal-scope`. +* Projects Agent має ключ `project-operator`. +* DAO Agent має ключ `protocol-access`, який Governance Agent може видати або анулювати. + +--- + +# 8. UI-інтеграція + +### 8.1. Сторінка Агентів + +У профілі агента: + +* показати блок **"Режим оператора"**: + + * увімкнено/вимкнено, + * дозволені дії, + * сфери дії, + * розклад. + +### 8.2. Налаштування microDAO + +Окремий розділ: + +* "Системні агенти" + + * Personal Agent (індивідуальний) + * Team Agents (список) + * Protocol Agents + +### 8.3. Журнал операторських дій + +* список автоматичних дій агентів, +* фільтри: агент → проєкт → тип дії. + +--- + +# 9. Інструкції для Cursor + +Приклад: + +``` +Implement Operator Modes & System Agents using: + +- 22_operator_modes_and_system_agents.md +- 12_agent_runtime_core.md +- 18_governance_access_agent.md +- microdao — RBAC and Entitlements (MVP) +- 10_agent_ui_system.md +- 05_coding_standards.md + +Tasks: + +1) Extend AgentConfig with operatorMode field. + +2) Add operatorMode guards to runAgentTurn(). + +3) Create database tables: + + - system_agents + - agent_permissions + - operator_logs + +4) Implement API: + + - GET/POST/PATCH /agents/:id/operator_mode + - GET /agents/:id/operator_logs + +5) Create UI: + + - Agent profile: Operator Mode section. + - System Agents page. + - Operator Logs page. + +Output: + +- list of files +- diff +- summary +``` + +--- + +# 10. Результат + +Після впровадження цього модуля: + +* приватні агенти можуть працювати як персональні оператори; +* командні агенти можуть працювати як "ритуальні організатори" microDAO; +* DAO Agent та Wallet Agent стають безпечними протокольними модулями; +* усі дії мають чіткі межі, правила і логування; +* система стає самокерованою, але контрольованою через дух спільноти. + + diff --git a/docs/cursor/23_agent_cards_and_console.md b/docs/cursor/23_agent_cards_and_console.md new file mode 100644 index 00000000..c4093085 --- /dev/null +++ b/docs/cursor/23_agent_cards_and_console.md @@ -0,0 +1,556 @@ +# 23 — Agent Cards and Console (MicroDAO) + +Живі картки агентів та повний інтерфейс Agent Console + +Цей документ описує UI/UX для агентів у форматі "живих карток" та повний інтерфейс Agent Console, де кожен агент представлений як учасник спільноти з власною історією, досвідом та репутацією. + +--- + +# 1. Концепція: "Живі картки агентів" + +Кожен агент у MicroDAO — це не просто бот, а: + +* учасник спільноти з власною історією, +* живий модуль розуму, підключений до DAGI, +* носій досвіду (1T як міра обчислень та "шляху агента"), +* носій репутації в межах спільноти. + +Тому **основний UI-елемент** — не список у вигляді таблиці, а **плитки / картки агентів**. + +--- + +# 2. Плитка агента (карточка в гріді) + +## 2.1. Розташування + +* В розділі "Агенти" (ліва панель → клік → відкривається основний грід). +* Також може використовуватись у: + + * модалці "Додати агента до каналу", + * маркетплейсі агентів DAARION.city, + * списку підключених агентів до microDAO. + +## 2.2. Структура картки + +Рекомендований layout: + +### 1. Верхній блок: Аватар + Відео-аватар + +* Статичний аватар (іконка/символ). +* Мала відео-плашка / анімований аватар (loop, без звуку). +* Індикатор "онлайн/активний" (маленький маркер). + +### 2. Імʼя та роль + +* `Імʼя агента` (наприклад, "DAGI Guide", "Tokenomics Keeper"). +* Короткий опис призначення у один рядок: + + * "Провідник microDAO" + * "Куратор знань" + * "Месенджер-організатор" + + Без жодних фінансових ролей. + +### 3. Метрики досвіду (без фінансової асоціації) + +* **Вік агента**: + + * "У спільноті: 3 тижні" / "6 місяців" / "1 рік 2 місяці". + +* **Досвід 1T**: + + * Лічильник: `Досвід: 12 340 1T` + * В UI пояснення через tooltip: + + > "1T — це внутрішня одиниця обчислень і досвіду агента в екосистемі DAARION.city." + + * Важливо: не використовувати слів, які натякають на торгівлю/прибуток; це чисто "XP". + +* **Репутація спільноти**: + + * Наприклад, шкала 0–100 або 0–5 "зірочок". + * Підпис: `Репутація в спільноті` / `Довіра спільноти`. + +### 4. Присутність у просторах + +* Маленькі бейджі: + + * `Учасник: 3 канали` + * `Працює в: 2 microDAO` + +* Позначки "публічний / конфіденційний": + + * іконка замка для конфіденційних контекстів. + +### 5. Статус підключення + +* Текст/бейдж: + + * `Підключено до цього простору` + * або `Доступний для підключення` + +* Кнопка: + + * `Підключити до контексту` (якщо ще не підʼєднаний). + +--- + +# 3. Ховер та клік по картці + +## 3.1. При наведенні курсору (hover) + +Показати поверх картки напівпрозорий оверлей з опціями: + +* Основна кнопка: + **"Почати взаємодію"** + +* Додаткові: + + * `Підключити до цього каналу` (якщо стіна контексту вже вибрана) + * `Деталі агента` (відкрити повний профіль) + +Можна додати коротку анімацію відео-аватара (легке пожвавлення). + +## 3.2. При натисканні + +Якщо клікаємо по основній площі картки: + +* Відкривається **нове вікно/панель агента** (Agent Console), де: + + * є текстовий чат, + * є керування голосовим режимом, + * є вкладка для обміну файлами/документами, + * є вкладка памʼяті/прав доступу. + +--- + +# 4. Agent Console: повний інтерфейс агента + +Приклад структури: + +## 4.1. Верхня панель + +* Аватар + відео-аватар (більший). +* Імʼя, роль, короткий опис. +* Показники: + + * Вік, + * Досвід 1T, + * Репутація спільноти. + +* Значок підключеності до поточного microDAO / каналу. + +## 4.2. Вкладки + +### Вкладка 1: Чат + +* Текстовий чат (як звичайний agent chat). +* Голосовий режим: кнопка "Голосовий діалог" (start/stop). +* Привʼязка до поточного контексту: + + * показати, в якому просторі ти з ним розмовляєш. + +### Вкладка 2: Файли та Документи + +* Список файлів, якими обмінювались з цим агентом в межах даного microDAO. +* Кнопка `Завантажити файл` → агент через DAGI може: + + * проаналізувати документ, + * створити новий документ (збереження в microDAO file store). + +* Обовʼязково: + + * **збереження у власних сховищах microDAO**, не у зовнішньому середовищі по замовчуванню. + +### Вкладка 3: Памʼять і Знання + +* Блоки з: + + * короткостроковою памʼяттю (останні теми), + * довгостроковими фактами про цю спільноту (як у 13_agent_memory_system). + +* Кнопки: + + * `Показати, що ти памʼятаєш про цей проєкт` + * `Очистити частину памʼяті` + +### Вкладка 4: Присутність / Права доступу + +* Список: + + * В яких каналах цей агент присутній (публічні/конфіденційні). + * В яких проєктах бере участь. + +* Для кожного: + + * перемикач `Підключити/Відключити`. + * Позначка рівня доступу (read/write/tasks/knowledge). + +* Кнопка: + + * `Додати до нового каналу/проєкту` → відкриває спрощений Invite-Agent-Flow, але вже з попередньо вибраним агентом. + +### Вкладка 5: Еволюція та дух спільноти + +* Замінює будь-який фінансовий наратив: + + * `Шлях агента в цій спільноті` + * Лог: + + * скільки разів агент допомагав у задачах, + * які типи запитів обробляє найчастіше, + * "внесок у колективний розум" (наприклад, скільки фактів/правил додано). + +* Репутація: + + * відгуки/оцінки від учасників (без мови торгівлі). + +--- + +# 5. DAGI, багатомодальність і сховища + +## 5.1. DAGI як бекенд агентських здібностей + +Кожен агент отримує від DAGI: + +* текстове мислення, +* мульти-модальні можливості: + + * розуміння зображень/файлів, + * створення текстів, планів, специфікацій, + * потенційно роботу з відео. + +Інтерфейс агента дає доступ до: + +* аналізу файлів: + + * "Поясни цей документ для команди" + * "Зроби витяг для каналу #planning" + +* генерації нових артефактів: + + * плани, + * дорожні карти, + * документація. + +## 5.2. Зберігання в MicroDAO, а не "десь в хмарі без контролю" + +Ключовий принцип: + +* **Результати роботи агента** (файли, документи, знання) зберігаються: + + * у сховищі степені MicroDAO (файлове / БД), + * або у локальних базах спільноти. + +* DAGI використовується як "мозок", але: + + * не забирає собі сирі дані без волі спільноти, + * не є єдиним місцем зберігання. + +Це важливо підкреслити в UX: + +* у консолі: + + * "Документи зберігаються в просторі вашої microDAO." + +* опції експорту: + + * "Поділитися в іншому просторі DAARION.city" + * "Надати доступ іншому агенту" + +--- + +# 6. Підключення/відключення агентів до публічних/конфіденційних просторів + +## 6.1. З точки зору плитки + +На картці агента: + +* бейджі: + + * `Публічні простори: 2` + * `Конфіденційні: 1` + +* При натисканні: + + * відкривається невеликий список: + + * `#general (публічний)` + * `#dev-mvp (конфіденційний)` + + * поруч — перемикач: + + * `Підключено / Відʼєднано`. + +## 6.2. З точки зору Agent Console + +У вкладці "Присутність / Права доступу": + +* Табличка: + + * Простір / Тип (публічний/конфіденційний) / Доступ / Перемикач. + +* Операції: + + * натискання `Відʼєднати`: + + * агент перестає отримувати потік повідомлень з цього каналу/простору; + * його не видно у списку учасників. + + * натискання `Підключити`: + + * запускає внутрішній Invite-Agent-Flow для відповідного ресурсу. + +Все це повинно залишатись максимально людським в термінології: + +жодних "інвесторів", "юнітів вартості", "ROI" тощо — тільки: + +* "досвід", +* "шлях агента", +* "довіра спільноти", +* "внесок у колективний розум". + +--- + +# 7. Компоненти та структура + +## 7.1. Agent Card Component + +```tsx +interface AgentCardProps { + agent: Agent; + onCardClick: () => void; + onConnect?: () => void; + currentContext?: { + teamId: string; + channelId?: string; + }; +} + +export function AgentCard({ agent, onCardClick, onConnect, currentContext }: AgentCardProps) { + // Рендер картки з усіма метриками +} +``` + +## 7.2. Agent Grid + +```tsx +interface AgentGridProps { + agents: Agent[]; + onAgentSelect: (agentId: string) => void; + filter?: "all" | "connected" | "available"; +} + +export function AgentGrid({ agents, onAgentSelect, filter }: AgentGridProps) { + // Сітка карток агентів +} +``` + +## 7.3. Agent Console + +```tsx +interface AgentConsoleProps { + agentId: string; + initialTab?: "chat" | "files" | "memory" | "presence" | "evolution"; +} + +export function AgentConsole({ agentId, initialTab = "chat" }: AgentConsoleProps) { + // Повний інтерфейс агента з вкладками +} +``` + +--- + +# 8. Типи даних + +## 8.1. Agent Metrics + +```ts +interface AgentMetrics { + age: { + weeks?: number; + months?: number; + years?: number; + }; + experience1T: number; // Досвід в 1T + reputation: { + score: number; // 0-100 або 0-5 + type: "stars" | "percentage"; + }; + presence: { + channels: number; + teams: number; + public: number; + confidential: number; + }; +} +``` + +## 8.2. Agent Presence + +```ts +interface AgentPresence { + channelId: string; + channelName: string; + type: "public" | "confidential"; + accessLevel: string[]; + connected: boolean; +} +``` + +## 8.3. Agent Evolution Log + +```ts +interface AgentEvolutionLog { + tasksHelped: number; + requestTypes: Record; // Типи запитів та їх кількість + contributions: { + factsAdded: number; + rulesCreated: number; + documentsGenerated: number; + }; + communityFeedback: { + positive: number; + negative: number; + averageRating: number; + }; +} +``` + +--- + +# 9. API Endpoints + +## 9.1. Agent Metrics + +```ts +GET /agents/{agentId}/metrics +// Повертає метрики агента (вік, досвід 1T, репутація) + +GET /agents/{agentId}/presence +// Список просторів, де агент присутній +``` + +## 9.2. Agent Files + +```ts +GET /agents/{agentId}/files +// Список файлів, з якими працював агент + +POST /agents/{agentId}/files +// Завантажити файл для аналізу агентом +{ + file: File; + context: { + teamId: string; + channelId?: string; + }; +} +``` + +## 9.3. Agent Evolution + +```ts +GET /agents/{agentId}/evolution/log +// Лог еволюції та внеску агента +``` + +--- + +# 10. UI/UX Деталі + +## 10.1. Відео-аватар + +* Формат: короткий loop (2-5 секунд) +* Розмір на картці: 64x64px +* Розмір в консолі: 128x128px +* Без звуку +* Анімація при hover: легке пожвавлення + +## 10.2. Метрики досвіду + +* Вік: "3 тижні", "6 місяців", "1 рік 2 місяці" +* 1T: велике число з розділювачами (12 340 1T) +* Репутація: візуальна шкала (зірки або прогрес-бар) + +## 10.3. Бейджі присутності + +* Компактні бейджі з іконками +* Кольори: синій для публічних, червоний для конфіденційних +* Іконка замка для конфіденційних просторів + +--- + +# 11. Інтеграція з існуючими модулями + +## 11.1. Agent UI System (10) + +Agent Cards використовують компоненти з `10_agent_ui_system.md`: +- AgentAvatar +- AgentChatWindow (у вкладці "Чат") +- AgentMemoryTab (у вкладці "Памʼять") + +## 11.2. Agent Memory System (13) + +Вкладка "Памʼять і Знання" інтегрується з: +- Short-term memory +- Long-term memory +- RAG retrieval + +## 11.3. Agent Runtime Core (12) + +Agent Console використовує: +- AgentContext для роботи з агентом +- Tools для аналізу файлів +- LLM для генерації документів + +--- + +# 12. Завдання для Cursor + +Приклад промта: + +``` +You are a senior React/TS engineer. + +Implement Agent Cards and Console using: + +- 23_agent_cards_and_console.md +- 10_agent_ui_system.md +- 13_agent_memory_system.md +- 12_agent_runtime_core.md +- 05_coding_standards.md + +Deliverables: + +1) AgentCard component with metrics (age, 1T experience, reputation). +2) AgentGrid component for displaying multiple agent cards. +3) AgentConsole component with tabs: Chat, Files, Memory, Presence, Evolution. +4) Integration with file upload/analysis through DAGI. +5) Presence management (connect/disconnect from channels/projects). + +Output: + +- list of modified files +- diff +- summary +``` + +--- + +# 13. Результат + +Після впровадження: + +* Агенти представлені як живі учасники спільноти, а не просто боти +* Користувач бачить досвід та репутацію кожного агента +* Повний контроль над підключеннями агентів до просторів +* Зберігання всіх результатів роботи агентів у сховищі microDAO +* Людська термінологія без фінансових наративів + +--- + +**Готово.** +Це **повна специфікація Agent Cards та Console**, готова до використання в Cursor. + + diff --git a/docs/cursor/23_domains_wallet_dao_deepdive.md b/docs/cursor/23_domains_wallet_dao_deepdive.md new file mode 100644 index 00000000..3be54670 --- /dev/null +++ b/docs/cursor/23_domains_wallet_dao_deepdive.md @@ -0,0 +1,447 @@ +# 23 — Domains, Wallet Agent & DAO Agent Deep Dive (MicroDAO) + +Технічна специфікація мультидоменного роутингу, Wallet Agent протоколу та DAO Agent синхронізації + +Цей документ деталізує три критичних технічних компоненти MicroDAO: + +1. **Мульти-тенант домени та роутінг** + +2. **Wallet Agent: безпечний підпис дій** + +3. **DAO Agent: звʼязок із зовнішнім DAO-протоколом** + +Документ інтегрований із попередніми модулями (12–22). + +--- + +# 1. MULTI-TENANT DOMAINS & ROUTING + +MicroDAO має підтримувати: + +- піддомени формату `*.daarion.city`, +- власні домени адміністраторів microDAO, +- гнучке маршрутизаційне дерево, +- коректну інтеграцію front/back-end, +- автоматичні SSL-сертифікати, +- безпечне розмежування команд. + +--- + +## 1.1. Модель БД + +### Таблиця `teams` (microDAO) + +```ts +teams: +- id: string +- slug: string // "greenfood", "musiclab" +- primary_domain_id: string | null +- created_at +``` + +### Таблиця `domains` + +```ts +domains: +- id: string +- team_id: string +- host: string // "greenfood.daarion.city", "mydao.org" +- status: "pending" | "active" | "disabled" +- is_primary: boolean +- verified_at: Date | null +- created_at +``` + +--- + +## 1.2. Алгоритм визначення `currentTeamId` по домену + +На початку кожного HTTP-запиту: + +``` +host := request.headers["Host"] + +1) спробувати знайти host у domains: + SELECT team_id FROM domains + WHERE host = $host AND status = 'active'; + +2) якщо знайшли → currentTeamId = team_id. + +3) якщо ні — це, можливо, піддомен DAARION.city: + slug = host.split('.')[0] + SELECT id FROM teams WHERE slug = $slug; + +4) якщо знайшли → currentTeamId = id. + +5) інакше → 404 або сторінка Onboarding ("microDAO не знайдено") +``` + +--- + +## 1.3. Підтримка двох режимів UI + +### Режим 1 — Піддомен / власний домен + +URL: + +``` +greenfood.daarion.city/ +mydao.org/ +``` + +Усі маршрути стають: + +``` +/ → головна команда +/projects +/agents +/settings +``` + +**Без /t/:teamId** — тому що `teamId` вже визначено з домену. + +### Режим 2 — Центральний домен (наприклад, app.daarion.city) + +URL: + +``` +app.daarion.city/t/:teamId/agents +``` + +Цей режим потрібен: + +* для розробки, +* для адміністрування, +* для роботи всередині DAARION.city як централізованої платформи. + +--- + +## 1.4. Налаштування кастомного домену (UX) + +### Потік: + +1. Адмін відкриває: **Settings → Domain** + +2. Поле: "Поточний домен: `greenfood.daarion.city`" + +3. Поле: "Додати власний домен" → `mydao.org` + +4. Система показує інструкцію: + + ``` + Створіть CNAME: + mydao.org → domains.daarion.city + ``` + +5. Домен створюється зі статусом `pending`. + +6. DNS checker (кожні 10 хв) змінює статус на `active`, коли знайдено CNAME. + +7. Автоматичний ACME/SSL випуск. + +8. Домен стає primary. + +--- + +# 2. WALLET AGENT — ПРОТОКОЛ БЕЗПЕЧНОГО ПІДПИСУ + +Wallet Agent — це **інтерфейс** між microDAO і зовнішніми гаманцями: + +* браузерні (MetaMask, WalletConnect), +* мобільні, +* апаратні (Tangem-подібні). + +Wallet Agent **ніколи не отримує приватний ключ**. + +--- + +## 2.1. Потік підпису дії + +Порядок: + +### Етап 1 — Агент хоче виконати дію + +Наприклад: Governance Agent хоче оновити правило. + +```ts +walletAgent.prepare_signature_payload({ + action: "update_policy", + params: {...} +}); +``` + +Wallet Agent: + +1. Валідатор: "Чи має агент право робити це?" +2. Створює запис у `sign_requests`. +3. Формує `human_description`. +4. Показує людині Approval UI. + +--- + +## 2.2. Модель `sign_requests` + +```ts +sign_requests: +- id +- team_id +- type // "governance_update", "dao_submit", ... +- payload_json // те, що треба підписати +- human_description +- created_by_agent_id +- created_by_user_id? // якщо ініціатор — людина +- status: "pending" | "signed" | "rejected" +- created_at +- updated_at +``` + +--- + +## 2.3. UX у фронтенді + +Коли є новий `sign_request`: + +* у UI зʼявляється: + + * "Агент пропонує підписати дію" + * опис, + * кнопки: + + * "Підписати" + * "Скасувати" + +Коли користувач натискає "Підписати": + +1. фронт надсилає `payload` у wallet provider (MetaMask / WC / Tangem SDK), +2. отримує `signature`, +3. викликає: + + ``` + POST /sign_requests/:id/confirm + { + signature: "0x..." + } + ``` + +--- + +## 2.4. Таблиця `sign_results` + +```ts +sign_results: +- id +- sign_request_id +- signature +- tx_hash? +- confirmed_at +- status: "broadcasted" | "failed" +``` + +--- + +## 2.5. Wallet Agent Tools + +```ts +tools: [ + "prepare_signature_payload", // формує sign_request + "request_signature", // запит до користувача (UI) + "verify_signature", // перевірка + "get_wallet_state" // поточні адреси, мережі, доступи +] +``` + +Wallet Agent — це декларативна прослойка між дією і підписом користувача. + +--- + +# 3. DAO AGENT — СИНХРОНІЗАЦІЯ З ON-CHAIN DAO + +Не кожному microDAO потрібен on-chain DAO. + +Але архітектура має підтримувати: + +* звʼязок з DAO-контрактами, +* синхронізацію ритуалів узгодження microDAO з DAO-голосуваннями, +* оновлення локальних правил після голосування, +* відправку результатів у DAO-контракт. + +--- + +## 3.1. Модель задач DAO Agent + +### 1) Fetch external proposals + +``` +fetch_dao_proposals(team_id) +``` + +Тягне список пропозицій з DAO-контракту чи API. + +### 2) Map rituals to proposals + +``` +map_ritual_to_proposal(ritual_id, proposal_id) +``` + +Звʼязує локальний ритуал і зовнішню пропозицію. + +### 3) Submit local result to DAO + +``` +submit_ritual_result(ritual_id) +``` + +Використовує Wallet Agent для підпису. + +### 4) Sync policy + +``` +sync_policies_onchain() +``` + +Порівнює локальні правила з DAO-версією. + +--- + +## 3.2. Модель БД + +### Таблиця `dao_proposals` + +```ts +dao_proposals: +- id +- team_id +- proposal_id_onchain +- title +- body +- status: "open" | "closed" +- result: "accepted" | "rejected" | "pending" +- mapped_ritual_id: string | null +- created_at +``` + +### Таблиця `dao_sync_logs` + +Журнал синхронізації. + +```ts +dao_sync_logs: +- id +- team_id +- action_type +- payload_json +- created_at +``` + +--- + +## 3.3. DAO Agent Tools + +```ts +tools: [ + "fetch_dao_proposals", + "sync_policies_onchain", + "submit_ritual_result", + "resolve_dao_result" +] +``` + +--- + +# 4. Інтеграція з Governance Agent та OperatorMode + +DAO Agent працює лише тоді, коли: + +* Governance Agent дозволяє це (entitlement), +* Wallet Agent підписує дії людиною. + +OperatorMode у DAO Agent: + +```ts +operatorMode: { + enabled: true, + scopes: ["team"], + allowedTools: [ + "fetch_dao_proposals", + "sync_policies_onchain" + ], + schedule: "0 */6 * * *", // кожні 6 годин + maxActionsPerHour: 5 +} +``` + +**Оновлення правил або відправка результатів ритуалу завжди вимагає людського підпису.** + +--- + +# 5. API ЕНДПОЇНТИ + +## 5.1. Domains API + +``` +GET /domains?team_id +POST /domains +PATCH /domains/:id +DELETE /domains/:id +``` + +## 5.2. Wallet API + +``` +GET /sign_requests?team_id +POST /sign_requests +POST /sign_requests/:id/confirm +POST /sign_requests/:id/reject +``` + +## 5.3. DAO API + +``` +GET /dao/proposals?team_id +POST /dao/sync +POST /dao/ritual/:id/submit +``` + +--- + +# 6. Інструкції для Cursor + +``` +Use 23_domains_wallet_dao_deepdive.md to implement: + +1) Multi-tenant domain routing (backend + frontend) + +2) Domains management UI (admin area) + +3) Wallet Agent protocol: + + - sign_requests + - sign_results + - prepare_signature_payload + - confirm/reject endpoints + +4) DAO Agent backend model: + + - dao_proposals + - dao_sync_logs + - mapping rituals <-> proposals + +5) Guard all DAO Agent actions with: + + - Governance/Access entitlements + - Wallet signature flow + +6) Add operatorMode guards where appropriate +``` + +--- + +# 7. Результат + +Після впровадження: + +* кожне microDAO може мати власний домен без конфігураційної плутанини, +* Wallet Agent забезпечує безпечний і прозорий протокол підпису, +* DAO Agent може синхронізуватися з зовнішніми DAO-протоколами, +* архітектура стає розширюваною для міжпросторових і міжмережевих інтеграцій, +* operatorMode забезпечує контрольований автоматизм без ризиків. diff --git a/docs/cursor/24_access_keys_capabilities_system.md b/docs/cursor/24_access_keys_capabilities_system.md new file mode 100644 index 00000000..2f37ffdb --- /dev/null +++ b/docs/cursor/24_access_keys_capabilities_system.md @@ -0,0 +1,677 @@ +# 24 — Access Keys & Capabilities System (MicroDAO) + +Універсальна система ключів доступу та capability-механіка + +Цей документ описує універсальну систему ключів доступу (access keys) та capability-механіку для платформи **microdao / DAARION.city**: + +- як видаються й перевіряються ключі; +- як описуються та застосовуються capabilities; +- як працюють **Wallet Agent** і **Embassy Module**; +- як система вбудовується в існуючі RBAC/Entitlements/Mode (public|confidential) та Governance. + +Ціль: єдиний шар авторизації для веб-клієнта, приватних агентів, API, інтеграцій та зовнішніх платформ. + +--- + +## 1. Purpose & Scope + +Цей документ описує універсальну систему ключів доступу (access keys) та capability-механіку для платформи **microdao / DAARION.city**: + +- як видаються й перевіряються ключі; +- як описуються та застосовуються capabilities; +- як працюють **Wallet Agent** і **Embassy Module**; +- як система вбудовується в існуючі RBAC/Entitlements/Mode (public|confidential) та Governance. + +Ціль: єдиний шар авторизації для веб-клієнта, приватних агентів, API, інтеграцій та зовнішніх платформ. + +--- + +## 2. Основні поняття + +### 2.1 Access Key + +Access Key — це матеріалізований «токен доступу» до певної області системи: + +- має унікальний `key_id`; +- прив'язаний до **суб'єкта** (user / team / agent / external platform); +- має **набір capabilities**; +- має строк дії та статус (active / revoked / expired). + +Приклади: + +- ключ API для інтеграції з GreenFood; +- ключ приватного агента до Co-Memory та Projects; +- ключ Embassy для міжплатформенної взаємодії. + +### 2.2 Capability + +Capability — атомарне право **на дію над ресурсом**. + +Формат (концептуально): + +```text +..[:] +``` + +Приклади: + +- `chat.message.send` +- `chat.channel.manage` +- `comemory.item.read:team` +- `projects.task.write` +- `wallet.balance.view` +- `wallet.stake.ringk` +- `governance.proposal.create` +- `energy.asset.read` +- `platform.greenfood.inventory.update` + +### 2.3 Capability Bundle (role / plan / template) + +Capability-набір: + +- набір capabilities, який прив'язується до: + - ролі (`Owner`, `Guardian`, `Member`, `Visitor`); + - тарифного плану (Freemium / Casual / Premium / Platformium); + - конкретного access key (API-ключ, агент, інтеграція). + +--- + +## 3. Модель доступу (оновлена формула allow) + +Базова формула авторизації: + +```text +allow = + RBAC(role, action, resource) + ∧ Entitlement(plan, RINGK_staked) + ∧ Capability(key, action, resource) + ∧ ACL(resource) + ∧ Mode(public|confidential) +``` + +Тобто: + +1. Роль дозволяє дію (Owner/Guardian/Member/Visitor). +2. План + стейк RINGK дають достатні ліміти/право (ентайтли). +3. Ключ (user/agent/API) має відповідну capability. +4. ACL ресурсу не забороняє (список дозволених/заборонених). +5. Режим каналу/команди (public/confidential) не блокує дію. + +--- + +## 4. Типи ключів + +### 4.1 User Session Key + +- Прив'язаний до користувача (`user_id`) і сесії (JWT / cookie). +- Використовується веб-клієнтом. +- Capabilities виводяться з ролі, ентайтлів і контексту (team, mode). + +### 4.2 Agent Access Key + +- Прив'язаний до приватного агента (`ag_…`). +- Використовується при викликах **Agent Mesh / Tooling API**. +- Має обмежений набір capabilities: + - `chat.message.read:scoped` + - `comemory.item.read:scoped` + - `followups.create` + - `projects.task.read/write` (за необхідності) +- Має обмеження за: + - токенами/хв; + - кількістю викликів; + - бюджетом 1T / KWT. + +### 4.3 API Key / Integration Key + +- Прив'язаний до інтеграції (`integrations`). +- Наприклад: Notion, Slack, GreenFood, Energy Union, Water Union. +- Capabilities для зовнішнього сервісу: + - `webhook.events.receive:team` + - `projects.task.sync` + - `rwa.energy.update` + - `platform.greenfood.sync` + +### 4.4 Embassy Key + +- Ключ для **Embassy Module** — шлюз між DAARION.city та зовнішньою платформою/мережею. +- Додаткові властивості: + - mapping зовнішніх ідентичностей (external_id ↔ DID/user_id); + - whitelist дозволених типів актів (`intent.created`, `offer.published`, `gift.ack`, `rwa.claim` тощо); + - окремий журнал дій для аудиту. + +### 4.5 Wallet Capability Key + +- Спеціальний ключ для **Wallet Agent**: + - `wallet.balance.view` + - `wallet.tx.initiate` + - `wallet.tx.sign` + - `wallet.stake.ringk` + - `wallet.claim.rwa` +- Може бути: + - нон-кастодіальний (підпис у клієнта, key лише для маршрутизації); + - кастодіальний (wallet service з 4-eyes контролем). + +--- + +## 5. Wallet Agent: специфікація + +### 5.1 Призначення + +Wallet Agent — це агент, який: + +- показує баланси токенів (RINGK, 1T, KWT, DAAR, DAARION тощо); +- ініціює й перевіряє дії стейкінгу/unstake RINGK; +- показує історію payouts (1T/KWT); +- працює з RWA-сертифікатами (Energy, GREENFOOD тощо) через Embassy. + +### 5.2 Основні флоу + +1. **View balances** + +- Виклик: `/wallet/balances`. +- Перевірка: + - RBAC: будь-який Member+ / Owner/Guardian. + - Capability: `wallet.balance.view`. + - Mode: не залежить від public/confidential. + +2. **Stake RINGK** + +- Виклик: `/staking/ringk` (`amount`). +- Перевірка: + - RBAC: Member+. + - Capability: `wallet.stake.ringk`. + - Entitlements: перевірка мінімального стейку, lock-параметрів. + - Governance: параметри стейку (lock_until, min_amount) беруться з onchain/DAO-конфігів. + +3. **Claim payouts (1T/KWT/RWA)** + +- Флоу: + - Wallet Agent читає `payouts`/`rwa_claims` з backend; + - ініціює підпис транзакції користувачем; + - виконує через onchain gateway/Embassy. +- Capabilities: + - `wallet.payout.view` + - `wallet.payout.claim` + - `rwa.claim` + +### 5.3 Дані (мінімум) + +- `wallets` (user_id ↔ address) +- `staking_ringk` +- `payouts` +- `rwa_certificates` / `rwa_claims` (через Embassy) + +--- + +## 6. Embassy Module: специфікація + +### 6.1 Призначення + +Embassy Module — шар інтеграції між: + +- DAARION.city (місто агентів, microdao); +- зовнішніми платформами (GreenFood, Energy Union, інші RWA-ініціативи); +- публічними мережами (L2, marketplace, вузли взаємообміну). + +Він відповідає за: + +- мапінг ідентичностей; +- валідацію актів взаємодії; +- трансформацію подій і capability-рівнів. + +### 6.2 Ідентичності + +- `resident_id` ↔ `user_id`/DID. +- `district_id` ↔ team/microDAO. +- `agent_id` ↔ citizen-agent. +- `rwa_id` ↔ сертифікат дару/актив RWA. + +Embassy Key має capability-набори: + +- `embassy.intent.read/write` +- `embassy.rwa.claim` +- `embassy.energy.update` +- `embassy.audit.view` + +### 6.3 Події (канонічні акти) + +- `intent.created` +- `offer.published` +- `gift.ack` +- `memory.update` +- `rwa.claim` +- `energy.update` + +Embassy: + +- приймає подію через webhook / шину (NATS); +- перевіряє capability Embassy Key; +- трансформує в внутрішні події (`reward.*`, `oracle.*`, `payout.*`). + +--- + +## 7. Runtime capability-check + +### 7.1 Компоненти + +- **PDP** (Policy Decision Point) — сервіс, який: + - приймає контекст запиту: `user_id / agent_id`, `team_id`, `resource`, `action`, `mode`, `key_id`; + - повертає `allow/deny` + причину. +- **PEP** (Policy Enforcement Point): + - live у API-gateway і сервісах (Messaging, Projects, Wallet, Governance). + +### 7.2 Кеш і формат токена + +- Для кожного access key формується компактний «capability token»: + - `sub` (user/agent/integration); + - `team_scope`; + - `caps` (список capability кодів або bitmap); + - `exp`. +- Токен зберігається в Redis / in-memory кеші для швидкої перевірки. + +### 7.3 Приклади перевірок + +1. Агент хоче прочитати Co-Memory: + +```text +action = comemory.item.read +resource = chat: c_123 +mode = confidential +subject = ag_456 +key_id = ak_789 + +→ RBAC: owner of agent = Member в team t_1 +→ Entitlements: план дозволяє приватні агенти +→ Capability(ak_789): містить comemory.item.read:scoped +→ ACL: чат дозволяє агентів +→ Mode: confidential → E2EE, агент отримує лише векторні ознаки/summary + +→ allow +``` + +2. Зовнішній RWA-хаб оновлює енергетичний актив: + +```text +action = energy.update +subject = embassy_key ek_001 +→ Capability(ek_001): енергетичні оновлення дозволені для конкретного district_id +→ Governance: політика для цього district_id активна + +→ allow +``` + +--- + +## 8. Інтеграція з Governance Agent + +Governance Agent: + +- має capability `governance.policy.manage` (тільки Owner/Guardian через DAO-процес); +- може: + - створювати/оновлювати **capability bundles**; + - прив'язувати bundles до ролей/планів/ключів; + - змінювати пороги доступу (напр. min RINGK stake для Premium/Platformium). + +Флоу: + +1. Створюється пропозиція (onchain / в DAO Service): + - змінити набір capabilities для `Platformium` плану; + - додати capability `platform.greenfood.inventory.update`. +2. Пропозиція голосується токеном DAARION. +3. Після прийняття Governance Agent: + - оновлює конфіг у Capability Registry; + - виконує міграцію активних access keys; + - логуються події `governance.policy.updated`. + +--- + +## 9. Дані та моделі (мінімальна схема) + +Таблиці (спрощений вигляд): + +```sql +create table access_keys ( + id text primary key, -- ak_... + subject_kind text not null, -- user|agent|integration|embassy + subject_id text not null, + team_id text null, + name text not null, + status text not null check (status in ('active','revoked','expired')), + created_at timestamptz not null default now(), + expires_at timestamptz null +); + +create table capabilities ( + id text primary key, -- cap_... + code text not null, -- chat.message.send, wallet.stake.ringk + description text not null +); + +create table access_key_caps ( + key_id text references access_keys(id) on delete cascade, + cap_id text references capabilities(id) on delete cascade, + primary key (key_id, cap_id) +); + +create table bundles ( + id text primary key, -- bundle_... + name text not null, -- e.g. "role.Member", "plan.Premium", "agent.default" + created_at timestamptz not null default now() +); + +create table bundle_caps ( + bundle_id text references bundles(id) on delete cascade, + cap_id text references capabilities(id) on delete cascade, + primary key (bundle_id, cap_id) +); +``` + +Access key може наслідувати capabilities з одного чи кількох bundles. + +--- + +## 10. Безпека + +- Мінімізований набір capabilities за замовчуванням (principle of least privilege). +- Для confidential-контенту: + - агенти не отримують plaintext без явної згоди; + - Embassy не передає контент, тільки агреговані/векторні дані. +- Всі access keys: + - зберігаються у зашифрованому вигляді (KMS); + - мають короткий час життя, періодичну ротацію; + - мають аудит використання (audit_log). + +--- + +## 11. Інтеграція з RBAC & Entitlements + +Посилання на документ: `microdao — RBAC і Entitlements (MVP).docx` + +1. Розширена формула доступу (оновлює пункт 2 у RBAC-документі): + +```text +allow = + RBAC(role, action, resource) + ∧ Entitlement(plan, RINGK_staked) + ∧ Capability(key, action, resource) + ∧ ACL(resource) + ∧ Mode(public|confidential) +``` + +2. Мапінг ролей з RBAC → capability bundles: + +- з таблиць `team_members.role` (`Owner`, `Guardian`, `Member`) та viewer-type (`reader`, `commenter`, `contributor`) формуються стартові bundles: + - `bundle.role.Owner` + - `bundle.role.Guardian` + - `bundle.role.Member` + - `bundle.role.Visitor` (для гостя в public-каналах). +- кожен bundle включає capabilities, що відповідають матрицям з розділу «4) Ресурси → дії (матриці)» RBAC-документу + (Community, Channels, Messages, Follow-ups, Projects, Tasks, Docs, Meetings). + +3. Мапінг Entitlements (плани + стейк RINGK): + +- таблиці з Data Model: + - `wallets` + - `staking_ringk` +- плани з RBAC-документу (`Freemium`, `Casual`, `Premium`, `Platformium`) задаються як: + - `bundle.plan.Freemium` + - `bundle.plan.Casual` + - `bundle.plan.Premium` + - `bundle.plan.Platformium` +- формула з RBAC → в capability-рівень: + +```text +effective_quota = min(plan_quota × multiplier(RINGK_staked), hard_limit) +``` + +- ліміти прив'язуються до capabilities на кшталт: + - `chat.message.send` + - `agent.run.invoke` + - `router.invoke` + - `wallet.payout.claim` + +--- + +## 12. Інтеграція з Security Architecture & Threat Model + +Посилання: `microdao — Security Architecture & Threat Model (MVP).docx` + +1. Зберігання ключів: + +- метадані ключа — в таблиці `access_keys` (див. розділ 13 нижче); +- сам секрет (`secret`) зберігається зашифрованим (KMS/HSM), згідно з розділами про secrets у Security Architecture; +- one-time reveal: після створення ключ не показується повторно. + +2. Транспорт і токени: + +- веб-клієнт: + - використовує сесію (`users` + сесійні токени на рівні Auth); + - capability-набір інкапсульовано в «capability token» (JWT/opaque), який несе: + - `sub` (u_/ag_/integr), + - `team_id`, + - стиснений список `caps`. +- API/Webhooks/Embassy: + - ключ передається в `Authorization: Bearer ` або в окремому заголовку; + - підпис вебхуків (Embassy) — HMAC, як у Security Architecture. + +3. Confidential-режим: + +- `teams.mode` ∈ (`public`, `confidential`); +- для `mode='confidential'`: + - агенти з Agent Access Key не бачать `chat_message.body` у plaintext, + - доступ дається до: + - агрегованих структур (`comemory_items`), + - embeddings/summary, сформованих локально або в E2EE-шарі; +- це наслідує E2EE-модель з Security-документу (сервер бачить мінімум метаданих). + +4. Threat model для access keys: + +- нові активи: + - `access_keys`, `bundles`, capability-кеш; +- загрози: + - компрометація ключа, зловживання Embassy-ключем, масовий abuse agent-ключів; +- мітiгації: + - короткий `expires_at`, обов'язкова ротація; + - strict capabilities (least privilege); + - обов'язковий аудит через події `audit.event` і нові `access_key.*` (див. нижче). + +--- + +## 13. Інтеграція з Data Model & Event Catalog + +Посилання: `microdao — Data Model & Event Catalog.docx` + +1. Нові таблиці (додати в розділ DB-схеми, поруч із Wallet / Governance): + +```sql +create table access_keys ( + id text primary key, -- ak_... + subject_kind text not null, -- 'user' | 'agent' | 'integration' | 'embassy' + subject_id text not null, -- u_/ag_/... + team_id text null, -- t_..., якщо scoped до команди + name text not null, + status text not null check (status in ('active','revoked','expired')), + created_at timestamptz not null default now(), + expires_at timestamptz null, + last_used_at timestamptz null +); + +create table capabilities ( + id text primary key, -- cap_... + code text not null unique, -- chat.message.send, wallet.stake.ringk, ... + description text not null +); + +create table access_key_caps ( + key_id text references access_keys(id) on delete cascade, + cap_id text references capabilities(id) on delete cascade, + primary key (key_id, cap_id) +); + +create table bundles ( + id text primary key, -- bundle_... + name text not null unique, -- role.Member / plan.Premium / agent.default + created_at timestamptz not null default now() +); + +create table bundle_caps ( + bundle_id text references bundles(id) on delete cascade, + cap_id text references capabilities(id) on delete cascade, + primary key (bundle_id, cap_id) +); +``` + +- конвенції ID узгоджуються з розділом «2) Конвенції»: + - `ak_…` для access keys; + - `cap_…` для capabilities; + - `bundle_…` для bundle-ів. + +2. Прив'язка до існуючих таблиць: + +- `access_keys.subject_id` → `users.id` / `agents.id` / `integrations.id` / Embassy-ідентифікатори (згідно з Data Model); +- `access_keys.team_id` → `teams.id` (team як microDAO/платформа). + +3. Нові події для Event Catalog (розширення enum `topic`): + +Додати в список `topic.enum`: + +```jsonc +"access_key.created", +"access_key.revoked", +"access_key.used" +``` + +та окремі `allOf`-entry з `$defs`: + +```jsonc +// envelope.topic = "access_key.created" +"access_key_created": { + "type": "object", + "properties": { + "key_id": { "type": "string" }, + "subject_kind": { "type": "string" }, + "subject_id": { "type": "string" }, + "team_id": { "type": ["string","null"] } + }, + "required": ["key_id","subject_kind","subject_id"] +} +``` + +аналогічні схеми для `access_key.revoked` і `access_key.used` +(з полями `revoked_by`, `action`, `resource_kind`). + +4. Зв'язок з уже наявними подіями: + +- `staking_ringk` + `payouts` вже мають події: + - `"staking.locked"` + - `"payout.generated"` + - `"rwa.inventory.updated"` +- Wallet Agent та Embassy в sequence-діаграмах нижче використовують саме ці topic-и; capability-check визначає, хто має право ініціювати або читати ці події. + +--- + +## 14. Sequence-діаграми (ключові флоу) + +### 14.1 Wallet Agent: login → access key → capability-check → stake RINGK + +```mermaid +sequenceDiagram + participant U as User (browser) + participant Auth as Auth Service + participant API as API Gateway + participant PDP as Policy Service + participant W as Wallet Service + participant BUS as NATS JetStream + + U->>Auth: 1) POST /login (email+code) + Auth-->>U: 2) Session (JWT/cookie з user_id + capability token) + + U->>API: 3) POST /wallet/stake {amount} + API->>PDP: 4) authorize(user_id, action=wallet.stake.ringk) + PDP-->>API: 5) allow / deny + + API->>W: 6) create_stake_request(user_id, amount) + W->>BUS: 7) publish topic="staking.locked" (payload.staking_id) + API-->>U: 8) 200 OK (stake pending) + + W->>BUS: 9) (після ончейн-обробки) publish topic="payout.generated" + BUS-->>U: 10) notification → Wallet Agent (claim available) +``` + +### 14.2 Embassy Module: external RWA → Embassy → capability-check → internal events + +```mermaid +sequenceDiagram + participant Ext as External RWA Hub + participant GW as Embassy Gateway (HTTP/Webhook) + participant PDP as Policy Service + participant BUS as NATS JetStream + + Ext->>GW: 1) POST /embassy/rwa {inventory_update} + access_key + GW->>PDP: 2) authorize(embassy_key, action=rwa.inventory.update) + PDP-->>GW: 3) allow / deny + + GW->>BUS: 4) publish topic="rwa.inventory.updated" (payload.rwa_id, delta) + BUS-->>BUS: 5) downstream services (Wallet/Gift Fabric) слухають подію +``` + +### 14.3 Energy Union: meter → Energy Union → Embassy → payouts + +```mermaid +sequenceDiagram + participant M as Metering Agent + participant EU as Energy Union Backend + participant Emb as Embassy Module + participant PDP as Policy Service + participant BUS as NATS JetStream + participant W as Wallet Service + + M->>EU: 1) send meter data (kWh) + EU->>EU: 2) aggregate & validate + + EU->>Emb: 3) POST /embassy/oracle {site, period, kWh} + access_key + Emb->>PDP: 4) authorize(embassy_key, action=oracle.reading.publish) + PDP-->>Emb: 5) allow + + Emb->>BUS: 6) publish topic="oracle.reading.published" + BUS->>W: 7) consume oracle → compute payouts + W->>BUS: 8) publish topic="payout.generated" (symbol="KWT"/"1T") + BUS-->>Users: 9) Wallet Agent показує доступні виплати +``` + +--- + +## 15. Завдання для Cursor + +```text +You are a senior backend engineer. Implement the Access Keys & Capabilities System using: +- 24_access_keys_capabilities_system.md +- 18_governance_access_agent.md +- 23_domains_wallet_dao_deepdive.md +- 05_coding_standards.md + +Tasks: +1) Create database schema: access_keys, capabilities, access_key_caps, bundles, bundle_caps. +2) Implement PDP (Policy Decision Point) service. +3) Integrate PEP (Policy Enforcement Point) into API Gateway. +4) Implement Wallet Agent endpoints with capability checks. +5) Create Embassy Module stub with capability validation. +6) Add capability-check middleware for all API endpoints. + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 16. Результат + +Після впровадження цієї системи: + +- єдиний шар авторизації для всіх типів доступу (users, agents, integrations, platforms); +- чіткий контроль прав через capabilities; +- інтеграція з Wallet Agent та Embassy Module; +- підготовка до масштабування та додавання нових платформ. + diff --git a/docs/cursor/24_agent_cards_tasks.md b/docs/cursor/24_agent_cards_tasks.md new file mode 100644 index 00000000..597e6072 --- /dev/null +++ b/docs/cursor/24_agent_cards_tasks.md @@ -0,0 +1,349 @@ +# 24 — Agent Cards and Console Tasks (MicroDAO) + +Структурований список задач для реалізації Agent Cards та Console + +Цей документ містить детальні технічні задачі для поетапної реалізації системи карток агентів та Agent Console. + +**Базовий документ:** `23_agent_cards_and_console.md` + +--- + +# Task 1 — Agent-Cards-Grid (плитки агентів) + +## Мета + +Створити компонент AgentCard та AgentGrid для відображення агентів у вигляді "живих карток" з метриками досвіду, репутації та присутності. + +## Специфікація + +### 1. Компонент AgentCard + +* Розмір: 280x360px (рекомендовано) +* Структура: + + * Верхній блок: Аватар + відео-аватар (64x64px) + * Імʼя та роль + * Метрики: Вік, Досвід 1T, Репутація + * Присутність: бейджі каналів/проєктів + * Статус підключення + +### 2. Компонент AgentGrid + +* Сітка карток (responsive: 1-4 колонки) +* Фільтри: "Всі", "Підключені", "Доступні" +* Пошук по імені/ролі + +### 3. Дані + +* API: `GET /agents?team_id=...` +* Метрики: `GET /agents/{id}/metrics` +* Присутність: `GET /agents/{id}/presence` + +### 4. Hover ефект + +* Напівпрозорий оверлей з кнопками: + * "Почати взаємодію" + * "Підключити до каналу" + * "Деталі агента" + +### 5. Клік + +* Відкриває Agent Console (Task 2) + +## Acceptance Criteria + +* Картки агентів відображаються у сітці +* Показуються метрики (вік, 1T, репутація) +* Hover показує опції взаємодії +* Клік відкриває Agent Console +* Фільтри та пошук працюють + +## Приклад промта для Cursor + +``` +Implement Agent Cards Grid using: + +- 23_agent_cards_and_console.md +- 10_agent_ui_system.md +- 05_coding_standards.md + +Deliverables: + +1) AgentCard component with avatar, name, role, metrics (age, 1T, reputation). +2) AgentGrid component with responsive layout (1-4 columns). +3) Hover overlay with action buttons. +4) Filters: All / Connected / Available. +5) Search by name/role. + +Output: list of files + diff + summary. +``` + +--- + +# Task 2 — Agent-Console-UI (повний інтерфейс) + +## Мета + +Створити Agent Console — повний інтерфейс для взаємодії з агентом з 5 вкладками. + +## Специфікація + +### 1. Структура Agent Console + +* Верхня панель: Аватар, імʼя, метрики +* Вкладки: Чат, Файли, Памʼять, Присутність, Еволюція +* Контент вкладок (деталі нижче) + +### 2. Вкладка "Чат" + +* Використовує `AgentChatWindow` з `10_agent_ui_system.md` +* Додатково: кнопка "Голосовий діалог" (stub для MVP) +* Показ поточного контексту + +### 3. Вкладка "Файли та Документи" + +* Список файлів (з API або stub) +* Кнопка "Завантажити файл" +* Індикатор: "Документи зберігаються в просторі вашої microDAO" + +### 4. Вкладка "Памʼять і Знання" + +* Використовує компоненти з `13_agent_memory_system.md` +* Короткострокова та довгострокова памʼять +* Кнопки управління памʼяттю + +### 5. Вкладка "Присутність / Права доступу" + +* Таблиця просторів (канали, проєкти) +* Перемикачі підключення +* Рівні доступу +* Кнопка "Додати до нового каналу/проєкту" + +### 6. Вкладка "Еволюція та дух спільноти" + +* Лог внеску агента +* Статистика запитів +* Репутація від спільноти +* Без фінансових термінів + +## Acceptance Criteria + +* Agent Console відкривається при кліку на картку +* Всі 5 вкладок працюють +* Чат інтегрований з Agent Runtime Core +* Файли показуються (stub дані OK) +* Памʼять інтегрована з Memory System +* Присутність показує реальні дані +* Еволюція показує лог (stub OK) + +## Приклад промта для Cursor + +``` +Implement Agent Console UI using: + +- 23_agent_cards_and_console.md +- 10_agent_ui_system.md +- 13_agent_memory_system.md +- 12_agent_runtime_core.md +- 05_coding_standards.md + +Deliverables: + +1) AgentConsole component with 5 tabs. +2) Chat tab: integrate AgentChatWindow. +3) Files tab: file list + upload button (stub). +4) Memory tab: integrate memory components. +5) Presence tab: table with connect/disconnect toggles. +6) Evolution tab: log display (stub data OK). + +Output: list of files + diff + summary. +``` + +--- + +# Task 3 — Agent-Experience-Metrics (1T + репутація) + +## Мета + +Реалізувати систему метрик досвіду агентів: вік, досвід 1T, репутація спільноти. + +## Специфікація + +### 1. Вік агента + +* Розрахунок: `created_at` до поточної дати +* Формат: "3 тижні", "6 місяців", "1 рік 2 місяці" +* API: `GET /agents/{id}/metrics` → `{ age: { weeks, months, years } }` + +### 2. Досвід 1T + +* Лічильник: велике число з розділювачами (12 340 1T) +* Tooltip: "1T — це внутрішня одиниця обчислень і досвіду агента" +* API: `GET /agents/{id}/metrics` → `{ experience1T: number }` +* Візуалізація: великий текст з іконкою + +### 3. Репутація спільноти + +* Шкала: 0-100 або 0-5 зірок +* Розрахунок: на основі фідбеку від учасників +* API: `GET /agents/{id}/metrics` → `{ reputation: { score, type } }` +* Візуалізація: прогрес-бар або зірки + +### 4. Компонент AgentMetrics + +```tsx +interface AgentMetricsProps { + agentId: string; + compact?: boolean; // для картки vs консолі +} + +export function AgentMetrics({ agentId, compact }: AgentMetricsProps) { + // Відображення метрик +} +``` + +## Acceptance Criteria + +* Вік агента розраховується правильно +* 1T показується з tooltip +* Репутація відображається візуально +* Метрики оновлюються при зміні даних + +## Приклад промта для Cursor + +``` +Implement Agent Experience Metrics using: + +- 23_agent_cards_and_console.md +- 03_api_core_snapshot.md +- 05_coding_standards.md + +Deliverables: + +1) Calculate agent age from created_at. +2) Display 1T experience with tooltip explanation. +3) Display reputation (0-100 scale or 0-5 stars). +4) AgentMetrics component for reuse in Card and Console. +5) API integration: GET /agents/{id}/metrics. + +Output: list of files + diff + summary. +``` + +--- + +# Task 4 — Agent-Connections-Toggles (підключення/відключення) + +## Мета + +Реалізувати управління підключеннями агентів до просторів (канали, проєкти) з перемикачами. + +## Специфікація + +### 1. На картці агента + +* Бейджі: "Публічні простори: 2", "Конфіденційні: 1" +* При кліку — модалка зі списком просторів +* Перемикачі для кожного простору + +### 2. У Agent Console (вкладка "Присутність") + +* Таблиця просторів: + * Простір / Тип / Доступ / Статус / Дії +* Перемикач "Підключено/Відʼєднано" +* Кнопка "Додати до нового простору" + +### 3. API + +* `GET /agents/{id}/presence` → список просторів +* `POST /agents/{id}/presence/connect` → підключити +* `POST /agents/{id}/presence/disconnect` → відключити + +### 4. UX + +* При відключенні: підтвердження +* При підключенні: вибір прав доступу +* Оновлення UI після зміни + +## Acceptance Criteria + +* Бейджі на картці показують кількість просторів +* Модалка зі списком просторів працює +* Перемикачі в консолі працюють +* API виклики зберігають зміни +* UI оновлюється після змін + +## Приклад промта для Cursor + +``` +Implement Agent Connections Management using: + +- 23_agent_cards_and_console.md +- 21_agent_only_interface.md +- 03_api_core_snapshot.md +- 05_coding_standards.md + +Deliverables: + +1) Badges on agent card showing presence count. +2) Modal with list of spaces (channels/projects) for agent. +3) Toggle switches in Agent Console Presence tab. +4) Connect/disconnect API calls. +5) UI updates after connection changes. + +Output: list of files + diff + summary. +``` + +--- + +# Порядок виконання задач + +Рекомендований порядок: + +1. **Task 1** — Agent-Cards-Grid (базова структура карток) +2. **Task 3** — Agent-Experience-Metrics (метрики для карток) +3. **Task 2** — Agent-Console-UI (повний інтерфейс) +4. **Task 4** — Agent-Connections-Toggles (управління підключеннями) + +--- + +# Залежності між задачами + +- **Task 1** не залежить від інших +- **Task 3** може використовуватися в Task 1 +- **Task 2** потребує Task 1 (відкриття консолі з картки) +- **Task 4** потребує Task 2 (вкладка "Присутність") + +--- + +# Загальні вимоги + +## Термінологія + +**Важливо:** Використовувати тільки людську термінологію: + +✅ Дозволено: +- "досвід" +- "шлях агента" +- "довіра спільноти" +- "внесок у колективний розум" +- "репутація" + +❌ Заборонено: +- "інвестиції" +- "юніти вартості" +- "ROI" +- "прибуток" +- будь-які фінансові терміни + +## Зберігання даних + +* Всі файли/документи зберігаються в сховищі microDAO +* Показувати індикатор: "Документи зберігаються в просторі вашої microDAO" +* DAGI використовується як "мозок", але не як сховище + +--- + +**Готово.** +Це **структурований список задач для Agent Cards та Console**, готовий до використання в Cursor. + + diff --git a/docs/cursor/25_deployment_infrastructure.md b/docs/cursor/25_deployment_infrastructure.md new file mode 100644 index 00000000..872770ab --- /dev/null +++ b/docs/cursor/25_deployment_infrastructure.md @@ -0,0 +1,480 @@ +# 25 — Deployment & Infrastructure (MicroDAO) + +*Deployment процес, середовища, інфраструктура, CI/CD, моніторинг* + +--- + +## 1. Purpose & Scope + +Цей документ описує інфраструктуру розгортання та процеси деплою для: + +- microdao (messenger + agents + governance + wallet); +- DAARION.city core (Second Me, Gift Fabric, Citizenship); +- інтеграційних модулів (Embassy, RWA, Energy Union, GREENFOOD та ін.); +- Event-driven шару (NATS/JetStream / Outbox). + +Ціль: + +- чітко визначити середовища (local/dev/staging/prod); +- описати основні компоненти інфра-стеку; +- стандартизувати CI/CD pipeline та керування міграціями; +- визначити моніторинг, логування, backup/restore. + +--- + +## 2. Environments + +### 2.1 Local + +Призначення: + +- швидка розробка; +- інтеграційні тести окремого розробника. + +Особливості: + +- Postgres (може бути Supabase local або Docker); +- NATS/JetStream локально (Docker); +- фронтенд (Next.js / React) — `localhost:3000`; +- backend/edge functions — `localhost:PORT`; +- спрощена конфігурація OAuth/Email. + +### 2.2 Dev + +Призначення: + +- інтеграція гілок; +- тестування нових фіч командою. + +Особливості: + +- часто автодеплой з `develop` / `dev` гілки; +- нестабільне середовище, допускається breaking changes; +- окремі ресурси БД, NATS, storage. + +### 2.3 Staging + +Призначення: + +- передпродакшн середовище, максимально наближене до прод; +- тестування релізів перед викоткою на prod; +- smoke-тести, регресія, перевірка міграцій. + +Особливості: + +- конфігурації максимально збігаються з prod; +- ті ж версії Postgres/NATS/Redis; +- мінімум тестових даних, максимально наближені сценарії. + +### 2.4 Prod + +Призначення: + +- бойове середовище для реальних користувачів та агентів; +- висока доступність, резервування, SLA. + +Особливості: + +- реплікація БД; +- резервні копії (snapshots + PITR); +- горизонтальне масштабування критичних сервісів; +- жорсткі політики безпеки, rate limiting, WAF. + +--- + +## 3. Core Infrastructure Components + +### 3.1 Database Layer + +- **Postgres** (Supabase / керований Postgres): + - основні таблиці: `users`, `teams`, `channels`, `messages`, `projects`, `tasks`, `agents`, `wallets`, `staking_ringk`, `payouts`, `rwa_inventory`, `embassy_*`, `access_keys`, `capabilities`, `bundles`, `audit_log`, `outbox_events`. + - схема й міграції описані в `27_database_schema_migrations.md`. + +Рекомендації: + +- один кластер на середовище (dev/staging/prod); +- не змішувати dev/staging/prod в одному кластері; +- використовувати read-replicas для prod (аналітика, довгі запити). + +### 3.2 Event Bus + +- **NATS JetStream** (або інший стейтовий event bus): + - теми (topics) з `Data Model & Event Catalog`; + - консьюмери: Wallet service, Gift Fabric, Embassies, Telemetry. + +Роль: + +- децентралізований шар подій; +- відв'язка інтерфейсу, агентів і бекенду; +- реалізація Outbox pattern (`outbox_events` → NATS). + +### 3.3 Application Layer + +- **API Gateway / Edge Functions**: + - REST/gRPC/API для frontend, агентів, інтеграцій; + - PEP (Policy Enforcement Point) для capability-check; + - валідація access keys, підписів Embassy, rate limiting. + +- **Domain Services** (можуть бути edge functions / окремі сервіси): + - Messaging Service (channels/messages/followups); + - Projects/Tasks Service; + - Agent Orchestrator (agent_runs, router); + - Wallet & Payouts; + - Embassy Service; + - Governance Service. + +### 3.4 Frontend + +- SPA/SSR (React/Next.js): + - DAARION.city UI; + - microdao messenger + agents; + - admin-консоль (telemetry, управління платформи). + +Рекомендації: + +- окремі build'и для user-facing (місто) і admin/ops; +- environment-specific base URLs. + +### 3.5 Object Storage + +- зберігання файлів/документів/зображень: + - user uploads (файли в каналах, документи); + - логи агентів (якщо великі); + - snapshot-и моделей/конфігів (якщо потрібно). + +--- + +## 4. High-level Topology + +Текстовий опис (спрощено): + +- Frontend (Web) → API Gateway +- API Gateway → Postgres / NATS / Services +- Agent Mesh ↔ API Gateway ↔ NATS +- Embassy Webhooks ↔ API Gateway ↔ NATS ↔ Services +- Observability Stack (Prometheus/Grafana/Logs) → читає метрики з усіх компонентів + +(Опційно можна додати Mermaid-діаграму у цьому файлі.) + +--- + +## 5. Deployment Workflows + +### 5.1 Local + +- `docker-compose` / Supabase local: + - `postgres`, `nats`, `minio` (опційно), `api`, `web`. +- Команди: + - `npm run dev` (web); + - `supabase db push` / `pnpm prisma migrate` / `golang-migrate up` (залежно від стеку); + - запуск background workers для Outbox → NATS. + +### 5.2 Dev + +Trigger: + +- push в `develop` / `dev` гілку. + +Кроки: + +1. CI: `lint`, `tests`, `typecheck`. +2. Build: + - web (static/SSR bundle); + - backend/edge functions (docker image або окремі функції). +3. Deploy: + - apply DB migrations; + - деплой API/edge; + - деплой web (dev URL). +4. Smoke-тести: + - healthcheck endpoints; + - простий сценарій (login → створити канал → відправити повідомлення). + +### 5.3 Staging + +Trigger: + +- merge/push у `main` з тегом `rc-*` або окрема `release/*` гілка. + +Кроки: + +1. CI повторює dev-пайплайн. +2. DB migrations: + - запуск у режимі dry-run (якщо підтримується); + - застосування на staging. +3. Deploy API, workers, web (staging domain). +4. Інтеграційні тести: + - агенти, Embassy вебхуки, payouts, RWA, governance flows. + +### 5.4 Prod + +Trigger: + +- тег `vX.Y.Z` або manual approval релізу. + +Кроки: + +1. Freeze staging (ті самі артефакти). +2. Backup prod DB (snapshot). +3. Apply migrations на prod. +4. Deploy API/edge з поетапним rollout (canary / по одному інстансу). +5. Deploy web (атомарна заміна, rollback через попередній build). +6. Post-deploy чек-лист: + - логін/чат; + - ворк агента; + - простий payout симуляційний (якщо є test mode); + - кілька Embassy викликів у test-конфігурації. + +--- + +## 6. Configuration & Environment Variables + +Приклад розділів `.env` (загальні ключі): + +### 6.1 Database + +- `DB_HOST` +- `DB_PORT` +- `DB_NAME` +- `DB_USER` +- `DB_PASSWORD` +- `DB_SSLMODE` (prod: `require`) + +### 6.2 NATS / Event Bus + +- `NATS_URL` +- `NATS_USER` +- `NATS_PASSWORD` +- `NATS_STREAM_EVENTS` (ім'я стріму для event catalog) +- `NATS_CONSUMER_WALLET` +- `NATS_CONSUMER_EMBASSY` +- `NATS_CONSUMER_GIFT_FABRIC` + +### 6.3 Auth / Security + +- `JWT_SECRET` (для capability-token, якщо локально) +- `SESSION_SECRET` +- `E2EE_PUBLIC_KEY` / `E2EE_PRIVATE_KEY` (або інший механізм) +- `RATE_LIMIT_GLOBAL` +- `RATE_LIMIT_PER_KEY` + +### 6.4 Embassy + +- `EMBASSY_WEBHOOK_SECRET_ENERGY_UNION` +- `EMBASSY_WEBHOOK_SECRET_GREENFOOD` +- `EMBASSY_WEBHOOK_SECRET_WATER_UNION` +- `EMBASSY_WEBHOOK_SECRET_ESSENCE_STREAM` + +### 6.5 Wallet / Chain + +- `CHAIN_RPC_URL` +- `CHAIN_EXPLORER_URL` +- `WALLET_SAFE_ADDRESS` (якщо multi-sig) +- `WALLET_PRIVATE_KEY` (краще в KMS, не у .env) + +--- + +## 7. Secrets Management + +- Prod/staging secrets **не зберігати** у `.env` у репозиторії. +- Використовувати: + - KMS (GCP/AWS/Azure) або + - менеджер секретів (Vault, Doppler, SSM Parameter Store тощо). +- Workers/API при старті: + - тягнуть секрети з KMS/secret manager; + - кешують лише в пам'яті (не логувати). + +Особливо чутливі: + +- ключі Embassy Webhooks; +- wallet private keys / hot signer; +- JWT/Session secrets. + +--- + +## 8. Database Migrations + +Посилання: `27_database_schema_migrations.md`. + +Правила: + +1. Міграції **ніколи** не змінюють/ламають дані під час prod розгортання без попередніх data-migrations. +2. `up`/`down` повинні бути ідемпотентними (DROP IF EXISTS / CREATE IF NOT EXISTS). +3. Порядок виконання: + - local: розробник запускає всі `000XXX_*.sql` + `seeds.sql`; + - dev/staging/prod: CI/CD застосовує міграції у правильному порядку. + +--- + +## 9. Event Bus & Outbox Pattern + +- Event producer-и (API/Services) не відправляють події напряму в NATS у критичних шляхах — спочатку пишуть у `outbox_events`. +- Background worker: + - читає `outbox_events` з `processed=false`; + - публікує у NATS відповідний topic; + - позначає `processed=true`, `processed_at=NOW()`. + +Це зменшує ймовірність втрати подій при часткових збоях. + +--- + +## 10. Monitoring & Logging + +### 10.1 Метрики + +- **API/Backend**: + - latency per endpoint; + - error rate (5xx, 4xx); + - rate limiting triggers. + +- **DB**: + - connections; + - slow queries; + - реплікація (lag). + +- **NATS/Event Bus**: + - backlog per consumer; + - delivery errors; + - redeliveries. + +- **Agents**: + - кількість запусків; + - середня тривалість run; + - помилки агента (LLM/tool errors). + +### 10.2 Логи + +- централізований збір (ELK / Loki / Cloud Logging); +- кореляційні ID: + - `X-Request-ID` на кожен HTTP-запит; + - propagation у NATS payload (trace_id / correlation_id). + +--- + +## 11. Backups & Restore + +### 11.1 Backups + +- Prod: + - щоденні повні snapshots; + - WAL / PITR (Point-In-Time Recovery) на 7–30 днів; +- Staging: + - щоденні або раз на 2–3 дні (за потреби). + +### 11.2 Restore Policy + +- тестовий restore на окремий тимчасовий кластер мінімум раз на місяць; +- документований сценарій: + - відновлення в новий кластер; + - redirect трафіку (якщо потрібно). + +--- + +## 12. Rollout Strategies + +### 12.1 API/Backend + +- **Canary**: + - невеликий відсоток трафіку на новий реліз; + - моніторинг помилок/латентності; + - поступове збільшення. + +- **Blue-Green**: + - parallel stack (blue/green); + - перемикання через load balancer/DNS. + +### 12.2 Frontend + +- атомарний switch build'ів (immutable artifacts); +- rollback = переключення на попередній build. + +### 12.3 Feature Flags + +- складні зміни (особливо агенти, Gift Fabric, RWA) — за feature flags: + - flags зберігаються в БД або у спеціальному конфіг-сервісі; + - викочуються спочатку на dev/staging, потім для частини користувачів у prod. + +--- + +## 13. CI/CD Pipeline (Reference) + +Псевдо-YAML для орієнтира: + +```yaml +name: deploy + +on: + push: + branches: [develop, main] + tags: ['v*'] + +jobs: + build-and-test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: '20' + - run: npm ci + - run: npm run lint + - run: npm test + - run: npm run build:web + - run: npm run build:api + + migrate-and-deploy: + needs: build-and-test + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Run DB migrations + run: | + ./scripts/migrate.sh up + - name: Deploy API + run: | + ./scripts/deploy_api.sh + - name: Deploy Web + run: | + ./scripts/deploy_web.sh +``` + +--- + +## 14. Завдання для Cursor + +```text +You are a senior DevOps engineer. Set up deployment infrastructure using: +- 25_deployment_infrastructure.md +- 27_database_schema_migrations.md +- 05_coding_standards.md + +Tasks: +1) Create docker-compose.yml for local development (postgres, nats, minio). +2) Create CI/CD pipeline configuration (GitHub Actions / GitLab CI). +3) Create deployment scripts (migrate.sh, deploy_api.sh, deploy_web.sh). +4) Set up environment variable templates (.env.example). +5) Create monitoring dashboard configuration (Grafana / Prometheus). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 15. Результат + +Після впровадження цієї інфраструктури: + +- чітко визначені середовища та процеси деплою; +- стандартизований CI/CD pipeline; +- готовність до масштабування та production deployment; +- моніторинг та логування для всіх компонентів; +- надійні backup/restore процеси. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/26_security_audit.md b/docs/cursor/26_security_audit.md new file mode 100644 index 00000000..bede21f7 --- /dev/null +++ b/docs/cursor/26_security_audit.md @@ -0,0 +1,452 @@ +# 26 — Security Audit Checklist (MicroDAO) + +*Безпека інфраструктури, сервісів, вебклієнта, агентів, Embassy, access keys, токенів та даних* + +Це документ для регулярного безпекового аудитування платформи **DAARION.city / microDAO / Embassy / Agent Mesh / Wallet / RWA**. + +Він структурований так, щоб аудитори, інженери, DevOps та SecOps могли пройтися checklist-пунктами і чітко виявити проблеми в: + +- Auth / Identity; +- Access Keys & Capability System; +- RBAC/Entitlements; +- Е2Е шифруванні повідомлень; +- Низькорівневій безпеці API, web, deployment; +- Embassy / Webhooks / Oracle-потоках; +- Wallet / Chain / Payouts; +- RWA flows; +- DB Security; +- Secrets Management; +- Logging/Audit/Compliance. + +Документ повністю відповідає архітектурі, яку ми вже побудували. + +--- + +## 1. Identity & Authentication + +### 1.1 Users + +- [ ] Email-based auth, OTP / Magic Link використовують одноразові токени. +- [ ] Термін дії OTP ≤ 10 хв. +- [ ] Повторне використання OTP заблоковано. +- [ ] Blocklist для підозрілих IP/UA-фінгерпринтів. +- [ ] MFA можлива (на roadmap). +- [ ] Session cookies: + - [ ] `HttpOnly` + - [ ] `Secure` + - [ ] `SameSite=Strict` для prod +- [ ] Session TTL визначений (24–72 год), auto-refresh без надмірного продовження. + +### 1.2 Agents + +- [ ] Приватні агенти НЕ використовують user-сесію. +- [ ] Кожен агент має свій **Agent Access Key** (`ak_*` з `subject_kind='agent'`). +- [ ] Немає можливості «перевтілюватися» в користувача. +- [ ] Rate limit для agent keys встановлений. + +### 1.3 Integrations / Webhooks + +- [ ] Інтеграції без JWT. Тільки API Key + HMAC. +- [ ] Embassy Webhooks: + - [ ] Secret зберігається в KMS. + - [ ] Підпис запиту перевіряється (`X-Signature`). + - [ ] Replay protection: timestamp + max time drift < 5 хв. + +--- + +## 2. Authorization Layer (RBAC + Entitlements + Capabilities) + +### 2.1 RBAC + +- [ ] Ролі існують: `Owner`, `Guardian`, `Member`, `Visitor`. +- [ ] Роль користувача залежить від `team_members.role`. +- [ ] Немає прямого доступу до таблиць без RBAC-check. + +### 2.2 Entitlements + +- [ ] `plan.Freemium`, `plan.Casual`, `plan.Premium`, `plan.Platformium`. +- [ ] Плани визначають квоти на: + - agent runs; + - router.invoke; + - message sends; + - wallet.payout.claim; +- [ ] Стейк RINGK коректно впливає на квоти (множники). + +### 2.3 Capability System + +- [ ] Access Key має capabilities через: + - [ ] bundle.role.* + - [ ] bundle.plan.* + - [ ] bundle.agent.* + - [ ] власні capabilities (`access_key_caps`) +- [ ] Формула: + + ```text + allow = RBAC ∧ Entitlement ∧ Capability ∧ ACL ∧ Mode + ``` + +- [ ] PDP працює централізовано. +- [ ] PEP на всіх API endpoints. + +--- + +## 3. Access Keys (User, Agent, Integration, Embassy) + +### 3.1 Зберігання + +- [ ] Secrets у KMS (не в базі). +- [ ] У таблиці `access_keys` зберігаються тільки metadata. +- [ ] Секрет видається один раз → не зберігається у plaintext. + +### 3.2 Політики + +- [ ] TTL для ключів (default 30–90 днів). +- [ ] Mandatory rotation. +- [ ] Revoke → негайна інвалідація. +- [ ] `status` ∈ (`active`, `revoked`, `expired`). + +### 3.3 Rate limiting + +- [ ] Okta-like limit per key. +- [ ] DDOS запобігання (global rate limit + per-key). + +--- + +## 4. Confidential Mode (E2EE-Like Messaging) + +### 4.1 На рівні каналів/команд + +- [ ] Якщо `teams.mode='confidential'`: + - [ ] сервер не бачить plaintext у `messages.body` (тільки ciphertext). + - [ ] агенти не отримують plaintext — тільки: + - embeddings; + - summary; + - обмежені метадані. + +### 4.2 Ключі шифрування + +- [ ] Зберігаються виключно на клієнті. +- [ ] Rotate при: + - зміні складу команди; + - зміні owner/guardian; + - виході учасника. + +### 4.3 E2EE Threat Model + +- [ ] Сервер не може дешифрувати повідомлення. +- [ ] Агенти працюють на «вивітрених» даних (privacy-preserving). + +--- + +## 5. API Security + +### 5.1 Input validation + +- [ ] Валідація payload (Zod/JSON schema). +- [ ] Неможливо запостити чужий team_id/channel_id/task_id. + +### 5.2 Rate limiting + +- [ ] per-IP +- [ ] per-user +- [ ] per-access-key +- [ ] per-endpoint (наприклад `/agent/run` має сильний ліміт) + +### 5.3 Common + +- [ ] CORS: origin whitelist +- [ ] TLS enforced +- [ ] Referrer policy: `strict-origin` +- [ ] Headers: + - [ ] `X-Frame-Options: DENY` + - [ ] `Content-Security-Policy` мінімум: + + ```text + default-src 'self'; + script-src 'self' 'unsafe-inline'; + connect-src 'self' https:; + img-src 'self' data: https:; + frame-ancestors 'none'; + ``` + +- [ ] Вимкнуто directory listing у CDN. + +--- + +## 6. Web Client Security + +### 6.1 Token handling + +- [ ] Немає зберігання секретів у localStorage. +- [ ] Capability-token не містить чутливих даних. +- [ ] Cookies: secure, httponly, samesite. + +### 6.2 UI-level attack surface + +- [ ] XSS захищено (React escaping). +- [ ] Посилання user-generated content: `rel="noopener noreferrer"`. + +### 6.3 Cache + +- [ ] Disable caching of sensitive pages. + +--- + +## 7. Database Security + +### 7.1 Структура + +- [ ] Всі таблиці пройдені аудитом (див. `27_database_schema_migrations.md`). +- [ ] Поля з критичними даними не мають plaintext секретів. + +### 7.2 Обмеження + +- [ ] CHECK / ENUM на: + - roles + - viewer_types + - message types + - task statuses + - wallet statuses + - access key statuses + - embassy platforms +- [ ] Foreign keys у всіх критичних зв'язках. + +### 7.3 Політика доступу + +- [ ] Web/API використовує RLS або server-side filters. +- [ ] Відсутня можливість запитів напряму «в сусідню команду». + +### 7.4 Backup & Restore + +- [ ] PITR 7–30 днів для prod. +- [ ] Snapshot перед кожним релізом. +- [ ] Процедура restore протестована. + +--- + +## 8. Secrets Management + +### 8.1 Джерело + +- [ ] Prod/Staging secrets в KMS або Vault. +- [ ] Немає `.env` у repo. +- [ ] Локальні `.env` окремо від production. + +### 8.2 Sensitive secrets + +- Embassy secrets +- Wallet signer private key +- JWT secret +- Session secret +- RWA oracle secrets + +### 8.3 Rotation + +- [ ] Rotation policy існує. +- [ ] Auto-rotate для Embassy secrets мінімум раз на 30–60 днів. + +--- + +## 9. Embassy Module & Webhooks Security + +### 9.1 Inbound Webhooks + +- [ ] Підпис перевіряється (`X-Signature`). +- [ ] Timestamp у тілі підпису. +- [ ] Maximum allowed skew < 5 хв. +- [ ] Body hashing (HMAC_SHA256). + +### 9.2 Outbound Webhooks + +- [ ] Retry з експоненційною затримкою. +- [ ] Dead-letter queue для NATS споживачів. + +### 9.3 Oracle Input + +- [ ] Oracle events проходять PDP capability-check: + - `embassy.energy.update` + - `embassy.rwa.claim` + - `embassy.intent.read` +- [ ] Oracle payload має структуру з валідацією (не приймати довільний json). + +--- + +## 10. Wallet & Chain Security + +### 10.1 Signer + +- [ ] Wallet private key у KMS. +- [ ] Операції підпису — через офіційну KMS-операцію (не на сервері). +- [ ] Multi-sig або 4-eyes approval для критичних транзакцій. + +### 10.2 Payouts + +- [ ] `payout.generated` приходить лише з wallet service. +- [ ] claim → tx → підтвердження → оновлення БД. +- [ ] Rate limit на claim. + +### 10.3 Chain RPC + +- [ ] Використовувати приватні RPC endpoint-и. +- [ ] Логи RPC запитів не містять приватних ключів. + +--- + +## 11. RWA Security + +### 11.1 Data-level + +- [ ] RWA inventory має типи: + - `energy`, `food`, `water`, `essence`, `generic`. +- [ ] Кожен update — подія `rwa.inventory.updated`. + +### 11.2 Embassy-guarded actions + +- [ ] тільки Embassy Keys з capability: + - `rwa.inventory.update` + - `embassy.rwa.claim` + - `embassy.energy.update` + +--- + +## 12. Logging & Audit Trail + +### 12.1 Audit Log + +- [ ] Всі критичні дії пишуть у `audit_log`: + - access key created/revoked, + - agent run invoked, + - payout claimed, + - governance actions, + - embassy updates. + +### 12.2 Log integrity + +- [ ] Логи доступні тільки admin/ops. +- [ ] Немає plaintext секретів. + +### 12.3 SIEM інтеграція + +- [ ] Підтримується forwarding у ELK / Loki / Cloud Logging. + +--- + +## 13. Monitoring & Alerting + +### 13.1 Метрики + +- API latency, error rate +- DB connections, slow queries +- NATS lag +- Agent run failures +- Embassy webhook failures +- Wallet TX errors + +### 13.2 Алерти + +- [ ] high latency +- [ ] high error rate (>2%) +- [ ] failed db migration +- [ ] stuck outbox events +- [ ] agent-run failure rate > заданого порогу +- [ ] "Embassy webhook signature mismatch" + +--- + +## 14. Incident Response + +### 14.1 Playbooks + +- [ ] DB corruption +- [ ] Chain stuck / RPC unreachable +- [ ] Embassy compromised key +- [ ] Access key leak +- [ ] Agent runaway (infinite loop / high cost) +- [ ] DDOS attack +- [ ] RWA incorrect oracle input + +### 14.2 Communication + +- [ ] Responsible security officer визначено. +- [ ] Питання ескалації прописані. + +--- + +## 15. Compliance + +### 15.1 Privacy + +- [ ] PII зберігається encrypted-at-rest. +- [ ] Резидентські дані обмежені на команди. +- [ ] E2EE для confidential-каналів гарантує приватність. + +### 15.2 Data retention + +- [ ] Логи зберігаються до 30–90 днів. +- [ ] Outbox events → 7 днів. + +### 15.3 Legal + +- [ ] Webhooks & Embassy: мінімізація PII. +- [ ] Wallet: відповідність нормам локальних регуляцій. + +--- + +## 16. Summary: Security Audit Status Table + +| Категорія | Статус | Проблеми | Пріоритет | +| ------------- | ------------------ | -------- | --------- | +| Identity/Auth | PASS / WARN / FAIL | … | High | +| Access Keys | PASS / WARN / FAIL | … | High | +| RBAC | PASS | … | Medium | +| Capabilities | PASS | … | High | +| E2EE | … | … | High | +| Embassy | … | … | High | +| Wallet | … | … | Critical | +| RWA | … | … | High | +| DB | … | … | High | +| Secrets | … | … | Critical | +| Logs | … | … | Medium | + +--- + +## 17. Завдання для Cursor + +```text +You are a senior security engineer. Implement security measures based on: +- 26_security_audit.md +- 24_access_keys_capabilities_system.md +- 25_deployment_infrastructure.md +- 12_agent_runtime_core.md + +Tasks: +1) Implement rate limiting middleware for API endpoints. +2) Add input validation (Zod schemas) for all API endpoints. +3) Implement security headers middleware (CSP, X-Frame-Options, etc.). +4) Add audit logging for critical actions (access keys, payouts, governance). +5) Implement secrets rotation policy. +6) Add security monitoring alerts. + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 18. Результат + +Після проходження цього чеклисту: + +- виявлені всі критичні вразливості безпеки; +- впроваджені best practices для всіх компонентів системи; +- готовність до production deployment з точки зору безпеки; +- чітка політика incident response та compliance. + +--- + +**Версія:** 1.0 (для MVP → RC → PROD) +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/27_database_schema_migrations.md b/docs/cursor/27_database_schema_migrations.md new file mode 100644 index 00000000..ef585af8 --- /dev/null +++ b/docs/cursor/27_database_schema_migrations.md @@ -0,0 +1,496 @@ +# 27 — Database Schema & Migrations (MicroDAO) + +*Повна виробнича специфікація* + +--- + +## 1. Purpose & Scope + +Цей документ описує: + +- повну схему бази даних microDAO / DAARION.city (всі таблиці); +- модулі: Messaging, Teams, RBAC, Projects, Docs/Co-Memory, Agents, Wallet, Staking, Payouts, Embassy, Capability System, RWA; +- порядок міграцій; +- правила naming-конвенцій; +- seed-дані для initial bootstrap; +- інтеграцію з Event Catalog; +- DevOps pipeline для застосування міграцій (local → staging → prod); +- rollback policy. + +Документ є «джерелом істини» для інженерів. + +--- + +## 2. High-level Structure of the Database + +### Домени: + +1. Auth / Users +2. Teams (microDAO ядра) +3. RBAC & Roles +4. Channels / Messages / Follow-ups / Co-Memory +5. Projects / Tasks +6. Agents / Agent Runs / Tooling +7. Wallet / Staking / Payouts +8. RWA (Real-World Assets) +9. Embassy Module (Webhooks, External Identity, Oracles) +10. Capability System (Access Keys, Bundles) +11. Audit & Telemetry +12. Event Catalog Support (Outbox pattern) + +--- + +## 3. Naming Conventions + +### Префікси ID: + +- `u_` — user +- `t_` — team +- `c_` — channel +- `m_` — message +- `f_` — followup +- `doc_` — document +- `p_` — project +- `task_` — task +- `ag_` — agent +- `run_` — agent run +- `ak_` — access key +- `cap_` — capability +- `bundle_` — capability bundle +- `rwa_` — RWA certificate +- `emb_` — embassy identity +- `hook_` — webhook +- `evt_` — outbox event + +### Таблиці у snake_case + +### Версії міграцій: + +`000001_init.sql`, `000002_users_teams.sql`, `000003_rbac.sql` … + +--- + +## 4. Full Schema by Modules + +Нижче — структурована схема по розділах. + +Це основа для міграцій (варіант C). + +--- + +### 4.1 Users & Auth + +```sql +create table users ( + id text primary key, -- u_... + email text unique not null, + created_at timestamptz default now(), + last_login_at timestamptz +); + +create table sessions ( + session_id text primary key, + user_id text references users(id) on delete cascade, + created_at timestamptz default now(), + expires_at timestamptz +); +``` + +--- + +### 4.2 Teams / microDAO + +```sql +create table teams ( + id text primary key, -- t_... + name text not null, + slug text unique not null, + mode text not null check (mode in ('public','confidential')), + created_at timestamptz default now() +); + +create table team_members ( + team_id text references teams(id) on delete cascade, + user_id text references users(id) on delete cascade, + role text not null, -- Owner | Guardian | Member + viewer_type text not null, -- reader | commenter | contributor + primary key (team_id, user_id) +); +``` + +--- + +### 4.3 Channels / Messages / Follow-ups / Co-Memory + +```sql +create table channels ( + id text primary key, -- c_... + team_id text references teams(id), + name text not null, + created_at timestamptz default now() +); + +create table messages ( + id text primary key, -- m_... + channel_id text references channels(id), + user_id text references users(id), + body text, -- plaintext or encrypted + created_at timestamptz default now(), + metadata jsonb +); + +create table followups ( + id text primary key, -- f_... + message_id text references messages(id) on delete cascade, + type text, -- agent/tool/summary... + payload jsonb, + created_at timestamptz default now() +); + +create table comemory_items ( + id text primary key, + team_id text references teams(id), + embeddings vector(1536), + summary text, + source_message text, + created_at timestamptz default now() +); +``` + +--- + +### 4.4 Projects / Tasks + +```sql +create table projects ( + id text primary key, -- p_... + team_id text references teams(id), + name text not null, + created_at timestamptz default now() +); + +create table tasks ( + id text primary key, -- task_... + project_id text references projects(id), + title text not null, + status text not null, + assignee text references users(id), + created_at timestamptz default now() +); +``` + +--- + +### 4.5 Agents / Tooling + +```sql +create table agents ( + id text primary key, -- ag_... + team_id text references teams(id), + name text, + config jsonb, + created_at timestamptz default now() +); + +create table agent_runs ( + id text primary key, -- run_... + agent_id text references agents(id), + input jsonb, + output jsonb, + created_at timestamptz default now(), + status text +); +``` + +--- + +### 4.6 Wallet / Staking / Payouts + +```sql +create table wallets ( + user_id text primary key references users(id), + address text unique +); + +create table staking_ringk ( + id text primary key, + user_id text references users(id), + amount numeric not null, + lock_until timestamptz, + created_at timestamptz default now() +); + +create table payouts ( + id text primary key, + user_id text references users(id), + amount numeric, + symbol text, -- KWT, 1T, DAAR… + created_at timestamptz default now() +); +``` + +--- + +### 4.7 RWA (Real-World Assets) + +```sql +create table rwa_inventory ( + id text primary key, -- rwa_... + team_id text references teams(id), + type text, -- energy/food/water/etc + quantity numeric, + metadata jsonb, + updated_at timestamptz default now() +); +``` + +--- + +### 4.8 Embassy Module + +```sql +create table embassy_identities ( + id text primary key, -- emb_... + external_id text, + platform text, -- energy_union/greenfood/etc + metadata jsonb +); + +create table embassy_webhooks ( + id text primary key, -- hook_... + platform text, + secret text, + url text, + created_at timestamptz default now() +); + +create table oracles ( + id text primary key, + platform text, + payload jsonb, + created_at timestamptz default now() +); +``` + +--- + +### 4.9 Capability System (Access Keys / Bundles) + +```sql +create table access_keys ( + id text primary key, -- ak_... + subject_kind text not null, -- user/agent/integration/embassy + subject_id text not null, + team_id text, + name text not null, + status text not null check (status in ('active','revoked','expired')), + created_at timestamptz default now(), + expires_at timestamptz, + last_used_at timestamptz +); + +create table capabilities ( + id text primary key, -- cap_... + code text not null unique, + description text not null +); + +create table access_key_caps ( + key_id text references access_keys(id) on delete cascade, + cap_id text references capabilities(id) on delete cascade, + primary key (key_id, cap_id) +); + +create table bundles ( + id text primary key, -- bundle_... + name text not null unique, + created_at timestamptz default now() +); + +create table bundle_caps ( + bundle_id text references bundles(id) on delete cascade, + cap_id text references capabilities(id) on delete cascade, + primary key (bundle_id, cap_id) +); +``` + +--- + +### 4.10 Audit & Telemetry + +```sql +create table audit_log ( + id text primary key, + user_id text, + team_id text, + action text, + resource_kind text, + data jsonb, + created_at timestamptz default now() +); +``` + +--- + +### 4.11 Outbox Events (Event Catalog) + +```sql +create table outbox_events ( + id text primary key, -- evt_... + topic text not null, + payload jsonb not null, + created_at timestamptz default now(), + processed boolean default false +); +``` + +--- + +## 5. Migration Order (Critical) + +### 000001_init.sql + +Users, Sessions. + +### 000002_microdao_core.sql + +Teams, Members, Channels, Messages, Follow-ups. + +### 000003_projects_tasks.sql + +Projects, Tasks. + +### 000004_agents.sql + +Agents, Agent Runs. + +### 000005_wallet_staking_payouts.sql + +Wallet, Staking, Payouts. + +### 000006_rwa.sql + +RWA Inventory. + +### 000007_embassy.sql + +Embassy identities, Webhooks, Oracles. + +### 000008_access_keys_capabilities.sql + +Access Keys, Capabilities, Bundles. + +### 000009_audit_outbox.sql + +Audit Log + Outbox Events. + +--- + +## 6. Seed Data + +### RBAC Roles + +- Owner, Guardian, Member, Visitor. + +### Capability bundles + +- `bundle.role.Owner` +- `bundle.role.Guardian` +- `bundle.role.Member` +- `bundle.role.Visitor` +- `bundle.plan.Freemium` / `Casual` / `Premium` / `Platformium` + +### Initial capabilities + +- `chat.message.send` +- `chat.message.read` +- `wallet.balance.view` +- `wallet.stake.ringk` +- `router.invoke` +- `agent.run.invoke` +- `rwa.inventory.update` +- `embassy.rwa.claim` + +--- + +## 7. Integration with Event Catalog + +Всі важливі сутності пишуть події в `outbox_events`. + +Основні topics: + +- `chat.message.created` +- `project.created` +- `task.created` +- `agent.run.completed` +- `staking.locked` +- `payout.generated` +- `rwa.inventory.updated` +- `access_key.created` +- `access_key.revoked` +- `audit.event` + +--- + +## 8. Local / Staging / Prod Migration Process + +1. `supabase db reset` (local only) +2. `supabase db push` → локальні міграції +3. CI запускає `pg_prove` або `pgtap` (опційно) +4. Staging застосовує ті ж міграції +5. Prod застосовує з confirm gate + +--- + +## 9. Rollback Policy + +- Кожна міграція має `-- down` секцію з DROP TABLE IF EXISTS. +- Для критичних таблиць rollback дозволено тільки до staging, на prod — лише forward-fix. +- Outbox events не відкочуються. +- RWA-поведінка не rollback'иться ніколи. + +--- + +## 10. Завдання для Cursor + +```text +You are a senior backend engineer. Generate SQL migration files based on: +- 27_database_schema_migrations.md +- 24_access_keys_capabilities_system.md +- 02_architecture_basics.md +- 05_coding_standards.md + +Tasks: +1) Create migration files in order: 000001_init.sql through 000009_audit_outbox.sql +2) Each migration should include: + - CREATE TABLE statements + - Indexes for foreign keys and frequently queried columns + - Constraints (CHECK, UNIQUE, FOREIGN KEY) + - Comments for each table/column +3) Create seed data SQL file for initial capabilities and bundles +4) Add rollback (-- down) sections for each migration + +Output: +- list of migration files +- diff +- summary +``` + +--- + +## 11. Результат + +Після створення цього документа: + +- повна схема БД задокументована як «джерело істини»; +- чіткий порядок міграцій для послідовного застосування; +- готовність до генерації реальних SQL-файлів (варіант C); +- інтеграція з Event Catalog через Outbox pattern; +- чітка політика rollback для безпеки. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/28_flows_wallet_embassy_energy_union.md b/docs/cursor/28_flows_wallet_embassy_energy_union.md new file mode 100644 index 00000000..7199076d --- /dev/null +++ b/docs/cursor/28_flows_wallet_embassy_energy_union.md @@ -0,0 +1,356 @@ +# 28 — Flows: Wallet, Embassy, Energy Union (MicroDAO) + +*Sequence-діаграми основних критичних потоків: авторизація, Wallet, Embassy, Energy Union, NATS Outbox* + +Це документ візуалізацій — «центральна нервова система» проєкту. + +Він показує, як працює процес: + +- login → capability → action, +- stake RINGK → payouts, +- embassy → nats → services, +- oracle updates → RWA → wallet, +- agent runs → PDP. + +Усі діаграми подані в **Mermaid**, GitHub рендерить їх автоматично. + +--- + +## 1. Purpose + +Цей документ описує **динамічні потоки** (sequence diagrams) між сервісами: + +- frontend (web), +- API Gateway (PEP), +- PDP (Policy Decision Point), +- Postgres (DB), +- NATS JetStream (event bus), +- Wallet Service, +- Embassy Service, +- Energy Union, +- Agent Mesh. + +Ці діаграми є частиною безпекового аудиту, дебагу, тестування, QA та документації для інтеграцій. + +--- + +## 2. Legend + +``` +U – User (browser/app) +A – Agent (private agent) +API – API Gateway (PEP) +PDP – Policy Service (capability checks) +DB – Postgres (core data) +WAL – Wallet Service +NATS – JetStream Event Bus +EMB – Embassy Gateway +EU – Energy Union backend +RUN – Agent Runtime +``` + +--- + +## 3. Login → Capability Token → Action + +```mermaid +sequenceDiagram + participant U as User (Web) + participant API + participant PDP + participant DB + + U->>API: POST /login (email+otp) + API->>DB: validate OTP + DB-->>API: OK + API->>DB: fetch team_members, role, plan, entitlements + DB-->>API: role=Member, plan=Premium, stake=100 RINGK + + API->>API: build capability-token (bundles role+plan) + API-->>U: session cookie + cap-token + + U->>API: GET /projects + API->>PDP: authorize(user, action=project.read) + PDP->>DB: lookup bundles+caps + DB-->>PDP: caps_allow + PDP-->>API: allow + API->>DB: SELECT * FROM projects + DB-->>API: result + API-->>U: JSON +``` + +--- + +## 4. Agent Run (Router → PDP → DB → RUN → NATS) + +```mermaid +sequenceDiagram + participant U as User + participant API + participant PDP + participant DB + participant RUN as Agent Runtime + participant NATS + + U->>API: POST /agent/run {prompt} + API->>PDP: authorize(user, action=agent.run.invoke) + PDP-->>API: allow + + API->>DB: INSERT INTO agent_runs (pending) + DB-->>API: OK + + API->>RUN: start(agent_id, input) + RUN-->>API: ack (accepted) + + RUN->>NATS: publish agent.run.started + U->>API: GET /agent/run/status + API->>DB: SELECT status=running + + RUN->>RUN: LLM inference / tools / reasoning + RUN->>DB: UPDATE agent_runs (output, status=completed) + RUN->>NATS: publish agent.run.completed + + API-->>U: result +``` + +--- + +## 5. Stake RINGK → Payout Flow + +Це один із ключових потоків у DAARION (економічна модель). + +```mermaid +sequenceDiagram + participant U as User + participant API + participant PDP + participant DB + participant WAL as Wallet Service + participant NATS + + U->>API: POST /wallet/stake {amount} + API->>PDP: authorize(user, action=wallet.stake.ringk) + PDP-->>API: allow + + API->>DB: INSERT INTO staking_ringk (locked) + DB-->>API: OK + + API->>WAL: notify stake_request(user, amount) + WAL->>NATS: publish staking.locked + + WAL->>WAL: compute payouts for period + WAL->>NATS: publish payout.generated {user, amount, symbol="KWT"} + + U->>API: GET /wallet/payouts + API->>DB: SELECT * FROM payouts + API-->>U: pending payout +``` + +--- + +## 6. Embassy Webhook → PDP → RWA Inventory → Wallet/NATS + +```mermaid +sequenceDiagram + participant EXT as External Platform (EnergyUnion/GreenFood/etc) + participant EMB + participant API + participant PDP + participant DB + participant NATS + participant WAL as Wallet Service + + EXT->>EMB: POST /embassy/energy {kWh} + HMAC Signature + EMB->>API: forward request + + API->>PDP: authorize(embassy_key, action=embassy.energy.update) + PDP-->>API: allow + + API->>DB: UPDATE rwa_inventory (type=energy) + DB-->>API: OK + + API->>NATS: publish rwa.inventory.updated + + NATS->>WAL: process inventory → compute payouts? + WAL->>NATS: publish payout.generated (1T/KWT) + + API-->>EMB: 200 OK +``` + +--- + +## 7. Energy Union → Embassy Oracle → NATS → Wallet + +```mermaid +sequenceDiagram + participant M as Meter Device + participant EU as Energy Union + participant EMB + participant API + participant PDP + participant DB + participant NATS + participant WAL + + M->>EU: send meter data + EU->>EMB: POST /embassy/oracle {site, kWh, ts} + + EMB->>API: request + API->>PDP: authorize(emb_key, action=embassy.energy.update) + PDP-->>API: allow + + API->>DB: INSERT INTO oracles (payload) + DB-->>API: OK + + API->>NATS: publish oracle.reading.published + + NATS->>WAL: recalc payouts (KWT/1T) + WAL->>DB: INSERT INTO payouts + WAL->>NATS: publish payout.generated +``` + +--- + +## 8. Wallet Claim Flow (User Claims Payout) + +```mermaid +sequenceDiagram + participant U as User + participant API + participant PDP + participant DB + participant WAL as Wallet Service + participant CHAIN as Blockchain + + U->>API: POST /wallet/claim {payout_id} + API->>PDP: authorize(user, action=wallet.payout.claim) + PDP-->>API: allow + + API->>DB: SELECT payout (pending) + DB-->>API: OK + + API->>WAL: execute claim + WAL->>CHAIN: submit tx + CHAIN->>WAL: tx confirmed + + WAL->>DB: UPDATE payouts (claimed) + API-->>U: success + tx_hash +``` + +--- + +## 9. Outbox → NATS Delivery (Guarantee: At-Least-Once) + +```mermaid +sequenceDiagram + participant DB + participant WORK as Outbox Worker + participant NATS + + DB->>WORK: SELECT events WHERE processed=false LIMIT 100 + WORK->>NATS: publish event + NATS-->>WORK: ack + WORK->>DB: UPDATE outbox_events SET processed=true +``` + +--- + +## 10. Governance Flow (Proposal → Vote → Policy Update) + +```mermaid +sequenceDiagram + participant U as User (Guardian/Owner) + participant API + participant PDP + participant DB + participant GOV as Governance Agent + participant NATS + + U->>API: POST /gov/proposal {change_policy} + API->>PDP: authorize(user, action=governance.proposal.create) + PDP-->>API: allow + + API->>DB: INSERT proposal + DB-->>API: OK + + API->>NATS: publish governance.proposal.created + + U->>API: POST /gov/vote + API->>PDP: authorize(user, action=governance.vote.cast) + PDP-->>API: allow + + API->>DB: UPDATE proposal votes + DB-->>API: OK + + GOV->>DB: finalize, update capability bundles + GOV->>NATS: publish governance.policy.updated +``` + +--- + +## 11. Threat Model Integration Points + +| Flow | Threat | Mitigation | +| --------------------- | -------------------------- | ------------------------------------------------- | +| Embassy webhook → API | Fake source, replay attack | HMAC + timestamp + PDP-check | +| Wallet claim | Double-spend | DB row-level lock + chain receipt | +| Agent run | Prompt injection | Input sanitization + safe tools | +| Confidential channels | E2EE bypass | No plaintext server-side, agent gets summary only | +| NATS events | Lost events | Outbox pattern | +| RWA updates | Poisoned oracle | PDP + oracle signature + anomaly detection | +| Payout generation | Fake energy data | embassy_key capabilities + oracle signatures | + +--- + +## 12. Summary + +Документ покриває основні системні флоу, які визначають: + +- безпеку, +- економіку, +- консистентність, +- надійність, +- інтеграцію з RWA, +- роботу агентів. + +Діаграми можуть бути імпортовані у Confluence/Notion/Docs автоматично. + +--- + +## 13. Завдання для Cursor + +```text +You are a senior backend engineer. Implement the flows described in: +- 28_flows_wallet_embassy_energy_union.md +- 24_access_keys_capabilities_system.md +- 12_agent_runtime_core.md + +Tasks: +1) Implement PDP (Policy Decision Point) service. +2) Implement PEP (Policy Enforcement Point) middleware for API Gateway. +3) Implement Outbox Worker for NATS event delivery. +4) Implement Wallet Service with stake/payout flows. +5) Implement Embassy Gateway with webhook signature verification. +6) Add sequence diagram validation tests. + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 14. Результат + +Після впровадження цих потоків: + +- чітко визначені всі критичні системні інтеграції; +- готовність до тестування end-to-end сценаріїв; +- документація для QA та інтеграційних тестів; +- основа для моніторингу та дебагу production issues. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 diff --git a/docs/cursor/29_scaling_and_high_availability.md b/docs/cursor/29_scaling_and_high_availability.md new file mode 100644 index 00000000..31efbdcc --- /dev/null +++ b/docs/cursor/29_scaling_and_high_availability.md @@ -0,0 +1,444 @@ +# 29 — Scaling & High Availability (MicroDAO) + +*Масштабування, відмовостійкість, балансування навантаження, кластеризація сервісів DAARION.city / microDAO / Embassy / Wallet / Agents / Event Bus* + +Це документ виробничого класу, який потрібний для: + +- архітекторів, +- SRE, +- DevOps, +- інженерів, що відповідають за HA (High Availability), +- аудиторів, які перевіряють стійкість платформи. + +Він відповідає на питання: + +- як масштабуються сервіси; +- як забезпечується відмовостійкість; +- як працюють кластери (Postgres, NATS, агентна мережа); +- як працює автоматичне масштабування; +- як відбувається failover; +- як відновлюється місто після аварій. + +--- + +## 1. Objectives + +Платформа DAARION.city має підтримувати: + +1. **Високу доступність (HA)** + SLA: 99.5%–99.9% залежно від сервісу. + +2. **Горизонтальне масштабування** + Чат, агенти, Embassy події, обробка RWA, NATS — мають масштабуватись окремо. + +3. **Event-driven архітектуру** + Потоки через NATS/JetStream. + +4. **Автоматичне відновлення після збоїв (self-healing)**. + +5. **Zero-downtime деплой**. + +--- + +## 2. High-level Architecture Overview + +``` + ┌─────────────────────────┐ + │ Load Balancer │ + └──────────┬──────────────┘ + │ + ┌─────────────┴──────────────┐ + │ API Gateway (PEP) │ + └─────────────┬──────────────┘ + │ + ┌──────────────┬────────────┬──────────────┐ + │ │ │ │ + Messaging Agents Embassy Wallet/RWA + Service Runtime Gateway Service + (stateless) (scalable) (stateless) (state + events) + + ┌────────────────┐ + │ NATS Cluster │ + └────────────────┘ + │ + ┌───────────────────┐ + │ Postgres HA │ + └───────────────────┘ +``` + +Основний принцип — **кожен домен масштабується автономно**. + +--- + +## 3. API Layer Scaling + +### 3.1 API Gateway / Edge Functions + +- Stateless +- Горизонтальне масштабування без обмежень +- Auto-scaling подіями: + - RPS, + - latency, + - CPU, + - queue length + +### 3.2 Failover + +- Health-check endpoints +- LB прибирає unhealthy інстанси +- Blue-Green або Canary rollout + +--- + +## 4. Backend Domain Services Scaling + +Статус сервісів DAARION: + +| Service | State | Scale Mode | +| ------------------ | ------------- | ---------------------------------------------- | +| Messaging | Stateless | Horizontal | +| Projects/Tasks | Stateless | Horizontal | +| Agent Orchestrator | Stateful (DB) | Horizontal (idempotent processing) | +| Wallet | Stateful | Horizontal (through DB locking, NATS ordering) | +| Embassy | Stateless | Horizontal | +| Telemetry | Stateless | Horizontal | + +### 4.1 Stateless Services + +- Messaging +- Channels +- Projects +- Embassy Gateway +- Telemetry +- Governance API + +Масштабуються **лінійно** кількістю інстансів. + +### 4.2 Stateful Services + +#### 🔹 Wallet Service + +Потребує: + +- row-level locks для `payout.claim` +- idempotent `payout.generated` +- deduplicated NATS consumer + +#### 🔹 Agent Orchestrator + +Потребує: + +- «at least once» NATS delivery +- run-idempotency (`agent_runs.id`) +- partitioning agent runs + +--- + +## 5. Agents Scaling + +### 5.1 Типи агентів + +1. **Private agents (per-user/team)** +2. **Global agents (Router / Planner / Observer)** +3. **Embassy agents (interpreters for RWA)** + +### 5.2 Як вони масштабуються + +```text +User → API → enqueue → Agent Runtime Pool +``` + +Agent Runtime Pool: + +- десятки/сотні ізольованих воркерів; +- один агент run не блокує інші; +- автоматичний autoscaling від: + - queue depth, + - throughput, + - LLM latency. + +### 5.3 Isolation Model + +Для кожного агентного run: + +- окремий підпроцес / worker / container +- можливість sandbox-обмеження + +--- + +## 6. NATS JetStream Scaling & HA + +### 6.1 Кластер + +Рекомендована конфігурація для прод: + +- **3 або 5 вузлів** JetStream +- Replication Factor = 3 для стрімів +- Consumer durability = `durable=true` +- Ack policy = explicit + +### 6.2 Потоки (streams) + +Структура тем: + +``` +chat.* +project.* +task.* +agent.run.* +wallet.* +embassy.* +oracle.* +rwa.* +governance.* +audit.* +``` + +### 6.3 Failure Scenarios + +| Failure | Наслідок | Відновлення | +| ---------------------- | ------------------- | ---------------------------------- | +| 1 вузол падає | Кворум зберігається | Автоматичний failover | +| 2 вузли падають (із 3) | Стрім read-only | Зберегти дані, обмеження на writes | +| Корупція стріму | Канарний споживач | Auto-resync | + +--- + +## 7. Postgres High Availability + +### 7.1 Архітектура + +- Primary + at least 1–2 replicas +- Synchronous replication (якщо SLA 99.9) +- Архівування WAL (PITR) +- Автоматичний failover (pg_auto_failover або cloud-managed) + +### 7.2 Таблиці з високими вимогами до консистентності + +- `wallets` +- `staking_ringk` +- `payouts` +- `rwa_inventory` +- `access_keys` +- `bundles` +- `outbox_events` + +Ці таблиці не допускають eventual consistency. + +### 7.3 Query Optimization + +- Index coverage for all hot-path queries +- Partitioning (опційно) для: + - `messages` + - `audit_log` + - `outbox_events` + +--- + +## 8. Outbox Pattern Scaling + +### 8.1 Worker Pool + +- 2–10 воркерів +- Кожен бере порцію подій +- Події після обробки маркуються `processed=true` + +### 8.2 Guarantees + +- At least once +- Ordering controlled by: + - Partition key (team_id) + - Consumer group + +### 8.3 Failure Mode + +- Pod kill → worker restarts → resumes work +- network flap → events re-delivered +- consumer crash → DLQ (dead letter queue) + +--- + +## 9. Embassy Scaling + +### 9.1 Incoming Webhooks + +- Stateless API +- Unlimited horizontal scaling +- Signature verification CPU-cheap + +### 9.2 Oracle bursts + +Embassy може отримати "бурст" даних з Energy Union: + +- 10k–100k meter readings +- обробляється пакетно +- Embassy → NATS → Wallet Service + +Wallet Service **має бути autoscaled**: + +- CPU > 70% +- NATS consumer lag > threshold + +--- + +## 10. Wallet Scaling & RWA + +### 10.1 Ключові вимоги + +Wallet Service обробляє: + +- payouts, +- claims, +- chain transactions, +- RWA reward distribution. + +Системні вимоги: + +- row-level lock на `payouts` при claim +- mutex на chain transaction +- idempotent TX submission + +### 10.2 Autoscaling Logic + +- ↑ CPU (chain operations heavy) +- ↑ NATS lag (payouts generated faster than processed) +- ↑ pending claim queue + +--- + +## 11. Scaling Frontend + +### 11.1 Static hosting + +- CDN кешування +- SSR вимикається для важких сторінок (агентів, wallets) + +### 11.2 Global edge distribution + +- географічні PoP +- розподіл: + - US-EAST + - EU + - South America + - Asia + +### 11.3 Feature Flag Rollout + +- мінімізація ризику на проді +- partial enablement + +--- + +## 12. Failover Strategies + +### 12.1 API Layer + +- LB → автоматична заміна unhealthy nodes +- Canary release на 5–10% + +### 12.2 Postgres + +- автоматичний failover на replica +- DNS/IP switch + +### 12.3 NATS + +- внутрішня виборність leader +- replica quorum + +### 12.4 Agents + +- job requeue → new worker takes over + +### 12.5 Embassy + +- stateless → fail instantly + +### 12.6 Wallet + +- idempotent DB writes → rescue after crash + +--- + +## 13. Disaster Recovery (DR) + +### 13.1 Scenarios + +1. Data center outage +2. Corrupted WAL / snapshot +3. Global cloud outage (provider-wide) +4. Stuck NATS cluster +5. Chain RPC outage +6. Embassy key leak +7. Agent DDOS / infinite loops + +### 13.2 Recovery Plan + +- Hot standby region (multi-region Postgres) +- Backup event bus +- Secondary RPC provider +- Embassy secrets rotation +- Agent Sandbox re-creation + +### 13.3 DR Tests + +- щоквартальні DR-ротації +- restore Postgres snapshot +- swap RPC endpoints +- revoke all Embassy keys + +--- + +## 14. Benchmark Targets + +| Компонент | Ціль | +| --------------- | ---------------------- | +| Messages | 500 msg/sec | +| Agent runs | 30–100 runs/min/worker | +| Embassy | 1000 webhook/sec | +| Wallet payouts | 50 payout/sec | +| NATS throughput | 20k–50k events/sec | +| Postgres | p95 < 100 ms | + +--- + +## 15. Завдання для Cursor + +```text +You are a senior DevOps/SRE engineer. Implement HA infrastructure using: +- 29_scaling_and_high_availability.md +- 25_deployment_infrastructure.md +- 26_security_audit.md + +Tasks: +1) Set up Postgres HA with automatic failover. +2) Configure NATS JetStream cluster (3-5 nodes). +3) Implement autoscaling for API Gateway and domain services. +4) Set up health checks and monitoring for all services. +5) Implement Outbox Worker pool with proper scaling. +6) Configure load balancer with health checks. +7) Set up disaster recovery procedures. + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 16. Summary + +- Архітектура підтримує HA та autoscaling на кожному шарі. +- Сервіси ізольовані за доменами. +- NATS та Postgres у кластерному режимі. +- Wallet / RWA / Embassy — найбільш критичні частини. +- Масштабування агентів окреме, з autoscaling та sandbox isolation. +- Готова база для prod-grade розгортання. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/30_cost_optimization_and_token_economics_infrastructure.md b/docs/cursor/30_cost_optimization_and_token_economics_infrastructure.md new file mode 100644 index 00000000..ece499b2 --- /dev/null +++ b/docs/cursor/30_cost_optimization_and_token_economics_infrastructure.md @@ -0,0 +1,401 @@ +# 30 — Cost Optimization & Token Economics Infrastructure (MicroDAO) + +*Оптимізація витрат інфраструктури та зв'язок з токеномікою (RINGK, 1T, KWT, DAAR/DAARION)* + +--- + +## 1. Purpose & Scope + +Цей документ описує, як: + +- технічні витрати (LLM, інфраструктура, зберігання, мережа, моніторинг) пов'язані з: + - токенами **RINGK** (стейк / ліміти), + - **1T** (обчислювальні потоки), + - **KWT** (енергетичні потоки), + - **DAAR/DAARION** (глобальна міська економіка); +- вводити технічні ліміти, щоби: + - платформа залишалась економічно стійкою; + - не було «безкоштовного» спалювання бюджету; + - користувачі бачили прозорі сигнали вартості. + +Ціль: зробити так, щоб архітектура не лише масштабувалась (див. `29_scaling_and_high_availability.md`), а й **не розвалювала економіку**. + +--- + +## 2. Основні центри витрат + +### 2.1 LLM / AI / Agents + +- Виклики великих моделей (hosted / власні). +- Токени контексту (input/output). +- Паралельні агенти, багатоінструментальні ланцюги. +- Фонові агенти (спостерігачі/аналітики). + +### 2.2 Compute & Networking + +- API/Backend CPU/RAM. +- Agent Runtime pool. +- Embassy Gateway (спайки вебхуків). +- Wallet Service / chain RPC. + +### 2.3 Storage + +- Postgres (об'єм + IOPS). +- Object storage (файли, логи агентів, документи). +- Long-term logs / audit. + +### 2.4 Observability + +- Метрики (Prometheus, Cloud Monitoring). +- Логи (ELK/Loki/Cloud). +- Traces (якщо є). + +--- + +## 3. Принципи оптимізації + +1. **Немає «нескінченного безкоштовного» LLM** + Кожен агентний виклик → лічильник → квота → кореляція з токенами/планами. + +2. **Бюджети на рівні:** + - користувача, + - команди (microDAO), + - платформи (GreenFood, Energy Union). + +3. **Економічні сигнали в UI** + Користувач бачить: + - «Скільки обчислювального бюджету залишилось»; + - «Які дії дорогі». + +4. **Soft- та hard-limits** + - Soft-limits → попередження/тротлінг. + - Hard-limits → зупинка / пропозиція оновити план / збільшити стейк. + +--- + +## 4. Зв'язок токенів з технічною економікою + +### 4.1 RINGK (стейк / права / ліміти) + +RINGK — базовий стейковий токен, який: + +- визначає **довгострокову участь**; +- впливає на: + - quota мультиплікатори (LLM, storage, bandwidth); + - пріоритет обробки; + - доступ до Platformium-рівня. + +Формула (концептуально): + +```text +effective_quota = base_quota(plan) × f(RINGK_staked) +``` + +Де `f(RINGK_staked)` — piecewise-функція (step / log): + +- 0 RINGK → 1.0× +- X RINGK → 1.5× +- Y RINGK → 2.0× … + +### 4.2 1T (compute-шар) + +1T — токен, пов'язаний з обчислювальною потужністю: + +- кожен LLM-виклик / агентний run / роутинг DAARWIZZ має **внутрішню собівартість** в 1T-еквіваленті; +- внутрішньо ведеться облік: + - `compute_units_used` → конвертується в 1T (offchain/onchain settlement); +- для кожної команди: + - `monthly_compute_budget_1T`; + - якщо план → включає X 1T / місяць. + +### 4.3 KWT (energy-шар) + +KWT — енергетичний токен (див. Energy Union): + +- залежно від того, чи обчислення живляться «зеленим» контуром: + - частина витрат в 1T «покривається» через локальне енергопостачання; +- для data-центрів / вузлів: + - `kwh → KWT` → subsidy / incentive. + +### 4.4 DAAR / DAARION (міський рівень) + +- DAAR/DAARION визначають: + - статус резидента; + - участь у міській економіці, Gift Fabric; +- через governance → можуть змінювати: + - ціни 1T для певних категорій; + - пільги для платформ (GreenFood, соціальні ініціативи). + +--- + +## 5. Технічні ліміти та Entitlements + +Загальна формула: + +```text +allow_action = + RBAC ∧ Capability ∧ ACL ∧ Mode + ∧ (usage < quota(plan, stake)) +``` + +З боку інфраструктури: + +### 5.1 Quotas (per user / team / platform) + +Приклади метрик: + +- `agent_runs_per_day` +- `tokens_llm_per_day` +- `router_invocations_per_day` +- `messages_per_day` +- `storage_mb_per_team` +- `embassy_events_per_day` +- `wallet_tx_per_day` + +Для кожного плану: + +| План | LLM-токени / місяць | Agent runs / день | Storage / team | Embassy events / місяць | +| ----------- | ------------------- | ----------------- | -------------- | ----------------------- | +| Freemium | N1 | R1 | S1 | E1 | +| Casual | N2 | R2 | S2 | E2 | +| Premium | N3 | R3 | S3 | E3 | +| Platformium | N4 | R4 | S4 | E4 | + +Множиться на `f(RINGK_staked)`. + +### 5.2 Механіка використання + +- Worker/API перед кожною дорогою операцією: + - інкрементує usage; + - порівнює з quotas; + - якщо близько до ліміту: + - soft-warning → UI/notification; + - якщо перевищено: + - hard-stop → 429 / custom error. + +--- + +## 6. Autoscaling vs. Cost Guards + +### 6.1 Autoscaling з budget-обмеженнями + +Класичне autoscaling (CPU/RPS) → може «роздути» рахунок. + +Тому на рівні SRE: + +- визначається **max_instances_per_service** per environment; +- для дорогих компонентів: + - Agent Runtime, + - Wallet Service, + - Embassy, + - LLM Proxies; + +застосовується: + +```text +desired_instances = min( + autoscaler_recommendation, + max_instances_budget +) +``` + +### 6.2 Burst-мод + +Для подій типу Energy Union / Embassy: + +- дозволяється короткий burst (наприклад, ×2–3 від норми) при: + - наявності RWA/енергетичного покриття; +- bursts логуються, накладається governance policy. + +--- + +## 7. LLM / Agents Cost Controls + +### 7.1 На рівні агента + +Кожен агент має конфіг: + +- `max_tokens_per_run` +- `max_cost_per_run` (у внутрішніх одиницях / 1T-еквівалент) +- `max_parallel_runs` +- `allowed_tools` (частина з них дорогі, напр. browser/crawler) + +Agent Orchestrator: + +- перед запуском оцінює потенційний cost; +- при chain-of-thought / multi-step run: + - веде контрліміти (break if too expensive). + +### 7.2 На рівні користувача/команди + +- кожен run → запис у таблицю usage: + - `team_id`, `agent_id`, `compute_cost`, `tokens_used`, `ts`; +- менеджер або Owner бачить usage dashboard: + - по агентах; + - по членах команди; + - по типам задач. + +--- + +## 8. Послуговування RWA/Embassy з економічними обмеженнями + +### 8.1 Embassy Limits + +- Кількість оброблених webhook'ів per платформа: + - `events_per_minute` / `events_per_day`; +- Для платформи: + - `free_tier` (для соціальних / важливих ініціатив); + - `sponsored_tier` (оплачується з RWA фонду); + - `commercial_tier` (необхідний стейк / плата 1T/DAARION). + +### 8.2 Oracle Inputs + +- Oracle'и можуть бути дорогими (обсяг даних). +- Вводяться: + - batch-обмеження; + - ліміти по `payload_size`; + - price per oracle event (у 1T-еквіваленті). + +--- + +## 9. Wallet / Chain / Gas Optimization + +### 9.1 Bundle-транзакції + +- Об'єднувати можливі tx: + - payout claims → batch claim, якщо можливо; + - aggregation перед ончейном. + +### 9.2 Chain Selection + +- Використовувати: + - L2 / sidechain з низьким gas; + - minimal calldata. + +### 9.3 Offchain-first + +- Стейт RWA, стейку, usage: + - максимально offchain (Postgres + NATS + audit_log); + - ончейн тільки фіналізація. + +--- + +## 10. Analytics для економіки + +### 10.1 Збір метрик + +Збираються агрегати: + +- `llm_tokens_per_team_per_day` +- `agent_runs_per_team_per_day` +- `events_embassy_per_platform_per_day` +- `wallet_tx_per_day` +- `gas_spent_per_day` +- `kwh_used_for_compute` (якщо є energy integration) + +### 10.2 Дашборди + +Для: + +- технічної команди: + - cost per component (LLM, API, NATS, DB, Chain); +- продуктової/економічної: + - cost per feature / platform / cohort; +- governance: + - чи треба змінити планові ліміти/ціни. + +--- + +## 11. Governance Controls + +### 11.1 Політики + +Governance Agent (див. попередні документи) може: + +- змінювати: + - quotas (N1–N4, R1–R4…); + - цінові коефіцієнти (1T per token, KWT subsidies); + - правила bursts / high-priority flows; +- вводити: + - пільги для окремих платформ/районів міста; + - обмеження для надмірних споживачів. + +### 11.2 Процес + +1. Пропозиція (proposal) з новими параметрами. +2. Голосування DAAR/DAARION. +3. Після прийняття: + - оновлення конфігів у Capability/Entitlements Registry; + - deployment змін в PDP/Pricing Service; + - журнал подій: `governance.policy.updated`. + +--- + +## 12. Практичні граничні значення (рекомендації MVP) + +Орієнтовні базові параметри для MVP (приклад): + +- Freemium: + - `agent_runs_per_day` — 20 + - `llm_tokens_per_day` — 20k–50k +- Casual: + - `agent_runs_per_day` — 100 + - `llm_tokens_per_day` — 100k–200k +- Premium: + - `agent_runs_per_day` — 500 + - `llm_tokens_per_day` — 1M +- Platformium: + - за домовленістю; ліміти → контракт + stake RINGK. + +Множники `f(RINGK_staked)`: + +- 0 RINGK — ×1.0 +- 1000 RINGK — ×1.25 +- 5000 RINGK — ×1.5 +- 20000 RINGK — ×2.0 + +(значення можна винести в окрему конфіг/таблицю і коригувати governance'ом). + +--- + +## 13. Завдання для Cursor + +```text +You are a senior backend engineer. Implement cost optimization and token economics using: +- 30_cost_optimization_and_token_economics_infrastructure.md +- 24_access_keys_capabilities_system.md +- 29_scaling_and_high_availability.md + +Tasks: +1) Create usage tracking tables (agent_runs_usage, llm_tokens_usage, etc.). +2) Implement quota checking middleware in API Gateway. +3) Integrate RINGK stake multipliers into quota calculations. +4) Create cost estimation service for agent runs. +5) Implement soft/hard limits with UI notifications. +6) Create usage dashboards for teams/owners. +7) Add governance hooks for quota policy updates. + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 14. Висновок + +- Інфраструктура не повинна «зливати» бюджет LLM/compute без зв'язку з токеномікою. +- Усі ключові операції (агенти, Embassy, Wallet, RWA) мають: + - квоти, + - usage-облік, + - прив'язку до планів і стейку RINGK, + - внутрішній 1T-еквівалент. +- Governance може змінювати правила, але технічна основа — у quotas, метриках та PDP. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/31_governance_policies_for_capabilities_and_quotas.md b/docs/cursor/31_governance_policies_for_capabilities_and_quotas.md new file mode 100644 index 00000000..c55b0136 --- /dev/null +++ b/docs/cursor/31_governance_policies_for_capabilities_and_quotas.md @@ -0,0 +1,516 @@ +# 31 — Governance Policies for Capabilities & Quotas (MicroDAO) + +*Політики DAO для управління доступами, квотами, використанням ресурсів (LLM/compute), RWA-потоками та енергетичними економічними параметрами* + +--- + +## 1. Purpose & Scope + +Цей документ визначає, як **Governance (DAARION DAO)** керує: + +- наборами capabilities, +- ролями й планами (Freemium → Platformium), +- квотами LLM / агенти / каналами / Embassy, +- compute-вартістю (1T), +- енергетичними потоками (KWT), +- RWA доступами, +- стейком RINGK. + +Модель відповідає концепції: + +``` +Governance → Policy Registry → Capability System → PDP → API/Agents +``` + +Це «конституція» доступів у DAARION.city. + +--- + +## 2. Actors + +### 2.1 Governance Token Holders + +Мають DAAR/DAARION — голосують за зміни політик. + +### 2.2 Governance Agent + +Служба, що: + +- приймає пропозиції (proposal), +- рахує голоси, +- застосовує політики, +- оновлює capability bundles, +- змінює entitlements, +- логуює події: `governance.policy.updated`. + +### 2.3 Capability Registry + +Внутрішнє джерело прав: + +- role bundles, +- plan bundles, +- custom bundles, +- platform bundles. + +### 2.4 Policy Service (PDP) + +Перевіряє доступи: + +```text +allow = RBAC ∧ Plan ∧ Stake(RINGK) ∧ Capabilities ∧ ACL ∧ Mode +``` + +--- + +## 3. Типи політик (policy types) + +Політика може змінювати будь-який з таких параметрів: + +### 3.1 Capability Policies + +- додавання capability в role-bundle, +- вилучення capability, +- зміна опису capability, +- змінення пріоритетів. + +### 3.2 Plan & Entitlement Policies + +- N1–N4 ліміти LLM-токенів, +- R1–R4 ліміти agent-run'ів, +- Embassy events quotas, +- Storage quotas, +- Router.invoke quotas, +- спеціальні тарифи. + +### 3.3 Stake / RINGK Policies + +- зміна функції `f(RINGK_staked)` (множники квот), +- мінімальний стейк для Platformium, +- параметри lock-періоду. + +### 3.4 1T Compute Policies + +- compute-вартість LLM токена (напр. 0.001 1T/1000 токенів), +- cost-per-agent-run, +- cost-per-router-hop, +- cost-per-embassy-event, +- burst price adjustments. + +### 3.5 KWT Energy Policies + +- коефіцієнти `kWh → KWT`, +- subsidies = `1T discount` для платформ з локальним енергетичним покриттям, +- обмеження RWA-енергетичних оновлень. + +### 3.6 RWA Access Policies + +- які команди можуть мати `rwa.inventory.update`, +- ліміти орієнтирів для oracle input, +- RWA reward distribution rules. + +### 3.7 Governance Process Policies + +- наявність кворуму, +- % голосів для прийняття, +- час тривалості голосування. + +--- + +## 4. Governance Policy Lifecycle + +### 4.1 Пропозиція ("policy proposal") + +Будь-який Guardian/Owner команди або DAARION громадянин зі статусом Level≥N може створити proposal: + +```json +{ + "policy_type": "capability.update", + "bundle_id": "bundle_role_member", + "changes": [ + { "add_cap": "chat.message.delete" } + ], + "reason": "Потрібно дозволити модерацію" +} +``` + +### 4.2 Валідатор + +Governance Agent перевіряє: + +- чи всі capability-коди існують, +- чи bundle існує, +- чи немає конфлікту (наприклад, розширення прав visitor), +- чи user має право подати цю пропозицію. + +### 4.3 Голосування + +Власники DAAR/DAARION голосують: + +- `yes`, +- `no`, +- `abstain`. + +Метрики голосування: + +- quorum ≥ X%, +- approval ≥ Y%, +- voting duration (3–7 днів). + +### 4.4 Застосування + +Governance Agent: + +- оновлює записи в таблицях: + - `bundles`, + - `bundle_caps`, + - `capabilities`, + - `entitlements`, +- викликає `policy.update()` на PDP (гаряча перезагрузка конфігу), +- пише подію: + +```json +{ + "topic":"governance.policy.updated", + "policy_id":"gov_123", + "bundle_updated":"bundle_role_member", + "changes":[ "..."], + "timestamp":"..." +} +``` + +### 4.5 Аудит + +Вся операція реєструється в `audit_log`. + +--- + +## 5. Governance Policy Structure (Schema) + +Пропозиція реалізується у форматі: + +```json +{ + "policy_id": "gov_policy_001", + "title": "Increase compute quotas for Premium", + "policy_type": "plan.entitlement.update", + "target": "plan.Premium", + "operations": [ + { + "op": "set_quota", + "metric": "llm_tokens_per_month", + "value": 2000000 + }, + { + "op": "set_quota", + "metric": "agent_runs_per_day", + "value": 1500 + } + ], + "metadata": { + "proposed_by": "u_abc", + "team": null + } +} +``` + +Підтримувані `op`: + +- `add_cap` +- `remove_cap` +- `set_quota` +- `increase_quota` +- `decrease_quota` +- `set_stake_multiplier` +- `set_compute_price` +- `set_energy_subsidy` +- `freeze_capabilities` +- `enable_burst_mode` +- `disable_burst_mode` +- `add_rwa_type` +- `remove_rwa_type` + +--- + +## 6. Policy Application Rules (Critical) + +### Rule 1 — No Privilege Escalation + +Capability не може бути додано до bundle рівня: + +- visitor → admin (Owner/Guardian), +- plan.Freemium → platformium (без vote). + +### Rule 2 — Plan Hierarchy + +Плани мають порядок: + +```text +Freemium < Casual < Premium < Platformium +``` + +Заборонено: + +- зменшувати квоти нижче рівнів нижчих планів. + +### Rule 3 — Capability Consistency + +Capability не може ламати fundamental правила: + +- `wallet.stake.ringk` тільки owner/member команди; +- `embassy.energy.update` тільки платформи; +- `governance.policy.manage` тільки Guardian/Owner/DAO. + +### Rule 4 — Conflict Detection + +Governance Agent перед застосуванням перевіряє: + +- чи не створює політика циклічних залежностей, +- чи не робить visitor прав адміну, +- чи не робить entitlements негативними, +- чи не створює «free infinite compute». + +### Rule 5 — Reversible + +Будь-яка політика повинна мати можливість: + +- або бути скасованою новою політикою, +- або мати rollback-сценарій (хоча б логічний). + +--- + +## 7. Policy Registry (Reference Implementation) + +Policy Registry — це централізований конфіг: + +### 7.1 Таблиці + +```sql +create table governance_policies ( + id text primary key, + policy_type text not null, + payload jsonb not null, + created_at timestamptz default now(), + applied_at timestamptz, + applied boolean default false, + proposed_by text references users(id) +); +``` + +Записи: + +- зберігають повну історію політик; +- при `applied=true` → immutable. + +--- + +## 8. PDP Integration + +Після застосування політик Governance Agent викликає: + +``` +POST /pdp/reload +``` + +Або публікує подію: + +``` +topic: governance.policy.updated +``` + +PDP: + +- оновлює кэш: + - bundle → caps + - plan → quotas + - stake multiplier + - compute pricing + - allowed RWA actions + +Гарантує: + +- нові політики починають діяти **миттєво**; +- старі токени (cap-token) → відкидаються якщо несумісні. + +--- + +## 9. Example Policies + +### 9.1 Розширення доступів Premium + +```json +{ + "policy_type": "capability.update", + "target": "bundle_plan_premium", + "operations": [ + { "op": "add_cap", "value": "embassy.intent.read" }, + { "op": "add_cap", "value": "rwa.inventory.update" } + ] +} +``` + +### 9.2 Зменшення compute-вартості (1T) + +```json +{ + "policy_type": "compute.price", + "target": "1T", + "operations": [ + { "op": "set_compute_price", "value": 0.0008 } + ] +} +``` + +### 9.3 Зміна множника стейку + +```json +{ + "policy_type": "stake.multiplier", + "target": "RINGK", + "operations": [ + { "op": "set_stake_multiplier", "range": "5000", "value": 1.5 } + ] +} +``` + +### 9.4 Ввімкнути burst-mode + +```json +{ + "policy_type": "burst_mode", + "operations": [ + { "op": "enable_burst_mode", "x_factor": 3, "duration": 3600 } + ] +} +``` + +--- + +## 10. Governance-Safe Defaults + +- Caps не можуть бути назавжди відключені для owner. +- Embassy caps тільки для платформ. +- RWA caps тільки для сертифікованих платформ. +- Compute-ціни мають нижні межі, щоб захистити економіку. +- Burst-mode має час і ліміт. + +--- + +## 11. Security Considerations + +### 11.1 Replay Protection + +Кожна політика має `policy_id` та timestamp. + +### 11.2 Immutable History + +Після `applied=true` рядок в таблиці є незмінним. + +### 11.3 Double-application Guard + +Governance Agent перевіряє `applied=false`. + +### 11.4 PDP не довіряє UI + +Усі capability-операції перевіряються на бекенді. + +--- + +## 12. Audit & Transparency + +- Усі політики: + - публічні, + - переглядаються резидентами, + - мають changelog, + - доступні через API: + - `GET /governance/policies`. + +- Audit log записує: + - хто подав пропозицію, + - хто голосував, + - застосовані зміни. + +--- + +## 13. Governance Failover Procedures + +### 13.1 Якщо Governance Agent недоступний + +- PDP повертає попередні політики. +- API не приймає нові пропозиції (fail-safe). +- Відновлення через re-deploy. + +### 13.2 Якщо Policy Registry пошкоджено + +- Використовується backup snapshot. +- Governance Agent перевіряє consistency з bundles. + +### 13.3 Якщо політика зламала доступи + +- Emergency rollback policy: + +```json +{ + "policy_type": "policy.rollback", + "target": "policy_id", + "reason": "breaks rights" +} +``` + +--- + +## 14. Integration with Other Docs + +Цей документ доповнює: + +- `24_access_keys_capabilities_system.md` +- `26_security_audit.md` +- `29_scaling_and_high_availability.md` +- `30_cost_optimization_and_token_economics_infrastructure.md` +- `27_database_schema_migrations.md` + +--- + +## 15. Завдання для Cursor + +```text +You are a senior backend engineer. Implement Governance Policies system using: +- 31_governance_policies_for_capabilities_and_quotas.md +- 24_access_keys_capabilities_system.md +- 30_cost_optimization_and_token_economics_infrastructure.md + +Tasks: +1) Create governance_policies table. +2) Implement Governance Agent service (proposal validation, voting, application). +3) Create Policy Registry with caching. +4) Implement policy operations (add_cap, set_quota, set_stake_multiplier, etc.). +5) Add conflict detection and validation rules. +6) Integrate with PDP for hot-reload of policies. +7) Add audit logging for all policy changes. + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 16. Summary + +Система Governance у DAARION.city: + +- керує capability-наборами, +- визначає квоти й compute-вартість, +- регулює RWA й енергетичні потоки, +- підтримує стейкову модель RINGK, +- має формальний policy lifecycle, +- повністю інтегрується в PDP. + +Це забезпечує масштабовану, безпечну, економічно стійку систему доступів. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/32_policy_service_PDP_design.md b/docs/cursor/32_policy_service_PDP_design.md new file mode 100644 index 00000000..605493f0 --- /dev/null +++ b/docs/cursor/32_policy_service_PDP_design.md @@ -0,0 +1,520 @@ +# 32 — Policy Service PDP Design (MicroDAO) + +*Архітектура Policy Decision Point (PDP), кешування, резолюція прав, квоти, інтеграція з API Gateway / Agents / Embassy* + +--- + +## 1. Purpose & Scope + +PDP — це центральний компонент авторизації платформи **DAARION.city / microDAO / Embassy / Agents / Wallet**. + +Він відповідає за: + +- розв'язання прав доступу на основі: + - RBAC, + - Capability Bundles, + - Entitlements (плани), + - Stake (RINGK), + - ACL, + - Mode (public/confidential), + - Quotas, +- кешування конфігів доступів, +- видачу дозволу або заборони на кожну дію, +- роботу у high-load середовищах, +- інтеграцію з API Gateway (PEP), +- безпечну роботу з Agent Mesh, Embassy, Wallet, RWA. + +Це ключовий документ для розробників API, агентного шару та бекенду. + +--- + +## 2. PDP Formula + +PDP приймає рішення за єдиною формулою: + +```text +allow = + RBAC(role, action, resource) AND + Entitlement(plan, stake_RINGK) AND + Capability(key, action, resource) AND + ACL(resource, subject) AND + Mode(resource_mode, subject_type) AND + Quota(subject, action) AND + SecurityContext(subject, key_status) +``` + +Кожен блок працює незалежно. + +--- + +## 3. PDP Inputs + +PDP приймає запит такого вигляду: + +```json +{ + "subject": { + "id": "u_123", + "type": "user" // user | agent | integration | embassy + }, + "team_id": "t_456", + "action": "task.create", + "resource": { + "id": "p_001", + "team_id": "t_456", + "mode": "public" // або confidential + }, + "key_id": "ak_789", + "context": { + "ip": "1.2.3.4", + "ua": "Mozilla/5.0", + "timestamp": 1700000000 + } +} +``` + +PDP повинен дати відповідь: + +```json +{ "allow": true, "reason": "ok" } +``` + +або: + +```json +{ "allow": false, "reason": "quota_exceeded" } +``` + +--- + +## 4. PDP Architecture Overview + +``` + ┌─────────────────────────┐ + │ Policy Registry │ + │ (bundles, caps, plans) │ + └───────────┬────────────┘ + │ + ┌──────────┴───────────┐ + │ PDP Core │ + │ (decision engine) │ + └──────────┬───────────┘ + │ + ┌──────────────────────┼─────────────────────────┐ + │ │ │ + API Gateway (PEP) Agent Mesh Embassy +``` + +--- + +## 5. Internal Modules + +### 5.1 Module: Role Resolver + +- Визначає роль користувача в команді: + - Owner + - Guardian + - Member + - Visitor + +Запит у БД (кешований): + +```sql +SELECT role, viewer_type FROM team_members WHERE ... +``` + +### 5.2 Module: Capability Resolver + +Для `key_id` PDP збирає: + +- capabilities з `access_key_caps` +- capabilities з `bundle.role.*` +- capabilities з `bundle.plan.*` +- capabilities з `bundle.agent.*` +- capabilities з `bundle.platform.*` (для платформи) + +Фінальний набір — **унія всіх capability-джерел**. + +### 5.3 Module: Entitlements + +План (`Freemium`, `Casual`, `Premium`, `Platformium`) → базові квоти: + +- LLM-токени +- Agent runs +- Router invokes +- Embassy events +- Storage +- Wallet claims + +Далі застосовується stake-множник: + +```text +effective_quota = base_quota × f(RINGK_staked) +``` + +### 5.4 Module: Quota Manager + +Робить такі перевірки: + +- usage < effective_quota +- якщо usage близько до межі → warning-флаг +- якщо перевищено → deny + +### 5.5 Module: ACL Resolver + +ACL ресурсу (якщо встановлено): + +- список дозволених user_id/team_id, +- список заборонених user_id/team_id. + +### 5.6 Module: Confidential Mode Resolver + +Важливо для каналів/чату: + +```text +if resource.mode == confidential: + if subject.type == 'agent': + deny reading plaintext +``` + +Agents не бачать plaintext у confidential-режимі. + +### 5.7 Module: Key Status Checker + +Перевіряє: + +- чи активний ключ, +- чи не expired, +- чи не revoked, +- чи не over-rate-limit. + +--- + +## 6. PDP Data Sources + +PDP отримує дані з: + +### 6.1 Capability Registry + +Таблиці: + +- `capabilities` +- `bundles` +- `bundle_caps` +- `access_keys` +- `access_key_caps` + +### 6.2 Role/Team Registry + +- `team_members` +- `teams` + +### 6.3 Usage Metrics (Per Team/User) + +- `usage_agent_runs` +- `usage_llm_tokens` +- `usage_embassy_events` +- `usage_storage` +- `usage_router_invokes` +- `usage_wallet_tx` + +(Можуть бути або materialized views, або окремі таблиці.) + +### 6.4 Resource Metadata + +- `channels` +- `projects` +- `tasks` +- `rwa_inventory` + +--- + +## 7. PDP Cache Design + +PDP має бути **дуже швидким**, тому більшість даних кешуються. + +### 7.1 Static Cache (Long-term) + +Завантажується при старті PDP: + +- capabilities list, +- bundles, +- bundle_caps. + +Оновлюється: + +- при події `"governance.policy.updated"`. + +### 7.2 Dynamic Cache (Short-term) + +Кешуються на 10–60 секунд: + +- role for (user_id, team_id) +- caps for (key_id) +- quotas for (team_id) +- stake multipliers + +### 7.3 Usage Cache + +Usage counter зберігається: + +- у Redis або Memcache, +- синхронізується з БД регулярно. + +--- + +## 8. PDP Decision Algorithm (Pseudocode) + +```python +def pdp_decide(request): + # 1) Key status + if key_is_invalid(request.key_id): + return deny("key_invalid") + + # 2) Role + role = get_role(request.subject, request.team_id) + if not role: + return deny("no_role") + + # 3) Capability + if not has_capability(request.key_id, request.action): + return deny("capability_missing") + + # 4) RBAC matrix + if not rbac_allows(role, request.action): + return deny("rbac_denied") + + # 5) ACL + if acl_blocks(request.resource, request.subject): + return deny("acl_block") + + # 6) Confidential mode + if is_confidential(request.resource) and is_agent(request.subject): + if request.action in ["chat.message.read"]: + return deny("confidential_mode_restriction") + + # 7) Quotas + if exceeds_quota(request.subject, request.action): + return deny("quota_exceeded") + + return allow() +``` + +--- + +## 9. PDP Integration with API Gateway (PEP) + +API Gateway виконує: + +1. Аутентифікацію +2. Витяг ключа (user session / access key) +3. Виклик PDP: + +``` +POST /pdp/decide +{ + subject: {...}, + team_id: "...", + action: "...", + resource: {...} +} +``` + +4. Отримує відповідь allow/deny +5. Продовжує або блокує запит +6. Збирає usage (LLM tokens, bytes, etc.) + +--- + +## 10. PDP Integration with Agents + +### 10.1 Agent run + +Перед кожним `agent.run.invoke`: + +- PDP перевіряє capability → `agent.run.invoke` +- PDP перевіряє квоти → `agent_runs_per_day` + +### 10.2 Tools + +Кожен tool має окремий action: + +- `tool.browser` +- `tool.code` +- `tool.search` + +Plugins: + +```text +tool..invoke +``` + +### 10.3 Confidential-mode + +Агенти отримують summary замість plaintext. + +--- + +## 11. PDP Integration with Embassy + +Embassy keys використовують capabilities: + +- `embassy.rwa.claim` +- `embassy.energy.update` +- `embassy.intent.read` + +При події: + +``` +POST /embassy/rwa +``` + +API Gateway викликає PDP: + +``` +authorize(embassy_key, action=embassy.rwa.claim) +``` + +PDP перевіряє: + +- ключ дійсний, +- capability збігається, +- quota embassy events не перевищена, +- ACL платформи. + +--- + +## 12. PDP Integration with Wallet + +Перед кожним: + +- `wallet.balance.view` +- `wallet.stake.ringk` +- `wallet.payout.claim` + +PDP: + +- перевіряє capability для користувача, +- перевіряє стейк (stake multipliers), +- перевіряє квоту на wallet tx, +- перевіряє ACL команди. + +--- + +## 13. PDP Integration with Governance + +Після прийняття governance policy: + +`governance.policy.updated` + +PDP: + +- скидає кеш bundles, +- оновлює entitlement-конфіги, +- застосовує stake multipliers, +- ідентифікає можливі конфлікти. + +--- + +## 14. PDP Logging & Audit + +Кожне рішення PDP опціонально логують: + +- action, +- subject, +- team, +- result, +- latency, +- quotas status. + +Для chathistory-sensitive дій → minimal metadata. + +--- + +## 15. PDP Performance Targets + +- p95 latency < 3 ms (кешований) +- p99 latency < 8 ms +- 5k–20k rps у проді +- 1–3 GB RAM кешу достатньо + +--- + +## 16. PDP Failure Modes & Recovery + +### 16.1 Cache Corruption + +→ Reload from Policy Registry +→ Governance Agent перевіряє consistency + +### 16.2 DB Unavailable + +→ PDP переходить у fail-safe режим (deny critical ops, allow read-only) + +### 16.3 Overloaded PDP + +→ Horizontal autoscaling +→ Rate limit API upstream + +### 16.4 Governance Hotfix + +→ Manual override policies +→ Emergency shutdown of dangerous capabilities + +--- + +## 17. Security Considerations + +- PDP не довіряє API Gateway +- PDP не довіряє клієнту +- Кеш capabilities підписано +- Governance updates підписані +- Embassy events мають HMAC-підписи +- Confidential mode ніколи не віддає plaintext агенту + +--- + +## 18. Завдання для Cursor + +```text +You are a senior backend engineer. Implement Policy Decision Point (PDP) using: +- 32_policy_service_PDP_design.md +- 24_access_keys_capabilities_system.md +- 31_governance_policies_for_capabilities_and_quotas.md + +Tasks: +1) Create PDP service with decision engine. +2) Implement internal modules (Role Resolver, Capability Resolver, Entitlements, Quota Manager, ACL Resolver, Confidential Mode Resolver, Key Status Checker). +3) Implement caching layer (static cache, dynamic cache, usage cache). +4) Create PDP decision algorithm. +5) Integrate with API Gateway (PEP). +6) Add PDP logging and audit. +7) Implement failure modes and recovery. + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 19. Summary + +PDP — основа безпеки та економічної стійкості міста: + +- централізує право доступу, +- інтегрується з governance, +- застосовує квоти, +- керує usage, +- забезпечує ізоляцію агентів, +- гарантує E2EE-приватність, +- контролює Embassy/RWA/Wallet потоки, +- підтримує масштабованість і HA. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/33_api_gateway_security_and_pep.md b/docs/cursor/33_api_gateway_security_and_pep.md new file mode 100644 index 00000000..957f2b21 --- /dev/null +++ b/docs/cursor/33_api_gateway_security_and_pep.md @@ -0,0 +1,537 @@ +# 33 — API Gateway Security & PEP (MicroDAO) + +*API Gateway Architecture, Policy Enforcement Point (PEP), Rate Limiting, Key Validation, PDP Integration, Embassy/Webhook Security, Usage Accounting* + +--- + +## 1. Purpose & Scope + +API Gateway — це **єдина точка входу** для всіх зовнішніх та внутрішніх HTTP-запитів у DAARION.city: + +- web-клієнтів (user/browser), +- приватних агентів, +- Embassy інтеграцій, +- mobile/desktop клієнтів, +- сторонніх сервісів DAARION-платформ. + +Цей документ описує: + +- архітектуру Gateway, +- логіку Policy Enforcement Point (PEP), +- інтеграцію з PDP, +- rate limiting на кожному рівні, +- захист API keys, агентів, Embassy, +- audit/logging/usage, +- безпекові guardrails. + +--- + +## 2. High-level Architecture + +``` + ┌──────────────────────────┐ + │ Load Balancer │ + └─────────────┬────────────┘ + │ + ┌────────────┴────────────┐ + │ API Gateway (PEP) │ + └────────────┬────────────┘ + │ + ┌──────────────┬──────────────┼──────────────┬───────────────┐ + │ │ │ │ │ + Core API Agent API Embassy API Wallet API Webhooks +``` + +Gateway = PEP (Policy Enforcement Point) + Key Validator + Rate Limiter + Router + Logging Engine. + +--- + +## 3. Key Responsibilities + +### 3.1 Authentication + +- User session tokens (cookies). +- Access Keys (user/agent/integration). +- Embassy HMAC signatures. +- Internal service JWT (якщо потрібно). + +### 3.2 Authorization (PEP) + +- виклик PDP для кожного action: + + ```text + action = . + ``` + +- PDP повертає allow/deny. + +### 3.3 Key Lifecycle Management + +- дієвість, +- TTL, +- rotation, +- revocation, +- rate limiting. + +### 3.4 Usage Accounting + +- лічильники: + - LLM tokens, + - agent runs, + - router invokes, + - storage size, + - embassy events, + - wallet tx. + +### 3.5 Transport Security + +- TLS termination, +- CORS, +- header hardening. + +--- + +## 4. Request Flow + +```mermaid +sequenceDiagram + participant C as Client + participant G as API Gateway (PEP) + participant PDP + participant S as Service + + C->>G: HTTP request + G->>G: extract identity (session/key) + G->>G: validate key signature/ttl/status + G->>PDP: authorization(action, subject, resource) + PDP-->>G: allow/deny + alt deny + G-->>C: 403 Forbidden + else allow + G->>S: forward request + S-->>G: response + G-->>C: return response + end +``` + +--- + +## 5. Identity Sources + +### 5.1 User Identity + +Отримується з: + +- session cookie, +- або user access key. + +### 5.2 Agent Identity + +- кожен агент має `ak_*` key: + + ```text + subject_kind = "agent" + subject_id = "ag_*" + ``` + +### 5.3 Embassy Identity + +Webhook-платформи не використовують JWT/keys, тільки: + +- HMAC signature, +- timestamp, +- platform_id. + +API Gateway перевіряє: + +```text +valid_signature AND timestamp < skew_limit +``` + +### 5.4 Integration Keys + +Треті сторони: + +- access_key з capability: `integration.*` + +--- + +## 6. Key Validation Pipeline + +Перед PDP-викликом Gateway перевіряє: + +1. **isAccessKeyPresent** +2. **isKnownKeyFormat** (ak_xxx) +3. **isKeyActive (status=='active')** +4. **notExpired (expires_at > now)** +5. **notRevoked** +6. **rateLimitPerKey** +7. **IP throttling** +8. **geo restrictions** (опційно) +9. **isAllowedSubjectType** (user/agent/integration/embassy) + +У разі невідповідності — **403 Forbidden**. + +--- + +## 7. PDP Integration + +Gateway формує PDP-запит: + +```json +{ + "subject": { + "id": "u_1", + "type": "user" + }, + "team_id": "t_123", + "action": "task.create", + "resource": { + "id": "p_44", + "team_id": "t_123", + "mode": "public" + }, + "key_id": "ak_777" +} +``` + +PDP відповідає: + +```text +allow / deny +reason +quota_status +``` + +### 7.1 Hard-deny reasons: + +- key_invalid +- capability_missing +- rbac_denied +- acl_block +- confidential_restriction +- quota_exceeded + +--- + +## 8. Rate Limiting Layer + +Gateway має багаторівневий rate limiting. + +### 8.1 Global (per environment) + +Наприклад: + +```text +1000 req/sec (dev) +5000 req/sec (staging) +20000 req/sec (prod) +``` + +### 8.2 Per IP + +Запобігає DDOS: + +```text +100 req/min +``` + +### 8.3 Per KEY (access_key_id) + +Важливо для: + +- agent keys, +- integration keys, +- embassy keys. + +Наприклад: + +```text +50 req/min for Freemium +200 req/min for Premium +1000 req/min for Platformium +``` + +### 8.4 Per ACTION + +Деякі дії дорогі: + +| Action | Ліміт | +| ------------------- | ------- | +| agent.run.invoke | 10/min | +| router.invoke | 30/min | +| wallet.payout.claim | 2/min | +| embassy.rwa.claim | 120/min | +| chat.message.send | 300/min | + +### 8.5 Per TEAM + +Для захисту БД. + +--- + +## 9. Resource Context Extraction + +Gateway визнає ресурс з URL. + +Приклади: + +| Endpoint | Resource | Action | +| ------------------ | ------------------ | ------------------ | +| POST /tasks | project_id=payload | task.create | +| POST /messages | channel_id=payload | chat.message.send | +| POST /wallet/stake | team_id=user.team | wallet.stake.ringk | +| POST /embassy/rwa | platform=header | embassy.rwa.claim | +| POST /agent/run | agent_id | agent.run.invoke | + +--- + +## 10. Confidential Mode Enforcement + +Gateway застосовує **PEP-level enforcement**: + +```text +if resource.mode == confidential: + if subject.kind == "agent": + if action in ["chat.message.read"]: + deny +``` + +Усі інші повідомлення: + +- plaintext → не передається агенту, +- агент отримує `summary`, `embeddings`, `role`. + +--- + +## 11. Embassy Webhook Security + +Для платформи (EnergyUnion, GREENFOOD, Water Union): + +### 11.1 Gateway виконує: + +1. Перевірка HMAC: + + ```text + HMAC(key=emb_secret, body) + ``` + +2. Перевірка `X-Timestamp`: + + ```text + |client_ts - server_ts| < 5 min + ``` + +3. Формування PDP-запиту: + + ```text + action = embassy.energy.update + subject_kind = embassy + subject_id = emb_ + ``` + +4. Quota-check (events per day) +5. Forward до Embassy Service + +### 11.2 Відмова у разі: + +- HMAC mismatch +- expired timestamp +- excess quota +- revoked embassy key + +--- + +## 12. Wallet API Security + +Wallet endpoints — найбільш критичні. + +Gateway виконує: + +1. PDP: + - `wallet.stake.ringk` + - `wallet.payout.claim` + - `wallet.balance.view` +2. Rate limiting (дуже низький) +3. Additional anti-fraud rules: + - geo-check (опційно) + - user consistency (IP fingerprint) +4. DB-level locking (handled by wallet service) +5. Chain RPC protection (delayed retry, jitter) + +--- + +## 13. Agent API Security + +Агенти — потенційно небезпечний трафік. + +Gateway блокує: + +1. розширені network operations (якщо немає capability) +2. небезпечні MIME-types +3. надмірно великі payloads (>512KB) +4. токсичні параметри (regex sanitize) +5. DoS через parallel agent runs + +Агентні ключі мають capability: + +- `agent.run.invoke` +- `tool.*` +- `router.invoke` + +--- + +## 14. Quota Enforcement Integration + +Після дозволу PDP, Gateway викликає: + +- `usage.increment(team_id, action, units)` + +Приклад: + +- для LLM tokens → units = tokens +- для agent-run → units = 1 +- для wallet claim → units = 1 +- для Embassy event → units = 1 + +Якщо usage впритул → soft-limit → warning header. + +--- + +## 15. Logging Model + +Gateway пише логи: + +- request_id +- subject_id +- key_id +- action +- team_id +- latency +- status +- quota_status +- PDP result +- IP/UA + +Логи **не містять plaintext** чату. + +--- + +## 16. API Hardening + +Gateway застосовує: + +### 16.1 Headers + +- `X-Frame-Options: DENY` +- `X-Content-Type-Options: nosniff` +- `Referrer-Policy: strict-origin-when-cross-origin` +- `Content-Security-Policy: frame-ancestors 'none'; script-src 'self' 'unsafe-inline'` + +### 16.2 Disable methods + +- TRACE +- OPTIONS (лише preflight) +- CONNECT + +### 16.3 Payload limits + +- max JSON body size (0.5–2 MB) +- timeouts (3–5 сек) + +--- + +## 17. Error Model + +Gateway повертає стандартизовані помилки: + +| Код | Статус | Причина | +| --- | --------------- | ----------------- | +| 401 | unauthenticated | no session/key | +| 403 | forbidden | PDP deny | +| 429 | rate_limited | too many requests | +| 400 | invalid_payload | schema mismatch | +| 500 | internal_error | unexpected | + +--- + +## 18. Performance Targets + +- p95 < 10 ms (навіть з PDP) +- p99 < 25 ms +- 20k rps sustained +- zero-downtime redeploy + +--- + +## 19. Failover & Resilience + +- Retry PDP з exponential backoff. +- Circuit-breaker: + - PDP недоступний → deny non-critical ops. +- Horizontal autoscaling. +- Canary deployments. + +--- + +## 20. Integration with Other Docs + +Цей документ доповнює: + +- `32_policy_service_PDP_design.md` +- `31_governance_policies_for_capabilities_and_quotas.md` +- `26_security_audit.md` +- `24_access_keys_capabilities_system.md` +- `25_deployment_infrastructure.md` +- `29_scaling_and_high_availability.md` + +--- + +## 21. Завдання для Cursor + +```text +You are a senior backend engineer. Implement API Gateway / PEP using: +- 33_api_gateway_security_and_pep.md +- 32_policy_service_PDP_design.md +- 24_access_keys_capabilities_system.md + +Tasks: +1) Create API Gateway service with PEP middleware. +2) Implement key validation pipeline. +3) Integrate with PDP for authorization. +4) Implement multi-level rate limiting (global, per-IP, per-key, per-action, per-team). +5) Add Embassy webhook security (HMAC, timestamp validation). +6) Implement Wallet API security (anti-fraud, rate limiting). +7) Add Agent API security (payload validation, DoS protection). +8) Implement quota enforcement integration. +9) Add logging and audit. +10) Implement API hardening (headers, payload limits, timeouts). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 22. Summary + +API Gateway / PEP — це: + +- єдина точка контролю доступів, +- захист від зловживань, +- інтеграція з PDP, +- enforcement квот, +- захист Embassy та вебхуків, +- критичний елемент Wallet/Chain безпеки, +- потужний rate limiting, +- основа для agent-безпеки, +- фундамент всієї системи авторизації DAARION.city. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/34_internal_services_architecture.md b/docs/cursor/34_internal_services_architecture.md new file mode 100644 index 00000000..6207925a --- /dev/null +++ b/docs/cursor/34_internal_services_architecture.md @@ -0,0 +1,679 @@ +# 34 — Internal Services Architecture (MicroDAO) + +*Архітектура внутрішніх сервісів, їхні ролі, API, дані, залежності, взаємодія з PDP, Gateway, NATS, DB* + +--- + +## 1. Purpose & Scope + +Цей документ описує: + +- які внутрішні сервіси існують, +- їхню відповідальність, +- текучку даних, +- API кожного сервісу, +- які таблиці вони контролюють, +- які події вони публікують у NATS, +- залежності між сервісами, +- що можна відокремити у мікросервіси, а що залишити монолітом, +- їх роль у масштабуванні та HA. + +Це **карта всіх backend-компонентів DAARION.city**. + +--- + +## 2. High-Level Service Landscape + +``` + ┌──────────────────────────┐ + │ API Gateway (PEP) │ + └───────────────┬──────────┘ + │ + ┌──────────────────┴──────────────────┐ + │ │ + Public API Internal Service Mesh +``` + +Внутрішні сервіси: + +1. **User/Team Service** +2. **Messaging Service** +3. **Projects/Tasks Service** +4. **Agent Orchestrator** +5. **LLM Proxy Service** +6. **Router/Planner Service (DAARWIZZ)** +7. **Wallet Service** +8. **RWA Inventory Service** +9. **Embassy Gateway Service** +10. **Oracle Processor** +11. **Governance Service** +12. **Capability Registry Service** +13. **Quota/Usage Service** +14. **Outbox Worker** +15. **Telemetry/Logs Service** +16. **Auth/Session Service** +17. **File Storage/Docs Service** + +Усі сервіси є **modular**, але можуть бути реалізовані або як microservices, або як modular monolith. + +--- + +## 3. Core Principles + +- **Stateless там, де можливо** → просте масштабування. +- **Stateful там, де потрібно (wallet, RWA)** → обережні транзакції. +- **Event-driven** через NATS. +- **PDP-централізована авторизація**. +- **Outbox pattern** для гарантій доставки подій. +- **Strong ACID** тільки на критичних таблицях. +- **Soft eventual-consistency** на неважливих частинах. + +--- + +## 4. Internal Services Overview + +### 4.1 User & Team Service + +#### Відповідальність: + +- Users, teams, memberships. +- Roles: Owner, Guardian, Member, Visitor. +- Viewer types: reader/commenter/contributor. +- Team mode: public/confidential. + +#### Таблиці: + +- `users` +- `teams` +- `team_members` + +#### API (internal): + +- `GET /internal/team/:id` +- `POST /internal/team/create` +- `POST /internal/team/member/add` +- `POST /internal/team/member/remove` + +#### Події (NATS): + +- `team.member.joined` +- `team.member.left` + +--- + +### 4.2 Messaging Service + +#### Відповідальність: + +- Channels, messages, followups. +- Co-memory embeddings. +- Confidential mode enforcement (via Gateway). + +#### Таблиці: + +- `channels` +- `messages` +- `followups` +- `comemory_items` + +#### API: + +- `POST /internal/message/send` +- `GET /internal/channel/:id/messages` +- `POST /internal/comemory/index` + +#### Події: + +- `chat.message.created` +- `comemory.item.created` + +--- + +### 4.3 Projects & Tasks Service + +#### Відповідальність: + +- Projects, tasks, workflow. + +#### Таблиці: + +- `projects` +- `tasks` + +#### Події: + +- `project.created` +- `task.created` +- `task.updated` + +--- + +### 4.4 Agent Orchestrator + +#### Відповідальність: + +- запуск приватних агентів; +- трекінг `agent_runs`; +- sandbox execution. + +#### Таблиці: + +- `agents` +- `agent_runs` + +#### Події: + +- `agent.run.started` +- `agent.run.completed` + +#### API: + +- `POST /internal/agent/run` +- `POST /internal/agent/finish` +- `GET /internal/agent/run/:id/status` + +--- + +### 4.5 LLM Proxy Service + +#### Завдання: + +- централізований доступ до LLM (OpenAI / local models). +- облік токенів. +- нормалізація моделей. + +#### API: + +- `POST /internal/llm/chat` +- `POST /internal/llm/embeddings` + +#### Event: + +- `llm.tokens.used` + +--- + +### 4.6 Router / Planner (DAARWIZZ) + +#### Відповідальність: + +- run multi-agent routing pipeline; +- orchestration of tools; +- intent recognition; +- complex "flows". + +#### API: + +- `POST /internal/router/route` +- `POST /internal/router/plan` + +#### Events: + +- `router.invoked` +- `router.completed` + +--- + +### 4.7 Wallet Service + +#### Відповідальність: + +- стейк RINGK; +- генерація payout'ів; +- claim payout; +- зв'язок з блокчейном. + +#### Таблиці: + +- `wallets` +- `staking_ringk` +- `payouts` + +#### API: + +- `POST /internal/wallet/stake` +- `POST /internal/wallet/payout/claim` +- `GET /internal/wallet/balance/:user` + +#### Events: + +- `staking.locked` +- `payout.generated` +- `payout.claimed` + +--- + +### 4.8 RWA Inventory Service + +#### Відповідальність: + +- облік energy/food/water/etc. +- інтеграція з Embassy. +- оновлення RWA стоків. + +#### Таблиці: + +- `rwa_inventory` + +#### Events: + +- `rwa.inventory.updated` + +--- + +### 4.9 Embassy Gateway Service + +#### Відповідальність: + +- прийом підписаних webhook'ів від платформ (EnergyUnion, GREENFOOD). +- HMAC перевірка. +- PDP авторизація (embassy keys). +- генерація подій для NATS. + +#### Таблиці: + +- `embassy_identities` +- `embassy_webhooks` + +#### API: + +- `POST /embassy/energy` +- `POST /embassy/rwa` + +#### Events: + +- `embassy.event.received` +- `embassy.energy.update` +- `embassy.rwa.claim` + +--- + +### 4.10 Oracle Processor + +#### Відповідальність: + +- обробка потоків енергетичних даних; +- нормалізація; +- створення `oracles`. + +#### Таблиці: + +- `oracles` + +#### Events: + +- `oracle.reading.published` + +--- + +### 4.11 Governance Service + +#### Відповідальність: + +- пропозиції, +- голосування, +- застосування політик, +- оновлення bundles/caps/quotas. + +#### Таблиці: + +- `governance_policies` + +#### Events: + +- `governance.policy.updated` + +--- + +### 4.12 Capability Registry Service + +#### Відповідальність: + +- управління: + - capabilities, + - bundles, + - bundle_caps, + - plan entitlements. + +#### Таблиці: + +- `capabilities` +- `bundles` +- `bundle_caps` +- `access_keys` +- `access_key_caps` + +--- + +### 4.13 Usage Service + +#### Відповідальність: + +- підрахунок usage: + - agent runs, + - LLM tokens, + - embassy events, + - router invokes, + - wallet transactions. + +#### Таблиці: + +(опціонально) + +- `usage_agent_runs` +- `usage_llm` +- `usage_storage` +- `usage_router` + +Або ж використовує event-driven pipeline. + +--- + +### 4.14 Outbox Worker + +#### Відповідальність: + +- читання `outbox_events` з БД; +- публікація у NATS; +- маркування `processed`. + +#### Таблиця: + +- `outbox_events` + +--- + +### 4.15 Telemetry / Logs Service + +#### Відповідальність: + +- прийом логів з фронтенду, +- прийом internal logs, +- агрегація в аналітичні стріми. + +#### Events: + +- `telemetry.client.event` +- `telemetry.error` +- `telemetry.screen_view` + +--- + +### 4.16 Auth / Session Service + +#### Відповідальність: + +- login, +- OTP/Magic-link, +- session cookies. + +#### Таблиці: + +- `sessions` (опціонально) + +--- + +### 4.17 File Storage / Docs Service + +#### Відповідальність: + +- завантаження файлів у каналах, +- документи, +- архіви, +- прев'ю. + +Технічно: + +- Minio/S3 + Postgres references. + +--- + +## 5. Dependency Graph + +Умовний граф залежностей: + +``` +User/Team → Messaging → Projects/Tasks → Agents → Router + ↓ ↓ ↓ + RWA Wallet Embassy + ↓ ↓ ↓ + Oracle → Usage → Governance → PDP +``` + +Простіший вигляд: + +``` +API Gateway (PEP) + ↓ PDP + ↓ +Internal Services + ↓ +DB + NATS +``` + +--- + +## 6. Internal API Standards + +Всі внутрішні сервіси мають: + +- JSON-only API, +- версію `/internal/v1/...`, +- заборона на виклик ззовні (тільки з Gateway), +- сервісні ключі (internal service key), +- PDP перевіряє **internal capabilities**: + - `service.mint.payout` + - `service.write.oracles` + - `service.update.capabilities` + - `service.read.internal_logs` + +--- + +## 7. Horizontal Scaling Responsibilities + +### Stateless services: + +- Messaging +- Projects/Tasks +- Embassy Gateway +- Telemetry +- Router/Planner (частково) +- LLM Proxy + +### Stateful services: + +- Wallet +- RWA +- Governance +- Capability Registry +- Usage Service (підрахунок) + +--- + +## 8. Event Streams (NATS Topics) + +**chat.*** + +**project.*** + +**task.*** + +**agent.run.*** + +**embassy.*** + +**oracle.*** + +**rwa.inventory.*** + +**wallet.*** + +**governance.*** + +**usage.*** + +**telemetry.*** + +--- + +## 9. Outbox Pattern (Mandatory) + +Всі сервіси, що створюють події: + +- пишуть у `outbox_events (processed=false)`, +- Outbox Worker публікує у NATS, +- записує `processed=true`. + +Це гарантує **at-least-once delivery**. + +--- + +## 10. Cross-service Transaction Rules + +Дозволені: + +- DB transaction → outbox insert → commit +- Outbox Worker → publish event + +Заборонені: + +- DB transaction → direct NATS publish → commit +- Cross-service DB транзакції + +--- + +## 11. Security Boundaries + +| Service | Sensitive? | Notes | +| ------------------- | ---------- | ------------------------- | +| Wallet | HIGH | Chain operations, payouts | +| Embassy | HIGH | RWA, energy events | +| Capability Registry | HIGH | controls all access | +| Governance | HIGH | updates policies | +| Usage | MEDIUM | affects quotas | +| Agents | MEDIUM | potential abuse | +| Messaging | MEDIUM | privacy | +| Router | HIGH | tool access | +| LLM Proxy | HIGH | cost centre | + +--- + +## 12. Suggested Deployment Model + +### Option A — Modular Monolith (MVP) + +Окремі модулі всередині одного репозиторію. + +Переваги: + +- мінімальні затрати, +- простий деплой, +- контроль consistency. + +### Option B — Microservices (Prod-Scale) + +Розділяються: + +- Wallet, +- Embassy, +- Router, +- LLM Proxy, +- Agent Orchestrator, +- Messaging, +- Projects, +- Governance, +- Capability Registry, +- Usage. + +--- + +## 13. Failure Isolation + +Сервіс повинен не ламати інших. + +Наприклад: + +- Wallet падає → Messaging працює далі. +- Embassy перевантажений → Agent Runs працюють. +- Router overloaded → Wallet стабільний. + +Це досягається: + +- NATS, +- independent autoscaling, +- clear API boundaries. + +--- + +## 14. Minimal Monitoring Set per Service + +Для кожного: + +- CPU/Memory +- Requests/sec +- Error rate +- Latency +- DB queries +- NATS event lag +- Circuit breaker status +- Quota usage + +--- + +## 15. Integration with Other Docs + +Цей документ доповнює: + +- `33_api_gateway_security_and_pep.md` +- `32_policy_service_PDP_design.md` +- `29_scaling_and_high_availability.md` +- `28_flows_wallet_embassy_energy_union.md` +- `27_database_schema_migrations.md` + +--- + +## 16. Завдання для Cursor + +```text +You are a senior backend architect. Design internal services architecture using: +- 34_internal_services_architecture.md +- 33_api_gateway_security_and_pep.md +- 32_policy_service_PDP_design.md + +Tasks: +1) Create service interfaces for all 17 services. +2) Define internal API contracts. +3) Implement Outbox Worker for event publishing. +4) Set up NATS event streams for all services. +5) Create service discovery mechanism (if microservices). +6) Implement cross-service communication patterns. +7) Add monitoring and observability for each service. + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 17. Summary + +Цей документ задає основу: + +- хто за що відповідає, +- які дані де живуть, +- які події кожен сервіс генерує, +- як сервіси взаємодіють, +- де потрібна строгість ACID, +- як працює event-driven архітектура, +- де є stateful точки опори. + +Це ключова частина всієї backend-карти міста. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/35_microdao_service_mesh_design.md b/docs/cursor/35_microdao_service_mesh_design.md new file mode 100644 index 00000000..adf4e8fc --- /dev/null +++ b/docs/cursor/35_microdao_service_mesh_design.md @@ -0,0 +1,517 @@ +# 35 — MicroDAO Service Mesh Design (MicroDAO) + +*Арова архітектура сервіс-меш, резолюція сервісів, мережеві політики, zero-trust, observability, retries, autoscaling та інженерні стандарти для DAARION.city / microDAO* + +--- + +## 1. Purpose & Scope + +MicroDAO Service Mesh — це внутрішня мережна платформа, що забезпечує: + +- безпечний виклик сервісів через **zero-trust** модель; +- внутрішнє балансування навантаження; +- автоматичне перез'єднання; +- контроль трафіку; +- observability (metrics / traces / logs); +- резолюцію сервісів та політики доступу; +- fault tolerance (retries, circuit breakers, rate limits). + +Цей документ — обов'язковий для: + +- backend-інженерів, +- DevOps/SRE, +- авторів внутрішніх сервісів, +- security-аудиторів. + +--- + +## 2. High-Level Mesh Architecture + +``` + ┌────────────────────────────────┐ + │ API Gateway (PEP) │ + └────────────────┬───────────────┘ + │ + ┌──────────────────┴─────────────────┐ + │ SERVICE MESH FABRIC │ + └─────────────┬─────────────┬────────┘ + │ │ + ┌─────────────────┘ └──────────────────┐ + Internal Services System Services +``` + +Основу складають: + +- Service Registry +- Sidecar Proxy (Envoy / Linkerd / Traefik Mesh) +- mTLS між сервісами +- Observability pipeline +- Traffic control (retries, timeouts, circuit breakers) + +--- + +## 3. Zero-Trust Model + +Платформа працює за правилом: + +```text +НІЯКІ ВНУТРІШНІ СЕРВІСИ НЕ ДОВІРЯЮТЬ ОДИН ОДНОМУ. +``` + +Тому кожен запит: + +- автентифікується, +- авторизується через PDP, +- шифрується, +- логуються метадані. + +### 3.1 Trust Boundaries + +| Boundary | Policy | +| ------------------ | ----------------------- | +| Gateway → Services | PDP enforced | +| Service → Service | mTLS + service identity | +| Service → DB | minimal DB roles | +| Service → NATS | per-stream permissions | + +--- + +## 4. Service Identity (mTLS) + +Кожен сервіс отримує власну сертифікацію: + +```text +CN = service_name +SAN = service_name.namespace.svc +``` + +mTLS забезпечує: + +- автентифікацію сервісу, +- заборону spoofing, +- шифрування трафіку. + +--- + +## 5. Service Registry + +Mesh потребує **централізованого каталогу сервісів**: + +```json +{ + "service": "wallet", + "host": "wallet.svc.cluster.local", + "port": 8081, + "metadata": { + "team": "core", + "version": "v1.4.0", + "zone": "eu-central-1" + } +} +``` + +У cloud-середовищі це зазвичай: + +- Kubernetes DNS, +- або Consul, +- або власний registry. + +--- + +## 6. Internal Service-to-Service Traffic + +### 6.1 Pattern + +```text +serviceA → Envoy Sidecar → Mesh → Envoy Sidecar → serviceB +``` + +### 6.2 Benefits + +- automatic retries, +- circuit breaking, +- mTLS, +- observability, +- fine-grained routing, +- traffic shadowing. + +--- + +## 7. Core Service Mesh Features + +### 7.1 mTLS Encryption + +- Усі внутрішні запити шифровані. +- Certificates rotate every 12–48 hours. + +### 7.2 Load Balancing (Layer 7) + +- round-robin, +- least_conn, +- locality-aware routing. + +### 7.3 Retries + +- max 3, +- exponential backoff, +- jitter. + +### 7.4 Circuit Breakers + +При перевантаженні: + +- mesh відкриває circuit → запити йдуть у failfast, +- після cooling-off — пробує відновити. + +### 7.5 Timeouts + +- default timeout: 3 seconds, +- wallet, embassy: 1 second (short to avoid blocking), +- agent runs: 10–60 seconds (handled separately). + +--- + +## 8. Internal API Standard (Mesh Requirements) + +Кожен сервіс має відповідати стандарту: + +- JSON over HTTP (no gRPC unless planned), +- `/internal/v1//`, +- атомарні операції, +- 4xx для клієнтських помилок, +- 5xx для сервісних. + +Приклад: + +```text +POST /internal/v1/wallet/payout/claim +POST /internal/v1/embassy/energy/update +POST /internal/v1/agent/run +``` + +--- + +## 9. PDP Integration (per-service) + +PEP живе тільки у API Gateway, але Services повинні: + +1. не довіряти payload, навіть після PDP → додаткова валідація; +2. виконувати DB-level ACL checks; +3. мутуючі операції мають виконуватись тільки через Gateway. + +**Жоден сервіс не приймає зовнішній трафік напряму.** + +--- + +## 10. Mesh-Level Policies + +### 10.1 Allow-lists + +Кожен сервіс може викликати тільки перелік інших сервісів: + +| Service | Allowed to Call | +| ------------------ | ----------------------------- | +| Messaging | Usage, Storage | +| Agent Orchestrator | LLM Proxy, Usage | +| Embassy | RWA, Usage | +| Wallet | Chain RPC, Usage | +| Router | Agent Orchestrator, LLM Proxy | +| RWA | Wallet, Usage | + +### 10.2 Deny-lists + +Забезпечує Zero-Trust: + +- Messaging → No direct Wallet access +- Agents → No direct RWA access +- Embassy → No direct Wallet claim +- Router → No low-level DB access + +--- + +## 11. Observability Model + +Mesh забезпечує повну видимість. + +### 11.1 Metrics + +- latency (p50, p95, p99), +- HTTP codes, +- retry count, +- circuit breaker events, +- request sizes, +- traffic spikes. + +### 11.2 Tracing + +Підтримується: + +- OpenTelemetry, +- distributed tracing (trace_id, span_id), +- propagation через Gateway → Mesh → Services → DB → NATS. + +### 11.3 Logs + +Збираються: + +- access logs, +- error logs, +- mesh-level logs. + +--- + +## 12. Failover & Resilience + +### 12.1 Multi-zone (Cloud) + +Mesh обирає найближчий healthy інстанс. + +### 12.2 Zonal Failover + +При провалі зони: + +- трафік автоматично перенаправляється в інші зони. + +### 12.3 Service Healthchecks + +- `livenessProbe`: чи не висить процес. +- `readinessProbe`: чи сервіс готовий приймати трафік. + +--- + +## 13. Mesh Traffic Rules for Critical Services + +### 13.1 Wallet Service + +- low timeout (1 sec) +- retries: 0 (щоб не дублювати транзакції) +- circuit-breaker sensitivity: high + +### 13.2 Embassy + +- retries: 1 +- timeout: 0.5 sec +- global rate limiting: + - embassy bursts можуть спричинити навантаження + +### 13.3 Agent Orchestrator + +- long timeout (10–60 sec) +- retries: none (idempotency?) +- dedicated queue routing + +### 13.4 Router/DAARWIZZ + +- timeout: 5–15 sec +- retries: 1–2 +- concurrency caps + +--- + +## 14. Service Mesh Security + +### 14.1 mTLS Everywhere + +- між усіма сервісами обов'язково. + +### 14.2 Internal Service Keys + +Кожен сервіс має: + +- `service_key`, +- capability: + + ```text + service.write.oracles + service.mint.payout + service.agent.run + service.read.usage + ``` + +- PDP авторизація на рівні сервісів. + +### 14.3 No direct DB access (where possible) + +Сервіси мають мінімальні ролі DB. + +### 14.4 Network Policies + +Забороняють: + +- доступ між сервісами, що не пов'язані функціонально, +- будь-які вихідні запити (egress) без дозволу. + +--- + +## 15. Deployment Model + +### 15.1 Sidecar Mode + +Рекомендовано: + +- Envoy sidecar у кожному pod, +- mesh контролер керує routing tables. + +### 15.2 Node-agent Mode (Alternative) + +- не потрібні sidecars, +- менше накладних витрат, +- простіше управління. + +### 15.3 Observability stack + +- Prometheus, +- Grafana, +- Loki (або Cloud Logging), +- Jaeger / Tempo. + +--- + +## 16. Service Mesh Integration with Scaling + +### 16.1 Auto-discovery + +Нові інстанси автоматично реєструються. + +### 16.2 Load-aware routing + +Mesh відправляє запити на: + +- найменш завантажені інстанси, +- локальні (в межах зони). + +### 16.3 Autoscaling Signals + +Mesh збирає: + +- CPU, +- memory, +- request rate, +- errors, +- queue depth (for agents). + +--- + +## 17. Message Patterns + +### 17.1 Request-Response + +Звичайні виклики: + +- Messaging +- Projects +- Wallet reads + +### 17.2 Asynchronous Events + +Через NATS: + +- payouts, +- RWA updates, +- agent events + +### 17.3 Long-running tasks + +Через Agent Orchestrator: + +- LLM chain-of-thought, +- multi-step flows. + +--- + +## 18. Example Mesh Policy Config (Illustrative) + +```yaml +# service: wallet +allow: + - usage + - chain_rpc +deny: + - messaging + - router + - embassy + +timeouts: + request: 1s + +retries: + enabled: false + +mTLS: required +``` + +```yaml +# service: embassy +allow: + - rwa + - usage +deny: + - wallet + - agent + - router + +mTLS: required +rate_limit: 500/min +``` + +--- + +## 19. Integration with Other Docs + +Цей документ доповнює: + +- `34_internal_services_architecture.md` +- `33_api_gateway_security_and_pep.md` +- `32_policy_service_PDP_design.md` +- `29_scaling_and_high_availability.md` +- `26_security_audit.md` + +--- + +## 20. Завдання для Cursor + +```text +You are a senior DevOps/SRE engineer. Implement Service Mesh using: +- 35_microdao_service_mesh_design.md +- 34_internal_services_architecture.md +- 29_scaling_and_high_availability.md + +Tasks: +1) Set up Service Registry (Kubernetes DNS or Consul). +2) Configure mTLS for all services. +3) Implement Envoy sidecar proxies (or node-agent mode). +4) Set up mesh-level policies (allow-lists, deny-lists). +5) Configure retries, timeouts, circuit breakers. +6) Integrate with observability stack (Prometheus, Grafana, Loki, Jaeger). +7) Set up health checks for all services. +8) Configure load balancing and failover. +9) Implement network policies for zero-trust. + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 21. Summary + +MicroDAO Service Mesh забезпечує: + +- захищені зв'язки між сервісами, +- шифрування всього внутрішнього трафіку, +- централізоване управління політиками, +- fault tolerance, +- трасування, +- динамічну маршрутизацію, +- стійкість до збоїв. + +Це «нервова система» DAARION.city, яка дозволяє системі масштабуватися й залишатися безпечною при зростанні навантаження та сервісів. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/36_agent_runtime_isolation_and_sandboxing.md b/docs/cursor/36_agent_runtime_isolation_and_sandboxing.md new file mode 100644 index 00000000..215a688e --- /dev/null +++ b/docs/cursor/36_agent_runtime_isolation_and_sandboxing.md @@ -0,0 +1,500 @@ +# 36 — Agent Runtime Isolation & Sandboxing (MicroDAO) + +*Безпечна ізоляція приватних агентів, sandbox-модель, інструменти, обмеження доступу, мережеві політики, memory policy, E2EE, PDP/PEP інтеграція* + +--- + +## 1. Purpose & Scope + +Агенти — найбільш потужний і найбільш небезпечний компонент DAARION.city. + +Цей документ визначає: + +- як виконується код/логіка агентів, +- які гарантії безпеки надані, +- як працює sandbox, +- які дії дозволені/заборонені, +- як працює інтеграція з PDP, +- які інструменти agent може використовувати, +- як запобігти «втечі із sandbox» і зловживанням, +- як працює memory / summarization у приватних і confidential контекстах. + +--- + +## 2. Threat Model + +### 2.1 Загрози від агента + +- перегляд приватних даних користувача, +- надмірні виклики LLM (cost explosion), +- шкідливі інструкції (prompt injection), +- доступ до чужих команд, +- маніпуляція гаманцем, +- неконтрольований код (плагін, tool), +- «втеча» в мережу, +- створення небезпечних запитів до Embassy/Wallet. + +### 2.2 Загрози для агента + +- обмеження через PDP, +- відсутність доступу до plaintext у confidential mode, +- можливі rate-limits, +- відключення інструментів. + +--- + +## 3. Agent Runtime Architecture + +``` +User/Team → API Gateway (PEP) → Agent Orchestrator → Agent Runtime Sandbox → LLM/Tools +``` + +Агент виконується в **ізольованому контейнері/воркері**, який: + +- обмежений у CPU/RAM, +- не має доступу до файлової системи поза sandbox, +- не має прямого мережевого доступу, +- не має доступу до БД, +- має доступ тільки до дозволених API через internal gateway. + +--- + +## 4. Sandbox Security Model + +### 4.1 Isolation Levels + +| Layer | Isolation | +| ---------- | ------------------------------------ | +| Process | кожен агент-run = окремий воркер | +| Filesystem | read-only FS, tmpfs для runtime | +| Network | за замовчуванням повністю відключена | +| Memory | очищується після кожного run | +| Tools | whitelisted | +| Logs | фільтруються, не містять plaintext | + +### 4.2 Namespaces / cgroups + +Sandbox використовує: + +- CPU limits, +- Memory limits, +- PID isolation, +- Network namespace, +- Seccomp (drop dangerous syscalls). + +### 4.3 Banned syscalls + +- `fork()` +- `execve()` (крім заздалегідь дозволених sandbox tools) +- `socket()` +- `mount` +- `open` (поза `/tmp/sandbox`) +- `ptrace` + +--- + +## 5. Network Policy + +### 5.1 Default: NO NETWORK + +Агенти НЕ можуть: + +- робити HTTP-запити в інтернет, +- дзвонити сторонні API, +- створювати сокети. + +### 5.2 Allowed network flows + +Дозволяється ТІЛЬКИ через internal gateway: + +| Target | Purpose | +| -------------------------- | ---------------- | +| `/internal/llm/chat` | LLM inference | +| `/internal/llm/embeddings` | embeddings | +| `/internal/router/*` | tool routing | +| `/internal/tools/*` | safe tools | +| `/internal/usage/*` | usage accounting | + +Sandbox не має прямого доступу до: + +- Wallet, +- Embassy, +- RWA, +- DB, +- Projects/Tasks, +- Messaging. + +Усе це виконується через Orchestrator (як посередник). + +--- + +## 6. Agent Permissions & PDP Integration + +Перед кожним запуском агента: + +```text +API Gateway → PDP → allow(agent.run.invoke) +``` + +Після цього Orchestrator створює sandbox-process. + +Всередині sandbox: + +- кожен виклик інструменту → PDP check: + + ```text + action = tool..invoke + ``` + +- якщо capability відсутня →拒否 (deny). + +--- + +## 7. Tools Architecture + +Tools = «дозволені інструменти» для агента. + +### 7.1 Types of Tools + +| Tool | Доступ | Ризик | +| ------------- | -------------- | -------- | +| math | локальний | низький | +| calendar | internal | низький | +| browser-lite | internal proxy | середній | +| code-executor | sandboxed | високий | +| memory | індексація | низький | +| search-lite | internal | середній | + +### 7.2 Tool Execution Model + +```text +Agent → Sandbox → Tool Proxy → Allowed internal API +``` + +### 7.3 Tool Security Rules + +- кожен tool має максимум runtime (timeout), +- memory cap, +- супутні rate-limits, +- PDP capability: `tool..invoke`. + +### 7.4 Dangerous Tools (Require Chief Approval) + +- browser (full internet), +- code execution with system calls, +- integration tools (webhooks, external calls). + +--- + +## 8. Agent Memory Model + +### 8.1 No persistent state (strict) + +Агенти не зберігають: + +- внутрішню пам'ять, +- plaintext історію, +- raw messages. + +Після виконання: + +- sandbox memory очищується, +- зберігається лише «summary» або «embeddings». + +### 8.2 Co-Memory Integration + +Агент може додавати summary у: + +- `comemory_items` + +- але не plaintext (особливо у confidential mode). + +### 8.3 Confidential Mode + +Якщо `team.mode == confidential`, агент: + +- НЕ бачить plaintext, +- отримує: + - embeddings, + - short summary, + - user roles, + - мінімальні метадані. + +--- + +## 9. Prompt Injection Protection + +На рівні Orchestrator: + +1. перевірка вводу користувача; +2. escaping of dangerous sequences; +3. instruction boundary: + + ```text + system: "Агент працює ТІЛЬКИ в дозволених межах." + ``` + +4. розділення user-prompts і instructions; +5. sandbox-level enforced policy. + +--- + +## 10. Runtime Limits + +### 10.1 CPU + +- 0.2–1 vCPU на агент-run. + +### 10.2 Memory + +- 256–1024 MB. + +### 10.3 Timeout + +- 60–300 секунд (залежно від plan/role). + +### 10.4 Parallel Agents + +Залежить від: + +- плану, +- стейку RINGK, +- governance policy. + +Приклад: + +```text +Freemium: max_parallel_runs = 1 +Casual: 2–3 +Premium: 5–10 +Platformium: 10–20 +``` + +--- + +## 11. File System Policy + +- read-only root FS, +- дозволено: + - `/tmp/sandbox` — ephemeral, +- не дозволено: + - читання системних файлів, + - запис поза `/tmp`, + - файлові операції, що залишають слід. + +--- + +## 12. Logging Policy + +Агентні логи: + +- не зберігають plaintext, +- не містять особистих даних, +- маскують небезпечні інструкції, +- зберігаються до 24–72 год (configurable), +- використовуються для debugging. + +--- + +## 13. Chain-of-Thought Protection + +Runtime приховує: + +- reasoning chain, +- проміжні кроки LLM, +- внутрішні підказки. + +LLM отримує: + +- системну інструкцію, +- узгоджені інструментальні виклики, +- стислі контексти. + +--- + +## 14. Deny-List Rules + +Sandbox не дозволяє: + +- зовнішні HTTP виклики, +- довільний TCP/UDP, +- відкриття файлів поза temp-сферою, +- доступ до DB, +- виконання shell команд, +- spawn процесів, +- код поза дозволеним toolset. + +--- + +## 15. Escalation Prevention + +### 15.1 Capability Escalation + +- agent keys мають capabilities, що жорстко обмежені: + - `agent.run.invoke` + - `tool.*` + +### 15.2 Tool Escalation + +- немає можливості відкрити: + - wallet endpoints, + - governance endpoints, + - embassy endpoints. + +### 15.3 API Escalation + +- agent sandbox не може викликати: + - `/internal/wallet/*` + - `/internal/embassy/*` + - `/internal/rwa/*` + - `/internal/projects/*` + - `/internal/messages/*` + +--- + +## 16. Governance Hooks for Agents + +Governance дозволяє налаштовувати: + +- максимальну кількість агентів, +- доступні інструменти, +- тайм-ліміти, +- cost per run, +- доступні потужності (через stake RINGK), +- whitelist/blacklist tools. + +--- + +## 17. Observability + +### 17.1 Metrics + +- number of runs, +- tokens used, +- average runtime, +- tool usage, +- error rate. + +### 17.2 Tracing + +- кожен run: + - trace_id, + - span_id, + - parent_id. + +### 17.3 Logs + +- agent-run logs per run, +- sampled/error-prone runs зберігаються довше. + +--- + +## 18. Agent Cost Control + +Механізм, описаний у Document 30: + +- облік compute (1T), +- ліміти per plan & stake RINGK, +- cost estimates до старту, +- hard cap. + +Example cost policy: + +```text +max_cost_per_run = 0.02 1T +max_cost_per_day = 0.5 1T +``` + +--- + +## 19. Failure Modes + +### 19.1 Infinite loops + +Sandbox має: + +- max compute instructions, +- max steps, +- timeout. + +### 19.2 Crash / OOM Kill + +Orchestrator: + +- маркує run як failed, +- додає подію `agent.run.failed`. + +### 19.3 Network abuse + +Неможливе через strict firewall. + +### 19.4 Prompt takeover + +Захищено instruction boundary. + +--- + +## 20. Integration with Other Docs + +Цей документ доповнює: + +- `12_agent_runtime_core.md` +- `13_agent_memory_system.md` +- `30_cost_optimization_and_token_economics_infrastructure.md` +- `32_policy_service_PDP_design.md` +- `33_api_gateway_security_and_pep.md` +- `26_security_audit.md` + +--- + +## 21. Завдання для Cursor + +```text +You are a senior backend engineer. Implement Agent Runtime Isolation & Sandboxing using: +- 36_agent_runtime_isolation_and_sandboxing.md +- 12_agent_runtime_core.md +- 32_policy_service_PDP_design.md + +Tasks: +1) Create sandbox environment with process isolation (cgroups, namespaces). +2) Implement network policy (default deny, allow-list for internal APIs). +3) Set up filesystem policy (read-only root, tmpfs for /tmp/sandbox). +4) Implement syscall filtering (seccomp, banned syscalls). +5) Create tool proxy system for safe tool execution. +6) Integrate PDP checks for tool invocations. +7) Implement memory cleanup after each run. +8) Add prompt injection protection. +9) Set up runtime limits (CPU, memory, timeout). +10) Implement logging policy (no plaintext, masking). +11) Add observability (metrics, tracing, logs). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 22. Summary + +Модель безпеки Agent Runtime гарантує: + +- повну ізоляцію кожного агентного run, +- безпечні інструменти, +- zero-trust доступ до внутрішніх сервісів, +- E2EE сумісність confidential mode, +- контроль compute-витрат, +- відсутність витоку даних від команд до команд, +- неможливість ескалації доступів, +- захист від prompt injection, +- детальну observability. + +Агенти перетворюються з «небезпечної чорної скриньки» у **контрольовану, передбачувану, економічно-керовану частину DAARION OS**. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/37_agent_tools_and_plugins_specification.md b/docs/cursor/37_agent_tools_and_plugins_specification.md new file mode 100644 index 00000000..f4261a14 --- /dev/null +++ b/docs/cursor/37_agent_tools_and_plugins_specification.md @@ -0,0 +1,458 @@ +# 37 — Agent Tools & Plugins Specification (MicroDAO) + +*Докладна специфікація інструментів агентів, категорій безпеки, API-викликів, plugins lifecycle, capability-кодів, sandbox-контрактів та інтеграції через DAARION Tool Fabric* + +--- + +## 1. Purpose & Scope + +Документ визначає: + +- повний список підтримуваних інструментів (tools), +- категорії інструментів за рівнями безпеки, +- правила використання, +- Plugins API (розширюваність), +- інтерфейс між агентом та Tool Proxy, +- capability-коди, +- сповіщення / події, +- обмеження (timeouts, rate limits, isolation), +- як підключаються інструменти DAARION Platforms (EnergyUnion, GREENFOOD, Water Union), +- як працюють інструменти в confidential mode. + +--- + +## 2. Architectural Overview + +``` +Agent → Sandbox Runtime → Tool Proxy → Internal Services → DB/NATS +``` + +Ключові компоненти: + +- **Tool Proxy** — єдина точка доступу агентів до інструментів. +- **PDP** — перевіряє `tool..invoke`. +- **Sandbox** — обмежує ресурси. +- **Plugins API** — дозволяє додавати нові інструменти без ризиків. + +--- + +## 3. Tool Security Categories + +Інструменти діляться на 4 категорії: + +### 3.1 Category A — Safe Tools (default-enabled) + +Не мають доступу до зовнішньої мережі, не можуть виконувати код. + +| Tool | Capability | Опис | +| ---------- | ---------------------- | ------------------------------- | +| math | tool.math.invoke | базові обчислення | +| text | tool.text.invoke | форматування тексту | +| memory | tool.memory.invoke | створення коротких summary | +| embeddings | tool.embeddings.invoke | генерація embedding'ів | +| calendar | tool.calendar.invoke | маніпуляції з датами/таймзонами | + +### 3.2 Category B — Controlled Tools (internal-only) + +Працюють тільки через internal APIs. + +| Tool | Capability | Доступ | +| ------------ | ------------------------ | -------------------------------- | +| search-lite | tool.search.invoke | внутрішній пошук | +| browser-lite | tool.browser_lite.invoke | обмежений перегляд HTML (без JS) | +| file | tool.file.invoke | читання з internal storage | +| project | tool.project.invoke | створення/оновлення проектів | +| task | tool.task.invoke | створення/оновлення задач | + +### 3.3 Category C — Sensitive Tools (restricted) + +Вимагають додаткових capability. + +| Tool | Capability | Опис | +| ---------- | ---------------------- | ------------------------------------- | +| router | tool.router.invoke | взаємодія з DAARWIZZ Router | +| llm | tool.llm.invoke | прямі виклики LLM (через токен-квоти) | +| agent | tool.agent.invoke | виклик іншого агента | +| data.query | tool.data_query.invoke | запити до структурованих даних | + +### 3.4 Category D — Critical Tools (governance-only) + +Потребують схвалення Governance. + +| Tool | Capability | Ризик | +| ------------ | ------------------------ | ---------------------------------------------- | +| browser-full | tool.browser_full.invoke | доступ до інтернету | +| external_api | tool.external_api.invoke | сторонні API | +| chain | tool.chain.invoke | ончейн-транзакції | +| platform | tool.platform.invoke | доступ до платформ DAARION (energy/food/water) | + +--- + +## 4. Tool Capability Model + +Кожен інструмент має capability: + +```text +tool..invoke +``` + +При запуску: + +```text +Agent Runtime → Tool Proxy → PDP(authorize) +``` + +Якщо capability відсутній → deny. + +--- + +## 5. Tool Execution Contract + +### 5.1 Request Format + +```json +{ + "tool": "browser_lite", + "args": { + "url": "...", + "max_bytes": 200000 + }, + "context": { + "agent_run_id": "ar_123", + "team_id": "t_555" + } +} +``` + +### 5.2 Response Format + +```json +{ + "ok": true, + "output": "... sanitized result ...", + "tokens_used": 123, + "cost_1t": 0.00002 +} +``` + +--- + +## 6. Tool Proxy Rules + +### 6.1 All Calls Go Through Proxy + +Агент не має прямого доступу до: + +- внутрішніх сервісів, +- БД, +- зовнішнього інтернету. + +### 6.2 PDP Check + +Перед кожним викликом: + +```text +PDP(action=tool..invoke) +``` + +### 6.3 Usage Accounting + +Tool Proxy інкрементує usage: + +- tokens (LLM), +- compute units, +- tool invocations per day. + +--- + +## 7. Timeouts & Limits per Category + +| Category | Timeout | Rate Limit | Notes | +| -------- | ------- | ---------- | --------------- | +| A | 1–2s | high | безпечні | +| B | 1–3s | medium | тільки internal | +| C | 3–5s | low | квоти/обмеження | +| D | 5–10s | very low | governance-only | + +--- + +## 8. Plugins API (Extensible Tools) + +Plugins дозволяють стороннім розробникам або платформам додавати нові інструменти. + +### 8.1 Plugin Manifest + +```json +{ + "name": "greenfood.order", + "version": "1.0.0", + "entry": "plugin.js", + "capabilities": [ + "tool.greenfood.order.invoke" + ], + "permissions": { + "network": false, + "filesystem": false, + "internal_api": ["greenfood"] + } +} +``` + +#### Allowed fields: + +- `name` +- `version` +- `entry` +- `capabilities` +- `permissions` + +--- + +### 8.2 Plugin Execution Flow + +```text +Agent → Tool Proxy → Plugin Runtime → Internal Service +``` + +#### Plugin Runtime: + +- запускається в окремому mini-sandbox, +- має read-only FS, +- немає network, +- отримує контекст: + - agent_run_id, + - team_id, + - capability list. + +--- + +### 8.3 Plugin Security Model + +- Plugins НЕ отримують plaintext повідомлень. +- Plugins НЕ бачать user session. +- Plugins НЕ можуть: + - запускати shell, + - читати файл-систему, + - робити сторонні HTTP-запити. + +--- + +## 9. Built-in Tools (Full List) + +### 9.1 Core Tools (Category A) + +- math +- date +- calendar +- text +- memory +- embeddings +- table +- format + +### 9.2 Internal Tools (Category B) + +- project +- task +- file.storage +- search-lite +- browser-lite + +### 9.3 Advanced Tools (Category C) + +- llm +- router +- agent +- data.query + +### 9.4 Platform Tools (Category D) + +- platform.energy +- platform.food +- platform.water +- chain (controlled by Wallet) +- external_api (disabled by default) + +--- + +## 10. Platform Tool Contracts (EnergyUnion, GREENFOOD) + +### 10.1 GREENFOOD Tool + +```text +tool.greenfood.order.invoke +``` + +Allow: + +- створення замовлення, +- перегляд інвентарю продуктів. + +Deny: + +- змінювати ціни, +- модифікувати склад. + +Input: + +```json +{ + "tool":"greenfood.order", + "args": { "product_id":"...", "qty":1 } +} +``` + +Output: + +```json +{ + "order_id": "...", + "status":"created" +} +``` + +--- + +### 10.2 EnergyUnion Tool + +```text +tool.energy.meter.read +``` + +Allow: + +- читати дані енергетики через Embassy. + +Deny: + +- оновлювати RWA дані. + +Output: + +```json +{ + "kwh": 123.5, + "timestamp": "..." +} +``` + +--- + +## 11. Confidential Mode — Tool Restrictions + +Якщо канал або команда має `confidential`: + +- Tools НЕ отримують plaintext. +- browser-lite додає redaction: + + ```text + [confidential section removed] + ``` + +- memory-tool зберігає тільки summary (не raw). + +--- + +## 12. Error Model + +Tool Proxy повертає структуровані помилки: + +| Code | Meaning | +| ----------------------- | -------------------- | +| tool_capability_missing | агент не має прав | +| tool_timeout | перевищено час | +| tool_restricted | заборонене в режимі | +| tool_invalid_args | некоректні аргументи | +| tool_sandbox_violation | порушено правила | +| tool_internal_error | помилка сервісу | + +--- + +## 13. Auditing & Logging + +- запис кожного tool invocation: + - tool name, + - agent_run_id, + - tokens used, + - duration, + - result (ok/error). + +- plaintext не зберігається. + +--- + +## 14. Governance Hooks + +Governance може: + +- вимикати/вмикати інструменти, +- змінювати rate limits, +- вимагати додатковий stake RINGK для категорії C/D, +- додавати або видаляти платформні інструменти, +- регулювати доступ до GreenFood/EnergyUnion. + +--- + +## 15. Integration with Other Docs + +Цей документ доповнює: + +- `36_agent_runtime_isolation_and_sandboxing.md` +- `12_agent_runtime_core.md` +- `32_policy_service_PDP_design.md` +- `31_governance_policies_for_capabilities_and_quotas.md` +- `DAARION_city_platforms_catalog.md` + +--- + +## 16. Завдання для Cursor + +```text +You are a senior backend engineer. Implement Agent Tools & Plugins system using: +- 37_agent_tools_and_plugins_specification.md +- 36_agent_runtime_isolation_and_sandboxing.md +- 32_policy_service_PDP_design.md + +Tasks: +1) Create Tool Proxy service. +2) Implement tool categories (A, B, C, D) with security rules. +3) Create tool execution contract (request/response format). +4) Integrate PDP checks for tool invocations. +5) Implement built-in tools (math, text, memory, embeddings, calendar, project, task, etc.). +6) Create Plugins API (Plugin Manifest, Plugin Runtime, Plugin Security Model). +7) Implement platform tool contracts (GREENFOOD, EnergyUnion). +8) Add confidential mode restrictions for tools. +9) Implement error model and auditing/logging. +10) Add governance hooks for tool management. + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 17. Summary + +Ця специфікація формує: + +- повний набір інструментів, +- безпечну модель доступу, +- zero-trust взаємодію, +- механізм розширення через Plugins, +- жорстку ізоляцію, +- чіткі capability-коди, +- контроль вартості (compute cost), +- сумісність із confidential режимом, +- інтеграцію з PDP/PEP, +- можливість підключення платформ DAARION через безпечні tool-plugins. + +Це — **DAARION Tool Fabric**, центральна платформа інструментів агентів. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/38_private_agents_lifecycle_and_management.md b/docs/cursor/38_private_agents_lifecycle_and_management.md new file mode 100644 index 00000000..1a5caa9b --- /dev/null +++ b/docs/cursor/38_private_agents_lifecycle_and_management.md @@ -0,0 +1,486 @@ +# 38 — Private Agents Lifecycle & Management (MicroDAO) + +*Життєвий цикл приватних агентів, створення, конфігурація, ключі доступу, capability-політики, оновлення, відновлення, видалення, безпечний аудит* + +--- + +## 1. Purpose & Scope + +Цей документ описує **повний життєвий цикл приватного агента**: + +- створення +- реєстрація та ініціалізація +- конфігурація +- генерація ключів +- робота та інвокації +- оновлення моделі +- облік пам'яті +- логування +- безпека +- призупинення +- видалення + +Це must-have документ для: + +- core backend, +- agent orchestrator team, +- security team, +- governance, +- app UI. + +--- + +## 2. What Is a Private Agent? + +Приватний агент — це: + +```text +Індивідуальний асистент, прив'язаний до: +- користувача або +- команди (microDAO) +``` + +Має: + +- власну конфігурацію, +- власні ключі доступу, +- власні capabilities, +- власні usage-ліміти, +- власний sandbox, +- окремі логи, +- окремий vault для embedding-based memory. + +--- + +## 3. Agent Types + +1. **User Agent** + - створений для конкретного користувача + - ключ: `ak_agent_u_*` + +2. **Team Agent (microDAO)** + - належить команді + - доступ має Owner/Guardian + - ключ: `ak_agent_t_*` + +3. **System Agent** + - глобальні агенти DAARION + - ключ: `ak_agent_sys_*` + +--- + +## 4. Agent Creation Flow + +Sequence: + +```mermaid +sequenceDiagram + participant U as User + participant G as API Gateway + participant PDP + participant A as Agent Orchestrator + participant DB + + U->>G: POST /agents/create {type, name} + G->>PDP: authorize(agent.create) + PDP-->>G: allow + G->>A: create_agent_request + A->>DB: INSERT INTO agents (...) + DB-->>A: agent_id + A->>DB: INSERT INTO access_keys (ak_agent_123) + A-->>G: agent_created + G-->>U: {agent_id, key_id} +``` + +--- + +## 5. Agent Schema (DB) + +```sql +create table agents ( + id text primary key, + team_id text, + owner_user_id text, + name text, + description text, + llm_model text, -- default model + config jsonb, -- toolsets, behavior, limits + created_at timestamptz, + updated_at timestamptz, + archived bool default false +); +``` + +--- + +## 6. Agent Initialization (Bootstrap) + +### Під час створення агент отримує: + +- capabilities: + + ```text + agent.run.invoke + agent.read.summary + tool..* (math, text, memory, embeddings) + ``` + +- планові ліміти: + - max_runs_per_day (залежить від плану) + - max_cost_per_run + +- sandbox контракти: + - cpu/memory/timeouts + +- default LLM model (team default або global default) + +--- + +## 7. Agent Access Keys + +### Генерується 1 або більше ключів: + +```text +ak_agent__ +``` + +З capability-наборами: + +- `agent.run.invoke` +- `tool.safe.*` +- (опціонально) `tool.internal.*` +- (опціонально) `tool.llm.invoke` + +Ключ: + +- активний / призупинений / видалений +- має ttl (опціонально) +- може бути re-rotated + +--- + +## 8. Agent Configuration Model + +У таблиці `agents.config` зберігається JSON: + +```json +{ + "model": "gpt-4o-mini", + "system_prompt": "You are a private agent...", + "tools_allowed": ["math", "text", "memory"], + "max_tokens": 12000, + "max_parallel_runs": 2, + "sandbox_limits": { + "timeout_sec": 60, + "cpu": "0.5", + "memory": "512m" + } +} +``` + +### Governance може оновити: + +- `tools_allowed`, +- максимальні ліміти, +- доступ до категорії C/D tools. + +--- + +## 9. Agent Update Flow + +```mermaid +sequenceDiagram + participant U + participant G as Gateway + participant PDP + participant A as Orchestrator + participant DB + + U->>G: PATCH /agents/:id {config_changes} + G->>PDP: authorize(agent.update) + PDP-->>G: allow + G->>A: update_config + A->>DB: UPDATE agents SET config=... + DB-->>A: ok + A-->>G: updated + G-->>U: updated +``` + +--- + +## 10. Agent Run Lifecycle + +### 10.1 Start + +- Gateway перевіряє `agent.run.invoke`. +- Orchestrator створює новий запис у `agent_runs`. + +### 10.2 Sandbox Spin-Up + +Orchestrator: + +- створює sandbox, +- завантажує config.agents, +- створює контекст: + `agent_run_id`, `team_id`, `usage_counters`. + +### 10.3 Execute + +Sandbox: + +- бере prompt, +- запускає LLM chain, +- викликає дозволені інструменти, +- логування в окремий канал, +- memory summarization (опціонально). + +### 10.4 Complete + +Orchestrator: + +- пише результат у DB, +- публікує подію: + + ```text + agent.run.completed + ``` + +- повертає відповідь Gateway → користувачу. + +--- + +## 11. Agent Memory Policy + +### 11.1 No plaintext storage + +Агент не може зберігати raw messages. + +### 11.2 Memory via Summaries + +Дозволено: + +- короткі текстові summaries, +- embeddings vectors. + +Зберігаються в `comemory_items`. + +### 11.3 Team Confidentiality + +Якщо команда confidential: + +- агент не бачить повного контенту, +- працює з summary / embeddings. + +--- + +## 12. Agent Logs + +### 12.1 Stored logs + +Логи агента містять: + +- час виконання, +- chain-of-tools (але без plaintext), +- токени, що були використані, +- summarize input, +- summarize output. + +### 12.2 Retention + +- 24–72 години (залежно від плану), +- 7–30 днів для Platformium. + +### 12.3 Sensitive Log Filtering + +- вилучення prompt injection, +- маскування user secrets. + +--- + +## 13. Agent Suspension + +### Можливі статуси агента: + +- active +- suspended (порушення політик, надмірне використання) +- archived (неактивний) +- deleted + +### Suspension logic: + +- Governance / Owner може призупинити агента. +- Причини: + - перевищення квот, + - підозріла активність, + - небезпечні chain-of-actions. + +--- + +## 14. Agent Deletion Flow + +```mermaid +sequenceDiagram + participant U + participant G + participant PDP + participant A as Orchestrator + participant DB + + U->>G: DELETE /agents/:id + G->>PDP: authorize(agent.delete) + PDP-->>G: allow + G->>A: delete_agent + A->>DB: archive agent + A->>DB: revoke keys + A-->>G: deleted + G-->>U: deleted +``` + +### Deletion rules: + +- агент позначається `archived=true` (м'яке видалення), +- ключі відкликані, +- sandbox конфігурація очищується, +- логи зберігаються N днів. + +--- + +## 15. Agent Versioning + +Агенти мають версію: + +```text +agent.version.major.minor.patch +``` + +Оновлення можливе у 3 режимах: + +- **manual** (Owner/Guardian), +- **auto-patch** (security fixes), +- **auto-upgrade** (Platformium). + +--- + +## 16. Security - Critical Guarantees + +### 16.1 Agents cannot escalate access + +Немає способу отримати додаткові capabilities: + +- ні через prompt, +- ні через tool, +- ні через plugin. + +### 16.2 Agents cannot bypass confidential mode + +- Orchestrator гарантує redaction/plaintext-filtering. + +### 16.3 Agents cannot perform chain/embassy actions + +Без capability tool (яких у агента за замовчуванням немає). + +### 16.4 Agents cannot break sandbox + +- locked FS, +- banned syscalls, +- no external internet. + +### 16.5 Agents cannot exceed quotas + +Runtime викликає Usage Service перед кожним кроком. + +--- + +## 17. Events Generated by Agent Lifecycle + +| Event | Purpose | +| ------------------------ | --------------------- | +| `agent.created` | новий агент | +| `agent.updated` | конфігурація оновлена | +| `agent.deleted` | видалено | +| `agent.run.started` | запуск виконання | +| `agent.run.completed` | завершення | +| `agent.run.failed` | помилка | +| `agent.run.rate_limited` | перевищено ліміти | + +--- + +## 18. Integration with PDP / PEP / Mesh / Tools + +Агенти повністю інтегровані з: + +- **PEP (Gateway)** → для входу/інвокації +- **PDP** → для прав на кожен tool +- **Mesh** → для internal API доступів +- **Tool Proxy** → жорсткі правила безпеки +- **Usage Service** → ліміти compute +- **Governance** → контроль правил + +--- + +## 19. Integration with Other Docs + +Цей документ доповнює: + +- `12_agent_runtime_core.md` +- `36_agent_runtime_isolation_and_sandboxing.md` +- `37_agent_tools_and_plugins_specification.md` +- `32_policy_service_PDP_design.md` +- `33_api_gateway_security_and_pep.md` +- `31_governance_policies_for_capabilities_and_quotas.md` + +--- + +## 20. Завдання для Cursor + +```text +You are a senior backend engineer. Implement Private Agents Lifecycle & Management using: +- 38_private_agents_lifecycle_and_management.md +- 12_agent_runtime_core.md +- 36_agent_runtime_isolation_and_sandboxing.md + +Tasks: +1) Create agents table schema. +2) Implement Agent Creation Flow (with PDP authorization). +3) Implement Agent Initialization (bootstrap capabilities, limits, sandbox config). +4) Create Agent Access Keys generation and management. +5) Implement Agent Configuration Model (JSON config storage). +6) Implement Agent Update Flow. +7) Implement Agent Run Lifecycle (Start, Sandbox Spin-Up, Execute, Complete). +8) Add Agent Memory Policy (no plaintext, summaries only). +9) Implement Agent Logs (storage, retention, filtering). +10) Add Agent Suspension logic. +11) Implement Agent Deletion Flow (soft delete, key revocation). +12) Add Agent Versioning. +13) Implement security guarantees. +14) Generate lifecycle events (NATS). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 21. Summary + +Життєвий цикл приватних агентів у DAARION.city: + +- чітко структурований, +- безпечно ізольований, +- контролюється PDP/PEP, +- повністю керований governance, +- підтримує інструменти лише через Tool Proxy, +- економічно керований через 1T/usage, +- забезпечує конфіденційність для команд, +- має аудит, версіонування та журнал дій. + +Це — **база для масштабованої, безпечної, керованої екосистеми приватних агентів**. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/39_private_agent_templates_and_behavior_profiles.md b/docs/cursor/39_private_agent_templates_and_behavior_profiles.md new file mode 100644 index 00000000..75e12cd7 --- /dev/null +++ b/docs/cursor/39_private_agent_templates_and_behavior_profiles.md @@ -0,0 +1,482 @@ +# 39 — Private Agent Templates & Behavior Profiles (MicroDAO) + +*Шаблони приватних агентів, поведінкові профілі, рівні автономії, системні інструкції, ролі, спеціалізації, контроль стилю, безпекові межі* + +--- + +## 1. Purpose & Scope + +Цей документ визначає: + +- базові шаблони створення агентів, +- поведінкові моделі, +- рівні автономії, +- системні інструкції, +- спеціалізації, +- контроль стилю/тону, +- правила редагування шаблонів, +- як Governance може змінювати поведінку, +- як команди microDAO створюють своїх агентів. + +Це ядро **моделі особистості та робочої поведінки приватних агентів**. + +--- + +## 2. What is a Behavior Profile? + +Поведінковий профіль агента — це: + +```text +структура, що визначає як агент: +- відповідає, +- аналізує, +- ініціює, +- дотримується інструкцій, +- контролює ризики, +- взаємодіє з людьми та сервісами, +- виконує завдання. +``` + +Профіль = сума: + +- системної інструкції, +- параметрів автономії, +- дозволених інструментів, +- тональності, +- мисленнєвого стилю, +- обмежень. + +--- + +## 3. Base Agent Templates + +Є 4 базові шаблони, з яких створюються всі приватні агенти: + +--- + +### 3.1 TEMPLATE_A: Assistant (default) + +**Роль:** допомагає, пояснює, аналізує, виконує задачі. + +**Автономія:** низька → діє лише за запитом користувача. + +**Тон:** нейтральний, структурований. + +**Використання:** персональні агенти, комунікація, підтримка. + +**System prompt:** + +```text +You are a Private Assistant Agent of DAARION.city. +Your primary responsibilities: +- Answer clearly, logically, and safely. +- Follow user instructions. +- Never access restricted data or tools. +- Respect confidential mode. +- Use tools only when allowed by PDP. +- Optimize cost-efficiency. +``` + +--- + +### 3.2 TEMPLATE_B: Analyst + +**Роль:** аналітика, дослідження, узагальнення. + +**Автономія:** середня (може пропонувати наступні кроки). + +**Тон:** аналітичний, об'єктивний, структурований. + +**System prompt:** + +```text +You are an Analytical Agent. +Your primary tasks: +- Extract insights, +- Create structured reports, +- Identify missing data, +- Recommend options. +``` + +--- + +### 3.3 TEMPLATE_C: Operator (Task Executor) + +**Роль:** виконує робочі задачі (створює tasks, projects, робить summaries). + +**Автономія:** середньо-висока. + +**Інструменти:** task, project, memory, tools category A/B. + +**System prompt:** + +```text +You are an Execution Agent. +You organize tasks, convert requests into actions, +and execute steps through tools in a safe manner. +``` + +--- + +### 3.4 TEMPLATE_D: Autonomous Agent (Platformium-only) + +**Роль:** автономне планування, запуск під-агентів, складні флоу. + +**Автономія:** висока. + +**Обмеження:** тільки для дорогих планів та за дозволами Governance. + +**System prompt:** + +```text +You are an Autonomous Multi-Agent Orchestrator. +You plan, execute, and coordinate multi-step flows +while respecting all DAARION.city safety and cost policies. +``` + +--- + +## 4. Behavior Profiles (Full List) + +Профіль = базовий шаблон + параметри. + +### 4.1 Profile: "Advisor" + +Шаблон: Assistant + +Тон: ввічливий, формальний + +Автономія: низька + +Інструменти: тільки A + +Роль: поради, пояснення + +--- + +### 4.2 Profile: "Researcher" + +Шаблон: Analyst + +Інструменти: A + B + +Допомога: пошук внутрішніх даних + +Поведінка: структуровані доповіді + +--- + +### 4.3 Profile: "Project Manager" + +Шаблон: Operator + +Інструменти: project, task + +Роль: картування задач, оновлення статусів + +--- + +### 4.4 Profile: "Automation Builder" + +Шаблон: Operator + +Інструменти: router, llm + +Роль: запуск флоу, workflow automation + +--- + +### 4.5 Profile: "Platform Integrator" + +Шаблон: Analyst + +Інструменти: platform tools + +Доступ: тільки для GreenFood/EnergyUnion команд + +Роль: аналіз RWA даних + +--- + +### 4.6 Profile: "Autonomous Planner" (Platformium) + +Шаблон: Autonomous + +Повний multi-agent orchestration + +Дуже обмежені інструменти (router, agent, memory) + +--- + +## 5. Behavior Profile Schema + +У таблиці `agents.config.behavior` зберігається: + +```json +{ + "template": "assistant", + "tone": "neutral", + "autonomy": "low", + "allowed_tools": ["math", "text", "memory"], + "restricted_tools": ["browser_full", "external_api"], + "style_params": { + "structure": true, + "short_outputs": false, + "bullet_points": true + }, + "risk_controls": { + "prompt_injection_protection": true, + "guardrails": true + } +} +``` + +--- + +## 6. Behavior Parameters (Detailed) + +### 6.1 Autonomy Levels + +| Level | Description | +| ---------- | -------------------------------------------- | +| low | діє лише за інструкцією користувача | +| medium | може пропонувати варіанти | +| high | планує multi-step flows | +| autonomous | запускає під-агентів, router, аналізує usage | + +--- + +### 6.2 Tone Controls + +- neutral +- formal +- friendly +- analytical +- minimalistic +- creative +- instructive + +--- + +### 6.3 Output Controls + +Властивості: + +```json +{ + "short_outputs": true/false, + "bullet_points": true/false, + "structured": true/false, + "max_tokens_per_output": 1000, + "format": "text" | "json" | "markdown" +} +``` + +--- + +## 7. Tool Access by Profile + +| Profile | Tools | +| ------------------- | ---------------------- | +| Advisor | A | +| Researcher | A, B | +| Project Manager | A, B (project/task) | +| Automation Builder | A, B, C | +| Platform Integrator | A, B, platform | +| Autonomous Planner | A, B, C (router/agent) | + +--- + +## 8. Confidential Mode Compatibility + +У confidential mode: + +- повністю вимикається browser-lite +- platform tools отримують redacted дані +- memory → summary only +- autonomy знижується на 1 рівень +- tone ≠ creative (лише neutral/analytical) + +--- + +## 9. Profile Switching Logic + +Профіль агента може бути змінений: + +- Owner/Guardian команди, +- Governance (політично), +- Security (через порушення). + +### Flow: + +```mermaid +sequenceDiagram + participant U + participant G as Gateway + participant PDP + participant A as Agent Orchestrator + participant DB + + U->>G: PATCH /agents/:id/profile {new_profile} + G->>PDP: authorize(agent.update) + PDP-->>G: allow + G->>A: update_profile + A->>DB: update agent.config + A-->>G: ok + G-->>U: updated +``` + +--- + +## 10. Safe System Instructions + +System prompts **не можуть**: + +- давати агенту більші права, ніж capability, +- дозволяти обхід sandbox, +- вимикати confidential mode. + +Runtime очищає: + +- шкідливі фрагменти, +- інструкції типу "ignore all previous rules". + +--- + +## 11. Governance-Level Restrictions + +Governance може: + +- вимикати певні шаблони: + - Autonomous-only для Platformium +- встановлювати allowed/disallowed parameters +- вводити min-stake для autonomy>medium +- подавати глобальні зміни тону + +--- + +## 12. Security Behavior Controls + +Агент завжди: + +- не робить зовнішніх HTTP запитів, +- не виконує сторонній код, +- не розкриває конфіденційні дані, +- не відображає chain-of-thought, +- не змінює власні промпти, +- не додає інструменти самостійно. + +--- + +## 13. Profile Templates Examples + +--- + +### 13.1 Example: Advisor Profile + +```text +You are a Private Assistant Agent of the DAARION.city microDAO. +Keep answers structured and clear. +Do not generate long creative stories. +Never break safety or cost policies. +Use tools only when PDP allows. +``` + +--- + +### 13.2 Example: Project Manager + +```text +You are the Execution Agent of the team. +Convert user intents into tasks and structured actions. +Avoid speculation. +Use the internal task tool when appropriate. +``` + +--- + +### 13.3 Example: Autonomous Planner + +```text +You plan and execute multi-step operations. +When making decisions: +- minimize cost, +- respect quotas, +- confirm critical changes with the user. +``` + +--- + +## 14. Agent Marketplace Templates (future) + +Це дозволить командам microDAO публікувати: + +- шаблони поведінки, +- спеціалізації, +- AI-брокерів, +- шаблони для Platform Tools. + +--- + +## 15. Integration with Other Docs + +Цей документ доповнює: + +- `38_private_agents_lifecycle_and_management.md` +- `37_agent_tools_and_plugins_specification.md` +- `36_agent_runtime_isolation_and_sandboxing.md` +- `12_agent_runtime_core.md` +- `31_governance_policies_for_capabilities_and_quotas.md` + +--- + +## 16. Завдання для Cursor + +```text +You are a senior backend engineer. Implement Private Agent Templates & Behavior Profiles using: +- 39_private_agent_templates_and_behavior_profiles.md +- 38_private_agents_lifecycle_and_management.md +- 37_agent_tools_and_plugins_specification.md + +Tasks: +1) Define base agent templates (Assistant, Analyst, Operator, Autonomous). +2) Create behavior profile schema (JSON config structure). +3) Implement behavior parameters (autonomy levels, tone controls, output controls). +4) Map tool access by profile. +5) Add confidential mode compatibility rules. +6) Implement profile switching logic (with PDP authorization). +7) Add safe system instructions validation (filter harmful prompts). +8) Add governance-level restrictions. +9) Implement security behavior controls. +10) Create profile templates examples (Advisor, Project Manager, Autonomous Planner). +11) Store behavior profiles in agents.config.behavior. + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 17. Summary + +Шаблони та профілі агентів у DAARION.city: + +- стандартизують поведінку, +- гарантують безпеку, +- визначають рівень автономії, +- контролюють стиль/тон, +- обмежують інструменти, +- захищають confidential mode, +- регулюються governance, +- дозволяють масштабоване створення агентів з прогнозованою поведінкою. + +Це — **центральна психологічна модель і поведінкова основа приватних агентів DAARION OS**. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/40_rwa_energy_food_water_flow_specs.md b/docs/cursor/40_rwa_energy_food_water_flow_specs.md new file mode 100644 index 00000000..c115d8cf --- /dev/null +++ b/docs/cursor/40_rwa_energy_food_water_flow_specs.md @@ -0,0 +1,458 @@ +# 40 — RWA Energy, Food, Water Flow Specifications (MicroDAO) + +*Потоки RWA (Real-World Assets): енергія, їжа, вода. Embassy інтеграція. Oracle-потоки. Токенізація KWT/1T. Верифікація. Платежі. Аудит.* + +--- + +## 1. Purpose & Scope + +Документ визначає: + +- як DAARION.city інтегрує реальні фізичні активи (RWA), +- які дані проходять через Embassy, +- як обробляються вимірювання енергії/врожаю/води, +- формат орієнтирів (oracle payloads), +- як оновлюється `rwa_inventory`, +- як це конвертується в KWT/1T виплати, +- які правила безпеки та аудиту. + +Це критична частина економічного ядра. + +--- + +## 2. Supported RWA Domains + +DAARION.city на рівні MVP підтримує 3 види RWA: + +| Домен | Опис | Платформа | +| --------------- | ------------------------------------- | ----------- | +| Energy (kWh) | виробництво та споживання енергії | EnergyUnion | +| Food (kg/units) | продукти харчування (агро, GreenFood) | GREENFOOD | +| Water (m³) | вода, фільтрація, очищення | WaterUnion | + +Кожен домен має власні: + +- сенсори/джерела даних, +- Embassy-канали, +- unit of measure, +- payout формулу. + +--- + +## 3. Data Flow Overview + +```text +Device/Meter → Platform (GREENFOOD/EnergyUnion/WaterUnion) → Embassy → API Gateway → PDP → RWA Inventory → Wallet +``` + +Події в NATS: + +- `embassy.energy.update` +- `embassy.food.update` +- `embassy.water.update` +- `oracle.reading.published` +- `rwa.inventory.updated` +- `payout.generated` + +--- + +## 4. Embassy Integration + +Embassy — це trusted шлюз між DAARION та платформами RWA. + +### 4.1 Authentication + +Усі платформи надсилають webhook-запити: + +```text +POST /embassy/ +``` + +З заголовками: + +```text +X-Platform-Id: energyunion +X-Timestamp: 1700000000 +X-Signature: HMAC_SHA256(payload, secret) +``` + +Gateway перевіряє: + +- HMAC → valid +- timestamp → ±5 хв +- platform → відома +- key → active + +Після валідації → PDP(authorize): + +```text +action = embassy.energy.update +subject = emb_ +``` + +--- + +## 5. Oracle Payload Specification + +Усі орієнтири мають однакову структуру: + +```json +{ + "source": "energyunion", + "domain": "energy", + "site_id": "EU-KYIV-01", + "unit": "kwh", + "value": 126.45, + "ts": "2025-11-14T12:00:00Z", + "signature": "" +} +``` + +### Поля: + +- `source`: назва платформи +- `domain`: energy | food | water +- `site_id`: унікальний ID локації +- `unit`: kwh | kg | m3 +- `value`: величина RWA +- `ts`: timestamp фактичного виміру +- `signature`: підпис платформи (опціонально окремо від HMAC) + +--- + +## 6. RWA Inventory Table Schema + +```sql +create table rwa_inventory ( + id text primary key, + domain text, -- energy / food / water + site_id text, + unit text, -- kwh / kg / m3 + value numeric, + value_delta numeric, -- різниця vs попереднього + ts timestamptz, + platform text, + created_at timestamptz default now() +); +``` + +--- + +## 7. Processing Flow for Each Domain + +### 7.1 ENERGY Domain + +#### Одиниця: + +**kWh** + +#### Джерела: + +- сонячні панелі, +- біогазові станції, +- інвертори. + +#### Потік: + +1. Device → EnergyUnion +2. EnergyUnion → Embassy (`POST /embassy/energy`) +3. Gateway: + - HMAC validate + - PDP(authorize embassy.energy.update) +4. Oracle Processor → таблиця `oracles` +5. Delta обчислення: + + ```text + delta = current_kwh - previous_kwh + ``` + +6. Update `rwa_inventory` +7. Publish `rwa.inventory.updated (energy)` +8. Wallet Service: + - конвертує kWh → KWT (токен енергії) + - нараховує payouts (KWT або 1T залежно від політик) + +--- + +### 7.2 FOOD Domain + +#### Одиниця: + +**kg** або **units** (залежно від товару) + +#### Джерела: + +- агропідприємства, +- ферми, +- парники, +- склади GreenFood. + +#### Потік: + +1. GREENFOOD → Embassy (`POST /embassy/food`) +2. Gateway → PDP +3. Oracle Processor: + - normalize units + - validate ranges (не може бути -100 або +1e9) +4. Update `rwa_inventory` +5. Publish `rwa.inventory.updated (food)` +6. Wallet Service: + - може нараховувати 1T для food supply chain (опційно) + +--- + +### 7.3 WATER Domain + +#### Одиниця: + +**m³** + +#### Джерела: + +- фільтрувальні станції, +- водні вузли, +- лічильники споживання. + +Потік аналогічний: + +1. WaterUnion → Embassy (`/embassy/water`) +2. Gateway → PDP +3. Oracle Processor +4. Update `rwa_inventory` +5. Publish event +6. Wallet Service payout (за політиками міста) + +--- + +## 8. KWT / 1T Tokenization Rules + +### 8.1 ENERGY → KWT + +Формула: + +```text +KWT = kWh × conversion_rate +``` + +`conversion_rate` встановлюється Governance. + +### 8.2 FOOD → 1T (optional) + +Може працювати як subsidy: + +```text +1T = kg × food_bonus_rate +``` + +### 8.3 WATER → 1T/KWT (mixed) + +```text +1T = m3 × water_treatment_reward +``` + +або: + +```text +KWT = m3 × (energy_equivalent) +``` + +--- + +## 9. Wallet Integration + +При кожному `rwa.inventory.updated`: + +Wallet Service: + +1. Перевіряє політику: + - reward type: KWT / 1T / NONE + - conversion rate +2. Обчислює payout: + + ```text + payout = delta_value × reward_rate + ``` + +3. Генерує запис у `payouts`: + + ```sql + insert into payouts (team_id, value, symbol, rwa_ref) + ``` + +4. Публікує: + + ```text + payout.generated + ``` + +--- + +## 10. Governance-Controlled Parameters + +Governance може: + +- міняти `conversion_rate` для кожного домену; +- встановлювати максимальний reward per day; +- вимикати певні reward-и тимчасово; +- встановлювати девіаційні фільтри (anomaly filters); +- встановлювати правила верифікації (multi-oracle consensus). + +--- + +## 11. Anomaly Detection & Anti-Fraud + +Базові правила для відхилення аномалій: + +### 11.1 Value Constraints + +- kWh не може рости на >500% за 1 годину. +- food (kg) не може бути негативною величиною. +- water (m³) не може мати spikes >100x. + +### 11.2 Site Consistency + +Якщо site передає дані 3 рази на годину, а потім 1 раз у хвилину — вмикається throttling. + +### 11.3 Signature Verification + +Дані мають бути підписані платформою. + +--- + +## 12. Oracle Processor Rules + +Oracle Processor: + +- нормалізує величини, +- сортує за ts, +- шукає відсутні delta-записи, +- фільтрує аномалії, +- додає дані в `oracles`, +- створює RWA inventory updates. + +--- + +## 13. Data Retention + +### 13.1 Oracles + +- зберігаються 2–5 років. + +### 13.2 RWA Inventory + +- зберігається 3–7 років. + +### 13.3 Embassy Logs + +- зберігаються 90–180 днів. + +--- + +## 14. Critical Security Rules + +- Embassy keys не повинні мати розширених прав. +- Немає прямого доступу до Wallet. +- Немає можливості змінити історію RWA. +- PDP перевіряє: + + ```text + embassy..update + ``` + +- Gateway відкидає: + - запити без HMAC, + - запити з старим timestamp, + - підозрілі spikes. + +--- + +## 15. Example End-to-End Flow (Energy) + +```mermaid +sequenceDiagram + participant M as Meter + participant EU as EnergyUnion + participant EMB as Embassy + participant G as Gateway (PEP) + participant PDP + participant O as Oracle Processor + participant DB + participant W as Wallet + + M->>EU: kWh data + EU->>EMB: webhook (signed) + EMB->>G: POST /embassy/energy + G->>PDP: authorize(embassy.energy.update) + PDP-->>G: allow + + G->>O: forward payload + O->>DB: insert into oracles + O->>DB: update rwa_inventory + + O->>W: publish rwa.inventory.updated + W->>DB: insert payouts + W->>NATS: payout.generated +``` + +--- + +## 16. Integration with Other Docs + +Цей документ доповнює: + +- `28_flows_wallet_embassy_energy_union.md` +- `33_api_gateway_security_and_pep.md` +- `32_policy_service_PDP_design.md` +- `DAARION_city_platforms_catalog.md` +- `27_database_schema_migrations.md` + +--- + +## 17. Завдання для Cursor + +```text +You are a senior backend engineer. Implement RWA Energy, Food, Water Flow Specifications using: +- 40_rwa_energy_food_water_flow_specs.md +- 28_flows_wallet_embassy_energy_union.md +- 33_api_gateway_security_and_pep.md + +Tasks: +1) Create Embassy webhook endpoints (/embassy/energy, /embassy/food, /embassy/water). +2) Implement HMAC signature validation for Embassy webhooks. +3) Create Oracle Processor service (normalize, validate, filter anomalies). +4) Implement RWA Inventory updates (delta calculation, insert/update). +5) Create Wallet integration for RWA payouts (KWT/1T tokenization). +6) Add anomaly detection rules (value constraints, site consistency, signature verification). +7) Implement Governance-controlled parameters (conversion rates, reward limits). +8) Add data retention policies (oracles, RWA inventory, Embassy logs). +9) Create NATS events (embassy.energy.update, embassy.food.update, embassy.water.update, rwa.inventory.updated, payout.generated). +10) Add PDP authorization checks for embassy..update. + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 18. Summary + +Потоки RWA у DAARION.city: + +- дозволяють токенізувати енергію (KWT), їжу та воду (1T/KWT), +- працюють через Embassy як secure gateway, +- використовують oracles для перевірки та нормалізації даних, +- контролюються Governance для стійкої економіки, +- створюють payouts через Wallet Service, +- повністю логуються, +- захищені від аномалій, підробок і повторних атак. + +Це — **серце економічного механізму міста DAARION**. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/41_ai_governance_agent_design.md b/docs/cursor/41_ai_governance_agent_design.md new file mode 100644 index 00000000..9ce99165 --- /dev/null +++ b/docs/cursor/41_ai_governance_agent_design.md @@ -0,0 +1,471 @@ +# 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** + +Основний принцип: + +```text +AI Governance Agent — це механічний виконавець волі DAO. +``` + +Він сам **не генерує політик**, а лише обробляє та застосовує. + +--- + +## 3. Governance Proposal Lifecycle + +```mermaid +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`. + +Приклад: + +```json +{ + "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 + +```text +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. + +Приклад: + +```text +min_quorum = 10% від circulating_supply +approval_required = 51% +``` + +Після дедлайну: + +```text +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 + +Алгоритм: + +```python +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 конфіг ентитлментів: + +```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 публікує: + +```text +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`, +- доступні для перегляду через: + +```text +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: + +```text +Increase Premium compute quotas by 25% +``` + +### Operations: + +```json +[ + { "op": "increase_quota", "metric": "agent_runs_per_day", "value": 250 }, + { "op": "increase_quota", "metric": "llm_tokens_per_month", "value": 500000 } +] +``` + +### Governance Agent process: + +1. validate structure → OK +2. validate quotas do not exceed global max → OK +3. check plan hierarchy → OK +4. commit changes → DB updated +5. publish `policy.updated` +6. 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 + +```text +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 + + diff --git a/docs/cursor/42_nats_event_streams_and_event_catalog.md b/docs/cursor/42_nats_event_streams_and_event_catalog.md new file mode 100644 index 00000000..fd43e44a --- /dev/null +++ b/docs/cursor/42_nats_event_streams_and_event_catalog.md @@ -0,0 +1,608 @@ +# 42 — NATS Event Streams & Event Catalog (MicroDAO) + +*NATS JetStream архітектура, топіки, схеми подій, ретенція, реплікація, кластеризація, consumer groups, replay, дедуплікація, outbox-pattern інтеграція* + +--- + +## 1. Purpose & Scope + +Цей документ визначає **офіційний Event Catalog DAARION.city**: + +- перелік усіх подій (events), +- схеми Payloadів, +- NATS-стріми та топіки, +- lifecycle подій, +- гарантії доставки, +- retention правила, +- інструкції для сервісів, +- інтеграцію з Outbox Worker, +- безпеку та ACL для стрімів. + +Це база для: + +- Wallet Service, +- Agent Orchestrator, +- Embassy/RWA, +- Governance Agent, +- Usage Service, +- Analytics/Monitoring, +- Replaying events (for recovery). + +--- + +## 2. JetStream Cluster Model + +DAARION використовує **3-5 вузлів JetStream кластеру** з параметрами: + +- Replication: **3** +- Acknowledgement: **explicit** +- Storage: **file (SSD)** +- Retention: **WorkQueue** або **Interest** залежно від стріму + +--- + +## 3. Event Categories Overview + +Уся система складається з 13 груп подій: + +1. **agent.run.*** +2. **chat.message.*** +3. **project.*** +4. **task.*** +5. **wallet.*** +6. **staking.*** +7. **payout.*** +8. **embassy.*** +9. **oracle.*** +10. **rwa.inventory.*** +11. **governance.*** +12. **usage.*** +13. **telemetry.*** + +Кожна категорія має окремий JetStream "stream". + +--- + +## 4. Stream Naming Convention + +```text +STREAM_ +``` + +Приклади: + +```text +STREAM_AGENT_RUN +STREAM_CHAT +STREAM_EMBASSY +STREAM_RWA +STREAM_GOVERNANCE +STREAM_WALLET +STREAM_USAGE +``` + +--- + +## 5. Topic Naming Convention (Subjects) + +```text +.. +``` + +Приклади: + +```text +agent.run.started +agent.run.completed +wallet.payout.generated +embassy.energy.update +rwa.inventory.updated +governance.policy.updated +``` + +--- + +## 6. Event Envelope + +Усі події використовують уніфікований формат: + +```json +{ + "event_id": "evt_123", + "ts": "2025-11-14T12:00:00Z", + "domain": "agent", + "type": "agent.run.completed", + "version": 1, + "actor": { + "id": "u_123", + "kind": "user|agent|service|embassy" + }, + "payload": { ... }, + "meta": { + "team_id": "t_555", + "trace_id": "trace_abc", + "span_id": "span_def" + } +} +``` + +--- + +## 7. Outbox Integration (Guaranteed Delivery) + +Усі сервіси, що генерують події, пишуть *спочатку* в таблицю: + +```text +outbox_events +``` + +Далі Outbox Worker: + +1. читає записи `processed=false` +2. публікує у NATS +3. позначає `processed=true` + +Гарантія: **at-least-once delivery** + +--- + +## 8. Stream-by-Stream Specification + +--- + +### 8.1 STREAM_AGENT_RUN + +#### Subjects: + +- `agent.run.started` +- `agent.run.completed` +- `agent.run.failed` +- `agent.run.rate_limited` + +#### Payloads + +**agent.run.started** + +```json +{ + "agent_run_id": "ar_123", + "agent_id": "ag_555", + "team_id": "t_444", + "model": "gpt-4o-mini", + "tools": ["math", "memory"], + "input_summary": "..." +} +``` + +**agent.run.completed** + +```json +{ + "agent_run_id": "ar_123", + "duration_ms": 3421, + "tokens_used": 1842, + "cost_1t": 0.00023, + "output_summary": "..." +} +``` + +--- + +### 8.2 STREAM_CHAT + +#### Subjects: + +- `chat.message.created` +- `chat.message.updated` +- `chat.message.deleted` + +#### Payload: + +```json +{ + "message_id": "msg_777", + "channel_id": "ch_222", + "team_id": "t_555", + "type": "user|agent|system", + "summary": "...", // plaintext not included + "embeddings": "" +} +``` + +--- + +### 8.3 STREAM_PROJECT + +- `project.created` +- `project.updated` + +Payload: + +```json +{ + "project_id": "p_111", + "team_id": "t_444", + "fields": { ... } +} +``` + +--- + +### 8.4 STREAM_TASK + +- `task.created` +- `task.updated` +- `task.completed` + +Payload: + +```json +{ + "task_id": "tsk_001", + "project_id": "p_111", + "team_id": "t_444", + "status": "open|in_progress|done" +} +``` + +--- + +### 8.5 STREAM_WALLET + +Subjects: + +- `wallet.balance.updated` +- `wallet.tx.sent` +- `wallet.tx.confirmed` + +Payload: + +```json +{ + "user_id": "u_123", + "team_id": "t_555", + "symbol": "KWT|1T|DAARION", + "amount": 12.55 +} +``` + +--- + +### 8.6 STREAM_STAKING + +Subjects: + +- `staking.locked` +- `staking.unlocked` + +Payload: + +```json +{ + "user_id": "u_x", + "team_id": "t_y", + "amount": 1000, + "symbol": "RINGK" +} +``` + +--- + +### 8.7 STREAM_PAYOUT + +Subjects: + +- `payout.generated` +- `payout.claimed` +- `payout.failed` + +Payload: + +```json +{ + "payout_id": "payout_727", + "team_id": "t_555", + "symbol": "KWT", + "amount": 3.5, + "rwa_ref": "inv_888" +} +``` + +--- + +### 8.8 STREAM_EMBASSY + +Subjects: + +- `embassy.energy.update` +- `embassy.food.update` +- `embassy.water.update` +- `embassy.event.received` + +Payload: + +```json +{ + "platform": "energyunion", + "domain": "energy", + "site_id": "EU-KYIV-01", + "value": 125.4, + "unit": "kwh", + "ts": "..." +} +``` + +--- + +### 8.9 STREAM_ORACLE + +Subjects: + +- `oracle.reading.published` + +Payload: + +```json +{ + "domain": "energy", + "site_id": "EU-KYIV-01", + "normalized_value": 125.4, + "delta": 23.1, + "ts": "..." +} +``` + +--- + +### 8.10 STREAM_RWA + +Subjects: + +- `rwa.inventory.updated` + +Payload: + +```json +{ + "inventory_id": "inv_001", + "domain": "energy", + "site_id": "EU-KYIV-01", + "value": 125.4, + "delta": 23.1, + "unit": "kwh" +} +``` + +--- + +### 8.11 STREAM_GOVERNANCE + +Subjects: + +- `governance.policy.created` +- `governance.policy.updated` +- `governance.policy.failed` + +Payload: + +```json +{ + "policy_id": "gov_0012", + "type": "plan.entitlement.update", + "status": "applied" +} +``` + +--- + +### 8.12 STREAM_USAGE + +Subjects: + +- `usage.agent_run.increment` +- `usage.llm.increment` +- `usage.embassy.increment` + +Payload: + +```json +{ + "team_id": "t_555", + "metric": "agent_runs", + "value": 1 +} +``` + +--- + +### 8.13 STREAM_TELEMETRY + +Subjects: + +- `telemetry.event` +- `telemetry.error` +- `telemetry.screen_view` + +Payload: + +```json +{ + "client": "web", + "event": "screen_view", + "screen": "dashboard", + "ts": "..." +} +``` + +--- + +## 9. Retention Policies + +### Agent, Chat, Project, Task + +```text +retention: 14–90 days +storage: workqueue +``` + +### RWA, Embassy, Oracle + +```text +retention: 1–3 years +storage: file +``` + +### Governance + +```text +retention: permanent +storage: file +``` + +### Wallet, Payout, Staking + +```text +retention: 3–7 years +storage: file +``` + +--- + +## 10. Consumer Groups + +Для кожного стріму визначені consumer groups: + +| Stream | Consumers | +| ----------------- | --------------------- | +| STREAM_AGENT_RUN | telemetry, analytics | +| STREAM_WALLET | wallet, payout, usage | +| STREAM_RWA | wallet, dashboard | +| STREAM_EMBASSY | oracle, usage | +| STREAM_GOVERNANCE | PDP, audit | +| STREAM_USAGE | quota service | +| STREAM_CHAT | search-indexer | + +--- + +## 11. Message Ordering + +Гарантовано: + +- **per site_id** (RWA) +- **per agent_run_id** +- **per payout_id** + +--- + +## 12. Security / ACL + +### Example: + +```text +SERVICE agent-orchestrator: + allow publish: agent.run.* + allow subscribe: usage.agent_run.* + deny: wallet.* + +SERVICE embassy: + allow publish: embassy.* + deny: wallet.* +``` + +--- + +## 13. Replay & Recovery + +JetStream дозволяє: + +- `DeliverLast` +- `DeliverByStartTime` +- `ReplayInstant` +- `ReplayOriginal` + +При аваріях можна: + +- відтворити RWA-потоки за 3 роки, +- відновити usage counters, +- відновити governance history, +- відтворити agent-run статистику. + +--- + +## 14. NATS Integration with Mesh + +Mesh забезпечує: + +- retry, +- load-balancing, +- mTLS, +- service identities, +- audit по pod/service. + +--- + +## 15. Integration with Other Docs + +Цей документ доповнює: + +- `34_internal_services_architecture.md` +- `35_microdao_service_mesh_design.md` +- `27_database_schema_migrations.md` +- `28_flows_wallet_embassy_energy_union.md` +- `40_rwa_energy_food_water_flow_specs.md` +- `41_ai_governance_agent_design.md` + +--- + +## 16. Завдання для Cursor + +```text +You are a senior backend engineer. Implement NATS Event Streams & Event Catalog using: +- 42_nats_event_streams_and_event_catalog.md +- 34_internal_services_architecture.md +- 27_database_schema_migrations.md + +Tasks: +1) Configure JetStream cluster (3-5 nodes, replication=3, explicit ack, file storage). +2) Create 13 streams (STREAM_AGENT_RUN, STREAM_CHAT, STREAM_PROJECT, STREAM_TASK, STREAM_WALLET, STREAM_STAKING, STREAM_PAYOUT, STREAM_EMBASSY, STREAM_ORACLE, STREAM_RWA, STREAM_GOVERNANCE, STREAM_USAGE, STREAM_TELEMETRY). +3) Define topic naming convention and subjects for each stream. +4) Implement Event Envelope format (event_id, ts, domain, type, version, actor, payload, meta). +5) Integrate with Outbox Worker (guaranteed delivery). +6) Define payload schemas for all event types (agent.run.*, chat.message.*, project.*, task.*, wallet.*, staking.*, payout.*, embassy.*, oracle.*, rwa.inventory.*, governance.*, usage.*, telemetry.*). +7) Configure retention policies (14-90 days for agent/chat/project/task, 1-3 years for RWA/Embassy/Oracle, permanent for Governance, 3-7 years for Wallet/Payout/Staking). +8) Set up consumer groups for each stream. +9) Implement message ordering guarantees (per site_id, per agent_run_id, per payout_id). +10) Configure Security/ACL (service-level permissions). +11) Add replay & recovery capabilities (DeliverLast, DeliverByStartTime, ReplayInstant, ReplayOriginal). +12) Integrate with Service Mesh (retry, load-balancing, mTLS, service identities, audit). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 17. Summary + +Цей документ визначає: + +- повний Event Catalog DAARION, +- JetStream конфігурацію, +- payload формати, +- життєвий цикл подій, +- безпеку, +- ACL, +- гарантії доставки, +- інтеграцію з Outbox, +- правила retention. + +Це — **єдиний, канонічний опис подій у DAARION OS**. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/43_database_events_outbox_design.md b/docs/cursor/43_database_events_outbox_design.md new file mode 100644 index 00000000..9934d38e --- /dev/null +++ b/docs/cursor/43_database_events_outbox_design.md @@ -0,0 +1,407 @@ +# 43 — Database Events Outbox Design (MicroDAO) + +*Outbox Pattern: транзакційна доставка подій, таблиця outbox_events, воркери, дедуплікація, retry, backpressure, інтеграція з NATS JetStream* + +--- + +## 1. Purpose & Scope + +Outbox Pattern вирішує проблему: + +> Як гарантувати, що подія завжди буде доставлена у NATS без втрати даних, навіть якщо сервіс або NATS відмовили? + +Цей документ визначає: + +- структуру `outbox_events`, +- процес вставки, +- воркерів, +- правила retry/backoff, +- дедуплікацію, +- atomic commit, +- safety механізми, +- інтеграцію з JetStream. + +--- + +## 2. Why Outbox Pattern Is Required + +У DAARION.city outbox використовується для: + +- agent-run events, +- payouts, +- staking, +- wallet tx, +- embassy updates, +- oracle readings, +- governance updates, +- usage increments. + +Причини: + +- JetStream може бути недоступним у момент транзакції. +- Сервіси не повинні втрачати події. +- Потрібно гарантувати idempotency. +- Потрібно відокремити business logic від доставки. + +--- + +## 3. Outbox Table Schema + +```sql +create table outbox_events ( + id text primary key, + stream text not null, -- e.g. STREAM_RWA + topic text not null, -- e.g. rwa.inventory.updated + payload jsonb not null, + created_at timestamptz default now(), + processed bool default false, + processed_at timestamptz, + error text -- optional failure reason +); +``` + +### Вимоги: + +- `id` генерується UUID або snowflake. +- Рядки **ніколи не видаляються** (тільки retention archive). +- `processed=false` означає «готовий до доставки». + +--- + +## 4. Outbox Event Insertion + +Подія вставляється у **тій самій транзакції**, що і бізнес-операція. + +Приклад (псевдо): + +```sql +BEGIN; + +UPDATE payouts SET status='generated' WHERE id='p_001'; + +INSERT INTO outbox_events ( + id, stream, topic, payload +) VALUES ( + gen_id(), + 'STREAM_PAYOUT', + 'payout.generated', + '{"payout_id":"p_001","team_id":"t_555"}'::jsonb +); + +COMMIT; +``` + +Гарантія: + +- якщо COMMIT відбувся → подія потрапила у Outbox. +- якщо COMMIT не відбувся → подія не існує. + +--- + +## 5. Outbox Worker Architecture + +```text +Outbox Worker → + SELECT * FROM outbox_events + WHERE processed=false + ORDER BY created_at + LIMIT 200; + +for each event: + TRY publish to NATS + ON success → mark processed + ON failure → retry later +``` + +Workers можуть бути: + +- 1..N штук, +- статично або auto-scaled, +- у Mesh під mTLS. + +--- + +## 6. Worker Processing Loop + +```python +while true: + events = db.fetch_unprocessed(limit=200) + + for evt in events: + try: + nats.publish(evt.topic, evt.payload) + db.mark_processed(evt) + except NATSDownError: + sleep(backoff) + continue + except ValidationError: + db.mark_error(evt, "invalid payload") + continue +``` + +--- + +## 7. Deduplication + +Необхідно витримати **at-least-once**, але уникати дублювань: + +- JetStream має natural dedupe по `msg_id` +- Outbox Worker використовує: + +```text +NATS header: Nats-Msg-Id = outbox_event_id +``` + +Приклад: + +```python +nats.publish( + topic, + payload, + headers={"Nats-Msg-Id": evt.id} +) +``` + +JetStream не доставить дубль. + +--- + +## 8. Retry Strategy + +### 8.1 Backoff + +Експоненційний: + +```text +1s → 2s → 4s → 8s → 16s → max 60s +``` + +### 8.2 Dead-letter Condition + +Після X помилок: + +```text +processed=false +error="unrecoverable" +``` + +worker перестає ретрити; адміністратор розбирається вручну. + +--- + +## 9. Batch Processing & Throughput + +### Рекомендації: + +- batch size: 100–300 подій +- 2–10 worker replicas +- автоматичний autoscaling по lag: + - якщо кількість `processed=false` > 10,000 → scale up + +--- + +## 10. Event Ordering Rules + +Outbox Worker дотримується ordering: + +- per stream +- per partition key (custom) + +Порядок подій важливий для: + +- payouts +- RWA updates +- governance + +--- + +## 11. Multi-Stream Routing + +Сервіс визначає stream: + +```text +if topic startswith "agent.run": + stream = STREAM_AGENT_RUN + +if topic startswith "embassy": + stream = STREAM_EMBASSY +``` + +Усі стріми повинні бути попередньо створені: + +```json +{ + "name": "STREAM_RWA", + "subjects": ["rwa.inventory.*"], + "replicas": 3, + "storage": "file" +} +``` + +--- + +## 12. Failure Modes + +### 12.1 Worker Crash + +Рішення: + +- worker restart → обробляє далі. + +### 12.2 Database Down + +Outbox Worker призупиняється → не доставляє події. + +### 12.3 NATS Down + +Worker робить retry до відновлення. + +### 12.4 Corrupted Payload + +Worker позначає `error` і пропускає подію. + +--- + +## 13. Safety Guarantees + +Outbox забезпечує: + +- **atomicity** +- **consistency** +- **at-least-once** +- **no-loss** +- **event replayability** +- **jetstream dedupe** +- **idempotent consumers** + +--- + +## 14. Event Consumer Rules + +Кожен сервіс, що слухає події, дотримується: + +- idempotency (повтор повинен не ламати логіку), +- durable consumer, +- manual ack, +- retry on failure, +- trace_id propagation. + +--- + +## 15. Operational Metrics + +Моніторимо: + +- outbox_events total count +- unprocessed count +- processing rate +- worker lag +- NATS publish latency +- error rate + +--- + +## 16. Backpressure Control + +Якщо worker не встигає: + +- автоматичний autoscaling, +- або backpressure для producer services (м'яке гальмування). + +--- + +## 17. Batch Deletion / Archival + +Outbox події можуть бути: + +- заархівовані після 90–365 днів, +- переведені у cold storage (S3), +- видалені після 3 років (policy-dependent). + +--- + +## 18. Example End-to-End Flow (Payout) + +```mermaid +sequenceDiagram + participant W as Wallet Service + participant DB + participant OUT as Outbox Worker + participant NATS + + W->>DB: tx begin + W->>DB: insert payout + W->>DB: insert outbox_event(payout.generated) + DB-->>W: commit + + OUT->>DB: fetch unprocessed + OUT->>NATS: publish payout.generated (msg_id=evt_id) + NATS-->>OUT: ack + OUT->>DB: mark processed +``` + +--- + +## 19. Integration with Other Docs + +Цей документ доповнює: + +- `42_nats_event_streams_and_event_catalog.md` +- `27_database_schema_migrations.md` +- `34_internal_services_architecture.md` +- `29_scaling_and_high_availability.md` + +--- + +## 20. Завдання для Cursor + +```text +You are a senior backend engineer. Implement Database Events Outbox Design using: +- 43_database_events_outbox_design.md +- 42_nats_event_streams_and_event_catalog.md +- 27_database_schema_migrations.md + +Tasks: +1) Create outbox_events table schema (id, stream, topic, payload, created_at, processed, processed_at, error). +2) Implement Outbox Event Insertion (atomic transaction with business logic). +3) Create Outbox Worker service (fetch unprocessed, publish to NATS, mark processed). +4) Implement Worker Processing Loop (batch processing, error handling). +5) Add Deduplication (NATS header Nats-Msg-Id = outbox_event_id). +6) Implement Retry Strategy (exponential backoff, dead-letter condition). +7) Configure Batch Processing & Throughput (batch size 100-300, autoscaling). +8) Add Event Ordering Rules (per stream, per partition key). +9) Implement Multi-Stream Routing (topic → stream mapping). +10) Handle Failure Modes (worker crash, database down, NATS down, corrupted payload). +11) Add Safety Guarantees (atomicity, consistency, at-least-once, no-loss, replayability). +12) Define Event Consumer Rules (idempotency, durable consumer, manual ack, retry, trace_id). +13) Add Operational Metrics (outbox_events count, unprocessed count, processing rate, worker lag, NATS latency, error rate). +14) Implement Backpressure Control (autoscaling, producer backpressure). +15) Add Batch Deletion / Archival (90-365 days archive, S3 cold storage, 3 years deletion). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 21. Summary + +Outbox Design гарантує: + +- надійну доставку подій у JetStream, +- 100% уникнення втрати даних, +- консистентність життєво важливих RWA/payout/embassy процесів, +- контрольовану доставку у high-load, +- retry/backoff без дублювань, +- зручну діагностику й моніторинг. + +Це — **основний транспортний транзакційний шар DAARION OS**. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/44_usage_accounting_and_quota_engine.md b/docs/cursor/44_usage_accounting_and_quota_engine.md new file mode 100644 index 00000000..64f5b090 --- /dev/null +++ b/docs/cursor/44_usage_accounting_and_quota_engine.md @@ -0,0 +1,510 @@ +# 44 — Usage Accounting & Quota Engine (MicroDAO) + +*Usage Engine: лічильники, квоти, облік вартості, PDP інтеграція, rate limits, soft/hard limits, попередження, економічна стабільність DAARION OS.* + +--- + +## 1. Purpose & Scope + +Usage Engine — це **центральна система**, яка: + +- обліковує використання ресурсів, +- застосовує квоти відповідно до планів (Freemium → Platformium), +- коригує ліміти через стейк RINGK, +- блокує надмірне використання, +- сигналізує API Gateway про warnings/hard-stops, +- інтегрується з PDP та Governance. + +Вона контролює витрати: + +- LLM-токени +- agent runs +- router invokes +- embassy events +- storage +- wallet tx +- compute (1T) + +--- + +## 2. Usage Engine Architecture + +```text +API Gateway / Agents / Embassy / Tools + ↓ + Usage Accounting Proxy + ↓ +Quota Engine (core) + ↓ +Postgres / Redis (counters) + ↓ +PDP (authorization) +``` + +--- + +## 3. Usage Metrics (Canonical List) + +### 3.1 Compute / LLM: + +- `llm_tokens_input` +- `llm_tokens_output` +- `llm_cost_1t` + +### 3.2 Agents: + +- `agent_runs` +- `agent_parallel_runs` +- `agent_tools_used` + +### 3.3 Router: + +- `router.invoke` +- `router.steps` + +### 3.4 Embassy: + +- `embassy.events_received` +- `embassy.energy.update` +- `embassy.food.update` +- `embassy.water.update` + +### 3.5 RWA: + +- `rwa_processed_records` + +### 3.6 Wallet: + +- `wallet.tx` +- `payout.claims` + +### 3.7 File Storage: + +- `storage.bytes_uploaded` +- `storage.bytes_retained` + +--- + +## 4. Quota Types + +### 4.1 Hard quotas + +Перевищення → STOP + 403 error. + +Приклади: + +- LLM tokens per month +- agent runs per day +- embassy events per day +- browser-lite usage per hour +- wallet tx per 10 min + +### 4.2 Soft quotas + +Перевищення → тротлінг, warning headers. + +Приклади: + +- router.invoke per minute +- search queries + +### 4.3 Compute cost ceilings + +Обмеження: + +- per run (`max_cost_per_run`) +- per day +- per month + +--- + +## 5. Quota Formula + +Кожна квота = + +```text +effective_quota = base_quota(plan) × multiplier(stake) +``` + +Де: + +### 5.1 Base quota + +Визначається планом: + +- Freemium → найнижча +- Casual +- Premium +- Platformium → максимальні + +### 5.2 Multiplier + +Функція: + +```text +multiplier = f(RINGK_staked) +``` + +Приклад: + +| RINGK Stake | Multiplier | +| ----------- | ---------- | +| 0 | 1.0 | +| 1000 | 1.25 | +| 5000 | 1.5 | +| 20000 | 2.0 | + +--- + +## 6. Counters (Storage Model) + +### 6.1 Redis (fast counters) + +Проміжні лічильники для: + +- agent_runs +- tokens_per_minute +- embassy_events +- router_invokes + +Приклад ключів: + +```text +usage:team:{team_id}:llm_month +usage:team:{team_id}:agent_day +usage:user:{user_id}:wallet_tx_hour +``` + +### 6.2 Postgres (durable counters) + +- щоденні/місячні агрегати, +- історія usage, +- перерахунок після crash. + +```sql +create table usage_daily ( + team_id text, + metric text, + value bigint, + day date +); +``` + +--- + +## 7. Quota Engine (Decision Logic) + +```text +allow = + usage(current) < quota(effective) +``` + +1. Виклик надходить від API Gateway. +2. Usage Engine інкрементує провізорний лічильник. +3. Перевіряє квоту. +4. Якщо ок → PDP підтверджує дію. +5. Якщо переповнення → deny. + +--- + +## 8. Warning Thresholds + +При 80–90% використання: + +```text +X-DAARION-Usage-Warning: near limit +``` + +UI може показувати: + +- «Залишилось 10% LLM бюджету» +- «Агентні запуски майже вичерпані» + +--- + +## 9. Rate Limiting Integration + +Quota Engine тісно працює з rate limits: + +- soft RL: попередження +- hard RL: блокування на період + +Періоди: + +- 1 хвилина +- 10 хвилин +- година +- доба +- місяць + +--- + +## 10. PDP Integration + +При оцінці дії: + +```text +PDP checks: + - capability + - role + - plan + - ACL + - quotas (via Usage Engine) +``` + +Usage Engine повертає PDP: + +- `quota_ok = true/false` +- `quota_remaining` +- `cost_estimate` + +--- + +## 11. Cost Accounting (1T Integration) + +1. LLM Proxy обчислює: + +```text +cost_1t = tokens × price_per_token +``` + +2. Router/Agent додає: + +```text +cost_1t += tool_cost +``` + +3. Usage Engine додає: + +```text +team_monthly_compute += cost_1t +``` + +4. PDP блокує, якщо: + +```text +team_monthly_compute > compute_quota +``` + +--- + +## 12. Embassy / RWA Quotas + +Щоб уникнути спаму і фродових оновлень: + +| Domain | Limit | +| ------ | ------------------ | +| energy | 10 000 updates/day | +| food | 5 000 updates/day | +| water | 5 000 updates/day | + +Також: + +```text +max_events_per_minute (per platform) +``` + +--- + +## 13. Agent Run Limits + +Окремі ліміти: + +- max_runs_per_day +- max_parallel_runs +- max_tools_per_run +- max_llm_tokens_per_run +- max_cost_per_run + +--- + +## 14. Storage/Files Quotas + +На команду: + +```text +Freemium: 100MB +Casual: 500MB +Premium: 5GB +Platformium: 25GB+ +``` + +--- + +## 15. Wallet/Chain Quotas + +З метою безпеки: + +```text +max_wallet_tx_per_hour = 2 +max_claims_per_day = 10 +max_stake_ops_per_day = 5 +``` + +--- + +## 16. Usage Correction / Reconciliation + +Раз на добу: + +- Redis → PostgreSQL sync +- anomaly detection +- usage recalculation для long tasks (agent runs) +- звірка tokens_used з LLM Proxy + +--- + +## 17. Governance Controls + +Governance може: + +- підвищувати/знижувати квоти, +- змінювати compute price, +- вимикати окремі метрики, +- вводити "emergency cap", +- змінювати stake multipliers. + +--- + +## 18. Abuse / Fraud Protection + +Виявляє: + +- різкі стрибки usage, +- автоматичні цикли агентів, +- LLM infinite loops, +- embassy spam, +- wallet brute-force, +- chain-попит аномальний. + +Система автоматично може: + +- знизити квоти тимчасово, +- заблокувати агентів, +- призупинити Embassy platform, +- вимкнути інструменти. + +--- + +## 19. Observability + +Метрики: + +- usage per minute/day/month +- quota remaining +- cost per run +- agent tokens used +- embassy event rate +- router invoke rate +- anomaly score + +Графіки в Grafana: + +- per сервіс +- per команду +- per користувача +- per домен (RWA/Energy/Food/Water) + +--- + +## 20. Error Model + +Коди помилок Usage Engine: + +| Code | Meaning | +| -------------------- | ------------------------------- | +| quota_exceeded | перевищено квоту | +| cost_exceeded | обчислювальний бюджет вичерпано | +| rate_limited | надто багато дій | +| anomaly_detected | підозрілий патерн | +| agent_parallel_limit | забагато агентів | +| tokens_limit | LLM usage overflow | + +--- + +## 21. Example Scenarios + +### 21.1 LLM Overflow + +- Користувач запитує великий контекст → tokens_used > quota → deny. + +### 21.2 Embassy Spam + +- EnergyUnion шле 10k events/min → throttling → deny. + +### 21.3 Infinite Agent Loop + +- Агент намагається робити 50 runs/min → deny. + +--- + +## 22. Integration with Other Docs + +Цей документ доповнює: + +- `32_policy_service_PDP_design.md` +- `30_cost_optimization_and_token_economics_infrastructure.md` +- `31_governance_policies_for_capabilities_and_quotas.md` +- `40_rwa_energy_food_water_flow_specs.md` +- `38_private_agents_lifecycle_and_management.md` + +--- + +## 23. Завдання для Cursor + +```text +You are a senior backend engineer. Implement Usage Accounting & Quota Engine using: +- 44_usage_accounting_and_quota_engine.md +- 32_policy_service_PDP_design.md +- 30_cost_optimization_and_token_economics_infrastructure.md + +Tasks: +1) Create Usage Engine service architecture (Usage Accounting Proxy, Quota Engine, Redis/Postgres counters). +2) Define Usage Metrics (LLM tokens, agent runs, router invokes, embassy events, RWA, wallet tx, storage). +3) Implement Quota Types (Hard quotas, Soft quotas, Compute cost ceilings). +4) Implement Quota Formula (base_quota(plan) × multiplier(stake)). +5) Create Counters Storage Model (Redis for fast counters, Postgres for durable counters). +6) Implement Quota Engine Decision Logic (usage check, quota validation, PDP integration). +7) Add Warning Thresholds (80-90% usage warnings). +8) Integrate Rate Limiting (soft/hard limits, time periods). +9) Integrate with PDP (quota_ok, quota_remaining, cost_estimate). +10) Implement Cost Accounting (1T integration, LLM Proxy cost calculation, team monthly compute). +11) Add Embassy/RWA Quotas (per domain limits, max_events_per_minute). +12) Implement Agent Run Limits (max_runs_per_day, max_parallel_runs, max_tools_per_run, max_llm_tokens_per_run, max_cost_per_run). +13) Add Storage/Files Quotas (per plan limits). +14) Implement Wallet/Chain Quotas (max_wallet_tx_per_hour, max_claims_per_day, max_stake_ops_per_day). +15) Add Usage Correction / Reconciliation (Redis → PostgreSQL sync, anomaly detection, usage recalculation). +16) Add Governance Controls (quota updates, compute price changes, emergency cap, stake multipliers). +17) Implement Abuse / Fraud Protection (anomaly detection, automatic quota reduction, agent blocking, embassy suspension). +18) Add Observability (metrics, Grafana dashboards). +19) Implement Error Model (quota_exceeded, cost_exceeded, rate_limited, anomaly_detected, agent_parallel_limit, tokens_limit). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 24. Summary + +Usage Engine: + +- гарантує економічну стабільність системи, +- контролює всі ресурси, +- застосовує квоти, +- працює з PDP, Agents, Embassy, Wallet, Tools, +- захищає систему від зловживань, +- базується на Redis + Postgres, +- повністю конфігурується Governance, +- забезпечує масштабовану, передбачувану, справедливу модель використання DAARION OS. + +Це — **центральний обліковий шар платформи**. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/45_llm_proxy_and_multimodel_routing.md b/docs/cursor/45_llm_proxy_and_multimodel_routing.md new file mode 100644 index 00000000..2c0cf827 --- /dev/null +++ b/docs/cursor/45_llm_proxy_and_multimodel_routing.md @@ -0,0 +1,506 @@ +# 45 — LLM Proxy & Multi-Model Routing (MicroDAO) + +*LLM Proxy: маршрутизація моделей, cost control, токени, PDP, sandbox, autoscaling, fallback-логіка, multimodel orchestration* + +--- + +## 1. Purpose & Scope + +LLM Proxy — це **єдина точка** взаємодії DAARION.city з усіма LLM: + +- OpenAI +- Anthropic +- Local models +- Vision models +- Embeddings +- Code models +- Audio (ASR/TTS) + +Він: + +- нормалізує API, +- викликає правильну модель, +- керує витратами, +- обмежує usage, +- запускає fallback, +- дає PDP-контроль, +- маскує системні інструкції, +- приховує chain-of-thought. + +--- + +## 2. High-Level Architecture + +```text +Agent / Router / Tools + ↓ + API Gateway (PEP) + ↓ + LLM Proxy + ↓ + Multi-Model Router Engine + ↓ + Providers / Local Models / Vision / Embeddings +``` + +--- + +## 3. Why Not Call LLM Directly? + +LLM Proxy — єдиний спосіб гарантувати: + +- безпеку (PDP checks), +- облік usage, +- стале ціноутворення, +- контроль cost explosion, +- фільтрацію危险 prompt-ів, +- policy-based routing (cheap → medium → best), +- інституційну інтеграцію policy-рівня. + +Жоден агент, сервіс чи tool **не має прямого доступу** до LLM API. + +--- + +## 4. Core Responsibilities + +- маршрутизація між моделями +- облік токенів +- облік вартості (1T) +- ліміти usage +- fallback до дешевших моделей +- нормалізація інтерфейсів +- конфіденційність (при confidential mode) +- безпека (prompt sanitizer) +- логування +- autoscaling воркерів +- дотримання governance-політик + +--- + +## 5. Supported Model Types + +### 5.1 Text models + +- gpt-4.1-mini +- gpt-4o +- sonnet +- local LLaMA xB +- Mistral інструктажні + +### 5.2 Vision models + +- gpt-4o-vision +- llava-v1.6 +- open-clip inference + +### 5.3 Embeddings + +- text-embedding-3-small +- local embeddings BGE-large + +### 5.4 Code Models + +- gpt-o1 +- Claude Code +- local starcoder + +### 5.5 Audio + +- Whisper +- Local ASR/TTS + +--- + +## 6. Normalized Request Schema + +Усі LLM запити приходять у форматі: + +```json +{ + "model": "auto|gpt-4o-mini|sonnet", + "messages": [...], + "max_tokens": 4096, + "temperature": 0.5, + "tools": [...], + "context": { + "team_id": "t_555", + "agent_run_id": "ar_001", + "confidential": false + } +} +``` + +--- + +## 7. Routing Modes + +### 7.1 Mode A — DIRECT + +Використати точно зазначену модель. + +### 7.2 Mode B — TIERED ROUTING + +```text +cheap → balanced → premium +``` + +Приклад логіки: + +```text +Якщо контекст короткий → gpt-4o-mini +Якщо потрібний reasoning → gpt-4o +Якщо треба vision → gpt-4o-vision +``` + +### 7.3 Mode C — Specialized + +- код → code model +- embeddings → embedding model +- vision → vision pipeline + +--- + +## 8. Fallback Logic + +1. Якщо модель 503/timeout: + + ```text + fallback to same-tier alternative + ``` + +2. Якщо токени не поміщаються: + + ```text + fallback to compression (summaries) + ``` + +3. Якщо залишився малий бюджет 1T: + + ```text + fallback to cheaper model + ``` + +--- + +## 9. Prompt Sanitization Layer + +Перед викликом моделі LLM Proxy: + +- видаляє інструкції, що намагаються зняти обмеження, +- фільтрує injections: + + ```text + ignore previous instructions + ``` + +- видаляє відомі jailbreak patterns, +- шифрує або редагує конфіденційні частини, +- перетворює спецсимволи. + +--- + +## 10. Confidential Mode + +Якщо у контексті: + +```text +confidential = true +``` + +Тоді LLM Proxy: + +- ховає/редагує plaintext, +- подає тільки summary/embeddings, +- забороняє інструменти з full text, +- вимикає vision (бо містить raw data). + +--- + +## 11. PDP Integration + +Перед виконанням: + +```text +PDP(authorize tool.llm.invoke) +``` + +Після — Usage Engine: + +```text +usage.llm.increment(tokens) +cost_1t = tokens * price +quota.check() +``` + +--- + +## 12. Token Counting + +Підтримуються: + +- exact token count +- pre-count estimation +- streaming token accumulation + +LLM Proxy повертає: + +```json +"usage": { + "prompt_tokens": 1321, + "completion_tokens": 552, + "total_tokens": 1873 +} +``` + +--- + +## 13. Cost Calculation (1T Integration) + +```text +cost_1t = total_tokens × model_price +``` + +*model_price* задається Governance. + +Зберігається у: + +- usage counters, +- agent run summary, +- analytics. + +--- + +## 14. Multi-Model Orchestration + +Підтримує: + +### 14.1 Router-Style Chains + +```text +step 1 → llm-mini +step 2 → llm-large +step 3 → embeddings +step 4 → llm-mini +``` + +### 14.2 Vision → Reasoning flow + +```text +image → vision encoder → LLM → tools → report +``` + +### 14.3 Agents → Tools → LLM → Memory + +--- + +## 15. Error Model + +LLM Proxy повертає: + +| Code | Meaning | +| -------------------------- | ------------------------------- | +| llm_timeout | провайдер не відповів | +| llm_over_quota | usage > quota | +| llm_confidential_violation | текст неможливо подати в модель | +| llm_model_unavailable | модель недоступна | +| llm_input_too_large | не поміщається у контекст | +| llm_safety_block | jailbreak / unsafe | + +--- + +## 16. Retry / Timeouts + +### Timeouts: + +- mini models: 10–25s +- main models: 25–60s +- vision: 45–90s + +### Retry: + +- кожну помилку класифікує Router Engine, +- retry через 1–5 секунд, +- не більше 2 разів. + +--- + +## 17. Model Selection Logic (Pseudo) + +```python +if model == "auto": + if request.has_images: + return "gpt-4o-vision" + if request.tokens < 2000: + return "gpt-4o-mini" + if request.requires_reasoning: + return "gpt-4o" + return "sonnet" +else: + return model +``` + +--- + +## 18. Local Model Constraints + +Local LLaMA/mistral використовуються коли: + +- confidential mode активний, +- cost override, +- автономна інфраструктура (offline mode). + +Обмеження: + +- контекст менше, +- reasoning слабший, +- відповіді короткі, +- інструменти зведені до мінімуму. + +--- + +## 19. Autoscaling + +LLM Proxy має worker pools: + +- text workers +- vision workers +- embeddings workers + +Autoscaling тригериться: + +- queue size +- average latency +- error rate + +--- + +## 20. Logging & Monitoring + +Усі виклики LLM Proxy → логуються (без plaintext): + +- модель +- тривалість +- токени +- cost +- тип інструменту +- fallback чи ні +- error reason + +Метрики в Grafana: + +- tokens/minute +- токени per team +- latency p95 +- fallback rate +- provider availability + +--- + +## 21. Safety / Guardrails + +LLM Proxy забороняє: + +- генерувати шкідливі інструкції, +- виконувати код, +- описувати небезпечні дії, +- обхід sandbox, +- інструкції, спрямовані на капітальні зміни політик. + +--- + +## 22. Example Complete Flow + +```mermaid +sequenceDiagram + participant AG as Agent Runtime + participant GW as Gateway + participant PDP + participant LP as LLM Proxy + participant MR as Router Engine + participant PV as Provider + + AG->>GW: LLM request + GW->>PDP: authorize tool.llm.invoke + PDP-->>GW: allow + GW->>LP: forward + LP->>MR: route(model=auto) + MR-->>LP: gpt-4o-mini + LP->>PV: call model + PV-->>LP: response + LP->>GW: tokens + result + GW->>AG: deliver +``` + +--- + +## 23. Integration with Other Docs + +Цей документ доповнює: + +- `11_llm_integration.md` +- `44_usage_accounting_and_quota_engine.md` +- `32_policy_service_PDP_design.md` +- `36_agent_runtime_isolation_and_sandboxing.md` +- `46_router_orchestrator_design.md` + +--- + +## 24. Завдання для Cursor + +```text +You are a senior backend engineer. Implement LLM Proxy & Multi-Model Routing using: +- 45_llm_proxy_and_multimodel_routing.md +- 11_llm_integration.md +- 44_usage_accounting_and_quota_engine.md + +Tasks: +1) Create LLM Proxy service architecture (Multi-Model Router Engine, Provider interfaces). +2) Implement Normalized Request Schema (unified format for all LLM requests). +3) Add Routing Modes (DIRECT, TIERED ROUTING, Specialized). +4) Implement Fallback Logic (timeout fallback, token compression, budget-based fallback). +5) Add Prompt Sanitization Layer (remove dangerous instructions, filter injections, jailbreak patterns). +6) Implement Confidential Mode (hide/redact plaintext, summary/embeddings only, disable vision). +7) Integrate with PDP (authorize tool.llm.invoke). +8) Add Token Counting (exact count, pre-count estimation, streaming accumulation). +9) Implement Cost Calculation (1T integration, model_price from Governance). +10) Add Multi-Model Orchestration (Router-Style Chains, Vision → Reasoning flow, Agents → Tools → LLM → Memory). +11) Implement Error Model (llm_timeout, llm_over_quota, llm_confidential_violation, llm_model_unavailable, llm_input_too_large, llm_safety_block). +12) Add Retry / Timeouts (per model type, retry logic). +13) Implement Model Selection Logic (auto routing based on request characteristics). +14) Add Local Model Constraints (confidential mode, cost override, offline mode). +15) Implement Autoscaling (worker pools, queue size, latency, error rate triggers). +16) Add Logging & Monitoring (metrics, Grafana dashboards). +17) Implement Safety / Guardrails (block harmful instructions, code execution, dangerous actions). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 25. Summary + +LLM Proxy забезпечує: + +- єдиний інтерфейс до всіх моделей, +- нормалізацію API, +- безпеку promptів, +- конфіденційний режим, +- розумне маршрутування, +- fallback, +- облік токенів, +- прогнозовану вартість, +- масштабованість, +- можливість multi-step orchestration, +- захист від зловживань. + +Це — **центральний обчислювальний шар всієї системи DAARION OS**. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/46_router_orchestrator_design.md b/docs/cursor/46_router_orchestrator_design.md new file mode 100644 index 00000000..730ede46 --- /dev/null +++ b/docs/cursor/46_router_orchestrator_design.md @@ -0,0 +1,452 @@ +# 46 — Router Orchestrator Design (MicroDAO) + +*DAARWIZZ Router: інструментальні маршрути, state machine, контекстні флоу, orchestration, паралелізація, безпека, облік вартості* + +--- + +## 1. Purpose & Scope + +DAARWIZZ Router — це **центральна оркестраційна система**, яка: + +- розбиває задачі на кроки +- викликає інструменти +- викликає агентів +- викликає LLM Proxy +- обробляє помилки +- зупиняє надмірні флоу +- гарантує дотримання cost / usage / quotas +- забезпечує state machine для multi-step процесів + +Це головний механізм **автоматизації процесів** в DAARION.city. + +--- + +## 2. High-Level Architecture + +```text +User / Agent / API + ↓ + Router Orchestrator + ↓ + Step Engine / State Machine + ↓ + Tools / Agents / LLM Proxy / Platform Tools +``` + +--- + +## 3. Input Specification + +Уніфікований формат запиту: + +```json +{ + "input": "...", + "goal": "...", + "constraints": {...}, + "context": { + "team_id": "t_444", + "agent_run_id": "ar_777", + "confidential": false + }, + "steps": "auto|structured", + "tools": ["math","project","llm","greenfood.order"] +} +``` + +--- + +## 4. Router Modes + +### 4.1 Mode A — AUTO PLAN + +Router сам планує кроки (використання лише у продвинутих планах): + +```text +Goal → Plan Generation → Step Execution +``` + +### 4.2 Mode B — STRUCTURED + +Користувач/агент визначає точні кроки: + +```json +steps: [ + { tool:"project.create", args:{...} }, + { tool:"llm", args:{...} } +] +``` + +### 4.3 Mode C — HYBRID + +AI пропонує план → користувач затверджує → Router виконує. + +--- + +## 5. State Machine Architecture + +Router має власний state machine: + +```text +INIT +PLAN +EXECUTE_STEP +WAIT_TOOL +WAIT_AGENT +ERROR_RECOVERY +DONE +``` + +### Переходи: + +- INIT → PLAN +- PLAN → EXECUTE_STEP +- EXECUTE_STEP → WAIT_TOOL/WAIT_AGENT +- WAIT_* → EXECUTE_STEP +- EXECUTE_STEP → DONE +- EXECUTE_STEP → ERROR_RECOVERY +- ERROR_RECOVERY → EXECUTE_STEP | DONE + +--- + +## 6. Step Engine + +Кожен крок має структуру: + +```json +{ + "id": "step_1", + "type": "tool|agent|llm", + "tool": "project.create", + "args": { ... } +} +``` + +### Типи кроків: + +- **LLM** — виклик LLM Proxy +- **Tool** — виклик інструменту +- **Agent** — запуск іншого агента (subagent pattern) +- **Platform** — інтеграція GREENFOOD/EnergyUnion +- **Branch** — умовні гілки (if/else) +- **Parallel** — паралельні підкроки +- **Loop** — повторення (обмежений) + +--- + +## 7. Safety Limits + +Обмеження, які Router зобов'язаний виконати: + +- max_steps = 50 +- max_parallel = 5 +- max_total_cost_1t = team_day_limit +- max_wait_time_per_step = 120s +- max_agent_invocations_per_flow = 5 +- no recursive router → router + +--- + +## 8. Cost Control + +Router виконує pre-estimate: + +```text +estimated_cost = sum(step.cost_estimates) +``` + +Якщо це > quota: + +```text +abort + error: cost_limit_exceeded +``` + +Після кожного кроку: + +- оновлюється фактичний cost +- Usage Engine робить ті самі перевірки +- PDP отримує оновлений контекст + +--- + +## 9. Confidential Mode + +Router: + +- фільтрує plaintext інформацію +- замінює raw → summary +- забороняє vision-кроки +- забороняє tools категорії C/D +- обмежує autonomy планування +- не зберігає input у логах + +--- + +## 10. Tool Execution Flow + +```mermaid +sequenceDiagram + participant R as Router + participant PDP + participant T as Tool Proxy + + R->>PDP: authorize(tool..invoke) + PDP-->>R: allow + R->>T: execute tool + T-->>R: output + usage +``` + +--- + +## 11. LLM Execution Flow + +```mermaid +sequenceDiagram + participant R + participant PDP + participant LLM + + R->>PDP: authorize(tool.llm.invoke) + R->>LLM: normalized request + LLM-->>R: output + tokens +``` + +--- + +## 12. Subagent Execution Flow + +Router може викликати агентів, але з обмеженнями: + +```text +max_subagents_per_flow = 3 +no_chained_subagent → subagent → subagent +``` + +Flow: + +```mermaid +sequenceDiagram + participant R + participant PDP + participant A as Agent Orchestrator + + R->>PDP: authorize(agent.run.invoke) + R->>A: trigger agent + A-->>R: result +``` + +--- + +## 13. Error Handling + +### Типи помилок: + +| Type | Action | +| ---------------------- | ---------------- | +| tool_timeout | retry → skip | +| llm_timeout | retry → fallback | +| invalid_args | fail step | +| unauthorized | abort | +| quota_exceeded | abort | +| agent_failed | skip/abort | +| branch_condition_error | default-fallback | + +### Recovery logic: + +```text +on error: + if retryable → retry 1-2 times + else break or skip +``` + +--- + +## 14. Logging + +Router логування (без plaintext): + +- steps +- timings +- cost +- tokens +- used tools +- fallback transitions +- error traces + +Logs → telemetry + NATS: + +```text +router.flow.started +router.flow.completed +router.flow.failed +``` + +--- + +## 15. Monitoring + +Показники: + +- steps/min +- average cost +- retry rate +- failure rate +- parallelism +- queue depth + +--- + +## 16. Platform Tool Integration (Energy/Food/Water) + +Router може викликати: + +```text +tool.greenfood.order +tool.energy.read +tool.water.read +``` + +Умови: + +- PDP must allow +- confidential mode → redacted +- no mass platform actions (>10 per flow) + +--- + +## 17. Parallel Steps + +Router може виконувати групи: + +```json +{ + "type": "parallel", + "steps": [ + {"type":"llm", ...}, + {"type":"tool", ...} + ] +} +``` + +Завершення: + +- всі успішні → success +- будь-який критичний failure → abort + +--- + +## 18. Branch Logic + +```json +{ + "type": "branch", + "condition": "output.text contains 'yes'", + "if_true": [...], + "if_false": [...] +} +``` + +Оцінка: + +- через LLM Proxy (cheap models) + +--- + +## 19. Loop Logic + +```text +max_loops = 5 +``` + +Loop без умови → abort. + +--- + +## 20. Full Example Flow + +```json +{ + "input": "Створи мені сторінку GreenFood", + "goal": "Сформувати JSON-структуру і завдання", + "steps": [ + { "type": "llm", "args": {"task":"extract_requirements"} }, + { "type": "tool", "tool": "project.create", "args": {...} }, + { "type": "parallel", "steps": [ + { "type": "llm", "args": {...} }, + { "type": "tool", "tool": "task.create", "args": {...} } + ] + } + ] +} +``` + +--- + +## 21. Integration with Other Docs + +Цей документ доповнює: + +- `45_llm_proxy_and_multimodel_routing.md` +- `37_agent_tools_and_plugins_specification.md` +- `32_policy_service_PDP_design.md` +- `44_usage_accounting_and_quota_engine.md` +- `40_rwa_energy_food_water_flow_specs.md` + +--- + +## 22. Завдання для Cursor + +```text +You are a senior backend engineer. Implement Router Orchestrator Design using: +- 46_router_orchestrator_design.md +- 45_llm_proxy_and_multimodel_routing.md +- 37_agent_tools_and_plugins_specification.md + +Tasks: +1) Create Router Orchestrator service architecture (Step Engine, State Machine). +2) Implement Input Specification (unified request format). +3) Add Router Modes (AUTO PLAN, STRUCTURED, HYBRID). +4) Implement State Machine Architecture (INIT, PLAN, EXECUTE_STEP, WAIT_TOOL, WAIT_AGENT, ERROR_RECOVERY, DONE). +5) Create Step Engine (step types: LLM, Tool, Agent, Platform, Branch, Parallel, Loop). +6) Add Safety Limits (max_steps, max_parallel, max_total_cost_1t, max_wait_time_per_step, max_agent_invocations_per_flow, no recursive router). +7) Implement Cost Control (pre-estimate, quota check, actual cost tracking). +8) Add Confidential Mode (filter plaintext, replace raw → summary, disable vision, disable category C/D tools, limit autonomy). +9) Implement Tool Execution Flow (PDP authorization, Tool Proxy integration). +10) Implement LLM Execution Flow (PDP authorization, LLM Proxy integration). +11) Add Subagent Execution Flow (max_subagents_per_flow, no chained subagents). +12) Implement Error Handling (error types, recovery logic, retry mechanism). +13) Add Logging (steps, timings, cost, tokens, tools, fallback, errors). +14) Add Monitoring (steps/min, average cost, retry rate, failure rate, parallelism, queue depth). +15) Implement Platform Tool Integration (GREENFOOD, EnergyUnion, WaterUnion). +16) Add Parallel Steps (parallel execution, success/failure handling). +17) Implement Branch Logic (conditional branches, LLM-based condition evaluation). +18) Add Loop Logic (max_loops, abort on infinite loops). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 23. Summary + +DAARWIZZ Router / Orchestrator: + +- управляє multi-step AI флоу +- гарантує безпеку кожного кроку +- інтегрує LLM, інструменти, агентів та платформи +- контролює витрати 1T та usage +- виконує state machine +- захищений policy engine +- підтримує branching, loops, parallelism +- працює в confidential mode +- є основою автоматизації у DAARION OS + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/47_messaging_channels_and_privacy_layers.md b/docs/cursor/47_messaging_channels_and_privacy_layers.md new file mode 100644 index 00000000..5222e888 --- /dev/null +++ b/docs/cursor/47_messaging_channels_and_privacy_layers.md @@ -0,0 +1,436 @@ +# 47 — Messaging Channels & Privacy Layers (MicroDAO) + +*Приватні та командні канали, конфіденційність, ACL, індексація, message lifetimes, agent visibility, редагування, модерація, шифрування* + +--- + +## 1. Purpose & Scope + +Цей документ встановлює: + +- архітектуру чатів та каналів, +- правила доступу (ACL), +- приватність і confidential mode, +- схему повідомлень, +- правила збереження / ретенції, +- індексацію (без plaintext), +- agent visibility, +- інтеграцію з tools, governance, PDP, LLM Proxy. + +Це основа всієї комунікаційної системи DAARION.city. + +--- + +## 2. Messaging Entities + +DAARION має три типи комунікаційних просторів: + +1. **Direct Messages (DM)** +2. **Team Channels (microDAO)** +3. **System Channels** (log streams, notifications) + +--- + +## 3. Channel Types + +### 3.1 DIRECT + +- між двома користувачами +- ACL: `user A` + `user B` +- агент має доступ тільки якщо дозволено вручну + +### 3.2 TEAM PUBLIC + +- доступні всій команді +- бачать усі користувачі + Agent Manager + +### 3.3 TEAM PRIVATE + +- обмежені `Owner/Guardian` та обрані учасники +- agents → **no access by default** + +### 3.4 CONFIDENTIAL CHANNEL + +**Найвищий рівень приватності:** + +- plaintext не індексується +- plaintext не передається агентам +- plaintext не зберігається в logs +- LLM Proxy отримує тільки summary/embeddings +- Router не може виконувати vision-кроки + +--- + +## 4. Channel Schema + +```sql +create table channels ( + id text primary key, + team_id text, + type text, -- direct, team_public, team_private, confidential + name text, + created_by text, + created_at timestamptz, + updated_at timestamptz +); +``` + +--- + +## 5. Message Schema + +```sql +create table messages ( + id text primary key, + channel_id text, + sender_id text, + sender_type text, -- user|agent|system + body_summary text, -- plaintext summary (clean) + body_embedding vector, -- embedding + body_raw text, -- encrypted E2EE blob (optional) + reply_to text, + created_at timestamptz, + updated_at timestamptz +); +``` + +**ВАЖЛИВО:** + +`body_raw` ніколи не зберігається у plaintext, тільки як зашифрований blob (або порожнє поле в confidential mode). + +--- + +## 6. E2EE Model (Optional Layer) + +E2EE може бути: + +- увімкнений на канал, +- увімкнений користувачем, +- увімкнений командою. + +E2EE робить: + +- `body_raw` → AES-256-GCM +- Encryption keys → local device +- Server → бачить тільки ciphertext + summary/embeddings + +--- + +## 7. Confidential Mode Rules + +Якщо канал має тип `confidential`: + +- `body_raw` → optional or must be encrypted +- не зберігається plaintext summary (тільки redacted summary) +- embeddings генеруються з redacted тексту +- агенти не бачать вміст +- LLM Proxy бачить тільки: + - `summary` + - high-level metadata +- vision заблокований +- tools категорії C/D → заблоковані +- Router автономія ↓ + +--- + +## 8. ACL Model + +У кожному каналі: + +```text +ACL = { users: [...], agents: [...], roles: [...] } +``` + +### Roles: + +- Owner +- Guardian +- Member +- Guest +- Agent + +В ACL обов'язково зазначаються: + +- хто може читати +- хто може писати +- хто може надсилати файли +- хто може переглядати історію + +Приклад ACL: + +```json +{ + "read": ["owner","guardian","member"], + "write": ["owner","guardian"], + "agents_allowed": ["ag_777"] +} +``` + +--- + +## 9. Agent Visibility Rules + +### Default: + +Агенти **не мають доступу** до каналів. + +### Дозволи: + +- Owner/Guardian може додати агента до каналу +- Агент отримує: + - summaries + - embeddings + - metadata +- Не отримує: + - filesystem attachments + - raw plaintext + - vision data + - files > 1MB + +--- + +## 10. Search Indexing + +Система не індексує plaintext. + +Індекс формується із: + +- `body_summary` (redacted якщо confidential) +- embeddings +- metadata (sender, timestamps, channel) + +Search Engine використовує: + +- vector search для semantic +- keyword index для metadata + +--- + +## 11. Message Lifecycle + +### 11.1 Create + +- plaintext → sanitization +- summary → create +- embedding → create +- body_raw → E2EE або skip +- запис у DB +- подія `chat.message.created` + +### 11.2 Edit + +- новий summary (raw не зберігається) +- подія `chat.message.updated` + +### 11.3 Delete + +- `body_summary = "[deleted]"` +- embeddings → zero vector +- raw → purged +- подія `chat.message.deleted` + +--- + +## 12. Retention Rules + +### Direct Messages + +- 30–180 днів + +### Team Public + +- 30–365 днів + +### Team Private + +- 90–365 днів + +### Confidential + +- 0–30 днів (політика команди) + +### System Channels + +- 90–365 днів + +--- + +## 13. Attachments (Files) + +Дозволено, але залежно від каналу: + +| Тип каналу | Макс розмір | Зберігання | Agent Access | +| ------------ | ----------- | ---------- | ------------ | +| direct | 10MB | encrypted | no | +| team_public | 25MB | encrypted | summary only | +| team_private | 25MB | encrypted | no | +| confidential | 5MB | encrypted | no | + +--- + +## 14. Moderate / Filter System + +Система фільтрує: + +- небезпечні prompt-інструкції +- sensitive data → summary only +- файли з підозрілим MIME +- external email/password leaks + +AI Moderator генерує: + +- `message.flagged` події +- автоматичні warnings + +--- + +## 15. Chat → Agent → LLM Proxy Flow + +```mermaid +sequenceDiagram + participant U as User + participant CH as Channel + participant AG as Agent + participant GW as Gateway + participant L as LLM Proxy + + U->>CH: send message + CH->>AG: notify (if allowed) + AG->>GW: llm request (summary only) + GW->>L: sanitized request + L-->>AG: output + AG-->>CH: agent reply +``` + +--- + +## 16. Chat → Router Flow + +Router може запускати multi-step flows, але: + +- тільки в каналах, що НЕ confidential +- тільки за дозволу каналу (`agents_allowed`) +- не більше 5 flows/hour/channel + +--- + +## 17. System Channels + +Система має спеціальні канали: + +- `system.audit` +- `system.notifications` +- `system.rwa` +- `system.wallet` +- `system.payouts` +- `system.governance` + +Ці канали: + +- read-only +- plaintext → summary only +- доступні Owner/Guardian +- агенти не бачать + +--- + +## 18. Governance Controls + +Governance може: + +- визначати максимальні retention політики +- визначати ACL policy templates +- активувати/деактивувати confidential режим +- визначати, чи агенти можуть бачити summaries +- обмежувати індексацію +- встановлювати file limits + +--- + +## 19. Observability & Telemetry + +Метрики: + +- messages/hour +- agent participation +- confidential ratio +- flagged messages +- search queries + +Логи без plaintext: + +- channel actions +- ACL changes +- dangerous content flags + +--- + +## 20. Integration with Other Docs + +Цей документ доповнює: + +- `04_ui_ux_onboarding_chat.md` +- `14_messenger_agent_module.md` +- `45_llm_proxy_and_multimodel_routing.md` +- `46_router_orchestrator_design.md` +- `32_policy_service_PDP_design.md` + +--- + +## 21. Завдання для Cursor + +```text +You are a senior backend engineer. Implement Messaging Channels & Privacy Layers using: +- 47_messaging_channels_and_privacy_layers.md +- 04_ui_ux_onboarding_chat.md +- 14_messenger_agent_module.md + +Tasks: +1) Create Channel Schema (channels table: id, team_id, type, name, created_by, created_at, updated_at). +2) Create Message Schema (messages table: id, channel_id, sender_id, sender_type, body_summary, body_embedding, body_raw, reply_to, created_at, updated_at). +3) Implement Channel Types (DIRECT, TEAM PUBLIC, TEAM PRIVATE, CONFIDENTIAL CHANNEL). +4) Add E2EE Model (optional layer, AES-256-GCM encryption, local device keys). +5) Implement Confidential Mode Rules (no plaintext indexing, no agent access, LLM Proxy summary only, disable vision, disable category C/D tools). +6) Create ACL Model (users, agents, roles: Owner, Guardian, Member, Guest, Agent). +7) Implement Agent Visibility Rules (default no access, Owner/Guardian can add, summaries/embeddings only, no filesystem attachments, no raw plaintext, no vision data, no files > 1MB). +8) Add Search Indexing (no plaintext, body_summary + embeddings + metadata, vector search, keyword index). +9) Implement Message Lifecycle (Create: sanitization, summary, embedding, E2EE; Edit: new summary; Delete: body_summary = "[deleted]", zero vector, purge raw). +10) Add Retention Rules (Direct Messages: 30-180 days, Team Public: 30-365 days, Team Private: 90-365 days, Confidential: 0-30 days, System Channels: 90-365 days). +11) Implement Attachments (Files) (per channel type limits, encryption, agent access rules). +12) Add Moderate / Filter System (dangerous prompts, sensitive data, suspicious MIME, email/password leaks, AI Moderator, message.flagged events). +13) Implement Chat → Agent → LLM Proxy Flow (summary only, sanitized request). +14) Add Chat → Router Flow (non-confidential only, agents_allowed permission, max 5 flows/hour/channel). +15) Create System Channels (system.audit, system.notifications, system.rwa, system.wallet, system.payouts, system.governance). +16) Add Governance Controls (retention policies, ACL templates, confidential mode activation, agent visibility, indexing limits, file limits). +17) Add Observability & Telemetry (metrics, logs without plaintext). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 22. Summary + +Messaging Layer у DAARION.city: + +- багаторівневий +- масштабований +- заснований на приватності +- сумісний з confidential режимом +- не зберігає plaintext +- має ACL-per-channel +- повністю інтегрований з PDP, Agents, LLM Proxy +- гарантує приватність команд/користувачів +- безпечний для автоматизації через Router + +Це — **комунікаційний шар DAARION OS**. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/48_teams_access_control_and_confidential_mode.md b/docs/cursor/48_teams_access_control_and_confidential_mode.md new file mode 100644 index 00000000..fc755f5c --- /dev/null +++ b/docs/cursor/48_teams_access_control_and_confidential_mode.md @@ -0,0 +1,409 @@ +# 48 — Teams Access Control & Confidential Mode (MicroDAO) + +*Командні доступи, ролі, членство, ACL, confidential mode, індексація, інструменти, агенти, governance-політики. Канонічна специфікація microDAO команд.* + +--- + +## 1. Purpose & Scope + +Цей документ визначає: + +- структуру команд (microDAO), +- ролі та дозволи, +- ACL для ресурсів, +- поведінку Confidential Mode, +- вплив на агентів, інструменти, чат, LLM Proxy, Router, Wallet, Embassy, Projects/Tasks, +- правила Governance. + +Це центральний рівень контролю безпеки й приватності у DAARION.city. + +--- + +## 2. Team (microDAO) Model + +Команда = організаційний домен, який має: + +- учасників (members), +- ролі, +- командні налаштування, +- власну економіку (1T / KWT / RINGK стейк), +- власний набір агентів, +- власні канали, +- власні ACL. + +--- + +## 3. Team Roles + +| Role | Capabilities | Опис | +| ------------ | ------------------------------------------------------- | -------------------- | +| **Owner** | повний контроль, зміна налаштувань, звільнення Guardian | creator of team | +| **Guardian** | майже все, крім знищення команди | security + oversight | +| **Admin** | керування каналами/агентами/ресурсами | operational | +| **Member** | доступ до основних інструментів | worker | +| **Guest** | читання + обмежені інструменти | limited | +| **Agent** | системний агент команди | restricted | + +Команда може мати: + +- 1 owner +- 0–N guardians +- 0–N admins +- 0–N members +- 0–N guests +- 0–N private agents + +--- + +## 4. Role Capability Mapping + +### Owner + +- повний доступ +- оновлювати план +- додавати/видаляти членів +- змінювати confidential mode +- випускати токени команди (якщо дозволено governance) + +### Guardian + +- контролює security sensitive +- додавання агентів +- доступ до private channels +- керування ACL +- активація E2EE + +### Admin + +- створення каналів +- створення проектів +- керування задачами +- запуск agent flows + +### Member + +- участь у каналах +- запуск агентів (якщо дозволено) +- створення задач у публічних проєктах + +### Guest + +- читання +- обмежені інструменти +- немає доступу до agent visibility + +### Agent + +- діє через PDP +- може діяти лише у дозволених каналах/проєктах +- не має власних ролей + +--- + +## 5. Team-Level ACL + +У команді існує ACL для кожного типу ресурсу: + +```text +RESOURCE → [allowed_roles] +``` + +Приклад: + +### Projects + +```text +create: [owner, guardian, admin] +read: [owner, guardian, admin, member] +update: [owner, guardian, admin] +delete: [owner, guardian] +``` + +### Channels + +```text +create: [owner, guardian, admin] +read/write: залежить від channel.acl +``` + +### Agents + +```text +create: [owner, guardian] +update: [owner, guardian] +run: [owner, guardian, member] (опційно) +``` + +### Wallet + +```text +view: [owner, guardian] +tx: [owner] +claim: [owner, guardian] +``` + +### Embassy Data + +```text +read: [owner, guardian] +write: none (тільки embassy service) +``` + +--- + +## 6. Team States + +Команда може перебувати в станах: + +- **active** — нормальна робота +- **locked** — тимчасове блокування (борги, порушення) +- **confidential** — підвищена приватність +- **suspended** — потребує KYC / security audit +- **archived** — команда закрита + +--- + +## 7. Confidential Mode + +Confidential Mode — це **режим максимального захисту** для команд. + +### Увімкнення: + +лише Owner або Guardian + +### Поведінка: + +#### 7.1 LLM Proxy + +- не бачить plaintext повідомлень +- використовує summary-only режим +- vision вимкнено +- embedding робиться з redacted тексту + +#### 7.2 Agents + +- не отримують plaintext +- не можуть використовувати tools категорії C/D +- не можуть використовувати platform tools +- autonomy знижується на 1 рівень +- не можуть запускати subagents + +#### 7.3 Messaging + +- повідомлення не зберігаються у plaintext +- DM канал між Owner та Guardian → E2EE only +- file attachments encrypt-only +- retention: 0–30 днів + +#### 7.4 Projects/Tasks + +- task description → summary-only +- файли завжди E2EE +- agent-run logs → redacted + +#### 7.5 Wallet/RWA + +- доступ обмежений Owner/Guardian +- payouts проходять без content-level history +- RWA дані теж redacted + +--- + +## 8. Team Privacy Layers + +Рівні приватності: + +| Level | Description | +| ------------ | --------------------------------- | +| open | звичайний режим | +| restricted | менш видимі канали | +| private | DM-like behavior | +| confidential | максимальний захист, summary-only | + +--- + +## 9. Team Settings Schema + +```json +{ + "team_id": "t_444", + "name": "GreenFood Hub", + "plan": "Premium", + "confidential": true, + "settings": { + "agents_enabled": true, + "allow_subagents": false, + "allow_router_flows": true, + "file_storage_limit_mb": 5000, + "agent_default_autonomy": "low" + }, + "acl_overrides": { + "wallet.view": ["owner","guardian"], + "wallet.tx": ["owner"], + "projects.create": ["owner","guardian","admin"] + } +} +``` + +--- + +## 10. PDP Integration + +PDP оцінює дію: + +- роль користувача +- ACL ресурсу +- командний стан +- confidential mode +- usage +- план команди +- stake RINGK + +Висновок: + +```text +allow | deny | require-confirmation +``` + +--- + +## 11. Governance Controls + +Governance може: + +- змінювати allowed roles +- визначати максимальну автономію агентів +- вмикати/вимикати confidential mode для певного плану +- вводити policy templates для ACL +- встановлювати KYC-вимоги +- заморожувати команди, що порушили правила + +--- + +## 12. Membership Lifecycle + +### Create Team: + +- Owner створює +- Дається початковий ACL + +### Invite Member: + +- Owner/Admin може запросити → role=member + +### Promote: + +- Member → Admin → Guardian + +### Demote: + +- лише Owner може демотити Guardian + +### Remove: + +- Owner або Guardian (якщо не Owner) + +--- + +## 13. Agent Integration Rules + +Агенти: + +- самі не мають ролей +- використовують access keys +- діють тільки через PDP +- бачать тільки те, що канал/проект дозволяє +- у confidential mode → summary-only +- не можуть змінювати ACL +- не можуть виконувати wallet.tx + +--- + +## 14. Examples + +### Example 1 — Створення приватного каналу + +```text +roles: [owner, guardian] +confidential: false +``` + +### Example 2 — Канал для автономного агента + +```text +roles: [owner, guardian, member] +agents_allowed: [ag_777] +confidential: false +``` + +### Example 3 — Канал у confidential mode + +```text +type: confidential +agents_allowed: [] +raw disabled +summary-only +``` + +--- + +## 15. Integration with Other Docs + +Цей документ доповнює: + +- `47_messaging_channels_and_privacy_layers.md` +- `32_policy_service_PDP_design.md` +- `36_agent_runtime_isolation_and_sandboxing.md` +- `45_llm_proxy_and_multimodel_routing.md` +- `46_router_orchestrator_design.md` +- `40_rwa_energy_food_water_flow_specs.md` + +--- + +## 16. Завдання для Cursor + +```text +You are a senior backend engineer. Implement Teams Access Control & Confidential Mode using: +- 48_teams_access_control_and_confidential_mode.md +- 32_policy_service_PDP_design.md +- 47_messaging_channels_and_privacy_layers.md + +Tasks: +1) Define Team Roles (Owner, Guardian, Admin, Member, Guest, Agent) with capabilities. +2) Implement Role Capability Mapping (per role permissions). +3) Create Team-Level ACL (Projects, Channels, Agents, Wallet, Embassy Data). +4) Implement Team States (active, locked, confidential, suspended, archived). +5) Add Confidential Mode (LLM Proxy behavior, Agents restrictions, Messaging rules, Projects/Tasks rules, Wallet/RWA rules). +6) Implement Team Privacy Layers (open, restricted, private, confidential). +7) Create Team Settings Schema (JSON config with settings and ACL overrides). +8) Integrate with PDP (role, ACL, team state, confidential mode, usage, plan, stake evaluation). +9) Add Governance Controls (allowed roles, agent autonomy, confidential mode activation, ACL templates, KYC requirements, team freezing). +10) Implement Membership Lifecycle (Create Team, Invite Member, Promote, Demote, Remove). +11) Add Agent Integration Rules (no roles, access keys, PDP-only, channel/project permissions, confidential mode restrictions, no ACL changes, no wallet.tx). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 17. Summary + +Система команд (microDAO): + +- має строгі ролі та ACL +- повністю інтегрована з PDP +- визначає дозволи для projects/tasks/wallet/agents +- підтримує confidential mode (summary-only, no plaintext, no vision) +- гарантує приватність даних +- дозволяє побудову складних робочих просторів +- є фундаментом безпеки та організації в DAARION OS + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/49_wallet_rwa_payouts_claims.md b/docs/cursor/49_wallet_rwa_payouts_claims.md new file mode 100644 index 00000000..c77cf9e2 --- /dev/null +++ b/docs/cursor/49_wallet_rwa_payouts_claims.md @@ -0,0 +1,395 @@ +# 49 — Wallet, RWA, Payouts & Claims (MicroDAO) + +*Архітектура Wallet Service: баланси, RWA-нарахування, KWT/1T економіка, payout-и, claims, ACL, подвійна верифікація, безпека.* + +--- + +## 1. Purpose & Scope + +Документ визначає: + +- модель гаманця (Wallet Service), +- токени, що підтримуються, +- RWA → KWT / 1T нарахування, +- payouts та claims, +- ACL для гаманця, +- інтеграцію з RWA, Embassy, Usage Engine, Governance. + +Це економічний центр системи DAARION. + +--- + +## 2. Wallet Tokens + +### 2.1 1T Token + +- внутрішній compute токен +- витрачається на LLM, agents, tools, router +- mint: Governance (policy-based) +- burn: Usage (auto) + +### 2.2 KWT Token + +- внутрішній енергетичний токен +- нараховується за kWh +- використовується на оплату енергетичних сервісів +- рідко витрачається на compute +- може бути конвертований у 1T (governance-defined) + +### 2.3 RINGK Token + +- stake token +- збільшує квоти +- впливає на governance +- не витрачається на compute + +### 2.4 DAARION Token + +- governance token +- використовується у голосуваннях +- не впливає на usage +- може бути конвертований у RINGK + +--- + +## 3. Wallet Architecture + +```text +API Gateway (PEP) + ↓ + PDP + ↓ + Wallet Service + ↓ +Postgres + NATS Events +``` + +Wallet обробляє: + +- read балансів +- записи payout +- claims +- внутрішні транзакції між командами +- audit логування + +--- + +## 4. Wallet Schema + +### 4.1 Balances + +```sql +create table wallet_balances ( + id text primary key, + owner_type text, -- user|team + owner_id text, + symbol text, -- 1T|KWT|RINGK|DAARION + balance numeric, + updated_at timestamptz +); +``` + +--- + +### 4.2 Transactions + +```sql +create table wallet_transactions ( + id text primary key, + owner_type text, + owner_id text, + symbol text, + amount numeric, + direction text, -- credit|debit + reason text, + ref text, + ts timestamptz +); +``` + +--- + +### 4.3 Payouts + +```sql +create table payouts ( + id text primary key, + team_id text, + symbol text, -- KWT|1T + amount numeric, + rwa_ref text, -- reference to rwa_inventory + status text, -- generated|claimed|failed + created_at timestamptz, + claimed_at timestamptz +); +``` + +--- + +## 5. ACL Rules + +### Wallet Access + +| Action | Roles Allowed | +| --------------- | --------------------------- | +| view balances | owner, guardian | +| claim payouts | owner, guardian | +| send tx | owner | +| convert tokens | owner | +| read audit | owner, guardian | +| no agent access | agents cannot read balances | + +Agent run **не може**: + +- бачити баланси +- робити payouts +- робити транзакції + +--- + +## 6. RWA → Payout Formula + +### 6.1 ENERGY → KWT + +```text +delta_kwh = inventory.delta +payout = delta_kwh × conversion_rate_energy_kwt +``` + +### 6.2 FOOD → 1T + +```text +delta_kg × conversion_rate_food_1t +``` + +### 6.3 WATER → 1T або KWT + +```text +delta_m3 × water_reward_rate (1T/KWT) +``` + +Conversion rates задає Governance. + +--- + +## 7. Payout Lifecycle + +```mermaid +sequenceDiagram + participant EMB as Embassy + participant RWA as RWA Processor + participant W as Wallet + participant OUT as Outbox + participant N as NATS + + EMB->>RWA: new measurement + RWA->>W: request payout + W->>W: calculate + W->>DB: insert payout + W->>OUT: insert outbox event + OUT->>N: payout.generated +``` + +--- + +## 8. Claim Lifecycle + +Owner/Guardian може забрати payout: + +```mermaid +sequenceDiagram + participant U + participant GW + participant PDP + participant W + + U->>GW: POST /wallet/payout/:id/claim + GW->>PDP: authorize(payout.claim) + PDP-->>GW: allow + + GW->>W: claim + W->>DB: update payout status + W->>DB: credit wallet balance + W-->>GW: success +``` + +--- + +## 9. Conversion Rules + +Команда може конвертувати: + +### KWT → 1T + +- курс визначає Governance +- зазвичай 1:1 або 1:0.85 +- обмеження на денний об'єм + +### DAARION → RINGK + +- тільки за рішенням governance +- збільшує stake + +### RINGK → 1T + +- неможливо (односторонній стейк) + +--- + +## 10. Daily/Monthly Limits + +Wallet Service накладає ліміти: + +- max claims/day +- max tx/day +- max conversion/day +- max payout value/day + +--- + +## 11. Fraud Protection + +Wallet блокує: + +- подвійні claims +- негативний баланс +- підозрілі великі нарахування +- конфлікт даних з RWA +- повторні RWA-події з однаковим timestamp +- підміну site_id + +--- + +## 12. Governance Controls + +Governance може: + +- встановлювати conversion rates +- встановлювати max rewards/day +- коригувати max payout +- вимикати reward-и на певний період +- включати emergency freeze +- контролювати стейк RINGK + +--- + +## 13. Integrations + +### 13.1 NATS Events + +Wallet генерує: + +- `wallet.balance.updated` +- `wallet.tx.sent` +- `payout.generated` +- `payout.claimed` + +### 13.2 Usage Engine + +Wallet використовує Usage Engine для billing за: + +- claims +- tx +- conversion + +### 13.3 PDP + +Кожна дія в гаманці → PDP(authorize). + +--- + +## 14. Transparency & Logs + +Wallet зберігає audit trail: + +- хто зробив claim +- коли +- з якого IP/device +- які payout-и пов'язані +- які RWA-дані були використані + +--- + +## 15. Example Scenarios + +### 15.1 Енергія + +Команда виробила 250 kWh → payout=250 KWT. + +### 15.2 Вода + +Очистка 1 m³ → 1T payout. + +### 15.3 Конвертація + +Owner конвертує 100 KWT → 80 1T. + +### 15.4 Claim + +Owner забирає payout → баланс додається → статус "claimed". + +--- + +## 16. Integration with Other Docs + +Цей документ доповнює: + +- `40_rwa_energy_food_water_flow_specs.md` +- `28_flows_wallet_embassy_energy_union.md` +- `32_policy_service_PDP_design.md` +- `44_usage_accounting_and_quota_engine.md` +- `48_teams_access_control_and_confidential_mode.md` + +--- + +## 17. Завдання для Cursor + +```text +You are a senior backend engineer. Implement Wallet, RWA, Payouts & Claims using: +- 49_wallet_rwa_payouts_claims.md +- 40_rwa_energy_food_water_flow_specs.md +- 28_flows_wallet_embassy_energy_union.md + +Tasks: +1) Create Wallet Service architecture (API Gateway → PDP → Wallet Service → Postgres + NATS). +2) Define Wallet Tokens (1T, KWT, RINGK, DAARION) with properties. +3) Create Wallet Schema (wallet_balances, wallet_transactions, payouts tables). +4) Implement ACL Rules (view balances, claim payouts, send tx, convert tokens, read audit, no agent access). +5) Implement RWA → Payout Formula (ENERGY → KWT, FOOD → 1T, WATER → 1T/KWT). +6) Implement Payout Lifecycle (Embassy → RWA Processor → Wallet → Outbox → NATS). +7) Implement Claim Lifecycle (User → Gateway → PDP → Wallet → DB update). +8) Add Conversion Rules (KWT → 1T, DAARION → RINGK, RINGK → 1T impossible). +9) Implement Daily/Monthly Limits (max claims/day, max tx/day, max conversion/day, max payout value/day). +10) Add Fraud Protection (double claims, negative balance, suspicious large credits, RWA data conflicts, duplicate RWA events, site_id tampering). +11) Add Governance Controls (conversion rates, max rewards/day, max payout, reward disabling, emergency freeze, RINGK stake control). +12) Integrate with NATS Events (wallet.balance.updated, wallet.tx.sent, payout.generated, payout.claimed). +13) Integrate with Usage Engine (billing for claims, tx, conversion). +14) Integrate with PDP (authorize every wallet action). +15) Add Transparency & Logs (audit trail: who, when, IP/device, related payouts, RWA data used). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 18. Summary + +Wallet Service: + +- веде баланси 1T/KWT/RINGK/DAARION +- керує payout-и за RWA +- забезпечує claim-и +- інтегрований з Embassy/RWA/Outbox/NATS +- має строгі ACL +- забезпечує прозору економічну модель +- є фундаментальним компонентом DAARION OS + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/50_daarion_city_website_integration.md b/docs/cursor/50_daarion_city_website_integration.md new file mode 100644 index 00000000..dbe8a3b0 --- /dev/null +++ b/docs/cursor/50_daarion_city_website_integration.md @@ -0,0 +1,596 @@ +# 50 — DAARION.city Website Integration (MicroDAO) + +*Специфікація інтеграції MicroDAO у офіційний сайт DAARION.city як перший публічний MicroDAO* + +--- + +## 1. Purpose & Scope + +Документ визначає: + +- як вбудовувати MicroDAO у офіційний сайт DAARION.city, +- API для публічного каналу міста, +- UI/UX для публічного каналу на сайті, +- Authentication flow для користувачів сайту, +- SEO та метадані для публічного каналу, +- Embedding/iframe інтеграцію (опційно), +- Analytics та tracking. + +Це перша інтеграція MicroDAO у зовнішній сайт. + +--- + +## 2. Architecture Overview + +### 2.1 High-Level Integration + +```text +DAARION.city Website (Next.js/React) + ↓ + Public Channel Embed + ↓ + MicroDAO API Gateway + ↓ + MicroDAO Backend Services +``` + +### 2.2 Integration Modes + +**Mode 1: Embedded Widget (Recommended)** +- MicroDAO публічний канал вбудовується як React компонент на сайті +- Використовує MicroDAO API напряму +- Повний контроль над UI/UX + +**Mode 2: iframe Embed** +- MicroDAO публічний канал відкривається в iframe +- Простіша інтеграція, менше контролю +- Використовується для швидкого прототипування + +**Mode 3: Full Redirect** +- Посилання з сайту веде на окрему сторінку MicroDAO +- Найпростіша реалізація +- Втрачається контекст сайту + +--- + +## 3. DAARION.city as First MicroDAO + +### 3.1 Team Setup + +DAARION.city має бути створений як перший MicroDAO: + +```sql +INSERT INTO teams ( + id, + name, + slug, + type, + mode, + description, + created_at +) VALUES ( + 'daarion-city', + 'DAARION.city', + 'daarion', + 'city', + 'public', + 'Офіційна спільнота міста DAARION', + NOW() +); +``` + +### 3.2 Public Channel Setup + +Створюється публічний канал для міста: + +```sql +INSERT INTO channels ( + id, + team_id, + title, + slug, + type, + is_public, + created_at +) VALUES ( + 'daarion-city-general', + 'daarion-city', + 'Загальний канал міста', + 'general', + 'public', + true, + NOW() +); +``` + +### 3.3 City Agent Setup + +Створюється міський агент: + +```sql +INSERT INTO agents ( + id, + team_id, + name, + role, + system_prompt, + memory_scope, + created_at +) VALUES ( + 'daarion-city-agent', + 'daarion-city', + 'Міський Асистент', + 'team_assistant', + 'Ти — міський асистент DAARION.city. Допомагаєш мешканцям та гостям міста.', + 'team', + NOW() +); +``` + +--- + +## 4. Public Channel API + +### 4.1 Get Public Channel Info + +```http +GET /api/v1/channels/{slug}/public +``` + +**Response:** +```json +{ + "id": "daarion-city-general", + "team_id": "daarion-city", + "title": "Загальний канал міста", + "slug": "general", + "description": "Публічний канал для обговорення міських питань", + "message_count": 1234, + "member_count": 567, + "is_public": true, + "team": { + "id": "daarion-city", + "name": "DAARION.city", + "slug": "daarion" + } +} +``` + +### 4.2 Get Public Messages + +```http +GET /api/v1/channels/{slug}/public/messages?limit=50&before={message_id} +``` + +**Response:** +```json +{ + "messages": [ + { + "id": "msg-123", + "sender": { + "id": "user-456", + "name": "Олександр", + "avatar_url": "https://..." + }, + "body": "Привіт, місто!", + "created_at": "2024-11-14T10:00:00Z", + "reactions": [] + } + ], + "pagination": { + "has_more": true, + "next_cursor": "msg-124" + } +} +``` + +### 4.3 Post Message (Authenticated) + +```http +POST /api/v1/channels/{slug}/public/messages +Authorization: Bearer {token} +Content-Type: application/json + +{ + "body": "Повідомлення від користувача" +} +``` + +### 4.4 Register as Viewer/Member + +```http +POST /api/v1/channels/{slug}/public/join +Content-Type: application/json + +{ + "email": "user@example.com", + "name": "Ім'я Користувача", + "viewer_type": "member" | "visitor" +} +``` + +**Response:** +```json +{ + "user_id": "user-789", + "access_token": "jwt-token", + "membership": { + "role": "member", + "viewer_type": "member" + } +} +``` + +--- + +## 5. UI/UX for Website Integration + +### 5.1 Embedded Widget Component + +**React Component:** +```tsx + +``` + +**Props:** +- `channelSlug`: slug каналу +- `teamSlug`: slug команди +- `apiUrl`: URL API Gateway +- `theme`: "light" | "dark" +- `showHeader`: показувати заголовок каналу +- `allowJoin`: дозволити реєстрацію з віджета + +### 5.2 Widget Layout + +``` +┌─────────────────────────────────────┐ +│ # Загальний канал міста │ +│ DAARION.city │ +├─────────────────────────────────────┤ +│ │ +│ [Messages List] │ +│ │ +│ ┌───────────────────────────────┐ │ +│ │ [Input Field] [Send] │ │ +│ └───────────────────────────────┘ │ +│ │ +│ [Join Button] (if not authenticated)│ +└─────────────────────────────────────┘ +``` + +### 5.3 Authentication Flow + +**Step 1: Guest View** +- Користувач бачить повідомлення (read-only) +- Кнопка "Приєднатися до обговорення" + +**Step 2: Join Modal** +- Форма: Email, Ім'я, Тип участі (Member/Visitor) +- Відправка запиту на `/api/v1/channels/{slug}/public/join` +- Отримання JWT токену + +**Step 3: Authenticated View** +- Користувач може писати повідомлення +- Відображається його профіль +- Доступ до повної функціональності каналу + +--- + +## 6. SEO & Metadata + +### 6.1 Open Graph Tags + +```html + + + + + +``` + +### 6.2 Twitter Cards + +```html + + + + +``` + +### 6.3 Structured Data (JSON-LD) + +```json +{ + "@context": "https://schema.org", + "@type": "DiscussionForumPosting", + "headline": "Загальний канал міста DAARION.city", + "description": "Публічний канал для обговорення міських питань", + "author": { + "@type": "Organization", + "name": "DAARION.city" + }, + "datePublished": "2024-11-14T10:00:00Z" +} +``` + +--- + +## 7. Security & Privacy + +### 7.1 CORS Configuration + +API Gateway має дозволяти запити з `https://daarion.city`: + +```typescript +const corsOptions = { + origin: [ + 'https://daarion.city', + 'https://www.daarion.city', + 'http://localhost:3000' // для розробки + ], + credentials: true, + methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'], + allowedHeaders: ['Content-Type', 'Authorization'] +}; +``` + +### 7.2 Rate Limiting + +Публічний канал має обмеження: + +- **Guest (read-only):** 100 requests/minute +- **Authenticated (write):** 30 messages/minute +- **Join requests:** 5 requests/hour per IP + +### 7.3 Content Moderation + +- Автоматична модерація через Agent +- Фільтрація спаму +- Блокування токсичного контенту +- Можливість скарг від користувачів + +--- + +## 8. Analytics & Tracking + +### 8.1 Events to Track + +```typescript +type AnalyticsEvent = + | { type: 'channel_view', channel_slug: string } + | { type: 'message_sent', channel_slug: string, user_id: string } + | { type: 'join_clicked', channel_slug: string } + | { type: 'join_completed', channel_slug: string, viewer_type: string } + | { type: 'widget_loaded', channel_slug: string, load_time: number }; +``` + +### 8.2 Integration with Analytics + +- Google Analytics 4 +- Plausible Analytics (privacy-friendly) +- Custom analytics endpoint + +--- + +## 9. Implementation Steps + +### Step 1: Backend Setup + +1. Створити DAARION.city team у БД +2. Створити публічний канал +3. Створити міського агента +4. Налаштувати CORS для `daarion.city` +5. Додати rate limiting для публічного каналу + +### Step 2: API Endpoints + +1. `GET /api/v1/channels/{slug}/public` — інформація про канал +2. `GET /api/v1/channels/{slug}/public/messages` — повідомлення +3. `POST /api/v1/channels/{slug}/public/messages` — надіслати повідомлення +4. `POST /api/v1/channels/{slug}/public/join` — приєднатися + +### Step 3: Frontend Widget + +1. Створити React компонент `MicroDAOChannelEmbed` +2. Інтегрувати з API +3. Додати authentication flow +4. Додати real-time оновлення (WebSocket/SSE) + +### Step 4: Website Integration + +1. Додати компонент на сторінку `daarion.city/channel/general` +2. Налаштувати SEO метадані +3. Додати analytics tracking +4. Тестування на production + +--- + +## 10. Example Integration Code + +### 10.1 Next.js Page + +```tsx +// pages/channel/[slug].tsx +import { MicroDAOChannelEmbed } from '@/components/MicroDAOChannelEmbed'; +import Head from 'next/head'; + +export default function ChannelPage({ channelSlug }) { + return ( + <> + + Загальний канал міста DAARION.city + + {/* Open Graph tags */} + {/* Twitter Cards */} + + +
+ +
+ + ); +} +``` + +### 10.2 React Widget Component + +```tsx +// components/MicroDAOChannelEmbed.tsx +import { useState, useEffect } from 'react'; +import { useChannelMessages, useJoinChannel } from '@/hooks/useMicroDAO'; + +export function MicroDAOChannelEmbed({ + channelSlug, + teamSlug, + apiUrl, + theme, + showHeader, + allowJoin +}) { + const [isAuthenticated, setIsAuthenticated] = useState(false); + const { messages, loadMore } = useChannelMessages(channelSlug, apiUrl); + const { join } = useJoinChannel(channelSlug, apiUrl); + + const handleJoin = async (email: string, name: string, viewerType: string) => { + const result = await join(email, name, viewerType); + if (result.access_token) { + localStorage.setItem('microdao_token', result.access_token); + setIsAuthenticated(true); + } + }; + + return ( +
+ {showHeader && ( +
+

# Загальний канал міста

+

DAARION.city

+
+ )} + +
+ {messages.map(msg => ( + + ))} +
+ + {isAuthenticated ? ( + + ) : ( + allowJoin && + )} +
+ ); +} +``` + +--- + +## 11. Testing Checklist + +### 11.1 Backend Tests + +- [ ] Публічний канал створено для DAARION.city +- [ ] API endpoints повертають коректні дані +- [ ] CORS налаштовано правильно +- [ ] Rate limiting працює +- [ ] Authentication flow працює + +### 11.2 Frontend Tests + +- [ ] Widget завантажується на сайті +- [ ] Повідомлення відображаються коректно +- [ ] Join flow працює +- [ ] Real-time оновлення працюють +- [ ] Responsive design на мобільних + +### 11.3 Integration Tests + +- [ ] SEO метадані відображаються +- [ ] Analytics tracking працює +- [ ] Content moderation працює +- [ ] Error handling коректний + +--- + +## 12. Integration with Other Docs + +Цей документ доповнює: + +- `DAARION_city_integration.md` — загальна архітектура DAARION.city +- `47_messaging_channels_and_privacy_layers.md` — архітектура каналів +- `04_ui_ux_onboarding_chat.md` — UI/UX специфікація +- `03_api_core_snapshot.md` — API контракти + +--- + +## 13. Завдання для Cursor + +```text +You are a senior full-stack engineer. Implement DAARION.city website integration using: +- 50_daarion_city_website_integration.md +- DAARION_city_integration.md +- 47_messaging_channels_and_privacy_layers.md +- 03_api_core_snapshot.md + +Tasks: +1) Create DAARION.city team in database (type='city', slug='daarion', mode='public'). +2) Create public channel for DAARION.city (slug='general', type='public', is_public=true). +3) Create city agent for DAARION.city (role='team_assistant', memory_scope='team'). +4) Implement Public Channel API endpoints: + - GET /api/v1/channels/{slug}/public (channel info) + - GET /api/v1/channels/{slug}/public/messages (messages with pagination) + - POST /api/v1/channels/{slug}/public/messages (send message, authenticated) + - POST /api/v1/channels/{slug}/public/join (register as viewer/member) +5) Configure CORS for daarion.city domain. +6) Add rate limiting for public channel (guest: 100 req/min, authenticated: 30 msg/min, join: 5 req/hour). +7) Create React component MicroDAOChannelEmbed (props: channelSlug, teamSlug, apiUrl, theme, showHeader, allowJoin). +8) Implement authentication flow (guest view → join modal → authenticated view). +9) Add real-time updates (WebSocket/SSE for new messages). +10) Add SEO metadata (Open Graph, Twitter Cards, JSON-LD). +11) Add analytics tracking (channel_view, message_sent, join_clicked, join_completed, widget_loaded). +12) Add content moderation (spam filter, toxic content detection, user reports). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 14. Summary + +Інтеграція MicroDAO у офіційний сайт DAARION.city: + +- DAARION.city стає першим MicroDAO типу "city" +- Публічний канал вбудовується на сайт як React компонент +- API endpoints для публічного каналу +- Authentication flow для користувачів сайту +- SEO та метадані для публічного каналу +- Analytics та tracking +- Security (CORS, rate limiting, content moderation) + +Це перша інтеграція MicroDAO у зовнішній сайт, яка стане основою для подальших інтеграцій з іншими платформами. + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/DAARION_city_integration.md b/docs/cursor/DAARION_city_integration.md new file mode 100644 index 00000000..4caf030e --- /dev/null +++ b/docs/cursor/DAARION_city_integration.md @@ -0,0 +1,403 @@ +# DAARION_city_integration.md + +DAARION.city як суперDAO над microDAO та інтеграція існуючих платформ + +Цей документ описує, як: + +1. DAARION.city розглядається як **міське superDAO**, побудоване на тих самих механізмах, що й microDAO. + +2. DAARION.city є **реєстром мешканців** та "над-організацією", яка об'єднує microDAO. + +3. Існуючі проєкти (наприклад, **greenfood.live**, **EnergyUnion**) стають **розвиненими microDAO-платформами**, а не окремими всесвітами. + +Документ задає архітектурну модель і конкретні задачі для Cursor. + +--- + +## 1. Модель: DAARION.city = microDAO типу "city" + SuperDAO над іншими microDAO + +### 1.1. Розширення `teams` / `microdaos` + +Базова сутність одна — `team`/`microdao`, але з типами: + +```ts +type TeamType = "city" | "platform" | "community" | "guild" | "lab" | "personal"; +``` + +Приклади: + +* `DAARION.city` → `type = "city"` (city-level superDAO) +* `GreenFood` → `type = "platform"` (eco/food marketplace) +* `EnergyUnion` → `type = "platform"` (BioMiner + AI + DAO екосистема) +* Приватні microDAO → `type = "community"` або `personal`. + +### 1.2. Ієрархія "місто → платформи → мікроDAO" + +Додаткова таблиця: + +```ts +city_links: +- id +- parent_team_id // зазвичай DAARION.city team_id +- child_team_id // microDAO або платформа +- relation_type // "platform", "community", "guild", "adapter" +- created_at +``` + +Інтерпретація: + +* `DAARION.city` як `parent_team_id` для: + + * платформ (GreenFood, EnergyUnion, інші платформи), + * приватних microDAO, які бажають "приписатися" до міста. + +--- + +## 2. Реєстр мешканців DAARION.city + +DAARION.city — це також **місце реєстрації всіх мешканців**. + +### 2.1. Модель користувача + +```ts +users: +- id +- city_handle // унікальний нік у DAARION.city +- display_name +- avatar_url +- created_at +``` + +### 2.2. Громадянство (citizenship) + +```ts +citizenships: +- id +- user_id +- city_id // team_id DAARION.city +- status: "active" | "pending" | "revoked" +- joined_at +``` + +### 2.3. Членство в microDAO / платформах + +```ts +memberships: +- id +- user_id +- team_id // будь-який microDAO (включно з платформами) +- role: "admin" | "member" | "guest" +- joined_at +``` + +DAARION.city у цьому сенсі — просто `team` із `type="city"`, де всі громадяни мають запис `citizenship`, а членство в платформах і microDAO моделюється через `memberships`. + +--- + +## 3. DAARION.city як суперDAO: city-level агенти + +DAARION.city має власний набір **city-level agentів**, які працюють поверх міських даних і child-microDAO: + +* **City Governance Agent** — міські правила, дух міста. +* **City Registry Agent** — реєстр мешканців, громадянство. +* **City Bridges Agent** — зв'язки між city ↔ платформи ↔ microDAO. +* **City Co-Memory Agent** — загальноміський простір знань. + +Ці агенти використовують ті самі механізми, що й агенти microDAO, але їх `team_id` = `DAARION.city`. + +--- + +## 4. Перетворення існуючих платформ на microDAO + +Мета: платформи **greenfood.live** та **EnergyUnion** стають microDAO-платформами в структурі DAARION.city. + +### 4.1. GreenFood як microDAO-платформа + +Факти про платформу: + +* GreenFood — еко-система для невеликих виробників та переробників органічної й домашньої продукції та вимогливих покупців. +* Підтримка блокчейн-технологій та внутрішня бартерна криптовалюта DAAR. + +#### Кроки перетворення GreenFood → microDAO: + +1. **Створити запис `team`**: + + * `name = "GreenFood"` + * `type = "platform"` + * `slug = "greenfood"` + +2. **Прив'язати до DAARION.city**: + + * `city_links.insert(parent_team_id = daarion_city_id, child_team_id = greenfood_id, relation_type = "platform")` + +3. **Задати blueprint GreenFood**: + + * агентська конфігурація: + + * Marketplace/Orders Agent, + * Producers & Buyers Agent, + * Eco/Quality Knowledge Agent, + * інтеграція з існуючим мобільним додатком / API (через Bridges Agent). + +4. **Bridges / adapters**: + + * Connector до існуючого GreenFood backend: + + * products → проєкти/категорії/knowledge, + * orders → tasks / workflows, + * farmers → окремий тип учасників. + +5. **DAAR-валюта як доступ**: + + * трактувати DAAR-токени як внутрішні "ключі доступу/бартерні одиниці" у Governance/Access, а не як фінансові активи. + +### 4.2. EnergyUnion як microDAO-платформа + +Факти про платформу: + +* ENERGY UNION BioMiner = платформа, що поєднує чисту енергію, AI та DAO в одній екосистемі. +* BioMiner конвертує біомасу в електроенергію для дата-центрів та AI-лабів, токени відкривають доступ до енергії (kWt), AI-обчислень (1T) та carbon+. + +#### Кроки перетворення EnergyUnion → microDAO: + +1. **Створити `team`**: + + * `name = "EnergyUnion"` + * `type = "platform"` + * `slug = "energyunion"` + +2. **Прив'язати до DAARION.city**: + + * `city_links.insert(parent_team_id = daarion_city_id, child_team_id = energyunion_id, relation_type = "platform")` + +3. **Blueprint EnergyUnion**: + + * агенти: + + * Energy Sites & BioMiner Agent (облік енергії, біомодулі), + * AI Power Agent (1T обчислення), + * kWt / 1T / carbon+ access-keys інтегровані в Governance & Access (як символьні ключі ресурсу, не як фінансові інструменти). + +4. **Bridges / adapters**: + + * Connector до energyunion.io / EnergyUnion.AI API: + + * energy production → knowledge/events, + * access tokens → capability keys у microDAO, + * DAO-логіка → DAO Agent (коли знадобиться). + +--- + +## 5. City-level Co-Memory: загальні знання міста + +DAARION.city має власний **Co-Memory**, побудований на основі модуля 17. + +### 5.1. City Knowledge Spaces + +Приклади city-spaces: + +* `City.Ecology` +* `City.Energy` +* `City.Food` +* `City.Governance` + +Кожна платформа-microDAO може: + +* публікувати обрані факти/документи в City Co-Memory: + + * `publish_to_city_memory(team_id, space_id, fact_id/doc_id)` + +* читати загальноміський контекст: + + * `get_city_knowledge(space_id, query)`. + +### 5.2. Політики відкритості + +Локальний Governance Agent платформи: + +* визначає, які дані: + + * залишаються тільки в локальному Co-Memory, + * можуть підніматися на рівень міста. + +--- + +## 6. City Bridges: обмін подіями між DAARION.city і microDAO + +### 6.1. Формат `city_event` + +Спільний формат подій: + +```ts +city_event: { + id: string; + source_team_id: string; // хто ініціював (microDAO або платформа) + target_team_id?: string; // куди адресовано (optionally) + type: string; // "announcement", "project_update", "energy_event", "market_update", ... + payload: Json; + ts: string; +} +``` + +### 6.2. City Bridges Agent + +Агент з `team_id = DAARION.city`: + +* приймає `city_event` від microDAO, +* ретранслює (broadcast / специфічним платформам), +* взаємодіє з Attention Agent на міському рівні. + +--- + +## 7. Governance: трирівнева модель правил + +1. **City Governance (DAARION.city)**: + + * загальні принципи, + * базові етичні стандарти, + * міські ритуали узгодження. + +2. **Platform Governance** (GreenFood, EnergyUnion): + + * правила конкретної платформи, + * локальні символічні ключі доступу. + +3. **Local microDAO Governance**: + + * правила конкретної спільноти/групи. + +DAO Agent і Wallet Agent можуть зʼявитися пізніше на міському шарі; наразі достатньо моделювати правила як політики доступу й ритуали узгодження без необхідної on-chain реалізації. + +--- + +## 8. UX-рівень: як користувач це відчуває + +1. Користувач реєструється в DAARION.city → отримує: + + * міське громадянство, + * city-profile. + +2. У міському інтерфейсі: + + * секція "Платформи": + + * GreenFood, EnergyUnion, інші платформи → всі це microDAO типу `platform`; + + * секція "Мої microDAO": + + * приватні/ком'юніті DAO. + +3. Клік по платформі (GreenFood / EnergyUnion): + + * відкривається Agent Hub цієї платформи (як microDAO), + * зі своїми агентами, каналами, проєктами. + +4. Зі свого приватного microDAO користувач може: + + * "Підключитися до платформи GreenFood": + + * створюється запис у `city_links` + налаштовуються Bridges + Governance/Access. + +--- + +## 9. Задачі для Cursor (Implementation Plan) + +### 9.1. Базова інтеграція DAARION.city як microDAO + +1. Додати поле `type` у `teams`: + + * `"city" | "platform" | "community" | "guild" | "lab" | "personal"`. + +2. Створити запис для DAARION.city: + + * `type = "city"`, `slug = "daarion"`. + +3. Створити таблицю `city_links`: + + * parent/child team, relation_type. + +### 9.2. Реєстр мешканців + +1. Створити таблиці: + + * `citizenships` (user ↔ city), + * `memberships` (user ↔ team). + +2. Додати city-profile в UI: + + * список платформ-microDAO, + * список власних microDAO. + +### 9.3. Інтеграція платформ GreenFood та EnergyUnion + +1. Створити `team` для GreenFood та EnergyUnion з `type="platform"`. + +2. Створити `city_links` із `parent_team_id = daarion_city_id`. + +3. Додати базові Agent Hub / Agent Cards для цих платформ. + +4. Створити Bridges stubs: + + * `greenfood_connector_agent`, + * `energyunion_connector_agent`, + + щоб пізніше інтегрувати їхні API (поки достатньо каркасу). + +### 9.4. City Co-Memory та City Bridges + +1. Створити city-level Knowledge Space (`City.Global`). + +2. Додати API: + + * `POST /city/knowledge/publish`, + * `POST /city/events`. + +3. Реалізувати City Bridges Agent: + + * мінімально — логування `city_event`ів. + +--- + +## 10. Інструкція для Cursor + +```text +Use DAARION_city_integration.md together with: + +- 12_agent_runtime_core.md +- 14_messenger_agent_module.md +- 15_projects_agent_module.md +- 17_comemory_knowledge_space.md +- 18_governance_access_agent.md +- 20_integrations_bridges_agent.md +- 22_operator_modes_and_system_agents.md +- 23_domains_wallet_dao_deepdive.md +- 10_agent_ui_system.md +- 05_coding_standards.md + +Goal: + +Unify DAARION.city and all platforms as microDAO instances, with DAARION.city as a "city" type superDAO and GreenFood / EnergyUnion as "platform" type microDAO. + +Implement in stages: + +1) Team types + city_links hierarchy. + +2) Citizen registry (citizenships, memberships). + +3) DAARION.city as city-level microDAO with its own Agent Hub. + +4) GreenFood and EnergyUnion as platform-type microDAO. + +5) City Co-Memory and City Bridges minimal skeletons. + +For each step: + +- list changed files, +- show diff, +- provide a short summary. +``` + +--- + +**Готово.** +Це **повна архітектура інтеграції DAARION.city з microDAO**, включаючи конкретні кроки перетворення GreenFood та EnergyUnion. diff --git a/docs/cursor/DAARION_city_platforms_catalog.md b/docs/cursor/DAARION_city_platforms_catalog.md new file mode 100644 index 00000000..c10b06a7 --- /dev/null +++ b/docs/cursor/DAARION_city_platforms_catalog.md @@ -0,0 +1,397 @@ +# DAARION.city Platforms Catalog (MicroDAO) + +Каталог платформ екосистеми DAARION.city + +Цей документ містить каталог платформ екосистеми **DAARION.city**, які інтегруються з microdao, DAGI та Gift-економікою міста: + +- опис домену кожної платформи; +- основні агентські модулі; +- ключі доступу (access keys + capabilities); +- Embassy-інтеграція; +- мінімальні флоу для MVP. + +Це **живий документ** — при додаванні нових платформ/районів додаються нові записи. + +--- + +## 1. Мета документа + +Каталог платформ екосистеми **DAARION.city**, які інтегруються з microdao, DAGI та Gift-економікою міста: + +- опис домену кожної платформи; +- основні агентські модулі; +- ключі доступу (access keys + capabilities); +- Embassy-інтеграція; +- мінімальні флоу для MVP. + +Це **живий документ** — при додаванні нових платформ/районів додаються нові записи. + +--- + +## 2. Структура запису про платформу + +Для кожної платформи описуємо: + +- `code` — короткий код (латиницею); +- `name` — назва; +- `domain` — предметна область; +- `owner` — хто курує (team/microDAO); +- `status` — idea / design / MVP / pilot / prod; +- основні **агентські ролі**; +- типи **access keys** і capabilities; +- Embassy-флоу (якщо є RWA/енергія/зовнішні мережі). + +--- + +## 3. Перелік платформ + +1. **DAARION Core** +2. **DAARWIZZ** +3. **GREENFOOD** +4. **Energy Union** +5. **Water Union** +6. **Essence Stream** + +(інші додаються в наступних версіях: Atlas, DAARWIZZ verticals тощо). + +--- + +## 4. DAARION Core + +- `code`: `daarion_core` +- `name`: DAARION Core / Місто Дарів +- `domain`: ядро міста, Second Me, резидентство, токеноміка DAAR/DAARION, MJD. +- `owner`: DAARION DAO Core Team +- `status`: pilot → prod + +### 4.1 Агентські модулі + +- **Second Me Agent** — персональний цифровий двійник резидента. +- **Citizenship Agent** — керує резидентством, рівнями доступу, DAARION-статусом. +- **Gift Fabric Agent** — відстежує акти взаємодії й відгук міста (MJD). +- **Governance Agent** — DAO-процеси, пропозиції, голосування, політики. + +### 4.2 Access keys & capabilities + +Приклади capability-груп: + +- `citizenship.status.view` +- `citizenship.level.upgrade` +- `gift.act.register` +- `governance.proposal.create` +- `governance.vote.cast` +- `governance.policy.manage` (лише для Guardian/Owner/DAO-агентів) + +Embassy-ключі DAARION Core обмежені: + +- `embassy.intent.read` +- `embassy.aggregate.metrics` + +--- + +## 5. DAARWIZZ + +- `code`: `daarwizz` +- `name`: DAARWIZZ — маршрутизатор агентів / планувальник Swarm-OS +- `domain`: оркестрація DAGI, роутинг запитів, multi-agent сценарії. +- `owner`: DAARION R&D Lab +- `status`: MVP / pilot + +### 5.1 Агентські модулі + +- **Router Agent** — розподіляє запити між моделями та агентами. +- **Planner Agent** — декомпозує задачі, запускає ланцюжки інструментів. +- **Observer/Telemetry Agent** — відстежує якість, латентність, бюджет. + +### 5.2 Access keys & capabilities + +- `router.invoke` +- `router.plan.run` +- `router.tool.call` +- `telemetry.events.write` +- `telemetry.events.read:aggregate` + +Користувацькі microDAO отримують DAARWIZZ-keys: + +- або через Wallet Agent (оплата DAAR / 1T); +- або через план Platformium. + +--- + +## 6. GREENFOOD + +- `code`: `greenfood` +- `name`: GREENFOOD — AI-ERP для крафтових виробників та кооперативів +- `domain`: склади, партії, логістика, кооперативні ланцюги постачання. +- `owner`: GREENFOOD microDAO +- `status`: design / MVP + +### 6.1 Агентські модулі + +- **Warehouse Agent** — облік партій/залишків. +- **Logistics Agent** — маршрути та хаби. +- **Accounting Agent** — автоматичні нарахування/розподіл по кооперативу. +- **Sales Agent** — інтеграція з маркетплейсами. +- **Community Coordinator Agent** — координація між учасниками спільноти. + +### 6.2 Access keys & capabilities + +Ключі типу: + +- `platform.greenfood.inventory.view/update` +- `platform.greenfood.shipment.create` +- `platform.greenfood.coop.balance.view` +- `platform.greenfood.member.register` + +Для інтеграції з microdao: + +- public API-ключі для: + - синхронізації задач Projects (`projects.task.sync`); + - Co-Memory (звіти, накладні); +- Embassy Key для RWA: + - `rwa.claim` (сертифікати продуктів); + - `rwa.stock.update` (запаси на складах). + +--- + +## 7. Energy Union + +- `code`: `energy_union` +- `name`: Energy Union — енергетична платформа з токенізованими активами +- `domain`: енергетичні RWA, KWT/1T виплати, енергетичний бартер. +- `owner`: Energy Union microDAO / партнерські енергокомпанії +- `status`: pilot + +### 7.1 Агентські модулі + +- **Metering Agent** — читає лічильники генерації/споживання. +- **Oracle Agent** — агрегує дані, формує виплати KWT/1T. +- **Facility Agent** — агент об'єкта (сонячна станція, дата-центр). +- **Energy Market Agent** — узгоджує акти енергетичного дарообміну. + +### 7.2 Access keys & capabilities + +- `energy.asset.read` +- `energy.meter.read` +- `energy.meter.update` (лише для trusted oracles) +- `energy.payout.compute` +- `wallet.payout.view/claim` + +Embassy-ключі: + +- `embassy.energy.update` +- `embassy.rwa.claim` (сертифікати енергетичних часток). + +--- + +## 8. Water Union + +- `code`: `water_union` +- `name`: Water Union — платформа для управління водними ресурсами +- `domain`: моніторинг води, RWA на основі водних активів/інфраструктури. +- `owner`: Water Union microDAO / місцеві громади +- `status`: idea / early design + +### 8.1 Агентські модулі + +- **Sensor Agent** — збір даних з сенсорів (якість/об'єм води). +- **Infrastructure Agent** — стан насосів, резервуарів. +- **Community Water Agent** — координація доступу громад, планування ремонтів. +- **Water RWA Agent** — сертифікати дару на водні ініціативи. + +### 8.2 Access keys & capabilities + +- `water.sensor.read` +- `water.sensor.update` +- `water.infrastructure.view` +- `rwa.water.claim` + +Embassy: + +- інтеграція з місцевими дата-центрами/IoT-шлюзами; +- прев'язка водних RWA до DAAR/DAARION через Gift Fabric. + +--- + +## 9. Essence Stream + +- `code`: `essence_stream` +- `name`: Essence Stream — платформа для культурних/освітніх ініціатив +- `domain`: курси, події, контент-стріми, творчі квести. +- `owner`: Essence Stream microDAO / культурні куратори +- `status`: idea / design + +### 9.1 Агентські модулі + +- **Curator Agent** — формує програми, добирає контент. +- **Event Agent** — події, квитки (як сертифікати дару). +- **Mentor Agent** — персоналізовані навчальні траєкторії. +- **Quest Agent** — квести/ігрові сценарії в DAARION.city. + +### 9.2 Access keys & capabilities + +- `essence.event.publish` +- `essence.event.register` +- `essence.course.view` +- `essence.quest.progress.update` + +Embassy: + +- RWA-сертифікати на участь у подіях (офлайн/онлайн); +- взаємодія з Gift Fabric для Міського Джерела Дарів. + +--- + +## 10. Зв'язок платформ з microdao + +### 10.1 Common pattern + +Кожна платформа: + +1. Має **свій microDAO** (team/ком'юніті) у microdao-месенджері. +2. Має набір **public channel(s)** для публічних оголошень/стрімів. +3. Використовує: + - Projects (проекти/ланцюги постачання/ініціативи), + - Co-Memory (документи, договори, технічні описи), + - приватних агентів (Router, Domain-агенти). + +### 10.2 Типи інтеграцій + +- **Embedded microdao**: платформа має вкладку «Community/Chat», що відкриває microdao-інтерфейс її microDAO. +- **API integration**: платформа викликає microdao API (`/projects`, `/tasks`, `/wallet`, `/governance`) з власними access keys. +- **Embassy**: для RWA/енергетики/сертифікатів дару використовується Embassy Module. + +--- + +## 10. Подальший розвиток каталогу + +Наступні версії документа: + +- додаємо нові платформи (Atlas, DAARWIZZ вертикалі, інші city-райони); +- деталізуємо capability-матриці (по аналогії з RBAC-таблицями); +- додаємо mapping до конкретних onchain-контрактів (RWA, EnergyNFT, DAAR/DAARION). + +--- + +## 11. Мапінг платформ на Data Model (таблиці) + +1. Усі платформи (DAARION Core, DAARWIZZ, GREENFOOD, Energy Union, Water Union, Essence Stream): + +- представлені як `teams`: + +```sql +create table teams ( + id text primary key, -- t_... + name text not null, + slug text unique not null, + mode text not null check (mode in ('public','confidential')), + created_at timestamptz not null default now() +); +``` + +- учасники платформ → `team_members`: + - роль (`Owner`, `Guardian`, `Member`); + - `viewer_type` (`reader`, `commenter`, `contributor`). + +2. DAARION Core: + +- працює поверх: + - `users`, `teams`, `team_members`, + - `channels`, `messages`, `followups`, + - `projects`, `tasks`, `docs`, `meetings`, + - `wallets`, `staking_ringk`, `payouts`, + - `proposals` (governance). + +3. GREENFOOD: + +- свій microDAO → одна або кілька сутностей `teams`; +- бізнес-процеси відображаються як: + - `projects` (кооперативні програми, постачання); + - `tasks` (відвантаження, контроль партій); + - RWA-складські залишки → через `rwa_inventory` (із подією `rwa.inventory.updated`). + +4. Energy Union: + +- об'єкти енергетики — як `projects`/`tasks` + RWA-записи в `rwa_inventory`; +- зв'язок із виплатами — через `staking_ringk` та `payouts`. + +5. Water Union / Essence Stream: + +- Water Union: сенсори/інфраструктура агрегуються як задачі/проєкти, а водні активи — RWA-записи; +- Essence Stream: події/курси — `projects` + `meetings`/`docs`, участь резидентів потрапляє в Gift Fabric через події. + +--- + +## 12. Мапінг платформ на Event Catalog (topics) + +1. DAARION Core: + +- використовує базові topics з `topic.enum`: + - `"chat.message.created"`, `"chat.message.edited"`, `"chat.message.deleted"` + - `"followup.created"`, `"followup.updated"` + - `"project.created"`, `"task.created"`, `"task.updated"` + - `"agent.run.started"`, `"agent.run.completed"` + - `"staking.locked"`, `"payout.generated"` + - `"rwa.inventory.updated"` + - `"governance.proposal.created"`, `"vote.cast"` + - `"audit.event"` + +2. GREENFOOD: + +- доменні події інвентарю/замовлень мапляться на: + - `"rwa.inventory.updated"` (оновлення складів/партій); + - `"project.created"` / `"task.created"` для логістичних ланцюжків. + +3. Energy Union: + +- енергетичні вимірювання та оракули: + - `"oracle.reading.published"` — агреговані дані з лічильників; + - далі → `"staking.locked"` / `"payout.generated"` для KWT/1T. + +4. Water Union: + +- якість/об'єм води → `"oracle.reading.published"` з типом `water`; +- видані водні сертифікати → `"rwa.inventory.updated"`; +- надалі можуть генерувати `"payout.generated"`, якщо є пов'язаний токенізований потік. + +5. Essence Stream: + +- участь у подіях/квестах платформи підписується як: + - `"reward.issued"` (Gift Fabric), + - `"audit.event"` для важливих соціальних/освітніх актів. + +--- + +## 13. Завдання для Cursor + +```text +You are a senior full-stack engineer. Implement platform integration patterns using: +- DAARION_city_platforms_catalog.md +- 24_access_keys_capabilities_system.md +- DAARION_city_integration.md +- 05_coding_standards.md + +Tasks: +1) Create platform registry in database (platforms table). +2) Implement platform-specific capability bundles. +3) Create Embassy Module integration for RWA platforms (Energy Union, GREENFOOD). +4) Add platform switcher UI in microDAO interface. +5) Implement platform-specific agent modules (stub for MVP). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 14. Результат + +Після впровадження каталогу: + +- чітке розуміння всіх платформ екосистеми DAARION.city; +- стандартизовані патерни інтеграції; +- готовність до додавання нових платформ; +- інтеграція з Access Keys & Capabilities System. + diff --git a/docs/cursor/DOCX_UPDATE_INSTRUCTIONS.md b/docs/cursor/DOCX_UPDATE_INSTRUCTIONS.md new file mode 100644 index 00000000..39dce417 --- /dev/null +++ b/docs/cursor/DOCX_UPDATE_INSTRUCTIONS.md @@ -0,0 +1,247 @@ +# Інструкції для оновлення .docx документів + +Цей документ містить інструкції для механічного оновлення Word документів (`.docx`), які не можна редагувати автоматично. + +--- + +## 1. `microdao — Data Model & Event Catalog.docx` + +### Крок 1: Додати новий розділ для таблиць access keys + +**Де:** Після `Heading 3 "3.9 Integrations / Webhooks / Audit"` + +**Що додати:** + +``` +Heading 3: 3.10 Access Keys & Capability Bundles +``` + +**SQL схема:** + +```sql +create table access_keys ( + id text primary key, -- ak_... + subject_kind text not null, -- 'user' | 'agent' | 'integration' | 'embassy' + subject_id text not null, -- u_/ag_/... + team_id text null, -- t_..., якщо scoped до команди + name text not null, + status text not null check (status in ('active','revoked','expired')), + created_at timestamptz not null default now(), + expires_at timestamptz null, + last_used_at timestamptz null +); + +create table capabilities ( + id text primary key, -- cap_... + code text not null unique, -- chat.message.send, wallet.stake.ringk, ... + description text not null +); + +create table access_key_caps ( + key_id text references access_keys(id) on delete cascade, + cap_id text references capabilities(id) on delete cascade, + primary key (key_id, cap_id) +); + +create table bundles ( + id text primary key, -- bundle_... + name text not null unique, -- role.Member / plan.Premium / agent.default + created_at timestamptz not null default now() +); + +create table bundle_caps ( + bundle_id text references bundles(id) on delete cascade, + cap_id text references capabilities(id) on delete cascade, + primary key (bundle_id, cap_id) +); +``` + +--- + +### Крок 2: Додати події в Event Catalog + +**Де:** У розділі `6.3 Події (JSON, скорочено)` + +**1. У список `topic` додати:** + +- `access_key.created` +- `access_key.revoked` +- `access_key.used` + +**2. Нижче, де йдуть payload-схеми, додати JSON-схеми:** + +**access_key.created:** + +```jsonc +// envelope.topic = "access_key.created" +"access_key_created": { + "type": "object", + "properties": { + "key_id": { "type": "string" }, + "subject_kind": { "type": "string" }, + "subject_id": { "type": "string" }, + "team_id": { "type": ["string","null"] } + }, + "required": ["key_id","subject_kind","subject_id"] +} +``` + +**access_key.revoked:** + +```jsonc +// envelope.topic = "access_key.revoked" +"access_key_revoked": { + "type": "object", + "properties": { + "key_id": { "type": "string" }, + "revoked_by": { "type": "string" }, + "revoked_at": { "type": "string", "format": "date-time" } + }, + "required": ["key_id","revoked_by","revoked_at"] +} +``` + +**access_key.used:** + +```jsonc +// envelope.topic = "access_key.used" +"access_key_used": { + "type": "object", + "properties": { + "key_id": { "type": "string" }, + "subject_id": { "type": "string" }, + "action": { "type": "string" }, + "resource_kind": { "type": "string" }, + "ts": { "type": "string", "format": "date-time" } + }, + "required": ["key_id","subject_id","action","resource_kind","ts"] +} +``` + +--- + +## 2. `microdao — RBAC і Entitlements (MVP).docx` + +### Крок 1: Оновити формулу доступу + +**Де:** У розділі `2) Модель доступу` + +**Знайти:** Нинішню формулу `allow = ...` + +**Замінити на:** + +```text +allow = + RBAC(role, action, resource) + ∧ Entitlement(plan, RINGK_staked) + ∧ Capability(key, action, resource) + ∧ ACL(resource) + ∧ Mode(public|confidential) +``` + +**Додати після формули:** + +> `Capability(key, …)` береться з bundles `bundle.role.*` + `bundle.plan.*` (детальніше див. `24_access_keys_capabilities_system.md`). + +--- + +### Крок 2: Додати мапінг Entitlements → bundles + +**Де:** У розділі `6) Entitlements від RINGK (стейк)`, в кінці розділу + +**Додати:** + +> **Мапінг Entitlements → capability-bundles** +> +> - плани `Freemium/Casual/Premium/Platformium` відповідають `bundle.plan.*`; +> - множники від стейку RINGK впливають на квоти для capabilities (`chat.message.send`, `agent.run.invoke`, `router.invoke`, `wallet.payout.claim`). + +--- + +## 3. `microdao — Security Architecture & Threat Model (MVP).docx` + +### Крок 1: Додати підрозділ про Access Keys & Policy Service + +**Де:** У розділі `5. Авторизація`, після першого підрозділу (5.1/5.2) + +**Додати:** + +``` +Heading 3: 5.x Access Keys & Policy Service (PDP/PEP) +``` + +**Текст:** + +- Access keys перевіряються через PDP (Policy Decision Point / Policy Service) +- PEP (Policy Enforcement Point) живе в API Gateway та сервісах +- Використовується capability-token (JWT/opaque), який несе: + - `sub` (user/agent/integration ID) + - `team_id` + - стиснений список `caps` (capabilities) + +--- + +### Крок 2: Додати підрозділ про зберігання access keys + +**Де:** У розділі `8. Зберігання та доступ` + +**Додати:** + +``` +Heading 3: 8.x Зберігання access keys +``` + +**Текст:** + +- Метадані зберігаються в таблиці `access_keys` (див. Data Model) +- Секрети (`secret`) зашифровані через KMS/HSM +- One-time reveal: після створення ключ не показується повторно +- Ротація: обов'язковий `expires_at`, періодична ротація ключів + +--- + +### Крок 3: Додати абзац про агентний шар + +**Де:** У розділі `11. Агентний шар` + +**Додати:** + +> Всі приватні агенти працюють виключно через Agent Access Keys з мінімальними capabilities. Для `mode='confidential'` агенти не отримують plaintext-повідомлень, тільки summary/embeddings (узгоджено з E2EE моделлю). + +--- + +### Крок 4: Додати абзац про Wallet/Staking + +**Де:** У розділі `12. Wallet/Staking/Токени` + +**Додати:** + +> Всі операції гаманця (`wallet.balance.view`, `wallet.stake.ringk`, `wallet.payout.claim`) завжди проходять через capability-check для ключа (user/agent). Перевірка виконується через PDP перед виконанням операції. + +--- + +## 4. Перевірка + +Після оновлення всіх `.docx` файлів перевір: + +- ✅ У Data Model додано розділ 3.10 з таблицями access keys +- ✅ У Event Catalog додано 3 нові topics та їх JSON-схеми +- ✅ У RBAC оновлено формулу доступу та додано мапінг Entitlements → bundles +- ✅ У Security Architecture додано 4 нові розділи/абзаци про Access Keys + +--- + +## 5. Посилання на Markdown документи + +Всі деталі вже є в Markdown документах: + +- `24_access_keys_capabilities_system.md` — повна специфікація +- `DAARION_city_platforms_catalog.md` — мапінг платформ +- `28_flows_wallet_embassy_energy_union.md` — sequence-діаграми + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/cursor/MISSING_DOCS_ANALYSIS.md b/docs/cursor/MISSING_DOCS_ANALYSIS.md new file mode 100644 index 00000000..50c5b6cc --- /dev/null +++ b/docs/cursor/MISSING_DOCS_ANALYSIS.md @@ -0,0 +1,178 @@ +# Аналіз відсутніх документів для microDAO2 + +**Що вже є vs що не вистачає для повного розуміння архітектури** + +--- + +## ✅ Що вже є (31 документ) + +### Фундамент (00-13) — ✅ Повний +- Overview, Product Brief, Architecture, API, UI/UX, Coding Standards +- Tasks, Testing Checklist +- Agent System (Onboarding, Evolutionary, UI, LLM, Runtime, Memory) + +### Модулі (14-20) — ✅ Повний +- Messenger, Projects, Followups, Co-Memory, Governance, Notifications, Integrations + +### Інтерфейс та системи (21-24) — ✅ Повний +- Agent-Only Interface, Operator Modes, Domains/Wallet/DAO, Agent Cards + +### Інтеграція — ✅ Є +- DAARION_city_integration.md +- MVP_VERTICAL_SLICE.md + +--- + +## ❌ Що не вистачає (критичне для старту) + +### 1. **24_access_keys_capabilities_system.md** ✅ СТВОРЕНО +**Статус:** Створено першу версію + +**Що має містити:** +- Універсальна система capability-ключів +- Wallet Agent детальна специфікація +- Embassy Module детальна специфікація +- Runtime capability-check +- Інтеграція з Governance Agent + +**Чому важливо:** Без цього неможливо реалізувати безпеку та доступи. + +--- + +### 2. **DAARION_city_platforms_catalog.md** ✅ СТВОРЕНО +**Статус:** Створено першу версію + +**Що має містити:** +- Каталог всіх платформ (GreenFood, EnergyUnion, DAARWIZZ, Water Union, Essence Stream) +- Агентські модулі кожної платформи +- Ключі доступу для кожної платформи +- Embassy Module інтеграція + +**Чому важливо:** Для розуміння повної екосистеми та інтеграції платформ. + +--- + +### 3. **25_deployment_infrastructure.md** ✅ СТВОРЕНО +**Статус:** Створено першу версію + +**Що містить:** +- Deployment процес (local/dev/staging/prod) +- Infrastructure setup (Postgres, NATS, API Gateway, Frontend, Object Storage) +- Environment variables +- Database migrations +- CI/CD pipeline +- Monitoring та logging +- Backups & Restore +- Rollout Strategies + +--- + +### 4. **26_security_audit.md** ✅ СТВОРЕНО +**Статус:** Створено першу версію + +**Що містить:** +- Security best practices (16 категорій) +- Authentication та authorization flow +- Data encryption (E2EE) +- Audit logging +- Rate limiting +- Vulnerability management +- Incident Response playbooks +- Compliance checklist + +--- + +### 5. **27_database_schema_migrations.md** ✅ СТВОРЕНО +**Статус:** Створено першу версію + SQL міграції (Варіант C) + +**Що містить:** +- Повна схема БД (всі таблиці) +- Migration стратегія (9 міграцій) +- Seed data (seeds.sql з 25 capabilities) +- Backup та restore (в 25_deployment_infrastructure.md) +- SQL міграції готові до використання + +--- + +## 📋 Що не вистачає (можна додати пізніше) + +### 6. **28_performance_optimization.md** +- Caching стратегія +- Database indexing +- Query optimization +- Frontend optimization +- WebSocket optimization + +### 7. **29_error_handling_monitoring.md** +- Error handling patterns +- Monitoring setup +- Alerting +- Logging strategy +- Error tracking (Sentry тощо) + +### 8. **30_api_full_specification.md** +- Повна API специфікація для всіх модулів +- OpenAPI 3.1 повна версія +- WebSocket протокол +- Rate limits +- Error codes + +### 9. **31_testing_strategy.md** +- Unit testing +- Integration testing +- E2E testing +- Performance testing +- Security testing + +### 10. **32_embassy_module_detailed.md** +- Детальна специфікація Embassy Module +- UI/UX для Embassy +- Інтеграція з Wallet Agent +- Capability management + +--- + +## 🎯 Рекомендації перед стартом розробки + +### Критичні (треба додати): + +1. ✅ **24_access_keys_capabilities_system.md** — система ключів доступу +2. ✅ **DAARION_city_platforms_catalog.md** — каталог платформ +3. ⚠️ **25_deployment_infrastructure.md** — deployment процес +4. ⚠️ **26_security_audit.md** — безпека +5. ⚠️ **27_database_schema_migrations.md** — схема БД та міграції + +### Важливі (можна додати під час розробки): + +6. **28_performance_optimization.md** +7. **29_error_handling_monitoring.md** +8. **30_api_full_specification.md** +9. **31_testing_strategy.md** +10. **32_embassy_module_detailed.md** + +--- + +## 📊 Пріоритети + +### Для MVP (перші користувачі): +1. **24_access_keys_capabilities_system.md** — критично +2. **DAARION_city_platforms_catalog.md** — важливо +3. **27_database_schema_migrations.md** — важливо +4. **25_deployment_infrastructure.md** — можна спростити для MVP +5. **26_security_audit.md** — можна базовий рівень для MVP + +### Для production: +- Всі документи з розділу "Критичні" +- Документи з розділу "Важливі" + +--- + +## ✅ Висновок + +**Мінімум для старту MVP:** +- ✅ 24_access_keys_capabilities_system.md +- ✅ DAARION_city_platforms_catalog.md +- ⚠️ 27_database_schema_migrations.md (базова версія) + +**Решту можна додавати під час розробки або після MVP.** + diff --git a/docs/cursor/MVP_VERTICAL_SLICE.md b/docs/cursor/MVP_VERTICAL_SLICE.md new file mode 100644 index 00000000..1a5bcac7 --- /dev/null +++ b/docs/cursor/MVP_VERTICAL_SLICE.md @@ -0,0 +1,537 @@ +# MVP_VERTICAL_SLICE — MicroDAO (Agent-First MVP) + +Вертикальний зріз для перших живих користувачів + +Цей документ визначає, ЩО саме потрібно реалізувати у першому MVP, щоб: + +- microDAO виглядало як окремий "живий простір", +- користувач одразу взаємодіє з агентами, +- є базові чати, проєкти, нагадування, +- агенти мають "обличчя" (картки + консолі), +- операторські режими вже закладені в архітектуру, але не перевантажують реалізацію. + +Документ збирає ключові фрагменти з: + +- 14_messenger_agent_module.md +- 15_projects_agent_module.md +- 16_followups_reminders_agent.md +- 21_agent_only_interface.md +- 22_operator_modes_and_system_agents.md +- 23_domains_wallet_dao_deepdive.md +- 23_agent_cards_and_console_tasks.md + +--- + +# 0. Мета MVP + +Зробити **один живий вертикальний шмат**: + +- людина заходить у свій microDAO (через slug.daarion.city), +- бачить Agent Hub (головний екран), +- спілкується з Team Assistant, +- бачить "Учасників" (Люди / Агенти), +- має базові канали (Messenger Agent), +- має хоча б один Проєкт і Задачі (Projects Agent), +- може сказати "нагадай" (Followups Agent), +- може зайти на `/agents` і побачити картки агентів, +- може відкрити Agent Console і подивитись, де агент присутній. + +Web3, DAO-протокол, Wallet Agent, глибокий Governance, Attention, Co-Memory — описані, але **не обовʼязково реалізуються в цьому MVP**, тільки каркас там, де це дешево. + +--- + +# 1. Multi-tenant & Team Context (без кастомних доменів) + +## 1.1. Обсяг MVP + +Реалізувати: + +- `teams.slug` + базовий domain routing по `slug.daarion.city`, +- `currentTeamId` у бекенд-контексті, +- два режими UI: + + - режим `/t/:teamId/...` (центральний домен), + - режим `slug.daarion.city/...` (автоматичне визначення `teamId` з домену). + +Не реалізувати: + +- кастомні домени користувачів (`mydao.org`), +- DNS-перевірки, SSL-автоматизацію. + +## 1.2. Tasks + +1) Додати в БД: + + - поле `slug` у `teams`. + +2) Реалізувати lookup: + + - `Host` → `slug` → `teamId`. + +3) У бекенд-контексті: + + - зберігати `currentTeamId`. + +4) На фронті: + + - якщо контекст дає `currentTeamId` з домену: + + - приховати `t/:teamId` у URL, + - використовувати просто `/home`, `/agents`, `/projects` тощо. + +--- + +# 2. Agent Hub (Home) + Agent-Only Interface Shell + +Спиратись на: + +`21_agent_only_interface.md` (Agent-Only Interface) + ++ базові UI стандарти (`10_agent_ui_system.md`). + +## 2.1. Обсяг MVP + +1) Новий маршрут: + + - `/t/:teamId/home` (у режимі slug-домену — просто `/home`). + +2) Лівий сайдбар: + + - блок "Простори / Проєкти" (stub-список, але справжні посилання), + - блок "Учасники": `Люди / Агенти / Роботи (плейсхолдер)`. + +3) Центральна область: + + - **Agent Hub Chat** з Team Assistant: + + - мінімальний AgentChatWindow, + - LLM-виклик з `agent_id = Team Assistant`. + +4) Правий сайдбар: + + - stub "Контекст команди": + + - кількість учасників, + - кількість проєктів, + - список останніх подій (можна поки мок). + +## 2.2. Tasks + +1) Додати компонент `AgentHubPage`. + +2) Додати маршрут `/t/:teamId/home`. + +3) У сайдбарі додати пункт "Головна / Agent Hub". + +4) Реалізувати базовий `AgentChatWindow`: + + - історія повідомлень, + - input для користувача, + - відправка на `/agents/{id}/chat` або відповідний endpoint. + +5) Підʼєднати Team Assistant як базового агента для цього екрану. + +--- + +# 3. Messenger Agent (14): канали, DM, "додати агента" + +Опиратись на: + +`14_messenger_agent_module.md` + ++ `Task Invite-Agent-Flow` з задачника. + +## 3.1. Обсяг MVP + +Реалізувати мінімум: + +1) Список каналів/чатів у лівому сайдбарі: + + - кілька каналів типу: + + - `#general`, + - `#mvp`. + +2) Центральний чат для вибраного каналу: + + - вивід історії, + - відправка повідомлень, + - позначення агента/людини автором. + +3) Кнопка "Додати учасника" у header каналу: + + - модалка зі вкладками: + + - `Люди`, + - `Агенти` (ми фокусуємось саме на цьому). + + - у вкладці `Агенти`: + + - список агентів (із `/agents`), + - вибір 1 агента, + - чекбокси прав: + + - `Читати`, + - `Писати`, + - `Створювати задачі`. + + - POST entitlements (stub-модель RBAC/Entitlements). + +Не обовʼязково: + +- складні фічі (search_messages, pinned messages, reactions і т.п.). + +## 3.2. Tasks + +1) Реалізувати модель: + + - `channels` + `messages`. + +2) Реалізувати simple REST: + + - `GET /channels`, `GET /channels/:id/messages`, `POST /messages`. + +3) Реалізувати "Add Participant → Agent" модалку: + + - frontend модалка, + - backend entitlements stub: `POST /entitlements` з `agent_id` + `channel_id` + scopes. + +4) Показувати аватари агентів у header каналу. + +--- + +# 4. Projects Agent (15): один проєкт, прості задачі + +Опиратись на: + +`15_projects_agent_module.md`. + +## 4.1. Обсяг MVP + +Реалізувати: + +1) Мінімальну модель: + + - `projects` (id, name, description, team_id), + - `tasks` (id, project_id, title, status, assignees, created_at). + +2) Правий сайдбар для проєктного каналу: + + - якщо канал привʼязаний до проєкту (наприклад `#mvp` → `MicroDAO MVP`): + + - показувати коротку панель: + + - назва проєкту, + - список задач (група за статусом: new / in_progress / done), + - кнопка "Нова задача". + +3) Модалка "Нова задача": + + - поля: + + - Назва, + - Опис (опційно), + - Статус (по замовчуванню `new`), + - Виконавці (поки можна просто селект із людей/агентів). + +4) Мінімальна інтеграція з Messenger: + + - при створенні задачі з правого сайдбару: + + - повідомлення у канал: + + > "Створено задачу: {title}". + +Можна НЕ робити поки: + +- спринти, +- складні фільтри, +- Planning Agent. + +## 4.2. Tasks + +1) Бекенд-моделі `projects` і `tasks` + API. + +2) Привʼязка каналу до проєкту (наприклад, поле `channel.project_id`). + +3) Компонент `ProjectSidebarPanel`: + + - читає з API `GET /projects/:id/tasks`, + - рендерить список, + - кнопка "Нова задача". + +4) Модалка створення задач: + + - `POST /tasks`, + - після успіху: оновити список + відправити повідомлення у канал через Messenger API. + +--- + +# 5. Followups & Reminders Agent (16): "нагадай мені" + +Опиратись на: + +`16_followups_reminders_agent.md`. + +## 5.1. Обсяг MVP + +Реалізувати: + +1) Модель `reminders`: + + - id, user_id, message, fire_at, created_at, status. + +2) Простий tool: + + - `create_reminder({ user_id, message, schedule })`: + + - для MVP: + + - підтримати шаблони: + + - "через N хвилин/годин/днів", + - "завтра о HH:MM". + +3) Інтеграція з чатом: + + - якщо користувач пише: + + - "нагадай мені завтра о 10 про X" + + - Followup Agent: + + - парсить час, + - створює reminder, + - відповідає: + + > "Нагадування створено: завтра о 10:00 — «X»." + +4) Worker / cron: + + - кожну хвилину: + + - `SELECT * FROM reminders WHERE fire_at <= now AND status = 'pending'`, + - відправити повідомлення користувачу (DM або системне повідомлення), + - помітити як `fired`. + +UI: + +- мінімальна панель "Мої нагадування" (наприклад, у профілі). + +## 5.2. Tasks + +1) Бекенд-таблиця `reminders` + API. + +2) Базовий Followup Agent з tool `create_reminder`. + +3) Простий parser NLU для фраз типу "нагадай мені завтра о 10": + + - можна почати з регулярок + rule-based. + +4) Cron/worker для тригеру ремайндерів. + +5) Простий UI список нагадувань (може бути не першочергово). + +--- + +# 6. Agent Cards Grid + Agent Console (23) + +Опиратись на: + +`23_agent_cards_and_console_tasks.md`. + +## 6.1. Обсяг MVP + +1) Маршрут `/t/:teamId/agents`: + + - грід карток агентів: + + - Team Assistant, + - Messenger Agent, + - Projects Agent, + - Followups Agent, + - Knowledge (stub), + - Governance (stub), + - Bridges (stub). + + - картка: + + - аватар, + - імʼя, + - коротке призначення, + - вік (можна згенерувати pseudo-дані), + - базовий текст `Досвід 1T: ...` + `Репутація: ...` (можна поки stub). + + - hover overlay: + + - "Почати взаємодію", + - "Деталі агента". + +2) Agent Console `/t/:teamId/agent/:agentId`: + + - хедер: + + - аватар, + - імʼя, + - опис, + - базові метрики (stub). + + - вкладки: + + - `Чат`: + + - той же `AgentChatWindow`. + + - `Присутність / Права`: + + - поки список каналів/проєктів, де агент підключений. + + - без складних toggle-операцій (можна просто read-only у MVP). + + - це має працювати як "профіль агента". + +## 6.2. Tasks + +1) Реалізувати `/agents` грід (Agent-Cards-Grid). + +2) Реалізувати `/agent/:agentId` консоль. + +3) Зв'язати "Почати взаємодію" → `AgentConsolePage` на вкладці "Чат". + +4) Створити простий endpoint `GET /agents` з базовими метаданими (name, role, created_at, stub-metrics). + +5) Створити endpoint `GET /agents/:id/presence`: + + - повертає: + + - канали, де агент присутній, + - повʼязані проєкти. + +--- + +# 7. OperatorMode — тільки каркас + +Опиратись на: + +`22_operator_modes_and_system_agents.md`. + +## 7.1. Обсяг MVP + +Реалізувати лише: + +1) Поле `operatorMode` у `AgentConfig`. + +2) Guard у `runAgentTurn` / scheduler: + + - якщо `trigger = "operator_tick"`: + + - перевірити: + + - `operatorMode.enabled`, + - ліміт дій на годину, + - allowedTools. + +3) Увімкнути operatorMode: + + - для Followups Agent: + + - для worker-а нагадувань можна поки використовувати прямий cron без LLM, але структуру вже передбачити. + + - опційно для Attention Agent (якщо буде час) — для базового daily digest. + +Не реалізовувати: + +- UI для operatorMode, +- розширені operator режими для всіх агентів. + +--- + +# 8. Що явно НЕ входить до цього MVP (але вже є в документації) + +- Wallet Agent (підпис дій). +- DAO Agent (on-chain DAO інтеграція). +- Повна Governance & Access реалізація (ключі, ритуали узгодження). +- Повний Co-Memory (17) як RAG-система. +- Повний Notifications & Attention Agent (розумні стріми уваги). +- Кастомні домени (`mydao.org`) з DNS-перевірками і auto-SSL. + +--- + +# 9. Порядок реалізації для Cursor (рекомендація) + +Рекомендований порядок задач: + +1) **Multi-tenant context + Agent Hub** + + - teams.slug, + - визначення `currentTeamId`, + - `/home` + базовий Agent Hub. + +2) **Messenger Agent (канали + чати + "додати агента")** + +3) **Projects Agent (проєкт + задачі + правий сайдбар)** + +4) **Followups Agent (reminders + інтеграція з чатом)** + +5) **Agent Cards Grid + Agent Console** + +6) **OperatorMode (каркас guard-ів)** + +Кожен блок можна оформлювати окремим промтом: + +"Implement part X of MVP_VERTICAL_SLICE.md using docs 14/15/16/21/22/23 + 05_coding_standards.md". + +--- + +# 10. Інструкція для Cursor (узагальнений промт) + +Приклад загального промта: + +```text +You are working on the MicroDAO MVP vertical slice. + +Use: + +- MVP_VERTICAL_SLICE.md +- 14_messenger_agent_module.md +- 15_projects_agent_module.md +- 16_followups_reminders_agent.md +- 21_agent_only_interface.md +- 22_operator_modes_and_system_agents.md +- 23_domains_wallet_dao_deepdive.md +- 23_agent_cards_and_console_tasks.md +- 10_agent_ui_system.md +- 05_coding_standards.md + +Goal: + +Implement the MVP vertical slice described in MVP_VERTICAL_SLICE.md, step by step. + +Start with: + +1) Multi-tenant team context + Agent Hub Home. + +Then: + +2) Messenger Agent basics (channels, messages, Add Agent to channel). + +3) Projects Agent basics (one project, tasks, right sidebar). + +4) Followups Agent basics (reminders + chat trigger "нагадай"). + +5) Agent Cards grid and Agent Console. + +6) OperatorMode guard skeleton. + +For each step: + +- list changed files, +- show diff, +- provide a short summary. +``` + +--- + +**Цей документ — твій "мастер-план" для першого живого MVP microDAO.** + +Далі можна або відразу йти в задачі для кроку 1 (multi-tenant + Agent Hub), або доповнити MVP ще якимись деталями, якщо бачиш прогалини. diff --git a/docs/cursor/PLAN_MODULES.md b/docs/cursor/PLAN_MODULES.md new file mode 100644 index 00000000..2a803dcd --- /dev/null +++ b/docs/cursor/PLAN_MODULES.md @@ -0,0 +1,85 @@ +# План модулів MicroDAO (Документи 14-20) + +Цей документ містить план наступних документів, які описують модулі MicroDAO як агенти. + +--- + +## 14. `14_messenger_agent_module.md` + +**Агент-месенджер MicroDAO** + +- Як агент управляє чатами/каналами +- Як "показує інтерфейс месенджера за запитом" +- Які класичні функції месенджера закладені "під капотом" +- Як це пов'язано з пам'яттю та еволюційним агентом + +--- + +## 15. `15_projects_agent_module.md` + +**Агент-проєктний менеджер** + +- Канбан, дедлайни, спринти +- Авто-генерація тасок з діалогів +- Стани, нагадування, резюме спринтів + +--- + +## 16. `16_followups_and_reminders_agent.md` + +**Агент нагадувань / follow-ups** + +- Як перетворює повідомлення на задачі +- Як планує час +- Як координується з Team Assistant + +--- + +## 17. `17_comemory_and_knowledge_space.md` + +**Агент простору знань (Co-Memory)** + +- Документи, wiki, нотатки +- RAG по документах та пам'яті +- Інтерфейс "покажи, що ми вже знаємо про X" + +--- + +## 18. `18_governance_and_tokenomics_agent.md` + +**Агент DAO/токеноміки** + +- Голосування, пропозиції, кворум +- Зв'язок з 1T / RINGK / іншими токенами +- Train-to-Earn з точки зору агента + +--- + +## 19. `19_notifications_and_attention_agent.md` + +**Агент уваги / нотифікацій** + +- Які події важливі, які — ні +- Digest-и, дайджести, персональні огляди дня/тижня + +--- + +## 20. `20_integrations_and_bridges_agent.md` + +**Агент-інтегратор** + +- Telegram / WhatsApp / email / календар +- Як мости працюють через агентську логіку +- Як маршрутизуються повідомлення і контекст + +--- + +## Наступні кроки + +Далі при потребі можна деталізувати кожен з цих модулів у другому шарі документів (UX, API, тест-плани). + +--- + +**Останнє оновлення:** 2024-11-13 + + diff --git a/docs/cursor/README.md b/docs/cursor/README.md index 4753739f..b5db5051 100644 --- a/docs/cursor/README.md +++ b/docs/cursor/README.md @@ -44,11 +44,312 @@ UI/UX специфікація: онбординг, чат, публічний **Коли використовувати:** При тестуванні та перевірці готовності MVP. +### 08_agent_first_onboarding.md +Специфікація агентського онбордингу: діалоговий інтерфейс з агентом-провідником, state-machine, intent parser, повний сценарій діалогу. + +**Коли використовувати:** При реалізації агентського онбордингу замість класичних форм/кроків. + +### 09_evolutionary_agent.md +Специфікація самонавчального еволюційного агента: 3-рівнева архітектура, Meta-Agent, feedback collector, pattern analyzer, версіонування, Train-to-Earn з DAGI. + +**Коли використовувати:** При реалізації функцій самонавчання агента та еволюційного покращення. + +### 10_agent_ui_system.md +Повна специфікація агентського інтерфейсу: типи агентів, компоненти UI (Agent Bubble, Chat Window), інтеграція з каналами, сторінка агента з вкладками, взаємодія з подіями. + +**Коли використовувати:** При реалізації агентського UI та інтеграції агента в інтерфейс MicroDAO. + +### 11_llm_integration.md +Інтеграція LLM (ChatGPT/OpenAI): архітектура, клієнт OpenAI, model router, інтеграція з Agent Chat, Onboarding, Evolutionary Agent, безпека, кешування, альтернативні провайдери. + +**Коли використовувати:** При інтеграції LLM у систему агентів MicroDAO та налаштуванні backend-викликів. + +### 12_agent_runtime_core.md +Agent Runtime Core: інтерфейси агента (AgentConfig, AgentContext), життєвий цикл (runAgentTurn), інтеграція з пам'яттю та LLM, інструменти (Tools), адаптери, структура файлів. + +**Коли використовувати:** При реалізації ядра runtime для агентів та створенні єдиної системи виконання для всіх типів агентів. + +### 13_agent_memory_system.md +Система пам'яті агентів: short-term, mid-term, long-term пам'ять, scopes (Personal/Channel/Team/Global), RAG (Retrieval-Augmented Generation), distillation jobs, інтеграція з еволюційним агентом. + +**Коли використовувати:** При реалізації системи пам'яті для агентів, RAG, та інтеграції з Agent Runtime Core. + +### 14_messenger_agent_module.md +Агент-месенджер MicroDAO: агентське переосмислення месенджера, ролі агентів, функціональні спроможності, інтеграція з Runtime Core та пам'яттю, типові сценарії, реалізація tools. + +**Коли використовувати:** При реалізації агентського модуля месенджера та інтеграції класичних функцій чату з агентською системою. + +### 15_projects_agent_module.md +Projects Agent Module: агент-проєктний менеджер, ролі (Projects Agent, Task Agent, Planning Agent), структура проєкту, модель задачі, авто-створення задач з діалогів, інтеграція з Runtime Core, пам'яттю та Messenger Agent, UI інтеграція. + +**Коли використовувати:** При реалізації агентського модуля управління проєктами та задачами. + +### 16_followups_reminders_agent.md +Follow-ups & Reminders Agent: агент-нагадувань та ритму роботи, ролі (Followup Agent, Personal Reminder Agent), фрази-тригери, інтеграція з Projects Agent, tools (create_followup, create_reminder, daily_digest), UI інтеграція. + +**Коли використовувати:** При реалізації агентського модуля нагадувань, фоллоуапів та організації ритму роботи спільноти. + +### 17_comemory_knowledge_space.md +Co-Memory & Knowledge Space: колективна пам'ять спільноти, структура знань (документи, факти, визначення), агенти (Memory Agent, Knowledge Curator, Knowledge Guide), RAG-пошук, життєвий цикл знань, інтеграція з DAGI. + +**Коли використовувати:** При реалізації модуля колективної пам'яті, простору знань та RAG-системи для агентів. + +### 18_governance_access_agent.md +Governance & Access Agent: агент правил, доступів та ритуалів спільноти, символічні ключі (Community Keys), ритуали узгодження, індекс довіри, інтеграція з RBAC та entitlements, без фінансової термінології. + +**Коли використовувати:** При реалізації модуля управління правилами, доступами та колективними рішеннями спільноти. + +### 19_notifications_attention_agent.md +Notifications & Attention Agent: агент уваги та інформаційної гігієни, фільтрація шуму, ранжування важливості, дайджести, потоки уваги (High/Normal/Low), інтеграція з усіма агентами, Attention Hub. + +**Коли використовувати:** При реалізації модуля управління сповіщеннями, фільтрації шуму та забезпечення інформаційної гігієни в спільноті. + +### 20_integrations_bridges_agent.md +Integrations & Bridges Agent: агент мостів та зовнішніх інтеграцій, месенджери (Telegram, Email), робочі інструменти (Calendar, GitHub), Cross-microDAO зв'язки, Web3-протоколи, Connector Agents, маршрутизація подій. + +**Коли використовувати:** При реалізації модуля інтеграцій з зовнішніми платформами, месенджерами та інструментами, а також міжпросторових зв'язків між microDAO. + +### 21_agent_only_interface.md +Agent-Only Interface: агентська ОС замість класичного застосунку, layout (3 колонки), панель учасників (Люди/Агенти/Роботи), Agent Hub як стартовий екран, запрошення агентів, обмін ресурсами, MVP. + +**Коли використовувати:** При реалізації агентського інтерфейсу та перетворенні MicroDAO на агентську операційну систему спільнот. + +### 22_operator_modes_and_system_agents.md +Operator Modes & System Agents: приватні агенти, спільні агенти, операторські режими, DAO Agent, Wallet Agent, модель operatorMode, інтеграція з доступами та ключами, принципи безпеки. + +**Коли використовувати:** При реалізації операторських режимів агентів, системних агентів (Personal, Team, Protocol) та інтеграції з Governance та Wallet Agent. + +### 22_agent_only_interface_tasks.md +Структурований список задач для реалізації Agent-Only Interface: 4 детальні задачі з специфікаціями, acceptance criteria та прикладами промптів для Cursor. + +**Коли використовувати:** При поетапній реалізації Agent-Only Interface — давати Cursor по одній задачі за раз. + +### 23_domains_wallet_dao_deepdive.md +Domains, Wallet & DAO Deep Dive: технічний дизайн доменної моделі з мульти-тенант роутінгом, OperatorMode guards, Wallet Agent протокол безпечного підпису, мінімальна реалізація DAO Agent, інтеграція компонентів. + +**Коли використовувати:** При реалізації системних компонентів: доменна модель, обмеження операторських режимів, безпечний підпис, інтеграція з on-chain DAO. + +### 23_agent_cards_and_console.md +Agent Cards and Console: концепція "живих карток агентів", структура картки, Agent Console з 5 вкладками, метрики досвіду (1T, репутація), підключення до просторів, DAGI інтеграція, зберігання в microDAO. + +**Коли використовувати:** При реалізації UI для агентів у форматі карток та повного інтерфейсу Agent Console. + +### 24_agent_cards_tasks.md +Структурований список задач для реалізації Agent Cards та Console: 4 детальні задачі (Cards Grid, Console UI, Experience Metrics, Connections Toggles). + +**Коли використовувати:** При поетапній реалізації системи карток агентів — давати Cursor по одній задачі за раз. + +## MVP Vertical Slice + +### MVP_VERTICAL_SLICE.md +Практичний план реалізації MVP для перших користувачів: послідовність етапів (Multi-Tenant + Agent Hub → Агенти → Agent Cards/Console → OperatorMode), приймальні критерії, що входить/не входить в MVP. + +**Коли використовувати:** При початку реалізації — це основний документ для створення живого вертикального зрізу системи. + +## DAARION.city Integration + +### DAARION_city_integration.md +Архітектура інтеграції міського рівня DAARION.city з microDAO: єдина модель (платформи = тип microDAO), спільна ідентичність, city-level Bridges Agent, City Co-Memory, трирівнева Governance, blueprints. + +**Коли використовувати:** При інтеграції платформ DAARION.city з microDAO архітектурою та створенні міського шару над microDAO. + +### DAARION_city_platforms_catalog.md +Каталог платформ екосистеми DAARION.city: опис домену кожної платформи, агентські модулі, ключі доступу, Embassy-інтеграція. Включає DAARION Core, DAARWIZZ, GREENFOOD, Energy Union, Water Union, Essence Stream. + +**Коли використовувати:** При інтеграції конкретних платформ DAARION.city з microDAO, налаштуванні access keys та capabilities для платформ. + +## Access Keys & Capabilities System + +### 24_access_keys_capabilities_system.md +Універсальна система ключів доступу та capability-механіка для microDAO/DAARION.city. Описує типи ключів (User Session, Agent Access, API Key, Embassy Key, Wallet Capability Key), Wallet Agent специфікацію, Embassy Module, runtime capability-check, інтеграцію з Governance Agent. + +**Коли використовувати:** При реалізації системи авторизації, Wallet Agent, Embassy Module, та налаштуванні capabilities для різних типів доступу. + +### 28_flows_wallet_embassy_energy_union.md +Sequence-діаграми (Mermaid) ключових флоу для Access Keys & Capabilities System: Login → Capability Token → Action, Agent Run, Stake RINGK → Payout Flow, Embassy Webhook → PDP → RWA Inventory, Energy Union → Embassy Oracle, Wallet Claim Flow, Outbox → NATS Delivery, Governance Flow. Містить опис кожного флоу, Threat Model Integration Points та ключові моменти. + +**Коли використовувати:** При реалізації PDP/PEP, Embassy Gateway, Wallet Service та інтеграції з NATS JetStream для event-driven архітектури, тестуванні end-to-end сценаріїв, дебагу production issues. + +## Database Schema & Migrations + +### 27_database_schema_migrations.md +Повна виробнича специфікація схеми бази даних microDAO/DAARION.city: всі таблиці по модулях (Users, Teams, RBAC, Channels, Messages, Projects, Agents, Wallet, Staking, Payouts, RWA, Embassy, Capability System, Audit, Outbox), порядок міграцій, naming-конвенції, seed-дані, інтеграція з Event Catalog, DevOps pipeline, rollback policy. + +**Коли використовувати:** При створенні міграцій БД, плануванні схеми, інтеграції з Supabase/PostgreSQL, та як «джерело істини» для архітектури БД. + +## Deployment & Infrastructure + +### 25_deployment_infrastructure.md +Deployment процес, середовища (local/dev/staging/prod), інфраструктура (Postgres, NATS, API Gateway, Frontend, Object Storage), CI/CD pipeline, конфігурація та environment variables, secrets management, моніторинг та логування, backups & restore, rollout strategies, feature flags. + +**Коли використовувати:** При налаштуванні інфраструктури, створенні CI/CD pipeline, deployment процесів, моніторингу та управлінні середовищами. + +## Security & Audit + +### 26_security_audit.md +Безпековий чеклист для регулярного аудитування платформи: Identity & Authentication, Authorization Layer (RBAC + Entitlements + Capabilities), Access Keys, Confidential Mode (E2EE), API Security, Web Client Security, Database Security, Secrets Management, Embassy & Webhooks Security, Wallet & Chain Security, RWA Security, Logging & Audit Trail, Monitoring & Alerting, Incident Response, Compliance. + +**Коли використовувати:** При проведенні безпекового аудиту, перевірці впровадження security best practices, підготовці до production deployment, та регулярних security reviews. + +## Scaling & High Availability + +### 29_scaling_and_high_availability.md +Масштабування, відмовостійкість, балансування навантаження, кластеризація сервісів: API Layer Scaling, Backend Domain Services Scaling, Agents Scaling, NATS JetStream Scaling & HA, Postgres High Availability, Outbox Pattern Scaling, Embassy Scaling, Wallet Scaling & RWA, Scaling Frontend, Failover Strategies, Disaster Recovery (DR), Benchmark Targets. + +**Коли використовувати:** При проектуванні HA-архітектури, налаштуванні autoscaling, плануванні disaster recovery, та оптимізації продуктивності для production deployment. + +## Cost Optimization & Token Economics + +### 30_cost_optimization_and_token_economics_infrastructure.md +Оптимізація витрат інфраструктури та зв'язок з токеномікою: основні центри витрат (LLM/AI/Agents, Compute, Storage, Observability), принципи оптимізації, зв'язок токенів (RINGK, 1T, KWT, DAAR/DAARION) з технічною економікою, технічні ліміти та Entitlements, Autoscaling vs. Cost Guards, LLM/Agents Cost Controls, RWA/Embassy обмеження, Wallet/Chain/Gas Optimization, Analytics для економіки, Governance Controls, практичні граничні значення для MVP. + +**Коли використовувати:** При проектуванні системи квот та обмежень, інтеграції токеноміки з технічною інфраструктурою, створенні usage tracking та cost controls, налаштуванні governance для економічних політик. + +## Governance & Policies + +### 31_governance_policies_for_capabilities_and_quotas.md +Політики DAO для управління доступами, квотами, використанням ресурсів: Actors (Governance Token Holders, Governance Agent, Capability Registry, Policy Service), типи політик (Capability, Plan & Entitlement, Stake/RINGK, 1T Compute, KWT Energy, RWA Access, Governance Process), Governance Policy Lifecycle, Policy Structure, Policy Application Rules, Policy Registry, PDP Integration, Example Policies, Governance-Safe Defaults, Security Considerations, Audit & Transparency, Governance Failover Procedures. + +**Коли використовувати:** При реалізації Governance Agent, створенні Policy Registry, інтеграції з PDP для управління capabilities та quotas, налаштуванні голосування та застосування політик. + +## Policy Service & PDP + +### 32_policy_service_PDP_design.md +Архітектура Policy Decision Point (PDP): PDP Formula, PDP Inputs, Architecture Overview, Internal Modules (Role Resolver, Capability Resolver, Entitlements, Quota Manager, ACL Resolver, Confidential Mode Resolver, Key Status Checker), PDP Data Sources, PDP Cache Design (Static, Dynamic, Usage Cache), PDP Decision Algorithm, Integration with API Gateway (PEP), Agents, Embassy, Wallet, Governance, PDP Logging & Audit, Performance Targets, Failure Modes & Recovery, Security Considerations. + +**Коли використовувати:** При реалізації Policy Decision Point, проектуванні системи авторизації, інтеграції PDP з API Gateway, Agents, Embassy, Wallet, налаштуванні кешування та оптимізації продуктивності. + +## API Gateway & Security + +### 33_api_gateway_security_and_pep.md +API Gateway Architecture та Policy Enforcement Point (PEP): High-level Architecture, Key Responsibilities (Authentication, Authorization, Key Lifecycle Management, Usage Accounting, Transport Security), Request Flow, Identity Sources (User, Agent, Embassy, Integration), Key Validation Pipeline, PDP Integration, Rate Limiting Layer (Global, Per-IP, Per-Key, Per-Action, Per-Team), Resource Context Extraction, Confidential Mode Enforcement, Embassy Webhook Security, Wallet API Security, Agent API Security, Quota Enforcement Integration, Logging Model, API Hardening, Error Model, Performance Targets, Failover & Resilience. + +**Коли використовувати:** При реалізації API Gateway, створенні PEP middleware, налаштуванні rate limiting, інтеграції з PDP, захисті Embassy webhooks, Wallet API, Agent API, та впровадженні безпекових guardrails. + +## Internal Services Architecture + +### 34_internal_services_architecture.md +Архітектура внутрішніх сервісів: High-Level Service Landscape, Core Principles, Internal Services Overview (17 сервісів: User/Team, Messaging, Projects/Tasks, Agent Orchestrator, LLM Proxy, Router/Planner, Wallet, RWA Inventory, Embassy Gateway, Oracle Processor, Governance, Capability Registry, Usage, Outbox Worker, Telemetry, Auth/Session, File Storage), Dependency Graph, Internal API Standards, Horizontal Scaling Responsibilities, Event Streams (NATS Topics), Outbox Pattern, Cross-service Transaction Rules, Security Boundaries, Suggested Deployment Model, Failure Isolation, Minimal Monitoring Set. + +**Коли використовувати:** При проектуванні backend-архітектури, визначенні відповідальності сервісів, плануванні мікросервісної архітектури, налаштуванні event-driven потоків, та організації взаємодії між сервісами. + +## Service Mesh + +### 35_microdao_service_mesh_design.md +MicroDAO Service Mesh: High-Level Mesh Architecture, Zero-Trust Model, Service Identity (mTLS), Service Registry, Internal Service-to-Service Traffic, Core Service Mesh Features (mTLS Encryption, Load Balancing, Retries, Circuit Breakers, Timeouts), Internal API Standard, PDP Integration, Mesh-Level Policies (Allow-lists, Deny-lists), Observability Model (Metrics, Tracing, Logs), Failover & Resilience, Mesh Traffic Rules for Critical Services, Service Mesh Security, Deployment Model (Sidecar Mode, Node-agent Mode, Observability stack), Service Mesh Integration with Scaling, Message Patterns, Example Mesh Policy Config. + +**Коли використовувати:** При налаштуванні service mesh, впровадженні zero-trust моделі, конфігурації mTLS, налаштуванні observability, та організації безпечної взаємодії між сервісами. + +## Agent Security & Isolation + +### 36_agent_runtime_isolation_and_sandboxing.md +Безпечна ізоляція приватних агентів: Threat Model, Agent Runtime Architecture, Sandbox Security Model (Isolation Levels, Namespaces/cgroups, Banned syscalls), Network Policy (Default NO NETWORK, Allowed network flows), Agent Permissions & PDP Integration, Tools Architecture (Types of Tools, Tool Execution Model, Tool Security Rules, Dangerous Tools), Agent Memory Model (No persistent state, Co-Memory Integration, Confidential Mode), Prompt Injection Protection, Runtime Limits (CPU, Memory, Timeout, Parallel Agents), File System Policy, Logging Policy, Chain-of-Thought Protection, Deny-List Rules, Escalation Prevention, Governance Hooks for Agents, Observability, Agent Cost Control, Failure Modes. + +**Коли використовувати:** При реалізації Agent Runtime, створенні sandbox-середовища, налаштуванні безпеки агентів, інтеграції з PDP для tool invocations, та впровадженні захисту від prompt injection та escalation. + +### 37_agent_tools_and_plugins_specification.md +Докладна специфікація інструментів агентів: Architectural Overview, Tool Security Categories (Category A — Safe Tools, Category B — Controlled Tools, Category C — Sensitive Tools, Category D — Critical Tools), Tool Capability Model, Tool Execution Contract, Tool Proxy Rules, Timeouts & Limits per Category, Plugins API (Plugin Manifest, Plugin Execution Flow, Plugin Security Model), Built-in Tools (Core, Internal, Advanced, Platform), Platform Tool Contracts (GREENFOOD, EnergyUnion), Confidential Mode — Tool Restrictions, Error Model, Auditing & Logging, Governance Hooks. + +**Коли використовувати:** При реалізації Tool Proxy, створенні інструментів для агентів, розробці Plugins API, інтеграції з платформами DAARION (GREENFOOD, EnergyUnion), та налаштуванні безпеки інструментів. + +### 38_private_agents_lifecycle_and_management.md +Життєвий цикл приватних агентів: What Is a Private Agent, Agent Types (User Agent, Team Agent, System Agent), Agent Creation Flow, Agent Schema (DB), Agent Initialization (Bootstrap), Agent Access Keys, Agent Configuration Model, Agent Update Flow, Agent Run Lifecycle (Start, Sandbox Spin-Up, Execute, Complete), Agent Memory Policy, Agent Logs, Agent Suspension, Agent Deletion Flow, Agent Versioning, Security - Critical Guarantees, Events Generated by Agent Lifecycle, Integration with PDP/PEP/Mesh/Tools. + +**Коли використовувати:** При реалізації Agent Orchestrator, створенні агентів, управлінні життєвим циклом агентів, налаштуванні конфігурації та безпеки агентів, та інтеграції з PDP/PEP для авторизації. + +### 39_private_agent_templates_and_behavior_profiles.md +Шаблони приватних агентів та поведінкові профілі: What is a Behavior Profile, Base Agent Templates (TEMPLATE_A: Assistant, TEMPLATE_B: Analyst, TEMPLATE_C: Operator, TEMPLATE_D: Autonomous Agent), Behavior Profiles (Advisor, Researcher, Project Manager, Automation Builder, Platform Integrator, Autonomous Planner), Behavior Profile Schema, Behavior Parameters (Autonomy Levels, Tone Controls, Output Controls), Tool Access by Profile, Confidential Mode Compatibility, Profile Switching Logic, Safe System Instructions, Governance-Level Restrictions, Security Behavior Controls, Profile Templates Examples. + +**Коли використовувати:** При створенні шаблонів агентів, налаштуванні поведінкових профілів, визначенні рівнів автономії, контролі стилю/тону, та стандартизації поведінки агентів. + +## RWA & Embassy Integration + +### 40_rwa_energy_food_water_flow_specs.md +Потоки RWA (Real-World Assets): Supported RWA Domains (Energy, Food, Water), Data Flow Overview, Embassy Integration (Authentication, HMAC validation), Oracle Payload Specification, RWA Inventory Table Schema, Processing Flow for Each Domain (ENERGY, FOOD, WATER), KWT / 1T Tokenization Rules, Wallet Integration, Governance-Controlled Parameters, Anomaly Detection & Anti-Fraud, Oracle Processor Rules, Data Retention, Critical Security Rules, Example End-to-End Flow (Energy). + +**Коли використовувати:** При реалізації Embassy webhook endpoints, Oracle Processor, RWA Inventory updates, Wallet integration для RWA payouts, інтеграції з платформами DAARION (GREENFOOD, EnergyUnion, WaterUnion), та налаштуванні безпеки RWA потоків. + +## Governance & AI Agent + +### 41_ai_governance_agent_design.md +AI Governance Agent: Governance Model Overview, Governance Proposal Lifecycle, Governance Proposal Structure, Governance Agent Responsibilities (Validation, Voting Finalization, Applying Policy, Audit, Failure Recovery), Governance Agent Internal Architecture, Policy Validation Rules (Format, Capability, Plan/Entitlements, Stake-multiplier, Compute/1T, RWA policies), Voting Engine, Policy Applicator, Registry Integration (Capability, Quota, Stake, RWA), PDP Integration, Security Rules (Critical), Error Recovery, Transparency & Audit, Governance Agent Runtime, Example Policy Application. + +**Коли використовувати:** При реалізації AI Governance Agent, створенні системи голосування та застосування політик, інтеграції з Policy Registry та PDP, налаштуванні безпеки Governance Agent, та впровадженні механізмів аудиту та прозорості. + +## Event Streams & NATS + +### 42_nats_event_streams_and_event_catalog.md +NATS Event Streams & Event Catalog: JetStream Cluster Model, Event Categories Overview (13 груп подій), Stream Naming Convention, Topic Naming Convention, Event Envelope, Outbox Integration (Guaranteed Delivery), Stream-by-Stream Specification (13 стрімів: AGENT_RUN, CHAT, PROJECT, TASK, WALLET, STAKING, PAYOUT, EMBASSY, ORACLE, RWA, GOVERNANCE, USAGE, TELEMETRY), Retention Policies, Consumer Groups, Message Ordering, Security / ACL, Replay & Recovery, NATS Integration with Mesh. + +**Коли використовувати:** При налаштуванні NATS JetStream, створенні event streams, визначенні payload схем, конфігурації retention policies, налаштуванні consumer groups, впровадженні ACL та безпеки, та інтеграції з Outbox Worker. + +### 43_database_events_outbox_design.md +Database Events Outbox Design: Why Outbox Pattern Is Required, Outbox Table Schema, Outbox Event Insertion (atomic transaction), Outbox Worker Architecture, Worker Processing Loop, Deduplication (NATS header Nats-Msg-Id), Retry Strategy (exponential backoff, dead-letter condition), Batch Processing & Throughput, Event Ordering Rules, Multi-Stream Routing, Failure Modes, Safety Guarantees (atomicity, consistency, at-least-once, no-loss, replayability), Event Consumer Rules, Operational Metrics, Backpressure Control, Batch Deletion / Archival, Example End-to-End Flow (Payout). + +**Коли використовувати:** При реалізації Outbox Pattern, створенні таблиці outbox_events, розробці Outbox Worker, забезпеченні гарантій доставки подій, інтеграції з NATS JetStream, та налаштуванні retry/backoff механізмів. + +## Usage & Quota Management + +### 44_usage_accounting_and_quota_engine.md +Usage Accounting & Quota Engine: Usage Engine Architecture, Usage Metrics (Canonical List - LLM, Agents, Router, Embassy, RWA, Wallet, Storage), Quota Types (Hard quotas, Soft quotas, Compute cost ceilings), Quota Formula (base_quota(plan) × multiplier(stake)), Counters Storage Model (Redis fast counters, Postgres durable counters), Quota Engine Decision Logic, Warning Thresholds, Rate Limiting Integration, PDP Integration, Cost Accounting (1T Integration), Embassy/RWA Quotas, Agent Run Limits, Storage/Files Quotas, Wallet/Chain Quotas, Usage Correction / Reconciliation, Governance Controls, Abuse / Fraud Protection, Observability, Error Model, Example Scenarios. + +**Коли використовувати:** При реалізації Usage Engine, створенні системи обліку використання ресурсів, налаштуванні квот, інтеграції з PDP, контролі вартості, захисті від зловживань, та налаштуванні rate limiting. + +## LLM & Router + +### 45_llm_proxy_and_multimodel_routing.md +LLM Proxy & Multi-Model Routing: High-Level Architecture, Why Not Call LLM Directly, Core Responsibilities, Supported Model Types (Text, Vision, Embeddings, Code, Audio), Normalized Request Schema, Routing Modes (DIRECT, TIERED ROUTING, Specialized), Fallback Logic, Prompt Sanitization Layer, Confidential Mode, PDP Integration, Token Counting, Cost Calculation (1T Integration), Multi-Model Orchestration, Error Model, Retry / Timeouts, Model Selection Logic, Local Model Constraints, Autoscaling, Logging & Monitoring, Safety / Guardrails, Example Complete Flow. + +**Коли використовувати:** При реалізації LLM Proxy, налаштуванні маршрутизації моделей, інтеграції з різними LLM провайдерами, контролі вартості та токенів, впровадженні fallback логіки, та забезпеченні безпеки promptів. + +### 46_router_orchestrator_design.md +Router Orchestrator Design: High-Level Architecture, Input Specification, Router Modes (AUTO PLAN, STRUCTURED, HYBRID), State Machine Architecture (INIT, PLAN, EXECUTE_STEP, WAIT_TOOL, WAIT_AGENT, ERROR_RECOVERY, DONE), Step Engine (LLM, Tool, Agent, Platform, Branch, Parallel, Loop), Safety Limits, Cost Control, Confidential Mode, Tool Execution Flow, LLM Execution Flow, Subagent Execution Flow, Error Handling, Logging, Monitoring, Platform Tool Integration, Parallel Steps, Branch Logic, Loop Logic, Full Example Flow. + +**Коли використовувати:** При реалізації DAARWIZZ Router, створенні multi-step orchestration, налаштуванні state machine, інтеграції з tools, agents, LLM Proxy, та контролі вартості та безпеки флоу. + +## Messaging & Privacy + +### 47_messaging_channels_and_privacy_layers.md +Messaging Channels & Privacy Layers: Messaging Entities (Direct Messages, Team Channels, System Channels), Channel Types (DIRECT, TEAM PUBLIC, TEAM PRIVATE, CONFIDENTIAL CHANNEL), Channel Schema, Message Schema, E2EE Model (Optional Layer), Confidential Mode Rules, ACL Model, Agent Visibility Rules, Search Indexing, Message Lifecycle (Create, Edit, Delete), Retention Rules, Attachments (Files), Moderate / Filter System, Chat → Agent → LLM Proxy Flow, Chat → Router Flow, System Channels, Governance Controls, Observability & Telemetry. + +**Коли використовувати:** При реалізації системи чатів та каналів, налаштуванні приватності та confidential mode, створенні ACL, інтеграції з агентами та LLM Proxy, та забезпеченні безпеки повідомлень. + +### 48_teams_access_control_and_confidential_mode.md +Teams Access Control & Confidential Mode: Team (microDAO) Model, Team Roles (Owner, Guardian, Admin, Member, Guest, Agent), Role Capability Mapping, Team-Level ACL (Projects, Channels, Agents, Wallet, Embassy Data), Team States (active, locked, confidential, suspended, archived), Confidential Mode (LLM Proxy behavior, Agents restrictions, Messaging rules, Projects/Tasks rules, Wallet/RWA rules), Team Privacy Layers (open, restricted, private, confidential), Team Settings Schema, PDP Integration, Governance Controls, Membership Lifecycle (Create Team, Invite Member, Promote, Demote, Remove), Agent Integration Rules, Examples. + +**Коли використовувати:** При реалізації системи доступів команд, налаштуванні ролей та ACL, впровадженні confidential mode, інтеграції з PDP, та управлінні членством у командах. + +## Wallet & RWA + +### 49_wallet_rwa_payouts_claims.md +Wallet, RWA, Payouts & Claims: Wallet Tokens (1T, KWT, RINGK, DAARION), Wallet Architecture, Wallet Schema (Balances, Transactions, Payouts), ACL Rules, RWA → Payout Formula (ENERGY → KWT, FOOD → 1T, WATER → 1T/KWT), Payout Lifecycle, Claim Lifecycle, Conversion Rules (KWT → 1T, DAARION → RINGK, RINGK → 1T impossible), Daily/Monthly Limits, Fraud Protection, Governance Controls, Integrations (NATS Events, Usage Engine, PDP), Transparency & Logs, Example Scenarios. + +**Коли використовувати:** При реалізації Wallet Service, створенні системи балансів та транзакцій, налаштуванні RWA нарахувань та payouts, інтеграції з Embassy/RWA/Outbox/NATS, та забезпеченні безпеки та прозорості економічної моделі. + +## Website Integration + +### 50_daarion_city_website_integration.md +DAARION.city Website Integration: Architecture Overview (Embedded Widget, iframe Embed, Full Redirect), DAARION.city as First MicroDAO (Team Setup, Public Channel Setup, City Agent Setup), Public Channel API (Get Channel Info, Get Messages, Post Message, Register as Viewer/Member), UI/UX for Website Integration (Embedded Widget Component, Widget Layout, Authentication Flow), SEO & Metadata (Open Graph Tags, Twitter Cards, Structured Data), Security & Privacy (CORS Configuration, Rate Limiting, Content Moderation), Analytics & Tracking, Implementation Steps, Example Integration Code (Next.js Page, React Widget Component), Testing Checklist. + +**Коли використовувати:** При інтеграції MicroDAO у офіційний сайт DAARION.city, створенні публічного каналу міста, вбудовуванні віджета на сайт, налаштуванні authentication flow для користувачів сайту, додаванні SEO метаданих та analytics tracking. + +## Tokenomics + +### tokenomics/city-tokenomics.md ⭐ CANONICAL +City Tokenomics — DAARION.city (v1.0.0, status: canonical): DAAR (Utility Token), DAARION (Civic/Identity Token), Рівні доступу (Звичайні користувачі, Постачальники, Створення платформ, Створення MicroDAO), Ієрархія MicroDAO (A1: DAARION.city, A2: Міські платформи, A3: Публічні MicroDAO, A4: Приватні MicroDAO), MicroDAO Tokens (GOV, UTIL, REP), Fees & Costs, Staking & Rewards (DAAR: 20% APR, DAARION: 4% + revenue share), Token Bridges & Onboarding, Integration Points (Wallet Service, PDP, Agents, DAGI Registry), Security Rules, MVP Scope. + +**Коли використовувати:** При реалізації токеноміки DAARION.city, створенні DAOFactory, TokenBridge, інтеграції з Wallet Service, PDP token-gating, staking системи, валідації доступу користувачів, роботі агентів DAARWIZZ, контролі доступу до платформ, ліцензуванні сервісів, та реалізації багаторівневої архітектури міста. + +> **Примітка:** Це єдиний актуальний документ з токеноміки. Попередній `tokenomics/README.md` перенесено в `docs/_archive/tokenomics_legacy_v0.md`. + ## Як використовувати з Cursor ### 1. Початкове налаштування Додай всю папку `docs/cursor/` в контекст Cursor або вкажи на конкретні файли при створенні промптів. +### 2. Початок роботи (MVP) +Почни з `MVP_VERTICAL_SLICE.md` — це практичний план для створення першого живого зрізу системи. + ### 2. Створення промптів Використовуй формат з `06_tasks_onboarding_mvp.md`: @@ -79,7 +380,9 @@ Please output: 1. **Ознайомся з проєктом:** `00_overview_microdao.md` 2. **Зрозумій бізнес-логіку:** `01_product_brief_mvp.md` 3. **Вивчи архітектуру:** `02_architecture_basics.md` -4. **Почни з онбордингу:** `06_tasks_onboarding_mvp.md` → Block A +4. **Почни з онбордингу:** + - Класичний: `06_tasks_onboarding_mvp.md` → Block A + - Агентський: `08_agent_first_onboarding.md` 5. **Тестуй:** `07_testing_checklist_mvp.md` ## Важливі примітки @@ -99,5 +402,5 @@ Please output: --- **Версія:** MVP v1.0 -**Останнє оновлення:** 2025-01-XX +**Останнє оновлення:** 2024-11-13 diff --git a/docs/daarion/README.md b/docs/daarion/README.md new file mode 100644 index 00000000..96b8bd90 --- /dev/null +++ b/docs/daarion/README.md @@ -0,0 +1,25 @@ +# DAARION.city — Документація + +Ця папка містить документацію про DAARION.city: roadmap, governance, токеноміку міста, інтеграцію з MicroDAO. + +## Структура + +### Стратегія та roadmap +- `vision.md` — бачення DAARION.city +- `roadmap.md` — roadmap розвитку +- `governance.md` — система управління та governance + +### Токеноміка +- `tokenomics.md` — токеноміка міста (DAAR, DAARION) +- `tokenomics-city.md` — детальна токеноміка (з `/docs/tokenomics/city-tokenomics.md`) + +### Інтеграція +- `integration-microdao.md` — інтеграція з MicroDAO +- `platforms-catalog.md` — каталог платформ (GREENFOOD, EnergyUnion, WaterUnion) + +## Посилання + +- [MicroDAO документація](../microdao/README.md) +- [Агентська система](../agents/README.md) +- [Технічна документація](../cursor/README.md) + diff --git a/docs/daarion/integration-microdao.md b/docs/daarion/integration-microdao.md new file mode 100644 index 00000000..4caf030e --- /dev/null +++ b/docs/daarion/integration-microdao.md @@ -0,0 +1,403 @@ +# DAARION_city_integration.md + +DAARION.city як суперDAO над microDAO та інтеграція існуючих платформ + +Цей документ описує, як: + +1. DAARION.city розглядається як **міське superDAO**, побудоване на тих самих механізмах, що й microDAO. + +2. DAARION.city є **реєстром мешканців** та "над-організацією", яка об'єднує microDAO. + +3. Існуючі проєкти (наприклад, **greenfood.live**, **EnergyUnion**) стають **розвиненими microDAO-платформами**, а не окремими всесвітами. + +Документ задає архітектурну модель і конкретні задачі для Cursor. + +--- + +## 1. Модель: DAARION.city = microDAO типу "city" + SuperDAO над іншими microDAO + +### 1.1. Розширення `teams` / `microdaos` + +Базова сутність одна — `team`/`microdao`, але з типами: + +```ts +type TeamType = "city" | "platform" | "community" | "guild" | "lab" | "personal"; +``` + +Приклади: + +* `DAARION.city` → `type = "city"` (city-level superDAO) +* `GreenFood` → `type = "platform"` (eco/food marketplace) +* `EnergyUnion` → `type = "platform"` (BioMiner + AI + DAO екосистема) +* Приватні microDAO → `type = "community"` або `personal`. + +### 1.2. Ієрархія "місто → платформи → мікроDAO" + +Додаткова таблиця: + +```ts +city_links: +- id +- parent_team_id // зазвичай DAARION.city team_id +- child_team_id // microDAO або платформа +- relation_type // "platform", "community", "guild", "adapter" +- created_at +``` + +Інтерпретація: + +* `DAARION.city` як `parent_team_id` для: + + * платформ (GreenFood, EnergyUnion, інші платформи), + * приватних microDAO, які бажають "приписатися" до міста. + +--- + +## 2. Реєстр мешканців DAARION.city + +DAARION.city — це також **місце реєстрації всіх мешканців**. + +### 2.1. Модель користувача + +```ts +users: +- id +- city_handle // унікальний нік у DAARION.city +- display_name +- avatar_url +- created_at +``` + +### 2.2. Громадянство (citizenship) + +```ts +citizenships: +- id +- user_id +- city_id // team_id DAARION.city +- status: "active" | "pending" | "revoked" +- joined_at +``` + +### 2.3. Членство в microDAO / платформах + +```ts +memberships: +- id +- user_id +- team_id // будь-який microDAO (включно з платформами) +- role: "admin" | "member" | "guest" +- joined_at +``` + +DAARION.city у цьому сенсі — просто `team` із `type="city"`, де всі громадяни мають запис `citizenship`, а членство в платформах і microDAO моделюється через `memberships`. + +--- + +## 3. DAARION.city як суперDAO: city-level агенти + +DAARION.city має власний набір **city-level agentів**, які працюють поверх міських даних і child-microDAO: + +* **City Governance Agent** — міські правила, дух міста. +* **City Registry Agent** — реєстр мешканців, громадянство. +* **City Bridges Agent** — зв'язки між city ↔ платформи ↔ microDAO. +* **City Co-Memory Agent** — загальноміський простір знань. + +Ці агенти використовують ті самі механізми, що й агенти microDAO, але їх `team_id` = `DAARION.city`. + +--- + +## 4. Перетворення існуючих платформ на microDAO + +Мета: платформи **greenfood.live** та **EnergyUnion** стають microDAO-платформами в структурі DAARION.city. + +### 4.1. GreenFood як microDAO-платформа + +Факти про платформу: + +* GreenFood — еко-система для невеликих виробників та переробників органічної й домашньої продукції та вимогливих покупців. +* Підтримка блокчейн-технологій та внутрішня бартерна криптовалюта DAAR. + +#### Кроки перетворення GreenFood → microDAO: + +1. **Створити запис `team`**: + + * `name = "GreenFood"` + * `type = "platform"` + * `slug = "greenfood"` + +2. **Прив'язати до DAARION.city**: + + * `city_links.insert(parent_team_id = daarion_city_id, child_team_id = greenfood_id, relation_type = "platform")` + +3. **Задати blueprint GreenFood**: + + * агентська конфігурація: + + * Marketplace/Orders Agent, + * Producers & Buyers Agent, + * Eco/Quality Knowledge Agent, + * інтеграція з існуючим мобільним додатком / API (через Bridges Agent). + +4. **Bridges / adapters**: + + * Connector до існуючого GreenFood backend: + + * products → проєкти/категорії/knowledge, + * orders → tasks / workflows, + * farmers → окремий тип учасників. + +5. **DAAR-валюта як доступ**: + + * трактувати DAAR-токени як внутрішні "ключі доступу/бартерні одиниці" у Governance/Access, а не як фінансові активи. + +### 4.2. EnergyUnion як microDAO-платформа + +Факти про платформу: + +* ENERGY UNION BioMiner = платформа, що поєднує чисту енергію, AI та DAO в одній екосистемі. +* BioMiner конвертує біомасу в електроенергію для дата-центрів та AI-лабів, токени відкривають доступ до енергії (kWt), AI-обчислень (1T) та carbon+. + +#### Кроки перетворення EnergyUnion → microDAO: + +1. **Створити `team`**: + + * `name = "EnergyUnion"` + * `type = "platform"` + * `slug = "energyunion"` + +2. **Прив'язати до DAARION.city**: + + * `city_links.insert(parent_team_id = daarion_city_id, child_team_id = energyunion_id, relation_type = "platform")` + +3. **Blueprint EnergyUnion**: + + * агенти: + + * Energy Sites & BioMiner Agent (облік енергії, біомодулі), + * AI Power Agent (1T обчислення), + * kWt / 1T / carbon+ access-keys інтегровані в Governance & Access (як символьні ключі ресурсу, не як фінансові інструменти). + +4. **Bridges / adapters**: + + * Connector до energyunion.io / EnergyUnion.AI API: + + * energy production → knowledge/events, + * access tokens → capability keys у microDAO, + * DAO-логіка → DAO Agent (коли знадобиться). + +--- + +## 5. City-level Co-Memory: загальні знання міста + +DAARION.city має власний **Co-Memory**, побудований на основі модуля 17. + +### 5.1. City Knowledge Spaces + +Приклади city-spaces: + +* `City.Ecology` +* `City.Energy` +* `City.Food` +* `City.Governance` + +Кожна платформа-microDAO може: + +* публікувати обрані факти/документи в City Co-Memory: + + * `publish_to_city_memory(team_id, space_id, fact_id/doc_id)` + +* читати загальноміський контекст: + + * `get_city_knowledge(space_id, query)`. + +### 5.2. Політики відкритості + +Локальний Governance Agent платформи: + +* визначає, які дані: + + * залишаються тільки в локальному Co-Memory, + * можуть підніматися на рівень міста. + +--- + +## 6. City Bridges: обмін подіями між DAARION.city і microDAO + +### 6.1. Формат `city_event` + +Спільний формат подій: + +```ts +city_event: { + id: string; + source_team_id: string; // хто ініціював (microDAO або платформа) + target_team_id?: string; // куди адресовано (optionally) + type: string; // "announcement", "project_update", "energy_event", "market_update", ... + payload: Json; + ts: string; +} +``` + +### 6.2. City Bridges Agent + +Агент з `team_id = DAARION.city`: + +* приймає `city_event` від microDAO, +* ретранслює (broadcast / специфічним платформам), +* взаємодіє з Attention Agent на міському рівні. + +--- + +## 7. Governance: трирівнева модель правил + +1. **City Governance (DAARION.city)**: + + * загальні принципи, + * базові етичні стандарти, + * міські ритуали узгодження. + +2. **Platform Governance** (GreenFood, EnergyUnion): + + * правила конкретної платформи, + * локальні символічні ключі доступу. + +3. **Local microDAO Governance**: + + * правила конкретної спільноти/групи. + +DAO Agent і Wallet Agent можуть зʼявитися пізніше на міському шарі; наразі достатньо моделювати правила як політики доступу й ритуали узгодження без необхідної on-chain реалізації. + +--- + +## 8. UX-рівень: як користувач це відчуває + +1. Користувач реєструється в DAARION.city → отримує: + + * міське громадянство, + * city-profile. + +2. У міському інтерфейсі: + + * секція "Платформи": + + * GreenFood, EnergyUnion, інші платформи → всі це microDAO типу `platform`; + + * секція "Мої microDAO": + + * приватні/ком'юніті DAO. + +3. Клік по платформі (GreenFood / EnergyUnion): + + * відкривається Agent Hub цієї платформи (як microDAO), + * зі своїми агентами, каналами, проєктами. + +4. Зі свого приватного microDAO користувач може: + + * "Підключитися до платформи GreenFood": + + * створюється запис у `city_links` + налаштовуються Bridges + Governance/Access. + +--- + +## 9. Задачі для Cursor (Implementation Plan) + +### 9.1. Базова інтеграція DAARION.city як microDAO + +1. Додати поле `type` у `teams`: + + * `"city" | "platform" | "community" | "guild" | "lab" | "personal"`. + +2. Створити запис для DAARION.city: + + * `type = "city"`, `slug = "daarion"`. + +3. Створити таблицю `city_links`: + + * parent/child team, relation_type. + +### 9.2. Реєстр мешканців + +1. Створити таблиці: + + * `citizenships` (user ↔ city), + * `memberships` (user ↔ team). + +2. Додати city-profile в UI: + + * список платформ-microDAO, + * список власних microDAO. + +### 9.3. Інтеграція платформ GreenFood та EnergyUnion + +1. Створити `team` для GreenFood та EnergyUnion з `type="platform"`. + +2. Створити `city_links` із `parent_team_id = daarion_city_id`. + +3. Додати базові Agent Hub / Agent Cards для цих платформ. + +4. Створити Bridges stubs: + + * `greenfood_connector_agent`, + * `energyunion_connector_agent`, + + щоб пізніше інтегрувати їхні API (поки достатньо каркасу). + +### 9.4. City Co-Memory та City Bridges + +1. Створити city-level Knowledge Space (`City.Global`). + +2. Додати API: + + * `POST /city/knowledge/publish`, + * `POST /city/events`. + +3. Реалізувати City Bridges Agent: + + * мінімально — логування `city_event`ів. + +--- + +## 10. Інструкція для Cursor + +```text +Use DAARION_city_integration.md together with: + +- 12_agent_runtime_core.md +- 14_messenger_agent_module.md +- 15_projects_agent_module.md +- 17_comemory_knowledge_space.md +- 18_governance_access_agent.md +- 20_integrations_bridges_agent.md +- 22_operator_modes_and_system_agents.md +- 23_domains_wallet_dao_deepdive.md +- 10_agent_ui_system.md +- 05_coding_standards.md + +Goal: + +Unify DAARION.city and all platforms as microDAO instances, with DAARION.city as a "city" type superDAO and GreenFood / EnergyUnion as "platform" type microDAO. + +Implement in stages: + +1) Team types + city_links hierarchy. + +2) Citizen registry (citizenships, memberships). + +3) DAARION.city as city-level microDAO with its own Agent Hub. + +4) GreenFood and EnergyUnion as platform-type microDAO. + +5) City Co-Memory and City Bridges minimal skeletons. + +For each step: + +- list changed files, +- show diff, +- provide a short summary. +``` + +--- + +**Готово.** +Це **повна архітектура інтеграції DAARION.city з microDAO**, включаючи конкретні кроки перетворення GreenFood та EnergyUnion. diff --git a/docs/daarion/platforms-catalog.md b/docs/daarion/platforms-catalog.md new file mode 100644 index 00000000..c10b06a7 --- /dev/null +++ b/docs/daarion/platforms-catalog.md @@ -0,0 +1,397 @@ +# DAARION.city Platforms Catalog (MicroDAO) + +Каталог платформ екосистеми DAARION.city + +Цей документ містить каталог платформ екосистеми **DAARION.city**, які інтегруються з microdao, DAGI та Gift-економікою міста: + +- опис домену кожної платформи; +- основні агентські модулі; +- ключі доступу (access keys + capabilities); +- Embassy-інтеграція; +- мінімальні флоу для MVP. + +Це **живий документ** — при додаванні нових платформ/районів додаються нові записи. + +--- + +## 1. Мета документа + +Каталог платформ екосистеми **DAARION.city**, які інтегруються з microdao, DAGI та Gift-економікою міста: + +- опис домену кожної платформи; +- основні агентські модулі; +- ключі доступу (access keys + capabilities); +- Embassy-інтеграція; +- мінімальні флоу для MVP. + +Це **живий документ** — при додаванні нових платформ/районів додаються нові записи. + +--- + +## 2. Структура запису про платформу + +Для кожної платформи описуємо: + +- `code` — короткий код (латиницею); +- `name` — назва; +- `domain` — предметна область; +- `owner` — хто курує (team/microDAO); +- `status` — idea / design / MVP / pilot / prod; +- основні **агентські ролі**; +- типи **access keys** і capabilities; +- Embassy-флоу (якщо є RWA/енергія/зовнішні мережі). + +--- + +## 3. Перелік платформ + +1. **DAARION Core** +2. **DAARWIZZ** +3. **GREENFOOD** +4. **Energy Union** +5. **Water Union** +6. **Essence Stream** + +(інші додаються в наступних версіях: Atlas, DAARWIZZ verticals тощо). + +--- + +## 4. DAARION Core + +- `code`: `daarion_core` +- `name`: DAARION Core / Місто Дарів +- `domain`: ядро міста, Second Me, резидентство, токеноміка DAAR/DAARION, MJD. +- `owner`: DAARION DAO Core Team +- `status`: pilot → prod + +### 4.1 Агентські модулі + +- **Second Me Agent** — персональний цифровий двійник резидента. +- **Citizenship Agent** — керує резидентством, рівнями доступу, DAARION-статусом. +- **Gift Fabric Agent** — відстежує акти взаємодії й відгук міста (MJD). +- **Governance Agent** — DAO-процеси, пропозиції, голосування, політики. + +### 4.2 Access keys & capabilities + +Приклади capability-груп: + +- `citizenship.status.view` +- `citizenship.level.upgrade` +- `gift.act.register` +- `governance.proposal.create` +- `governance.vote.cast` +- `governance.policy.manage` (лише для Guardian/Owner/DAO-агентів) + +Embassy-ключі DAARION Core обмежені: + +- `embassy.intent.read` +- `embassy.aggregate.metrics` + +--- + +## 5. DAARWIZZ + +- `code`: `daarwizz` +- `name`: DAARWIZZ — маршрутизатор агентів / планувальник Swarm-OS +- `domain`: оркестрація DAGI, роутинг запитів, multi-agent сценарії. +- `owner`: DAARION R&D Lab +- `status`: MVP / pilot + +### 5.1 Агентські модулі + +- **Router Agent** — розподіляє запити між моделями та агентами. +- **Planner Agent** — декомпозує задачі, запускає ланцюжки інструментів. +- **Observer/Telemetry Agent** — відстежує якість, латентність, бюджет. + +### 5.2 Access keys & capabilities + +- `router.invoke` +- `router.plan.run` +- `router.tool.call` +- `telemetry.events.write` +- `telemetry.events.read:aggregate` + +Користувацькі microDAO отримують DAARWIZZ-keys: + +- або через Wallet Agent (оплата DAAR / 1T); +- або через план Platformium. + +--- + +## 6. GREENFOOD + +- `code`: `greenfood` +- `name`: GREENFOOD — AI-ERP для крафтових виробників та кооперативів +- `domain`: склади, партії, логістика, кооперативні ланцюги постачання. +- `owner`: GREENFOOD microDAO +- `status`: design / MVP + +### 6.1 Агентські модулі + +- **Warehouse Agent** — облік партій/залишків. +- **Logistics Agent** — маршрути та хаби. +- **Accounting Agent** — автоматичні нарахування/розподіл по кооперативу. +- **Sales Agent** — інтеграція з маркетплейсами. +- **Community Coordinator Agent** — координація між учасниками спільноти. + +### 6.2 Access keys & capabilities + +Ключі типу: + +- `platform.greenfood.inventory.view/update` +- `platform.greenfood.shipment.create` +- `platform.greenfood.coop.balance.view` +- `platform.greenfood.member.register` + +Для інтеграції з microdao: + +- public API-ключі для: + - синхронізації задач Projects (`projects.task.sync`); + - Co-Memory (звіти, накладні); +- Embassy Key для RWA: + - `rwa.claim` (сертифікати продуктів); + - `rwa.stock.update` (запаси на складах). + +--- + +## 7. Energy Union + +- `code`: `energy_union` +- `name`: Energy Union — енергетична платформа з токенізованими активами +- `domain`: енергетичні RWA, KWT/1T виплати, енергетичний бартер. +- `owner`: Energy Union microDAO / партнерські енергокомпанії +- `status`: pilot + +### 7.1 Агентські модулі + +- **Metering Agent** — читає лічильники генерації/споживання. +- **Oracle Agent** — агрегує дані, формує виплати KWT/1T. +- **Facility Agent** — агент об'єкта (сонячна станція, дата-центр). +- **Energy Market Agent** — узгоджує акти енергетичного дарообміну. + +### 7.2 Access keys & capabilities + +- `energy.asset.read` +- `energy.meter.read` +- `energy.meter.update` (лише для trusted oracles) +- `energy.payout.compute` +- `wallet.payout.view/claim` + +Embassy-ключі: + +- `embassy.energy.update` +- `embassy.rwa.claim` (сертифікати енергетичних часток). + +--- + +## 8. Water Union + +- `code`: `water_union` +- `name`: Water Union — платформа для управління водними ресурсами +- `domain`: моніторинг води, RWA на основі водних активів/інфраструктури. +- `owner`: Water Union microDAO / місцеві громади +- `status`: idea / early design + +### 8.1 Агентські модулі + +- **Sensor Agent** — збір даних з сенсорів (якість/об'єм води). +- **Infrastructure Agent** — стан насосів, резервуарів. +- **Community Water Agent** — координація доступу громад, планування ремонтів. +- **Water RWA Agent** — сертифікати дару на водні ініціативи. + +### 8.2 Access keys & capabilities + +- `water.sensor.read` +- `water.sensor.update` +- `water.infrastructure.view` +- `rwa.water.claim` + +Embassy: + +- інтеграція з місцевими дата-центрами/IoT-шлюзами; +- прев'язка водних RWA до DAAR/DAARION через Gift Fabric. + +--- + +## 9. Essence Stream + +- `code`: `essence_stream` +- `name`: Essence Stream — платформа для культурних/освітніх ініціатив +- `domain`: курси, події, контент-стріми, творчі квести. +- `owner`: Essence Stream microDAO / культурні куратори +- `status`: idea / design + +### 9.1 Агентські модулі + +- **Curator Agent** — формує програми, добирає контент. +- **Event Agent** — події, квитки (як сертифікати дару). +- **Mentor Agent** — персоналізовані навчальні траєкторії. +- **Quest Agent** — квести/ігрові сценарії в DAARION.city. + +### 9.2 Access keys & capabilities + +- `essence.event.publish` +- `essence.event.register` +- `essence.course.view` +- `essence.quest.progress.update` + +Embassy: + +- RWA-сертифікати на участь у подіях (офлайн/онлайн); +- взаємодія з Gift Fabric для Міського Джерела Дарів. + +--- + +## 10. Зв'язок платформ з microdao + +### 10.1 Common pattern + +Кожна платформа: + +1. Має **свій microDAO** (team/ком'юніті) у microdao-месенджері. +2. Має набір **public channel(s)** для публічних оголошень/стрімів. +3. Використовує: + - Projects (проекти/ланцюги постачання/ініціативи), + - Co-Memory (документи, договори, технічні описи), + - приватних агентів (Router, Domain-агенти). + +### 10.2 Типи інтеграцій + +- **Embedded microdao**: платформа має вкладку «Community/Chat», що відкриває microdao-інтерфейс її microDAO. +- **API integration**: платформа викликає microdao API (`/projects`, `/tasks`, `/wallet`, `/governance`) з власними access keys. +- **Embassy**: для RWA/енергетики/сертифікатів дару використовується Embassy Module. + +--- + +## 10. Подальший розвиток каталогу + +Наступні версії документа: + +- додаємо нові платформи (Atlas, DAARWIZZ вертикалі, інші city-райони); +- деталізуємо capability-матриці (по аналогії з RBAC-таблицями); +- додаємо mapping до конкретних onchain-контрактів (RWA, EnergyNFT, DAAR/DAARION). + +--- + +## 11. Мапінг платформ на Data Model (таблиці) + +1. Усі платформи (DAARION Core, DAARWIZZ, GREENFOOD, Energy Union, Water Union, Essence Stream): + +- представлені як `teams`: + +```sql +create table teams ( + id text primary key, -- t_... + name text not null, + slug text unique not null, + mode text not null check (mode in ('public','confidential')), + created_at timestamptz not null default now() +); +``` + +- учасники платформ → `team_members`: + - роль (`Owner`, `Guardian`, `Member`); + - `viewer_type` (`reader`, `commenter`, `contributor`). + +2. DAARION Core: + +- працює поверх: + - `users`, `teams`, `team_members`, + - `channels`, `messages`, `followups`, + - `projects`, `tasks`, `docs`, `meetings`, + - `wallets`, `staking_ringk`, `payouts`, + - `proposals` (governance). + +3. GREENFOOD: + +- свій microDAO → одна або кілька сутностей `teams`; +- бізнес-процеси відображаються як: + - `projects` (кооперативні програми, постачання); + - `tasks` (відвантаження, контроль партій); + - RWA-складські залишки → через `rwa_inventory` (із подією `rwa.inventory.updated`). + +4. Energy Union: + +- об'єкти енергетики — як `projects`/`tasks` + RWA-записи в `rwa_inventory`; +- зв'язок із виплатами — через `staking_ringk` та `payouts`. + +5. Water Union / Essence Stream: + +- Water Union: сенсори/інфраструктура агрегуються як задачі/проєкти, а водні активи — RWA-записи; +- Essence Stream: події/курси — `projects` + `meetings`/`docs`, участь резидентів потрапляє в Gift Fabric через події. + +--- + +## 12. Мапінг платформ на Event Catalog (topics) + +1. DAARION Core: + +- використовує базові topics з `topic.enum`: + - `"chat.message.created"`, `"chat.message.edited"`, `"chat.message.deleted"` + - `"followup.created"`, `"followup.updated"` + - `"project.created"`, `"task.created"`, `"task.updated"` + - `"agent.run.started"`, `"agent.run.completed"` + - `"staking.locked"`, `"payout.generated"` + - `"rwa.inventory.updated"` + - `"governance.proposal.created"`, `"vote.cast"` + - `"audit.event"` + +2. GREENFOOD: + +- доменні події інвентарю/замовлень мапляться на: + - `"rwa.inventory.updated"` (оновлення складів/партій); + - `"project.created"` / `"task.created"` для логістичних ланцюжків. + +3. Energy Union: + +- енергетичні вимірювання та оракули: + - `"oracle.reading.published"` — агреговані дані з лічильників; + - далі → `"staking.locked"` / `"payout.generated"` для KWT/1T. + +4. Water Union: + +- якість/об'єм води → `"oracle.reading.published"` з типом `water`; +- видані водні сертифікати → `"rwa.inventory.updated"`; +- надалі можуть генерувати `"payout.generated"`, якщо є пов'язаний токенізований потік. + +5. Essence Stream: + +- участь у подіях/квестах платформи підписується як: + - `"reward.issued"` (Gift Fabric), + - `"audit.event"` для важливих соціальних/освітніх актів. + +--- + +## 13. Завдання для Cursor + +```text +You are a senior full-stack engineer. Implement platform integration patterns using: +- DAARION_city_platforms_catalog.md +- 24_access_keys_capabilities_system.md +- DAARION_city_integration.md +- 05_coding_standards.md + +Tasks: +1) Create platform registry in database (platforms table). +2) Implement platform-specific capability bundles. +3) Create Embassy Module integration for RWA platforms (Energy Union, GREENFOOD). +4) Add platform switcher UI in microDAO interface. +5) Implement platform-specific agent modules (stub for MVP). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 14. Результат + +Після впровадження каталогу: + +- чітке розуміння всіх платформ екосистеми DAARION.city; +- стандартизовані патерни інтеграції; +- готовність до додавання нових платформ; +- інтеграція з Access Keys & Capabilities System. + diff --git a/docs/daarion/tokenomics-city.md b/docs/daarion/tokenomics-city.md new file mode 100644 index 00000000..c5dcdedf --- /dev/null +++ b/docs/daarion/tokenomics-city.md @@ -0,0 +1,393 @@ +--- +title: City Tokenomics +version: 1.0.0 +status: canonical +last_updated: 2024-11-14 +--- + +> **Цей документ є актуальною версією токеноміки міста.** +> Усі попередні документи з токеноміки вважаються застарілими. + +# City Tokenomics — DAARION.city (Integration-Ready) + +**Цей документ є обов'язковим для додавання у репозиторій під час інтеграції MicroDAO у DAARION.city.** + +DAARION.city — це **перше MicroDAO у мережі** (A1-рівень), що очолюється системним агентом **DAARWIZZ**. Усі інші компоненти міської екосистеми — це наступні рівні MicroDAO-структури. + +--- + +## 1. Загальний огляд токеноміки міста + +Місто працює на **двоєдиній моделі токенів**: + +- **DAAR** — утиліті-токен (оплата сервісів, платформи, транзакції) +- **DAARION** — civic / identity токен (громадянство, доступ, статус) + +Ця пара створює повноцінну економіку доступів та взаємодій. + +--- + +## 2. DAAR — Utility Token + +### Використання + +- оплата товарів та послуг +- взаємодія з міськими платформами (GreenFood, EnergyUnion, WaterUnion тощо) +- оплата агентів +- оплата створення та роботи microDAO +- внутрішні транзакції між користувачами та DAO + +**DAAR — енергія міської економіки.** + +### Tokenomics + +- динамічний випуск +- джерело: DAARsales (USDT/POL → DAAR) +- комісія на транзакції DAAR: **0.5% → DAO Share Pool** +- APR: **20%** (в стейкінгу) + +--- + +## 3. DAARION — Civic Token / Identity Token + +### Використання + +- підтвердження статусу громадянина міста +- доступ до глибинних рівнів інфраструктури +- ліцензійний ключ для створення платформ +- доступ до advanced API та інтеграцій + +**DAARION — статус, права і розширені можливості.** + +### Tokenomics + +- стартова емісія: **500 DAARION** +- дефляція: **5% burn** при продажу +- APR: **4% + частка від комісій DAAR** +- джерело: DAARIONsales (100 DAAR → 1 DAARION) + +--- + +## 4. Рівні доступу за DAAR та DAARION + +### 4.1 Звичайні користувачі / Покупці + +- доступ до платформ: **лише наявність DAAR** +- DAARION не потрібен + +### 4.2 Постачальники / Вендори + +- доступ до роботи на платформах: **0.01 DAARION у стейкінгу** + +### 4.3 Створення платформ + +- право створити платформу: **1 DAARION у стейкінгу** + +### 4.4 Створення MicroDAO + +- доступ: **1 DAAR або 0.01 DAARION** + +--- + +## 4.5 MicroDAO Tokens (Local Layer) + +Кожне microDAO має власні три токени, емітовані DAOFactory: + +| Token | Function | Activation | +| -------- | ---------------------------------------------- | ---------------- | +| **GOV** | governance / voting key inside DAO | cost: **1 DAAR** | +| **UTIL** | внутрішня економіка DAO (операції, винагороди) | cost: **1 DAAR** | +| **REP** | репутаційний токен (невзаємозамінний) | cost: **1 DAAR** | + +**Emission model:** +- DAO може емітувати будь-яку кількість, згідно з власною політикою +- DAOFactory перевіряє баланс користувача (1 DAAR або 0.01 DAARION) +- Емісія gas-free (off-chain), періодична синхронізація on-chain + +**Economic Flow Inside MicroDAO:** +```text +DAAR → eMINT GOV/UTIL/REP → DAO Operations → UTIL Rewards → TokenBridge → DAAR +``` + +--- + +## 5. Ієрархія MicroDAO у DAARION.city + +**ДАЖЕСТВА МІСТА — ЦЕ ДЕРЕВО MICRODAO.** + +### **A1 — DAARION.city (перше MicroDAO)** + +- кореневе DAO міста +- очолюється агентом **DAARWIZZ** +- керує реєстрами, платформами, правами доступу + +### **A2 — Міські платформи (другий рівень)** + +Платформи є MicroDAO другого порядку. + +Поточний список: + +- **Helion** — енергетика +- **GreenFood ERP** — агро/харчові продукти +- **Soul** — соціальна система +- **Dario** — міські сервіси +- **Nutra** — здоровʼя і нутриція +- **WaterAGI** — вода та очищення + +Кожна платформа має власних агентів. + +### **A3 — Публічні MicroDAO (третій рівень)** + +- не підпорядковуються платформам +- доступні для всіх резидентів +- можуть взаємодіяти з A1 та A2 через DAAR + +### **A4/F4 — Приватні MicroDAO (четвертий рівень)** + +- повна автономія +- не мають підлеглості іншим DAO +- доступні лише за запрошенням + +--- + +## 6. Логіка доступів на основі DAARION (Framework) + +**Більше DAARION = більше можливостей**, зокрема: + +- доступ до інституційних функцій +- доступ до створення платформ +- доступ до глибоких API +- доступ до керування DAO високого рівня +- більший пріоритет у DAGI + +Це ядро формує модель: **Civic Token → Access Tier → City Expansion**. + +--- + +## 7. Патерн розвитку токеноміки + +Система спроектована так, що нові рівні доступу та права можуть додаватися з розвитком: + +- запуск нових платформ +- нові типи агентів +- DAO-функції наступних фаз +- нові MetaDAO рівні + +Токен DAARION — універсальний ключ для майбутньої інфраструктурної експансії. + +--- + +## 8. Використання DAAR і DAARION у інтеграції MicroDAO + +При підключенні MicroDAO до DAARION.city ця сторінка повинна бути додана у розділ: + +```text +docs/tokenomics/city-tokenomics.md +``` + +MicroDAO використовує ці правила для: + +- валідації доступу користувачів +- роботи DAOFactory +- роботи агентів DAARWIZZ +- контролю доступу до платформ +- ліцензування сервісів + +DAARION.city — це **кореневе MicroDAO (A1)**, а вся міська екосистема — це дерево MicroDAO. + +--- + +## 9. Інтеграція з іншими документами + +Цей документ доповнює: + +- `DAARION_city_integration.md` — архітектура інтеграції +- `50_daarion_city_website_integration.md` — інтеграція з сайтом +- `32_policy_service_PDP_design.md` — PDP token-gating +- `49_wallet_rwa_payouts_claims.md` — Wallet Service + +> **Примітка:** Попередній документ `tokenomics/README.md` перенесено в `docs/_archive/tokenomics_legacy_v0.md`. Вся актуальна інформація об'єднана в цьому канонічному документі. + +--- + +## 10. Завдання для Cursor + +```text +You are a senior blockchain/full-stack engineer. Implement City Tokenomics using: +- docs/tokenomics/city-tokenomics.md (⭐ CANONICAL) +- 32_policy_service_PDP_design.md +- 49_wallet_rwa_payouts_claims.md + +Tasks: +1) Implement access tier validation (DAAR ≥ 1.00 or DAARION ≥ 0.01 for MicroDAO creation). +2) Implement platform creation access (DAARION ≥ 1.00 staked). +3) Implement vendor access (DAARION ≥ 0.01 staked). +4) Implement DAARION.city as A1-level MicroDAO (root DAO). +5) Implement platform hierarchy (A2-level: Helion, GreenFood, Soul, Dario, Nutra, WaterAGI). +6) Implement public MicroDAO (A3-level) and private MicroDAO (A4-level) access rules. +7) Integrate DAARWIZZ agent as system agent for A1-level. +8) Add DAAR/DAARION balance checks in PDP for all access levels. +9) Implement tier-based access logic (more DAARION = more capabilities). +10) Add platform licensing system (1 DAARION staked = platform creation right). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 11. Підсумок + +- **DAAR** = універсальна енергія економіки +- **DAARION** = статус, рівні доступу, громадянство +- платформи належать рівню A2 +- публічні MicroDAO — A3 +- приватні MicroDAO — A4 +- DAARION.city — перше, головне DAO (A1), центр усієї мережі + +Це формує стійку багаторівневу архітектуру міста та екосистеми MicroDAO. + +--- + +## 12. Fees & Costs (MicroDAO Economics) + +### City Fees (denominated in DAAR) + +| Action | Cost | +| ------------------------------- | ------------- | +| Створення microDAO | **1 DAAR** | +| Емісія GOV | **1 DAAR** | +| Емісія UTIL | **1 DAAR** | +| Емісія REP | **1 DAAR** | +| Підключення агента DAGI | **0.25 DAAR** | +| Реєстрація DAO у каталозі міста | **0.05 DAAR** | + +**90% DAO / 10% City Rule:** Діє для DePIN-DAO та DAO, що працюють з постійною DAGI-активністю. + +--- + +## 13. Staking & Rewards + +### DAAR Staking (APR: 20%) +- Rewards → DAAR +- Смартконтракт: `APRStaking` + +### DAARION Staking (APR: 4% + revenue share) +- Rewards → DAAR +- Частка від DAAR-комісій (0.5%) розподіляється пропорційно до стейку DAARION +- Смартконтракт: `DAARDistributor` + +--- + +## 14. Token Bridges & Onboarding + +### Flow +```text +USDT/POL → DAAR → DAARION → DAO → DAGI → Rewards in DAAR +``` + +### Components + +| Component | Function | +| ----------------- | ------------------------------ | +| **DAARsales** | Купівля DAAR за USDT/POL | +| **DAARIONsales** | 100 DAAR → 1 DAARION | +| **DAOFactory** | Створення MicroDAO | +| **TokenBridge** | UTIL ↔ DAAR обмін | +| **DAGI Registry** | Реєстрація DAO, агентів, знань | + +### Primary Access Flow (Onboarding) + +1. **Balance Check** — Wallet Agent перевіряє: ≥ 1 DAAR **або** ≥ 0.01 DAARION +2. **Eligibility** — `eligible_for_MicroDAO = true` +3. **DAO Creation (DAOFactory)** — списується 1 DAAR, DAO отримує унікальний `dao_id` +4. **Token Activation** — користувач може емітувати GOV / UTIL / REP (1 DAAR за кожен тип) +5. **DAGI Sync** — DAO реєструється у DAGI Registry + +--- + +## 15. Integration Points (Architecture) + +### Wallet Service +- баланси DAAR / DAARION +- fee accounting (0.5%) +- DAOFactory calls +- staking +- token exchange + +### PDP (Access Control) +- наявність токенів +- права доступу до DAO +- gas-free стани +- DAO governance rules + +### Agents +**Можуть:** +- працювати з UTIL +- виконувати дії DAO +- розподіляти REP +- взаємодіяти з DAGI Registry + +**Не можуть:** +- змінювати баланси DAAR/DAARION +- створювати DAO без користувача +- змінювати тарифні плани + +### DAGI Registry +- DAO metadata +- Agent slots +- Knowledge mining rewards +- Off-chain/on-chain settlement + +--- + +## 16. Security Rules + +- тільки Owner може виконувати DAOFactory +- DAAR/DAARION операції виконуються он-чейн +- UTIL/GOV/REP — off-chain з періодичною валідацією +- burn 5% DAARION при продажі — обов'язковий +- reentrancy guard +- мінімальна кількість GOV для голосування встановлюється DAO + +--- + +## 17. MVP Scope (Required for Launch) + +### Must-have +- DAAR / DAARION баланс-чек +- DAOFactory (1 DAAR → create) +- eMINT GOV / UTIL / REP +- TokenBridge (UTIL ↔ DAAR) +- DAARsales, DAARIONsales +- Basic staking (DAAR, DAARION) +- PDP token-gating +- Wallet v1 + +### Optional MVP+ +- Knowledge Mining Rewards +- REP reputation logic +- Multi-DAO bridges + +--- + +## 18. Changelog + +### v1.0.0 — 2024-11-14 +- Початкова версія токеноміки міста +- Додано DAAR та DAARION токени +- Додано ієрархію MicroDAO (A1-A4) +- Додано рівні доступу +- Додано GOV/UTIL/REP токени для microDAO +- Додано DAOFactory та TokenBridge +- Додано staking та rewards +- Додано security rules + +--- + +**Версія:** 1.0.0 +**Останнє оновлення:** 2024-11-14 +*Документ готовий до інтеграції у Cursor, GitHub або будь-який інший проект.* + diff --git a/docs/integration-daarion.md b/docs/integration-daarion.md new file mode 100644 index 00000000..54a60f27 --- /dev/null +++ b/docs/integration-daarion.md @@ -0,0 +1,358 @@ +# Integration Guide: MicroDAO → DAARION.city + +*Консолідований документ для інтеграції MicroDAO у офіційний сайт DAARION.city* + +--- + +## 1. Quick Start + +Цей документ об'єднує ключову інформацію для інтеграції MicroDAO у DAARION.city. Він посилається на детальні специфікації в `docs/cursor/` та `docs/tokenomics/`. + +### Ключові документи + +- `docs/cursor/50_daarion_city_website_integration.md` — детальна інтеграція з сайтом +- `docs/cursor/DAARION_city_integration.md` — архітектура інтеграції +- `docs/tokenomics/city-tokenomics.md` ⭐ — канонічна токеноміка міста (v1.0.0) + > **Примітка:** Це єдиний актуальний документ з токеноміки. Попередній `tokenomics/README.md` перенесено в `docs/_archive/tokenomics_legacy_v0.md`. + +--- + +## 2. DAARION.city as First MicroDAO (A1-Level) + +### 2.1 Setup + +DAARION.city має бути створений як перше MicroDAO у системі: + +```sql +-- Створення DAARION.city team +INSERT INTO teams ( + id, + name, + slug, + type, + mode, + description, + created_at +) VALUES ( + 'daarion-city', + 'DAARION.city', + 'daarion', + 'city', -- A1-level + 'public', + 'Офіційна спільнота міста DAARION', + NOW() +); + +-- Створення публічного каналу +INSERT INTO channels ( + id, + team_id, + title, + slug, + type, + is_public, + created_at +) VALUES ( + 'daarion-city-general', + 'daarion-city', + 'Загальний канал міста', + 'general', + 'public', + true, + NOW() +); + +-- Створення міського агента DAARWIZZ +INSERT INTO agents ( + id, + team_id, + name, + role, + system_prompt, + memory_scope, + created_at +) VALUES ( + 'daarion-city-agent', + 'daarion-city', + 'DAARWIZZ', + 'team_assistant', + 'Ти — міський асистент DAARION.city. Допомагаєш мешканцям та гостям міста.', + 'team', + NOW() +); +``` + +### 2.2 Hierarchy + +``` +A1: DAARION.city (root DAO, DAARWIZZ agent) + ├── A2: Міські платформи + │ ├── Helion (енергетика) + │ ├── GreenFood ERP (агро/харчові продукти) + │ ├── Soul (соціальна система) + │ ├── Dario (міські сервіси) + │ ├── Nutra (здоровʼя і нутриція) + │ └── WaterAGI (вода та очищення) + ├── A3: Публічні MicroDAO + └── A4: Приватні MicroDAO +``` + +--- + +## 3. Tokenomics Integration + +### 3.1 Access Requirements + +| Action | DAAR | DAARION | +|--------|------|---------| +| Доступ до платформ | ≥ 0 | - | +| Робота на платформах (вендори) | - | ≥ 0.01 staked | +| Створення платформи | - | ≥ 1.00 staked | +| Створення MicroDAO | ≥ 1.00 | ≥ 0.01 | + +### 3.2 Token Flow + +```text +USDT/POL → DAAR → DAARION → DAO → DAGI → Rewards in DAAR +``` + +### 3.3 Integration Points + +- **Wallet Service** — баланси DAAR/DAARION, staking, fees +- **PDP** — token-gating перевірки +- **DAOFactory** — створення MicroDAO (1 DAAR або 0.01 DAARION) +- **TokenBridge** — обмін UTIL ↔ DAAR + +--- + +## 4. Public Channel API + +### 4.1 Endpoints + +```http +# Отримати інформацію про публічний канал +GET /api/v1/channels/{slug}/public + +# Отримати повідомлення +GET /api/v1/channels/{slug}/public/messages?limit=50&before={message_id} + +# Надіслати повідомлення (authenticated) +POST /api/v1/channels/{slug}/public/messages +Authorization: Bearer {token} + +# Приєднатися до каналу +POST /api/v1/channels/{slug}/public/join +``` + +### 4.2 Authentication Flow + +1. **Guest View** — read-only доступ до повідомлень +2. **Join Modal** — форма: Email, Ім'я, Тип участі (Member/Visitor) +3. **Authenticated View** — повний доступ до каналу + +--- + +## 5. Website Integration + +### 5.1 Embedded Widget + +```tsx + +``` + +### 5.2 Next.js Page Example + +```tsx +// pages/channel/[slug].tsx +import { MicroDAOChannelEmbed } from '@/components/MicroDAOChannelEmbed'; +import Head from 'next/head'; + +export default function ChannelPage({ channelSlug }) { + return ( + <> + + Загальний канал міста DAARION.city + + + +
+ +
+ + ); +} +``` + +--- + +## 6. Security & Privacy + +### 6.1 CORS Configuration + +```typescript +const corsOptions = { + origin: [ + 'https://daarion.city', + 'https://www.daarion.city', + 'http://localhost:3000' // для розробки + ], + credentials: true, + methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'], + allowedHeaders: ['Content-Type', 'Authorization'] +}; +``` + +### 6.2 Rate Limiting + +- **Guest (read-only):** 100 requests/minute +- **Authenticated (write):** 30 messages/minute +- **Join requests:** 5 requests/hour per IP + +### 6.3 Content Moderation + +- Автоматична модерація через Agent +- Фільтрація спаму +- Блокування токсичного контенту +- Можливість скарг від користувачів + +--- + +## 7. Implementation Checklist + +### Backend + +- [ ] Створити DAARION.city team у БД (type='city', slug='daarion') +- [ ] Створити публічний канал (slug='general') +- [ ] Створити міського агента DAARWIZZ +- [ ] Реалізувати Public Channel API endpoints +- [ ] Налаштувати CORS для `daarion.city` +- [ ] Додати rate limiting для публічного каналу +- [ ] Інтегрувати token-gating (PDP перевірки DAAR/DAARION) + +### Frontend + +- [ ] Створити React компонент `MicroDAOChannelEmbed` +- [ ] Інтегрувати з API +- [ ] Додати authentication flow +- [ ] Додати real-time оновлення (WebSocket/SSE) +- [ ] Додати SEO метадані (Open Graph, Twitter Cards) +- [ ] Додати analytics tracking + +### Integration + +- [ ] Додати компонент на сторінку `daarion.city/channel/general` +- [ ] Налаштувати SEO метадані +- [ ] Додати analytics tracking +- [ ] Тестування на production + +--- + +## 8. Key Integration Points + +### 8.1 Wallet Service + +- Баланси DAAR / DAARION +- Fee accounting (0.5%) +- DAOFactory calls +- Staking (DAAR: 20% APR, DAARION: 4% + revenue share) +- Token exchange + +### 8.2 PDP (Policy Decision Point) + +- Token-gating перевірки +- Access control на основі DAAR/DAARION +- Capability checks +- Team-level ACL + +### 8.3 Agents + +- DAARWIZZ як системний агент A1-рівня +- Платформенні агенти (A2-рівень) +- Team Assistant агенти (A3-A4 рівні) + +### 8.4 DAGI Registry + +- DAO registration +- Agent slots +- Knowledge mining rewards +- Off-chain/on-chain settlement + +--- + +## 9. Testing + +### 9.1 Backend Tests + +- [ ] Публічний канал створено для DAARION.city +- [ ] API endpoints повертають коректні дані +- [ ] CORS налаштовано правильно +- [ ] Rate limiting працює +- [ ] Authentication flow працює +- [ ] Token-gating перевірки працюють + +### 9.2 Frontend Tests + +- [ ] Widget завантажується на сайті +- [ ] Повідомлення відображаються коректно +- [ ] Join flow працює +- [ ] Real-time оновлення працюють +- [ ] Responsive design на мобільних + +### 9.3 Integration Tests + +- [ ] SEO метадані відображаються +- [ ] Analytics tracking працює +- [ ] Content moderation працює +- [ ] Error handling коректний + +--- + +## 10. References + +### Core Documents + +- `docs/cursor/50_daarion_city_website_integration.md` — детальна інтеграція з сайтом +- `docs/cursor/DAARION_city_integration.md` — архітектура інтеграції +- `docs/cursor/32_policy_service_PDP_design.md` — PDP design +- `docs/cursor/24_access_keys_capabilities_system.md` — Access Keys & Capabilities +- `docs/cursor/49_wallet_rwa_payouts_claims.md` — Wallet Service + +### Tokenomics + +- `docs/tokenomics/city-tokenomics.md` ⭐ — канонічна токеноміка міста (v1.0.0) + > **Примітка:** Це єдиний актуальний документ з токеноміки. Попередній `tokenomics/README.md` перенесено в `docs/_archive/tokenomics_legacy_v0.md`. + +### API + +- `docs/cursor/03_api_core_snapshot.md` — API контракти + +--- + +## 11. Support + +Для питань та підтримки: + +- Документація: `docs/cursor/README.md` +- Контекст проєкту: `PROJECT_CONTEXT.md` +- Швидкий старт: `docs/cursor/50_daarion_city_website_integration.md` + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 +*Документ готовий до інтеграції у Cursor, GitHub або будь-який інший проект.* + diff --git a/docs/microdao-admin-console.md b/docs/microdao-admin-console.md new file mode 100644 index 00000000..fd454817 --- /dev/null +++ b/docs/microdao-admin-console.md @@ -0,0 +1,331 @@ +--- +title: MicroDAO Admin Console — Unified Admin UI Spec +version: 1.0.0 +status: canonical +last_updated: 2024-11-14 +--- + +# MicroDAO Admin Console — Unified Admin UI Spec + +**Цей документ описує стандартизовану адмін-панель для всіх MicroDAO в екосистемі DAARION.city.** + +Адмінка має бути: + +* однаково структурованою для A1, A2, A3, A4/F4 DAO, +* з обовʼязковою присутністю головного агента DAO на Overview-сторінці, +* розширюваною (можна додавати вкладки, але не прибирати базові), +* адаптивною (від A1 SuperDAO до маленького приватного DAO). + +--- + +# 1. Цілі та принципи + +1. **Уніфікація** — будь-яке MicroDAO має однакову логіку налаштувань. + +2. **Agent-first Admin** — головний агент DAO присутній на кожній адмін-сторінці як помічник. + +3. **Role-aware** — доступ до консолі залежить від ролі користувача (Owner/Admin тощо). + +4. **Safe-by-default** — всі критичні дії проходять через PDP та підтвердження. + +5. **Composable** — модулі адмінки можна вмикати/вимикати залежно від рівня DAO (A1/A2/A3/A4). + +--- + +# 2. Доступ до адмін-панелі + +Адмін-панель доступна за маршрутом: + +```text +/dao/:dao_id/admin +``` + +Доступ мають користувачі з ролями: + +* **Owner** +* **Admin** + +Опційно (тільки для читання): + +* **Auditor / Observer** (якщо така роль буде додана пізніше). + +Агенти можуть "бачити" адмін-панель через окремий API, але **ніколи не відкривають її як UI**. + +--- + +# 3. Загальний layout адмінки + +Адмінка складається з трьох основних зон: + +1. **Header (верхня панель)** +2. **Sidebar (ліва навігація)** +3. **Main Content (центральна зона)** + +## 3.1 Header + +Містить: + +* Назву DAO: `DAO Name` +* Рівень: `A1 / A2 / A3 / A4/F4` +* Статус: `active | paused | archived | private` +* Інформація про супідпорядкування: + * якщо `parent_dao_id != null`, показати: `Частина SuperDAO: ` + * якщо це A1: `SuperDAO Root (DAARION.city)` + +Опційно: + +* кнопка швидкого перемикання між DAO (для адмінів, що керують кількома DAO) + +## 3.2 Sidebar (навігація) + +Базові розділи (обовʼязкові для всіх DAO): + +1. **Overview** +2. **Members & Roles** +3. **Tokenomics & Wallet** +4. **Agents** +5. **Integrations** +6. **Settings** +7. **Security & Logs** + +Для A1/A2 можуть зʼявлятися додаткові вкладки (наприклад: `Platforms`, `Federation`, `City Config`). + +## 3.3 Main Content (залежить від обраної вкладки) + +Основна зона використовується кожним розділом по-різному. + +--- + +# 4. Overview (головний екран адміна) + +**Overview** — це центральна точка входу для будь-якого адміна DAO. + +## 4.1 Блок "Головний агент DAO" + +У верхній частині Overview **завжди** присутній блок із головним агентом DAO. + +* Для A1: **DAARWIZZ** +* Для A2-платформ: головний платформний агент, напр. `Helion.CoreAgent` +* Для A3/A4: агент, обраний власником DAO (наприклад `Main DAO Agent`) + +Блок містить: + +* аватар/іконку агента +* імʼя та короткий опис ролі +* статус (online / busy / maintenance) +* кнопку "Поставити запитання" або "Попросити рекомендацію" + +Головний агент може: + +* показувати TODO для адміна ("налаштуйте ролі", "додайте інтеграцію"). +* пояснювати налаштування адмінки простими словами. + +## 4.2 Стан DAO (Status & Health) + +Секція з основними метриками: + +* кількість учасників DAO +* рівень DAO (A2/A3/A4) +* чи є DAO частиною SuperDAO (і якого) +* основні активні інтеграції +* стан токенів (базово: наявність DAAR/DAARION для роботи DAO) + +## 4.3 Останні події + +Лог останніх важливих подій: + +* зміни ролей +* включення/відключення агентів +* підключення інтеграцій +* спроби критичних дій (успішні/відхилені PDP) + +--- + +# 5. Members & Roles + +Розділ для управління учасниками DAO. + +Функції: + +* перегляд списку учасників (імʼя, роль, статус) +* призначення/зміна ролей (Owner, Admin, Member, Guest) +* запрошення нових учасників (e-mail/handle/ID) +* видалення/бан учасників + +Особливості: + +* лише **Owner** може передавати роль Owner іншому користувачу +* лише **Owner/Admin** можуть змінювати ролі інших + +У майбутньому тут може зʼявитися інтеграція з токенами репутації (REP). + +--- + +# 6. Tokenomics & Wallet + +Розділ для перегляду й управління економічною частиною DAO. + +Елементи: + +* баланс DAAR / DAARION (для DAO, якщо це передбачено) +* індикатор відповідності токеноміці (чи достатньо DAAR/DAARION для поточних функцій) +* інформація про локальні токени DAO (якщо DAO використовує GOV/UTIL/REP) + +Обмеження: + +* фінансові операції (перекази, стейкінг, виплати) мають відкривати окремий безпечний флоу, де всі дії проходять через Wallet Service + PDP. +* агенти можуть лише пропонувати дії ("запропонувати транзакцію"), але не виконувати їх самостійно. + +--- + +# 7. Agents + +Розділ для управління агентами DAO. + +Елементи: + +* список агентів DAO (назва, тип, статус, рівень доступу) +* позначка "Main Agent" (головний агент DAO) +* кнопки: + * **Додати агента** (з каталогу типів або кастомний) + * **Увімкнути/вимкнути** агента + * **Налаштувати** (деталі поведінки, рівень автономії, дозволені дії) + +Обовʼязкові правила: + +* головний агент DAO завжди має бути один +* вилучення головного агента має вимагати підтвердження та, можливо, участі A1 (для A2)-рівня DAO +* усі зміни конфігурації агентів логуються в Security & Logs + +--- + +# 8. Integrations + +Розділ для підключення зовнішніх сервісів та міських платформ. + +Приклади: + +* інтеграція з GreenFood ERP +* інтеграція з Helion (енергетика) +* інтеграція з WaterAGI +* інтеграція з зовнішніми сервісами (наприклад, CRM/Notion/Jira у майбутньому) + +Механіка: + +* список доступних інтеграцій (каталог) +* кнопка "Підключити" +* статус: `connected | disconnected | error` + +Усі інтеграції мають описуватися як capability-keys для агентів. + +--- + +# 9. Settings + +Розділ для налаштувань DAO. + +Параметри: + +* назва DAO, опис, аватар/лого +* тип DAO: `platform | public | private` +* рівень видимості (чисто для UI): `public catalog | invite-only` +* налаштування онбордингу (чи можна подати заявку на вступ) + +Для A2/A3/A4 можуть бути додаткові поля. + +Зміна критичних налаштувань: + +* вимагає підтвердження (наприклад, повторне введення пароля/підпису транзакції) +* логуються в Security & Logs + +--- + +# 10. Security & Logs + +Розділ для аудиту дій. + +Містить: + +* список останніх важливих дій (зміни ролей, агентів, налаштувань) +* логи спроб доступу +* результат перевірок PDP (allow/deny) + +Мета: + +* прозорість +* можливість розслідування інцидентів + +--- + +# 11. Специфіка для рівнів A1 / A2 / A3 / A4 + +## 11.1 A1 (DAARION.city) + +Додаткові розділи: + +* **Federation / SuperDAO** (коли буде описано) +* **City Config** — міські політики, глобальні ліміти, токеноміка + +Головний агент: **DAARWIZZ** — завжди відображається на Overview. + +## 11.2 A2 (платформи) + +Додаткові опції: + +* керування продуктами/сервісами платформи +* керування вендорами + +Головний агент: головний агент відповідної платформи. + +## 11.3 A3/A4 (публічні та приватні DAO) + +Стандартний набір вкладок, мінімалістичний: + +* Overview, Members, Agents, Settings, Security + +Головний агент: вибирається засновником DAO. + +--- + +# 12. Використання цього документа + +Ця специфікація використовується для: + +* проектування UI/UX адмін-панелі для всіх MicroDAO +* уніфікації досвіду адміністрування в DAARION.city +* інтеграції агентів у адмінку (Agent-as-Admin-Assistant) +* узгодження між frontend/backend/архітекторами + +Будь-які зміни в ролях, аґентній архітектурі чи токеноміці мають синхронізуватися з цим документом, щоб адмінка залишалась єдиною для всієї екосистеми. + +--- + +## 13. Integration with Other Docs + +Цей документ інтегрується з: + +- `microdao-architecture.md` — архітектура A1-A4 +- `agents.md` — агенти та їх права +- `pdp_access.md` — PDP та система доступів +- `superdao-federation.md` — SuperDAO та федерації +- `api.md` — API для адмін-консолі +- `tokenomics/city-tokenomics.md` — токеноміка + +--- + +## 14. Changelog + +### v1.0.0 — 2024-11-14 +- Початкова версія специфікації MicroDAO Admin Console +- Додано структуру layout (Header, Sidebar, Main Content) +- Додано розділи: Overview, Members & Roles, Tokenomics & Wallet, Agents, Integrations, Settings, Security & Logs +- Додано обов'язковий блок головного агента на Overview +- Додано специфіку для рівнів A1/A2/A3/A4 + +--- + +**Версія:** 1.0.0 +**Останнє оновлення:** 2024-11-14 +*Документ готовий до інтеграції у Cursor, GitHub або будь-який інший проект.* + + diff --git a/docs/microdao/README.md b/docs/microdao/README.md new file mode 100644 index 00000000..05fc61e7 --- /dev/null +++ b/docs/microdao/README.md @@ -0,0 +1,25 @@ +# MicroDAO — Документація + +Ця папка містить документацію про систему MicroDAO: архітектуру, RBAC, токеноміку, технічні специфікації. + +## Структура + +### Архітектура та дизайн +- `architecture.md` — загальна архітектура системи +- `rbac.md` — система ролей та доступів (RBAC) +- `tokenomics.md` — токеноміка MicroDAO + +### Технічна документація +- `api.md` — API специфікація +- `database-schema.md` — схема бази даних +- `security.md` — безпека та аудит + +### Для розробників +Детальна технічна документація для розробки знаходиться в `/docs/cursor/` — це специфікації для Cursor AI та розробників. + +## Посилання + +- [Технічна документація для розробки](../cursor/README.md) +- [DAARION.city інтеграція](../daarion/README.md) +- [Агентська система](../agents/README.md) + diff --git a/docs/microdao/access-keys-capabilities.md b/docs/microdao/access-keys-capabilities.md new file mode 100644 index 00000000..2f37ffdb --- /dev/null +++ b/docs/microdao/access-keys-capabilities.md @@ -0,0 +1,677 @@ +# 24 — Access Keys & Capabilities System (MicroDAO) + +Універсальна система ключів доступу та capability-механіка + +Цей документ описує універсальну систему ключів доступу (access keys) та capability-механіку для платформи **microdao / DAARION.city**: + +- як видаються й перевіряються ключі; +- як описуються та застосовуються capabilities; +- як працюють **Wallet Agent** і **Embassy Module**; +- як система вбудовується в існуючі RBAC/Entitlements/Mode (public|confidential) та Governance. + +Ціль: єдиний шар авторизації для веб-клієнта, приватних агентів, API, інтеграцій та зовнішніх платформ. + +--- + +## 1. Purpose & Scope + +Цей документ описує універсальну систему ключів доступу (access keys) та capability-механіку для платформи **microdao / DAARION.city**: + +- як видаються й перевіряються ключі; +- як описуються та застосовуються capabilities; +- як працюють **Wallet Agent** і **Embassy Module**; +- як система вбудовується в існуючі RBAC/Entitlements/Mode (public|confidential) та Governance. + +Ціль: єдиний шар авторизації для веб-клієнта, приватних агентів, API, інтеграцій та зовнішніх платформ. + +--- + +## 2. Основні поняття + +### 2.1 Access Key + +Access Key — це матеріалізований «токен доступу» до певної області системи: + +- має унікальний `key_id`; +- прив'язаний до **суб'єкта** (user / team / agent / external platform); +- має **набір capabilities**; +- має строк дії та статус (active / revoked / expired). + +Приклади: + +- ключ API для інтеграції з GreenFood; +- ключ приватного агента до Co-Memory та Projects; +- ключ Embassy для міжплатформенної взаємодії. + +### 2.2 Capability + +Capability — атомарне право **на дію над ресурсом**. + +Формат (концептуально): + +```text +..[:] +``` + +Приклади: + +- `chat.message.send` +- `chat.channel.manage` +- `comemory.item.read:team` +- `projects.task.write` +- `wallet.balance.view` +- `wallet.stake.ringk` +- `governance.proposal.create` +- `energy.asset.read` +- `platform.greenfood.inventory.update` + +### 2.3 Capability Bundle (role / plan / template) + +Capability-набір: + +- набір capabilities, який прив'язується до: + - ролі (`Owner`, `Guardian`, `Member`, `Visitor`); + - тарифного плану (Freemium / Casual / Premium / Platformium); + - конкретного access key (API-ключ, агент, інтеграція). + +--- + +## 3. Модель доступу (оновлена формула allow) + +Базова формула авторизації: + +```text +allow = + RBAC(role, action, resource) + ∧ Entitlement(plan, RINGK_staked) + ∧ Capability(key, action, resource) + ∧ ACL(resource) + ∧ Mode(public|confidential) +``` + +Тобто: + +1. Роль дозволяє дію (Owner/Guardian/Member/Visitor). +2. План + стейк RINGK дають достатні ліміти/право (ентайтли). +3. Ключ (user/agent/API) має відповідну capability. +4. ACL ресурсу не забороняє (список дозволених/заборонених). +5. Режим каналу/команди (public/confidential) не блокує дію. + +--- + +## 4. Типи ключів + +### 4.1 User Session Key + +- Прив'язаний до користувача (`user_id`) і сесії (JWT / cookie). +- Використовується веб-клієнтом. +- Capabilities виводяться з ролі, ентайтлів і контексту (team, mode). + +### 4.2 Agent Access Key + +- Прив'язаний до приватного агента (`ag_…`). +- Використовується при викликах **Agent Mesh / Tooling API**. +- Має обмежений набір capabilities: + - `chat.message.read:scoped` + - `comemory.item.read:scoped` + - `followups.create` + - `projects.task.read/write` (за необхідності) +- Має обмеження за: + - токенами/хв; + - кількістю викликів; + - бюджетом 1T / KWT. + +### 4.3 API Key / Integration Key + +- Прив'язаний до інтеграції (`integrations`). +- Наприклад: Notion, Slack, GreenFood, Energy Union, Water Union. +- Capabilities для зовнішнього сервісу: + - `webhook.events.receive:team` + - `projects.task.sync` + - `rwa.energy.update` + - `platform.greenfood.sync` + +### 4.4 Embassy Key + +- Ключ для **Embassy Module** — шлюз між DAARION.city та зовнішньою платформою/мережею. +- Додаткові властивості: + - mapping зовнішніх ідентичностей (external_id ↔ DID/user_id); + - whitelist дозволених типів актів (`intent.created`, `offer.published`, `gift.ack`, `rwa.claim` тощо); + - окремий журнал дій для аудиту. + +### 4.5 Wallet Capability Key + +- Спеціальний ключ для **Wallet Agent**: + - `wallet.balance.view` + - `wallet.tx.initiate` + - `wallet.tx.sign` + - `wallet.stake.ringk` + - `wallet.claim.rwa` +- Може бути: + - нон-кастодіальний (підпис у клієнта, key лише для маршрутизації); + - кастодіальний (wallet service з 4-eyes контролем). + +--- + +## 5. Wallet Agent: специфікація + +### 5.1 Призначення + +Wallet Agent — це агент, який: + +- показує баланси токенів (RINGK, 1T, KWT, DAAR, DAARION тощо); +- ініціює й перевіряє дії стейкінгу/unstake RINGK; +- показує історію payouts (1T/KWT); +- працює з RWA-сертифікатами (Energy, GREENFOOD тощо) через Embassy. + +### 5.2 Основні флоу + +1. **View balances** + +- Виклик: `/wallet/balances`. +- Перевірка: + - RBAC: будь-який Member+ / Owner/Guardian. + - Capability: `wallet.balance.view`. + - Mode: не залежить від public/confidential. + +2. **Stake RINGK** + +- Виклик: `/staking/ringk` (`amount`). +- Перевірка: + - RBAC: Member+. + - Capability: `wallet.stake.ringk`. + - Entitlements: перевірка мінімального стейку, lock-параметрів. + - Governance: параметри стейку (lock_until, min_amount) беруться з onchain/DAO-конфігів. + +3. **Claim payouts (1T/KWT/RWA)** + +- Флоу: + - Wallet Agent читає `payouts`/`rwa_claims` з backend; + - ініціює підпис транзакції користувачем; + - виконує через onchain gateway/Embassy. +- Capabilities: + - `wallet.payout.view` + - `wallet.payout.claim` + - `rwa.claim` + +### 5.3 Дані (мінімум) + +- `wallets` (user_id ↔ address) +- `staking_ringk` +- `payouts` +- `rwa_certificates` / `rwa_claims` (через Embassy) + +--- + +## 6. Embassy Module: специфікація + +### 6.1 Призначення + +Embassy Module — шар інтеграції між: + +- DAARION.city (місто агентів, microdao); +- зовнішніми платформами (GreenFood, Energy Union, інші RWA-ініціативи); +- публічними мережами (L2, marketplace, вузли взаємообміну). + +Він відповідає за: + +- мапінг ідентичностей; +- валідацію актів взаємодії; +- трансформацію подій і capability-рівнів. + +### 6.2 Ідентичності + +- `resident_id` ↔ `user_id`/DID. +- `district_id` ↔ team/microDAO. +- `agent_id` ↔ citizen-agent. +- `rwa_id` ↔ сертифікат дару/актив RWA. + +Embassy Key має capability-набори: + +- `embassy.intent.read/write` +- `embassy.rwa.claim` +- `embassy.energy.update` +- `embassy.audit.view` + +### 6.3 Події (канонічні акти) + +- `intent.created` +- `offer.published` +- `gift.ack` +- `memory.update` +- `rwa.claim` +- `energy.update` + +Embassy: + +- приймає подію через webhook / шину (NATS); +- перевіряє capability Embassy Key; +- трансформує в внутрішні події (`reward.*`, `oracle.*`, `payout.*`). + +--- + +## 7. Runtime capability-check + +### 7.1 Компоненти + +- **PDP** (Policy Decision Point) — сервіс, який: + - приймає контекст запиту: `user_id / agent_id`, `team_id`, `resource`, `action`, `mode`, `key_id`; + - повертає `allow/deny` + причину. +- **PEP** (Policy Enforcement Point): + - live у API-gateway і сервісах (Messaging, Projects, Wallet, Governance). + +### 7.2 Кеш і формат токена + +- Для кожного access key формується компактний «capability token»: + - `sub` (user/agent/integration); + - `team_scope`; + - `caps` (список capability кодів або bitmap); + - `exp`. +- Токен зберігається в Redis / in-memory кеші для швидкої перевірки. + +### 7.3 Приклади перевірок + +1. Агент хоче прочитати Co-Memory: + +```text +action = comemory.item.read +resource = chat: c_123 +mode = confidential +subject = ag_456 +key_id = ak_789 + +→ RBAC: owner of agent = Member в team t_1 +→ Entitlements: план дозволяє приватні агенти +→ Capability(ak_789): містить comemory.item.read:scoped +→ ACL: чат дозволяє агентів +→ Mode: confidential → E2EE, агент отримує лише векторні ознаки/summary + +→ allow +``` + +2. Зовнішній RWA-хаб оновлює енергетичний актив: + +```text +action = energy.update +subject = embassy_key ek_001 +→ Capability(ek_001): енергетичні оновлення дозволені для конкретного district_id +→ Governance: політика для цього district_id активна + +→ allow +``` + +--- + +## 8. Інтеграція з Governance Agent + +Governance Agent: + +- має capability `governance.policy.manage` (тільки Owner/Guardian через DAO-процес); +- може: + - створювати/оновлювати **capability bundles**; + - прив'язувати bundles до ролей/планів/ключів; + - змінювати пороги доступу (напр. min RINGK stake для Premium/Platformium). + +Флоу: + +1. Створюється пропозиція (onchain / в DAO Service): + - змінити набір capabilities для `Platformium` плану; + - додати capability `platform.greenfood.inventory.update`. +2. Пропозиція голосується токеном DAARION. +3. Після прийняття Governance Agent: + - оновлює конфіг у Capability Registry; + - виконує міграцію активних access keys; + - логуються події `governance.policy.updated`. + +--- + +## 9. Дані та моделі (мінімальна схема) + +Таблиці (спрощений вигляд): + +```sql +create table access_keys ( + id text primary key, -- ak_... + subject_kind text not null, -- user|agent|integration|embassy + subject_id text not null, + team_id text null, + name text not null, + status text not null check (status in ('active','revoked','expired')), + created_at timestamptz not null default now(), + expires_at timestamptz null +); + +create table capabilities ( + id text primary key, -- cap_... + code text not null, -- chat.message.send, wallet.stake.ringk + description text not null +); + +create table access_key_caps ( + key_id text references access_keys(id) on delete cascade, + cap_id text references capabilities(id) on delete cascade, + primary key (key_id, cap_id) +); + +create table bundles ( + id text primary key, -- bundle_... + name text not null, -- e.g. "role.Member", "plan.Premium", "agent.default" + created_at timestamptz not null default now() +); + +create table bundle_caps ( + bundle_id text references bundles(id) on delete cascade, + cap_id text references capabilities(id) on delete cascade, + primary key (bundle_id, cap_id) +); +``` + +Access key може наслідувати capabilities з одного чи кількох bundles. + +--- + +## 10. Безпека + +- Мінімізований набір capabilities за замовчуванням (principle of least privilege). +- Для confidential-контенту: + - агенти не отримують plaintext без явної згоди; + - Embassy не передає контент, тільки агреговані/векторні дані. +- Всі access keys: + - зберігаються у зашифрованому вигляді (KMS); + - мають короткий час життя, періодичну ротацію; + - мають аудит використання (audit_log). + +--- + +## 11. Інтеграція з RBAC & Entitlements + +Посилання на документ: `microdao — RBAC і Entitlements (MVP).docx` + +1. Розширена формула доступу (оновлює пункт 2 у RBAC-документі): + +```text +allow = + RBAC(role, action, resource) + ∧ Entitlement(plan, RINGK_staked) + ∧ Capability(key, action, resource) + ∧ ACL(resource) + ∧ Mode(public|confidential) +``` + +2. Мапінг ролей з RBAC → capability bundles: + +- з таблиць `team_members.role` (`Owner`, `Guardian`, `Member`) та viewer-type (`reader`, `commenter`, `contributor`) формуються стартові bundles: + - `bundle.role.Owner` + - `bundle.role.Guardian` + - `bundle.role.Member` + - `bundle.role.Visitor` (для гостя в public-каналах). +- кожен bundle включає capabilities, що відповідають матрицям з розділу «4) Ресурси → дії (матриці)» RBAC-документу + (Community, Channels, Messages, Follow-ups, Projects, Tasks, Docs, Meetings). + +3. Мапінг Entitlements (плани + стейк RINGK): + +- таблиці з Data Model: + - `wallets` + - `staking_ringk` +- плани з RBAC-документу (`Freemium`, `Casual`, `Premium`, `Platformium`) задаються як: + - `bundle.plan.Freemium` + - `bundle.plan.Casual` + - `bundle.plan.Premium` + - `bundle.plan.Platformium` +- формула з RBAC → в capability-рівень: + +```text +effective_quota = min(plan_quota × multiplier(RINGK_staked), hard_limit) +``` + +- ліміти прив'язуються до capabilities на кшталт: + - `chat.message.send` + - `agent.run.invoke` + - `router.invoke` + - `wallet.payout.claim` + +--- + +## 12. Інтеграція з Security Architecture & Threat Model + +Посилання: `microdao — Security Architecture & Threat Model (MVP).docx` + +1. Зберігання ключів: + +- метадані ключа — в таблиці `access_keys` (див. розділ 13 нижче); +- сам секрет (`secret`) зберігається зашифрованим (KMS/HSM), згідно з розділами про secrets у Security Architecture; +- one-time reveal: після створення ключ не показується повторно. + +2. Транспорт і токени: + +- веб-клієнт: + - використовує сесію (`users` + сесійні токени на рівні Auth); + - capability-набір інкапсульовано в «capability token» (JWT/opaque), який несе: + - `sub` (u_/ag_/integr), + - `team_id`, + - стиснений список `caps`. +- API/Webhooks/Embassy: + - ключ передається в `Authorization: Bearer ` або в окремому заголовку; + - підпис вебхуків (Embassy) — HMAC, як у Security Architecture. + +3. Confidential-режим: + +- `teams.mode` ∈ (`public`, `confidential`); +- для `mode='confidential'`: + - агенти з Agent Access Key не бачать `chat_message.body` у plaintext, + - доступ дається до: + - агрегованих структур (`comemory_items`), + - embeddings/summary, сформованих локально або в E2EE-шарі; +- це наслідує E2EE-модель з Security-документу (сервер бачить мінімум метаданих). + +4. Threat model для access keys: + +- нові активи: + - `access_keys`, `bundles`, capability-кеш; +- загрози: + - компрометація ключа, зловживання Embassy-ключем, масовий abuse agent-ключів; +- мітiгації: + - короткий `expires_at`, обов'язкова ротація; + - strict capabilities (least privilege); + - обов'язковий аудит через події `audit.event` і нові `access_key.*` (див. нижче). + +--- + +## 13. Інтеграція з Data Model & Event Catalog + +Посилання: `microdao — Data Model & Event Catalog.docx` + +1. Нові таблиці (додати в розділ DB-схеми, поруч із Wallet / Governance): + +```sql +create table access_keys ( + id text primary key, -- ak_... + subject_kind text not null, -- 'user' | 'agent' | 'integration' | 'embassy' + subject_id text not null, -- u_/ag_/... + team_id text null, -- t_..., якщо scoped до команди + name text not null, + status text not null check (status in ('active','revoked','expired')), + created_at timestamptz not null default now(), + expires_at timestamptz null, + last_used_at timestamptz null +); + +create table capabilities ( + id text primary key, -- cap_... + code text not null unique, -- chat.message.send, wallet.stake.ringk, ... + description text not null +); + +create table access_key_caps ( + key_id text references access_keys(id) on delete cascade, + cap_id text references capabilities(id) on delete cascade, + primary key (key_id, cap_id) +); + +create table bundles ( + id text primary key, -- bundle_... + name text not null unique, -- role.Member / plan.Premium / agent.default + created_at timestamptz not null default now() +); + +create table bundle_caps ( + bundle_id text references bundles(id) on delete cascade, + cap_id text references capabilities(id) on delete cascade, + primary key (bundle_id, cap_id) +); +``` + +- конвенції ID узгоджуються з розділом «2) Конвенції»: + - `ak_…` для access keys; + - `cap_…` для capabilities; + - `bundle_…` для bundle-ів. + +2. Прив'язка до існуючих таблиць: + +- `access_keys.subject_id` → `users.id` / `agents.id` / `integrations.id` / Embassy-ідентифікатори (згідно з Data Model); +- `access_keys.team_id` → `teams.id` (team як microDAO/платформа). + +3. Нові події для Event Catalog (розширення enum `topic`): + +Додати в список `topic.enum`: + +```jsonc +"access_key.created", +"access_key.revoked", +"access_key.used" +``` + +та окремі `allOf`-entry з `$defs`: + +```jsonc +// envelope.topic = "access_key.created" +"access_key_created": { + "type": "object", + "properties": { + "key_id": { "type": "string" }, + "subject_kind": { "type": "string" }, + "subject_id": { "type": "string" }, + "team_id": { "type": ["string","null"] } + }, + "required": ["key_id","subject_kind","subject_id"] +} +``` + +аналогічні схеми для `access_key.revoked` і `access_key.used` +(з полями `revoked_by`, `action`, `resource_kind`). + +4. Зв'язок з уже наявними подіями: + +- `staking_ringk` + `payouts` вже мають події: + - `"staking.locked"` + - `"payout.generated"` + - `"rwa.inventory.updated"` +- Wallet Agent та Embassy в sequence-діаграмах нижче використовують саме ці topic-и; capability-check визначає, хто має право ініціювати або читати ці події. + +--- + +## 14. Sequence-діаграми (ключові флоу) + +### 14.1 Wallet Agent: login → access key → capability-check → stake RINGK + +```mermaid +sequenceDiagram + participant U as User (browser) + participant Auth as Auth Service + participant API as API Gateway + participant PDP as Policy Service + participant W as Wallet Service + participant BUS as NATS JetStream + + U->>Auth: 1) POST /login (email+code) + Auth-->>U: 2) Session (JWT/cookie з user_id + capability token) + + U->>API: 3) POST /wallet/stake {amount} + API->>PDP: 4) authorize(user_id, action=wallet.stake.ringk) + PDP-->>API: 5) allow / deny + + API->>W: 6) create_stake_request(user_id, amount) + W->>BUS: 7) publish topic="staking.locked" (payload.staking_id) + API-->>U: 8) 200 OK (stake pending) + + W->>BUS: 9) (після ончейн-обробки) publish topic="payout.generated" + BUS-->>U: 10) notification → Wallet Agent (claim available) +``` + +### 14.2 Embassy Module: external RWA → Embassy → capability-check → internal events + +```mermaid +sequenceDiagram + participant Ext as External RWA Hub + participant GW as Embassy Gateway (HTTP/Webhook) + participant PDP as Policy Service + participant BUS as NATS JetStream + + Ext->>GW: 1) POST /embassy/rwa {inventory_update} + access_key + GW->>PDP: 2) authorize(embassy_key, action=rwa.inventory.update) + PDP-->>GW: 3) allow / deny + + GW->>BUS: 4) publish topic="rwa.inventory.updated" (payload.rwa_id, delta) + BUS-->>BUS: 5) downstream services (Wallet/Gift Fabric) слухають подію +``` + +### 14.3 Energy Union: meter → Energy Union → Embassy → payouts + +```mermaid +sequenceDiagram + participant M as Metering Agent + participant EU as Energy Union Backend + participant Emb as Embassy Module + participant PDP as Policy Service + participant BUS as NATS JetStream + participant W as Wallet Service + + M->>EU: 1) send meter data (kWh) + EU->>EU: 2) aggregate & validate + + EU->>Emb: 3) POST /embassy/oracle {site, period, kWh} + access_key + Emb->>PDP: 4) authorize(embassy_key, action=oracle.reading.publish) + PDP-->>Emb: 5) allow + + Emb->>BUS: 6) publish topic="oracle.reading.published" + BUS->>W: 7) consume oracle → compute payouts + W->>BUS: 8) publish topic="payout.generated" (symbol="KWT"/"1T") + BUS-->>Users: 9) Wallet Agent показує доступні виплати +``` + +--- + +## 15. Завдання для Cursor + +```text +You are a senior backend engineer. Implement the Access Keys & Capabilities System using: +- 24_access_keys_capabilities_system.md +- 18_governance_access_agent.md +- 23_domains_wallet_dao_deepdive.md +- 05_coding_standards.md + +Tasks: +1) Create database schema: access_keys, capabilities, access_key_caps, bundles, bundle_caps. +2) Implement PDP (Policy Decision Point) service. +3) Integrate PEP (Policy Enforcement Point) into API Gateway. +4) Implement Wallet Agent endpoints with capability checks. +5) Create Embassy Module stub with capability validation. +6) Add capability-check middleware for all API endpoints. + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 16. Результат + +Після впровадження цієї системи: + +- єдиний шар авторизації для всіх типів доступу (users, agents, integrations, platforms); +- чіткий контроль прав через capabilities; +- інтеграція з Wallet Agent та Embassy Module; +- підготовка до масштабування та додавання нових платформ. + diff --git a/docs/microdao/architecture.md b/docs/microdao/architecture.md new file mode 100644 index 00000000..986f4b7a --- /dev/null +++ b/docs/microdao/architecture.md @@ -0,0 +1,33 @@ +# MicroDAO - Огляд системи + +## Що таке MicroDAO + +MicroDAO — це приватна мережа ШІ-агентів для малих спільнот (5-50 учасників). Система дозволяє створювати спільноти (teams) з автоматичним створенням micro-DAO, публічні та приватні канали для спілкування, проєкти з задачами, базу знань (Co-Memory) та приватних ШІ-агентів, які допомагають у роботі команди. + +## Ключові модулі + +1. **Auth** — авторизація через magic-link (email) +2. **Teams** — спільноти з автоматичним створенням micro-DAO +3. **Channels** — публічні та приватні канали для спілкування +4. **Messages** — повідомлення в каналах з підтримкою markdown +5. **Co-Memory** — база знань (файли, посилання, wiki) +6. **Follow-ups** — задачі, створені з повідомлень +7. **Projects** — проєкти з канбан-дошками (Backlog / In Progress / Done) +8. **Agents** — приватні ШІ-агенти для кожної спільноти +9. **Search** — пошук по повідомленнях та документах (Meilisearch) + +## Режими спільнот + +- **Public** — публічний канал, гості можуть читати та реєструватися як глядачі (viewer-type) +- **Confidential** — тільки запрошені учасники, E2EE для чатів, без публічного індексування + +## Посилання на документацію + +- `01_product_brief_mvp.md` — Product Requirements для MVP +- `02_architecture_basics.md` — Технічна архітектура +- `03_api_core_snapshot.md` — API контракти для MVP +- `04_ui_ux_onboarding_chat.md` — UI/UX специфікація +- `05_coding_standards.md` — Стандарти кодування +- `06_tasks_onboarding_mvp.md` — Задачі для реалізації +- `07_testing_checklist_mvp.md` — Чеклист тестування + diff --git a/docs/microdao/rbac.md b/docs/microdao/rbac.md new file mode 100644 index 00000000..fc755f5c --- /dev/null +++ b/docs/microdao/rbac.md @@ -0,0 +1,409 @@ +# 48 — Teams Access Control & Confidential Mode (MicroDAO) + +*Командні доступи, ролі, членство, ACL, confidential mode, індексація, інструменти, агенти, governance-політики. Канонічна специфікація microDAO команд.* + +--- + +## 1. Purpose & Scope + +Цей документ визначає: + +- структуру команд (microDAO), +- ролі та дозволи, +- ACL для ресурсів, +- поведінку Confidential Mode, +- вплив на агентів, інструменти, чат, LLM Proxy, Router, Wallet, Embassy, Projects/Tasks, +- правила Governance. + +Це центральний рівень контролю безпеки й приватності у DAARION.city. + +--- + +## 2. Team (microDAO) Model + +Команда = організаційний домен, який має: + +- учасників (members), +- ролі, +- командні налаштування, +- власну економіку (1T / KWT / RINGK стейк), +- власний набір агентів, +- власні канали, +- власні ACL. + +--- + +## 3. Team Roles + +| Role | Capabilities | Опис | +| ------------ | ------------------------------------------------------- | -------------------- | +| **Owner** | повний контроль, зміна налаштувань, звільнення Guardian | creator of team | +| **Guardian** | майже все, крім знищення команди | security + oversight | +| **Admin** | керування каналами/агентами/ресурсами | operational | +| **Member** | доступ до основних інструментів | worker | +| **Guest** | читання + обмежені інструменти | limited | +| **Agent** | системний агент команди | restricted | + +Команда може мати: + +- 1 owner +- 0–N guardians +- 0–N admins +- 0–N members +- 0–N guests +- 0–N private agents + +--- + +## 4. Role Capability Mapping + +### Owner + +- повний доступ +- оновлювати план +- додавати/видаляти членів +- змінювати confidential mode +- випускати токени команди (якщо дозволено governance) + +### Guardian + +- контролює security sensitive +- додавання агентів +- доступ до private channels +- керування ACL +- активація E2EE + +### Admin + +- створення каналів +- створення проектів +- керування задачами +- запуск agent flows + +### Member + +- участь у каналах +- запуск агентів (якщо дозволено) +- створення задач у публічних проєктах + +### Guest + +- читання +- обмежені інструменти +- немає доступу до agent visibility + +### Agent + +- діє через PDP +- може діяти лише у дозволених каналах/проєктах +- не має власних ролей + +--- + +## 5. Team-Level ACL + +У команді існує ACL для кожного типу ресурсу: + +```text +RESOURCE → [allowed_roles] +``` + +Приклад: + +### Projects + +```text +create: [owner, guardian, admin] +read: [owner, guardian, admin, member] +update: [owner, guardian, admin] +delete: [owner, guardian] +``` + +### Channels + +```text +create: [owner, guardian, admin] +read/write: залежить від channel.acl +``` + +### Agents + +```text +create: [owner, guardian] +update: [owner, guardian] +run: [owner, guardian, member] (опційно) +``` + +### Wallet + +```text +view: [owner, guardian] +tx: [owner] +claim: [owner, guardian] +``` + +### Embassy Data + +```text +read: [owner, guardian] +write: none (тільки embassy service) +``` + +--- + +## 6. Team States + +Команда може перебувати в станах: + +- **active** — нормальна робота +- **locked** — тимчасове блокування (борги, порушення) +- **confidential** — підвищена приватність +- **suspended** — потребує KYC / security audit +- **archived** — команда закрита + +--- + +## 7. Confidential Mode + +Confidential Mode — це **режим максимального захисту** для команд. + +### Увімкнення: + +лише Owner або Guardian + +### Поведінка: + +#### 7.1 LLM Proxy + +- не бачить plaintext повідомлень +- використовує summary-only режим +- vision вимкнено +- embedding робиться з redacted тексту + +#### 7.2 Agents + +- не отримують plaintext +- не можуть використовувати tools категорії C/D +- не можуть використовувати platform tools +- autonomy знижується на 1 рівень +- не можуть запускати subagents + +#### 7.3 Messaging + +- повідомлення не зберігаються у plaintext +- DM канал між Owner та Guardian → E2EE only +- file attachments encrypt-only +- retention: 0–30 днів + +#### 7.4 Projects/Tasks + +- task description → summary-only +- файли завжди E2EE +- agent-run logs → redacted + +#### 7.5 Wallet/RWA + +- доступ обмежений Owner/Guardian +- payouts проходять без content-level history +- RWA дані теж redacted + +--- + +## 8. Team Privacy Layers + +Рівні приватності: + +| Level | Description | +| ------------ | --------------------------------- | +| open | звичайний режим | +| restricted | менш видимі канали | +| private | DM-like behavior | +| confidential | максимальний захист, summary-only | + +--- + +## 9. Team Settings Schema + +```json +{ + "team_id": "t_444", + "name": "GreenFood Hub", + "plan": "Premium", + "confidential": true, + "settings": { + "agents_enabled": true, + "allow_subagents": false, + "allow_router_flows": true, + "file_storage_limit_mb": 5000, + "agent_default_autonomy": "low" + }, + "acl_overrides": { + "wallet.view": ["owner","guardian"], + "wallet.tx": ["owner"], + "projects.create": ["owner","guardian","admin"] + } +} +``` + +--- + +## 10. PDP Integration + +PDP оцінює дію: + +- роль користувача +- ACL ресурсу +- командний стан +- confidential mode +- usage +- план команди +- stake RINGK + +Висновок: + +```text +allow | deny | require-confirmation +``` + +--- + +## 11. Governance Controls + +Governance може: + +- змінювати allowed roles +- визначати максимальну автономію агентів +- вмикати/вимикати confidential mode для певного плану +- вводити policy templates для ACL +- встановлювати KYC-вимоги +- заморожувати команди, що порушили правила + +--- + +## 12. Membership Lifecycle + +### Create Team: + +- Owner створює +- Дається початковий ACL + +### Invite Member: + +- Owner/Admin може запросити → role=member + +### Promote: + +- Member → Admin → Guardian + +### Demote: + +- лише Owner може демотити Guardian + +### Remove: + +- Owner або Guardian (якщо не Owner) + +--- + +## 13. Agent Integration Rules + +Агенти: + +- самі не мають ролей +- використовують access keys +- діють тільки через PDP +- бачать тільки те, що канал/проект дозволяє +- у confidential mode → summary-only +- не можуть змінювати ACL +- не можуть виконувати wallet.tx + +--- + +## 14. Examples + +### Example 1 — Створення приватного каналу + +```text +roles: [owner, guardian] +confidential: false +``` + +### Example 2 — Канал для автономного агента + +```text +roles: [owner, guardian, member] +agents_allowed: [ag_777] +confidential: false +``` + +### Example 3 — Канал у confidential mode + +```text +type: confidential +agents_allowed: [] +raw disabled +summary-only +``` + +--- + +## 15. Integration with Other Docs + +Цей документ доповнює: + +- `47_messaging_channels_and_privacy_layers.md` +- `32_policy_service_PDP_design.md` +- `36_agent_runtime_isolation_and_sandboxing.md` +- `45_llm_proxy_and_multimodel_routing.md` +- `46_router_orchestrator_design.md` +- `40_rwa_energy_food_water_flow_specs.md` + +--- + +## 16. Завдання для Cursor + +```text +You are a senior backend engineer. Implement Teams Access Control & Confidential Mode using: +- 48_teams_access_control_and_confidential_mode.md +- 32_policy_service_PDP_design.md +- 47_messaging_channels_and_privacy_layers.md + +Tasks: +1) Define Team Roles (Owner, Guardian, Admin, Member, Guest, Agent) with capabilities. +2) Implement Role Capability Mapping (per role permissions). +3) Create Team-Level ACL (Projects, Channels, Agents, Wallet, Embassy Data). +4) Implement Team States (active, locked, confidential, suspended, archived). +5) Add Confidential Mode (LLM Proxy behavior, Agents restrictions, Messaging rules, Projects/Tasks rules, Wallet/RWA rules). +6) Implement Team Privacy Layers (open, restricted, private, confidential). +7) Create Team Settings Schema (JSON config with settings and ACL overrides). +8) Integrate with PDP (role, ACL, team state, confidential mode, usage, plan, stake evaluation). +9) Add Governance Controls (allowed roles, agent autonomy, confidential mode activation, ACL templates, KYC requirements, team freezing). +10) Implement Membership Lifecycle (Create Team, Invite Member, Promote, Demote, Remove). +11) Add Agent Integration Rules (no roles, access keys, PDP-only, channel/project permissions, confidential mode restrictions, no ACL changes, no wallet.tx). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 17. Summary + +Система команд (microDAO): + +- має строгі ролі та ACL +- повністю інтегрована з PDP +- визначає дозволи для projects/tasks/wallet/agents +- підтримує confidential mode (summary-only, no plaintext, no vision) +- гарантує приватність даних +- дозволяє побудову складних робочих просторів +- є фундаментом безпеки та організації в DAARION OS + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + + diff --git a/docs/microdao_project_notes.ipynb b/docs/microdao_project_notes.ipynb new file mode 100644 index 00000000..62e83990 --- /dev/null +++ b/docs/microdao_project_notes.ipynb @@ -0,0 +1,181 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# MicroDAO MVP - Проєктні нотатки та аналіз\n", + "\n", + "Цей ноутбук містить:\n", + "- Документацію про проєкт\n", + "- Приклади використання API\n", + "- Нотатки та ідеї\n", + "- Аналіз архітектури\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 📋 Інформація про проєкт\n", + "\n", + "**Назва:** MicroDAO MVP\n", + "\n", + "**Опис:** Приватна мережа ШІ-агентів для малих спільнот (5-50 членів)\n", + "\n", + "**Технології:**\n", + "- Frontend: React 18, TypeScript, Vite, Tailwind CSS\n", + "- Backend: API Gateway (`https://api.microdao.xyz/v1`)\n", + "- База даних: PostgreSQL\n", + "- Message Bus: NATS JetStream\n", + "- Пошук: Meilisearch\n", + "- Storage: S3-сумісне сховище\n", + "- WebSockets для real-time комунікації\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 🗂️ Структура проєкту\n", + "\n", + "```\n", + "MicroDAO 3/\n", + "├── docs/\n", + "│ ├── cursor/ # Документація для Cursor AI\n", + "│ └── microdao_project_notes.ipynb # Цей ноутбук\n", + "├── src/\n", + "│ ├── api/ # API клієнти\n", + "│ ├── components/ # React компоненти\n", + "│ │ └── onboarding/ # Компоненти онбордингу\n", + "│ ├── hooks/ # React hooks\n", + "│ ├── pages/ # Сторінки\n", + "│ └── types/ # TypeScript типи\n", + "├── package.json\n", + "└── vite.config.ts\n", + "```\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 🔌 Приклади використання API\n", + "\n", + "### Базовий API клієнт\n", + "\n", + "API Gateway: `https://api.microdao.xyz/v1`\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Приклад використання API (Python)\n", + "import requests\n", + "import json\n", + "\n", + "API_BASE = \"https://api.microdao.xyz/v1\"\n", + "\n", + "# Приклад: Створення команди\n", + "def create_team(name: str, description: str = None, token: str = None):\n", + " \"\"\"Створити нову команду (micro-DAO)\"\"\"\n", + " headers = {\n", + " \"Authorization\": f\"Bearer {token}\",\n", + " \"Content-Type\": \"application/json\"\n", + " }\n", + " \n", + " data = {\n", + " \"name\": name,\n", + " \"description\": description\n", + " }\n", + " \n", + " response = requests.post(\n", + " f\"{API_BASE}/teams\",\n", + " headers=headers,\n", + " json=data\n", + " )\n", + " \n", + " return response.json()\n", + "\n", + "print(\"Функція create_team() готова до використання\")\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 💡 Нотатки та ідеї\n", + "\n", + "### MVP Features:\n", + "- ✅ Онбординг (6 кроків)\n", + "- ⏳ Автентифікація (magic-link email)\n", + "- ⏳ Чат з повідомленнями\n", + "- ⏳ Публічні канали для гостей\n", + "- ⏳ Follow-ups (нагадування)\n", + "- ⏳ Projects & Tasks (Kanban-lite)\n", + "- ⏳ Приватні агенти\n", + "- ⏳ Базові налаштування\n", + "\n", + "### Out of Scope для MVP:\n", + "- ❌ E2EE (заглушка)\n", + "- ❌ Повноцінний Kanban\n", + "- ❌ Складні налаштування агентів\n", + "- ❌ Мобільний додаток\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 📅 Історія змін\n", + "\n", + "### 2024-11-13\n", + "- ✅ Створено базову структуру проєкту\n", + "- ✅ Реалізовано онбординг (6 кроків)\n", + "- ✅ Налаштовано Git репозиторій\n", + "- ✅ Встановлено залежності та запущено dev server\n", + "- ✅ Створено документацію для Cursor (8 файлів)\n", + "- ✅ Створено Jupyter ноутбук для нотаток\n", + "\n", + "---\n", + "\n", + "*Оновлюйте цей розділ при важливих змінах у проєкті*\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 🔗 Корисні посилання\n", + "\n", + "- **Документація для Cursor:** `docs/cursor/README.md`\n", + "- **API документація:** `docs/cursor/03_api_core_snapshot.md`\n", + "- **UI/UX специфікація:** `docs/cursor/04_ui_ux_onboarding_chat.md`\n", + "- **Технічні задачі:** `docs/cursor/06_tasks_onboarding_mvp.md`\n", + "\n", + "## 📝 Швидкий старт\n", + "\n", + "```bash\n", + "# Встановити залежності\n", + "npm install\n", + "\n", + "# Запустити dev server\n", + "npm run dev\n", + "\n", + "# Відкрити в браузері\n", + "http://localhost:3000/onboarding\n", + "```\n" + ] + } + ], + "metadata": { + "language_info": { + "name": "python" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/superdao-federation.md b/docs/superdao-federation.md new file mode 100644 index 00000000..1263ef0b --- /dev/null +++ b/docs/superdao-federation.md @@ -0,0 +1,299 @@ +--- +title: SuperDAO Federation — Об'єднання та Роз'єднання MicroDAO +version: 1.0.0 +status: canonical +last_updated: 2024-11-14 +--- + +# SuperDAO Federation — Об'єднання та Роз'єднання MicroDAO + +**Цей документ формалізує модель SuperDAO, федерацій та механізмів об'єднання/роз'єднання MicroDAO у мережі DAARION.city.** + +Весь DAO-ландшафт DAARION.city є деревом MicroDAO (A1–A4/F4). Механіка SuperDAO дозволяє: + +* об'єднувати декілька DAO під спільне управління, +* створювати федеративні структури (SuperDAO ↔ MemberDAO), +* вільно від'єднуватись (дефедералізація), +* делегувати частину повноважень "наверх" або "вниз". + +--- + +# 1. Основні поняття + +## 1.1 SuperDAO + +DAO, яке має дочірні DAO (`child_dao_ids[]`) і виконує роль центру федерації. + +Ознаки: + +* `federation_mode = superdao` +* може встановлювати політики для дочірніх DAO +* може надавати інфраструктурну підтримку/агентів/інструменти + +Приклад: + +* **DAARION.city (A1)** — кореневе SuperDAO +* Платформи A2 — можуть бути SuperDAO для A3 DAO + +## 1.2 MemberDAO + +DAO, яке підпорядковується SuperDAO, але зберігає автономність. + +Ознаки: + +* має `parent_dao_id` +* може мати власні політики, агентів, ролі +* може вийти з федерації + +## 1.3 Federation Graph + +Структура зв'язків між DAO. + +Приклад дерева: + +``` +DAARION.city (A1) + + ├── Helion (A2) + + │ ├── SolarDAO (A3) + + │ └── GridWatch (A3) + + ├── GreenFood ERP (A2) + + │ └── AgroCoop DAO (A3) + + └── Soul (A2) + + └── Neighborhood DAO (A3) +``` + +## 1.4 FederationMode + +``` +none → DAO працює самостійно + +member → DAO входить до складу SuperDAO + +superdao → DAO має дочірні DAO і формує федерацію +``` + +--- + +# 2. Модель даних (MetaDAO структура) + +Мінімальний набір полів у таблиці DAO: + +```json +{ + "dao_id": "string", + "name": "string", + "level": "A1 | A2 | A3 | A4", + "parent_dao_id": "string | null", + "child_dao_ids": ["string"], + "federation_mode": "none | member | superdao", + "policies": {}, + "agents": [], + "settings": {} +} +``` + +--- + +# 3. Операції федерації + +## 3.1 Join Federation (вступ DAO до SuperDAO) + +**Сценарій:** DAO вирішує приєднатися до SuperDAO. + +### Умови: + +* обране SuperDAO повинно мати `federation_mode = superdao` +* DAO має бути A3 або A4 (винятки для A2 — за правилами A1) + +### Алгоритм: + +1. `PDP.check(policy.federation.join)` +2. DAO встановлює `parent_dao_id = superdao_id` +3. SuperDAO додає DAO до `child_dao_ids[]` +4. DAGI Registry синхронізує агентні дозволи + +--- + +## 3.2 Leave Federation (вихід DAO з SuperDAO) + +**Сценарій:** DAO хоче стати незалежним. + +### Умови: + +* дозвіл Owner DAO +* відсутні активні критичні зобовʼязання перед SuperDAO + +### Алгоритм: + +1. `PDP.check(policy.federation.leave)` +2. DAO встановлює `parent_dao_id = null` +3. SuperDAO видаляє DAO з `child_dao_ids[]` +4. DAGI Registry обмежує delegations + +--- + +## 3.3 Create SuperDAO (DAO стає SuperDAO) + +Будь-яке DAO може стати SuperDAO, якщо воно приносить структуру під себе. + +### Умови: + +* DAO має ≥ 1 дочірнє DAO +* Owner обирає тип: `federation_mode = superdao` + +--- + +## 3.4 Dissolve SuperDAO (розформування федерації) + +**Сценарій:** SuperDAO розпускає федерацію. + +### Алгоритм: + +1. `PDP.check(policy.federation.dissolve)` +2. Всі `child_dao_ids[]` переходять у `parent_dao_id = null` +3. SuperDAO отримує режим `federation_mode = none` + +--- + +# 4. Ролі в федерації + +Федерація вводить додаткові ролі: + +## 4.1 SuperDAO Admin + +* керує federated-політиками +* може делегувати агентів вниз по структурі + +## 4.2 Federation Member Admin + +* керує власним DAO +* приймає federated-політики, але може перевизначати частину + +## 4.3 Federation Observer + +* читає структуру, але не управляє + +--- + +# 5. Політики федерації (PDP) + +## 5.1 policy.federation.join + +``` +allow: user.role == owner AND target.federation_mode == superdao +``` + +## 5.2 policy.federation.leave + +``` +allow: user.role == owner +``` + +## 5.3 policy.federation.create-superdao + +``` +allow: user.role == owner AND dao.child_count >= 1 +``` + +## 5.4 policy.federation.dissolve + +``` +allow: user.role == owner AND dao.level != A1 +``` + +*A1 не може бути розформовано — це корінь міста.* + +--- + +# 6. Взаємодія з агентами + +Федерація дозволяє делегувати агентів із SuperDAO вниз: + +### Приклади: + +* A1 (DAARWIZZ) може давати обмежені функції платформам A2. +* A2-платформи можуть давати community-агентам A3 частину можливостей (наприклад, аналітику, інтеграції). + +### Принцип: + +* Дозволи йдуть **зверху вниз**, але ніколи **знизу вверх**. +* A3/A4 не можуть впливати на A1/A2. + +--- + +# 7. Взаємодія з токеномікою + +Федерація не змінює фундаментальні правила доступу. + +Але SuperDAO може: + +* встановлювати локальні комісії +* вимагати DAAR або DAARION для участі в підфедерації +* давати знижки або преференції учасникам федерації + +--- + +# 8. Публічні та приватні федерації + +## 8.1 Публічна федерація (A1 → A2 → A3) + +* частина дерева видима у каталозі DAARION.city +* DAO можуть добровільно приєднуватися + +## 8.2 Приватна федерація (A4 ↔ A4) + +* не показується публічно +* власні правила +* може будуватися для бізнесів, клубів, дослідницьких груп + +--- + +# 9. Використання цього документа + +Цей документ потрібен для: + +* моделювання дерева MicroDAO +* проєктування Admin Console (розділ Federation) +* впровадження PDP-політок +* побудови майбутньої механіки федерацій у DAOFactory + +Федерація — це ключова функція децентралізованого міста: вона дозволяє DAO організовуватися в більші структури без втрати автономності. + +--- + +## 10. Integration with Other Docs + +Цей документ інтегрується з: + +- `microdao-architecture.md` — архітектура A1-A4 +- `pdp_access.md` — PDP та система доступів +- `agents.md` — агенти та їх права +- `microdao-admin-console.md` — адмін-панель +- `api.md` — API для федерацій + +--- + +## 11. Changelog + +### v1.0.0 — 2024-11-14 +- Початкова версія специфікації SuperDAO Federation +- Додано модель SuperDAO/MemberDAO +- Додано операції: join, leave, create, dissolve +- Додано ролі в федерації +- Додано PDP-політики для федерацій +- Додано взаємодію з агентами та токеномікою + +--- + +**Версія:** 1.0.0 +**Останнє оновлення:** 2024-11-14 +*Документ готовий до інтеграції у Cursor, GitHub або будь-який інший проект.* + + diff --git a/docs/tokenomics/city-tokenomics.md b/docs/tokenomics/city-tokenomics.md new file mode 100644 index 00000000..c5dcdedf --- /dev/null +++ b/docs/tokenomics/city-tokenomics.md @@ -0,0 +1,393 @@ +--- +title: City Tokenomics +version: 1.0.0 +status: canonical +last_updated: 2024-11-14 +--- + +> **Цей документ є актуальною версією токеноміки міста.** +> Усі попередні документи з токеноміки вважаються застарілими. + +# City Tokenomics — DAARION.city (Integration-Ready) + +**Цей документ є обов'язковим для додавання у репозиторій під час інтеграції MicroDAO у DAARION.city.** + +DAARION.city — це **перше MicroDAO у мережі** (A1-рівень), що очолюється системним агентом **DAARWIZZ**. Усі інші компоненти міської екосистеми — це наступні рівні MicroDAO-структури. + +--- + +## 1. Загальний огляд токеноміки міста + +Місто працює на **двоєдиній моделі токенів**: + +- **DAAR** — утиліті-токен (оплата сервісів, платформи, транзакції) +- **DAARION** — civic / identity токен (громадянство, доступ, статус) + +Ця пара створює повноцінну економіку доступів та взаємодій. + +--- + +## 2. DAAR — Utility Token + +### Використання + +- оплата товарів та послуг +- взаємодія з міськими платформами (GreenFood, EnergyUnion, WaterUnion тощо) +- оплата агентів +- оплата створення та роботи microDAO +- внутрішні транзакції між користувачами та DAO + +**DAAR — енергія міської економіки.** + +### Tokenomics + +- динамічний випуск +- джерело: DAARsales (USDT/POL → DAAR) +- комісія на транзакції DAAR: **0.5% → DAO Share Pool** +- APR: **20%** (в стейкінгу) + +--- + +## 3. DAARION — Civic Token / Identity Token + +### Використання + +- підтвердження статусу громадянина міста +- доступ до глибинних рівнів інфраструктури +- ліцензійний ключ для створення платформ +- доступ до advanced API та інтеграцій + +**DAARION — статус, права і розширені можливості.** + +### Tokenomics + +- стартова емісія: **500 DAARION** +- дефляція: **5% burn** при продажу +- APR: **4% + частка від комісій DAAR** +- джерело: DAARIONsales (100 DAAR → 1 DAARION) + +--- + +## 4. Рівні доступу за DAAR та DAARION + +### 4.1 Звичайні користувачі / Покупці + +- доступ до платформ: **лише наявність DAAR** +- DAARION не потрібен + +### 4.2 Постачальники / Вендори + +- доступ до роботи на платформах: **0.01 DAARION у стейкінгу** + +### 4.3 Створення платформ + +- право створити платформу: **1 DAARION у стейкінгу** + +### 4.4 Створення MicroDAO + +- доступ: **1 DAAR або 0.01 DAARION** + +--- + +## 4.5 MicroDAO Tokens (Local Layer) + +Кожне microDAO має власні три токени, емітовані DAOFactory: + +| Token | Function | Activation | +| -------- | ---------------------------------------------- | ---------------- | +| **GOV** | governance / voting key inside DAO | cost: **1 DAAR** | +| **UTIL** | внутрішня економіка DAO (операції, винагороди) | cost: **1 DAAR** | +| **REP** | репутаційний токен (невзаємозамінний) | cost: **1 DAAR** | + +**Emission model:** +- DAO може емітувати будь-яку кількість, згідно з власною політикою +- DAOFactory перевіряє баланс користувача (1 DAAR або 0.01 DAARION) +- Емісія gas-free (off-chain), періодична синхронізація on-chain + +**Economic Flow Inside MicroDAO:** +```text +DAAR → eMINT GOV/UTIL/REP → DAO Operations → UTIL Rewards → TokenBridge → DAAR +``` + +--- + +## 5. Ієрархія MicroDAO у DAARION.city + +**ДАЖЕСТВА МІСТА — ЦЕ ДЕРЕВО MICRODAO.** + +### **A1 — DAARION.city (перше MicroDAO)** + +- кореневе DAO міста +- очолюється агентом **DAARWIZZ** +- керує реєстрами, платформами, правами доступу + +### **A2 — Міські платформи (другий рівень)** + +Платформи є MicroDAO другого порядку. + +Поточний список: + +- **Helion** — енергетика +- **GreenFood ERP** — агро/харчові продукти +- **Soul** — соціальна система +- **Dario** — міські сервіси +- **Nutra** — здоровʼя і нутриція +- **WaterAGI** — вода та очищення + +Кожна платформа має власних агентів. + +### **A3 — Публічні MicroDAO (третій рівень)** + +- не підпорядковуються платформам +- доступні для всіх резидентів +- можуть взаємодіяти з A1 та A2 через DAAR + +### **A4/F4 — Приватні MicroDAO (четвертий рівень)** + +- повна автономія +- не мають підлеглості іншим DAO +- доступні лише за запрошенням + +--- + +## 6. Логіка доступів на основі DAARION (Framework) + +**Більше DAARION = більше можливостей**, зокрема: + +- доступ до інституційних функцій +- доступ до створення платформ +- доступ до глибоких API +- доступ до керування DAO високого рівня +- більший пріоритет у DAGI + +Це ядро формує модель: **Civic Token → Access Tier → City Expansion**. + +--- + +## 7. Патерн розвитку токеноміки + +Система спроектована так, що нові рівні доступу та права можуть додаватися з розвитком: + +- запуск нових платформ +- нові типи агентів +- DAO-функції наступних фаз +- нові MetaDAO рівні + +Токен DAARION — універсальний ключ для майбутньої інфраструктурної експансії. + +--- + +## 8. Використання DAAR і DAARION у інтеграції MicroDAO + +При підключенні MicroDAO до DAARION.city ця сторінка повинна бути додана у розділ: + +```text +docs/tokenomics/city-tokenomics.md +``` + +MicroDAO використовує ці правила для: + +- валідації доступу користувачів +- роботи DAOFactory +- роботи агентів DAARWIZZ +- контролю доступу до платформ +- ліцензування сервісів + +DAARION.city — це **кореневе MicroDAO (A1)**, а вся міська екосистема — це дерево MicroDAO. + +--- + +## 9. Інтеграція з іншими документами + +Цей документ доповнює: + +- `DAARION_city_integration.md` — архітектура інтеграції +- `50_daarion_city_website_integration.md` — інтеграція з сайтом +- `32_policy_service_PDP_design.md` — PDP token-gating +- `49_wallet_rwa_payouts_claims.md` — Wallet Service + +> **Примітка:** Попередній документ `tokenomics/README.md` перенесено в `docs/_archive/tokenomics_legacy_v0.md`. Вся актуальна інформація об'єднана в цьому канонічному документі. + +--- + +## 10. Завдання для Cursor + +```text +You are a senior blockchain/full-stack engineer. Implement City Tokenomics using: +- docs/tokenomics/city-tokenomics.md (⭐ CANONICAL) +- 32_policy_service_PDP_design.md +- 49_wallet_rwa_payouts_claims.md + +Tasks: +1) Implement access tier validation (DAAR ≥ 1.00 or DAARION ≥ 0.01 for MicroDAO creation). +2) Implement platform creation access (DAARION ≥ 1.00 staked). +3) Implement vendor access (DAARION ≥ 0.01 staked). +4) Implement DAARION.city as A1-level MicroDAO (root DAO). +5) Implement platform hierarchy (A2-level: Helion, GreenFood, Soul, Dario, Nutra, WaterAGI). +6) Implement public MicroDAO (A3-level) and private MicroDAO (A4-level) access rules. +7) Integrate DAARWIZZ agent as system agent for A1-level. +8) Add DAAR/DAARION balance checks in PDP for all access levels. +9) Implement tier-based access logic (more DAARION = more capabilities). +10) Add platform licensing system (1 DAARION staked = platform creation right). + +Output: +- list of modified files +- diff +- summary +``` + +--- + +## 11. Підсумок + +- **DAAR** = універсальна енергія економіки +- **DAARION** = статус, рівні доступу, громадянство +- платформи належать рівню A2 +- публічні MicroDAO — A3 +- приватні MicroDAO — A4 +- DAARION.city — перше, головне DAO (A1), центр усієї мережі + +Це формує стійку багаторівневу архітектуру міста та екосистеми MicroDAO. + +--- + +## 12. Fees & Costs (MicroDAO Economics) + +### City Fees (denominated in DAAR) + +| Action | Cost | +| ------------------------------- | ------------- | +| Створення microDAO | **1 DAAR** | +| Емісія GOV | **1 DAAR** | +| Емісія UTIL | **1 DAAR** | +| Емісія REP | **1 DAAR** | +| Підключення агента DAGI | **0.25 DAAR** | +| Реєстрація DAO у каталозі міста | **0.05 DAAR** | + +**90% DAO / 10% City Rule:** Діє для DePIN-DAO та DAO, що працюють з постійною DAGI-активністю. + +--- + +## 13. Staking & Rewards + +### DAAR Staking (APR: 20%) +- Rewards → DAAR +- Смартконтракт: `APRStaking` + +### DAARION Staking (APR: 4% + revenue share) +- Rewards → DAAR +- Частка від DAAR-комісій (0.5%) розподіляється пропорційно до стейку DAARION +- Смартконтракт: `DAARDistributor` + +--- + +## 14. Token Bridges & Onboarding + +### Flow +```text +USDT/POL → DAAR → DAARION → DAO → DAGI → Rewards in DAAR +``` + +### Components + +| Component | Function | +| ----------------- | ------------------------------ | +| **DAARsales** | Купівля DAAR за USDT/POL | +| **DAARIONsales** | 100 DAAR → 1 DAARION | +| **DAOFactory** | Створення MicroDAO | +| **TokenBridge** | UTIL ↔ DAAR обмін | +| **DAGI Registry** | Реєстрація DAO, агентів, знань | + +### Primary Access Flow (Onboarding) + +1. **Balance Check** — Wallet Agent перевіряє: ≥ 1 DAAR **або** ≥ 0.01 DAARION +2. **Eligibility** — `eligible_for_MicroDAO = true` +3. **DAO Creation (DAOFactory)** — списується 1 DAAR, DAO отримує унікальний `dao_id` +4. **Token Activation** — користувач може емітувати GOV / UTIL / REP (1 DAAR за кожен тип) +5. **DAGI Sync** — DAO реєструється у DAGI Registry + +--- + +## 15. Integration Points (Architecture) + +### Wallet Service +- баланси DAAR / DAARION +- fee accounting (0.5%) +- DAOFactory calls +- staking +- token exchange + +### PDP (Access Control) +- наявність токенів +- права доступу до DAO +- gas-free стани +- DAO governance rules + +### Agents +**Можуть:** +- працювати з UTIL +- виконувати дії DAO +- розподіляти REP +- взаємодіяти з DAGI Registry + +**Не можуть:** +- змінювати баланси DAAR/DAARION +- створювати DAO без користувача +- змінювати тарифні плани + +### DAGI Registry +- DAO metadata +- Agent slots +- Knowledge mining rewards +- Off-chain/on-chain settlement + +--- + +## 16. Security Rules + +- тільки Owner може виконувати DAOFactory +- DAAR/DAARION операції виконуються он-чейн +- UTIL/GOV/REP — off-chain з періодичною валідацією +- burn 5% DAARION при продажі — обов'язковий +- reentrancy guard +- мінімальна кількість GOV для голосування встановлюється DAO + +--- + +## 17. MVP Scope (Required for Launch) + +### Must-have +- DAAR / DAARION баланс-чек +- DAOFactory (1 DAAR → create) +- eMINT GOV / UTIL / REP +- TokenBridge (UTIL ↔ DAAR) +- DAARsales, DAARIONsales +- Basic staking (DAAR, DAARION) +- PDP token-gating +- Wallet v1 + +### Optional MVP+ +- Knowledge Mining Rewards +- REP reputation logic +- Multi-DAO bridges + +--- + +## 18. Changelog + +### v1.0.0 — 2024-11-14 +- Початкова версія токеноміки міста +- Додано DAAR та DAARION токени +- Додано ієрархію MicroDAO (A1-A4) +- Додано рівні доступу +- Додано GOV/UTIL/REP токени для microDAO +- Додано DAOFactory та TokenBridge +- Додано staking та rewards +- Додано security rules + +--- + +**Версія:** 1.0.0 +**Останнє оновлення:** 2024-11-14 +*Документ готовий до інтеграції у Cursor, GitHub або будь-який інший проект.* + diff --git a/index.html b/index.html new file mode 100644 index 00000000..eaf1463d --- /dev/null +++ b/index.html @@ -0,0 +1,14 @@ + + + + + + + MicroDAO - MVP + + +
+ + + + diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 00000000..cd3f6282 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,4524 @@ +{ + "name": "microdao-mvp", + "version": "1.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "microdao-mvp", + "version": "1.0.0", + "dependencies": { + "lucide-react": "^0.294.0", + "react": "^18.2.0", + "react-dom": "^18.2.0", + "react-router-dom": "^6.20.0" + }, + "devDependencies": { + "@types/react": "^18.2.43", + "@types/react-dom": "^18.2.17", + "@typescript-eslint/eslint-plugin": "^6.14.0", + "@typescript-eslint/parser": "^6.14.0", + "@vitejs/plugin-react": "^4.2.1", + "autoprefixer": "^10.4.16", + "eslint": "^8.55.0", + "eslint-plugin-react-hooks": "^4.6.0", + "eslint-plugin-react-refresh": "^0.4.5", + "postcss": "^8.4.32", + "tailwindcss": "^3.3.6", + "typescript": "^5.2.2", + "vite": "^5.0.8" + } + }, + "node_modules/@alloc/quick-lru": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/@alloc/quick-lru/-/quick-lru-5.2.0.tgz", + "integrity": "sha512-UrcABB+4bUrFABwbluTIBErXwvbsU/V7TZWfmbgJfbkwiBuziS9gxdODUyuiecfdGQ85jglMW6juS3+z5TsKLw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/@babel/code-frame": { + "version": "7.27.1", + "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.27.1.tgz", + "integrity": "sha512-cjQ7ZlQ0Mv3b47hABuTevyTuYN4i+loJKGeV9flcCgIK37cCXRh+L1bd3iBHlynerhQ7BhCkn2BPbQUL+rGqFg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/helper-validator-identifier": "^7.27.1", + "js-tokens": "^4.0.0", + "picocolors": "^1.1.1" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/compat-data": { + "version": "7.28.5", + "resolved": "https://registry.npmjs.org/@babel/compat-data/-/compat-data-7.28.5.tgz", + "integrity": "sha512-6uFXyCayocRbqhZOB+6XcuZbkMNimwfVGFji8CTZnCzOHVGvDqzvitu1re2AU5LROliz7eQPhB8CpAMvnx9EjA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/core": { + "version": "7.28.5", + "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.28.5.tgz", + "integrity": "sha512-e7jT4DxYvIDLk1ZHmU/m/mB19rex9sv0c2ftBtjSBv+kVM/902eh0fINUzD7UwLLNR+jU585GxUJ8/EBfAM5fw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/code-frame": "^7.27.1", + "@babel/generator": "^7.28.5", + "@babel/helper-compilation-targets": "^7.27.2", + "@babel/helper-module-transforms": "^7.28.3", + "@babel/helpers": "^7.28.4", + "@babel/parser": "^7.28.5", + "@babel/template": "^7.27.2", + "@babel/traverse": "^7.28.5", + "@babel/types": "^7.28.5", + "@jridgewell/remapping": "^2.3.5", + "convert-source-map": "^2.0.0", + "debug": "^4.1.0", + "gensync": "^1.0.0-beta.2", + "json5": "^2.2.3", + "semver": "^6.3.1" + }, + "engines": { + "node": ">=6.9.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/babel" + } + }, + "node_modules/@babel/core/node_modules/semver": { + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==", + "dev": true, + "license": "ISC", + "bin": { + "semver": "bin/semver.js" + } + }, + "node_modules/@babel/generator": { + "version": "7.28.5", + "resolved": "https://registry.npmjs.org/@babel/generator/-/generator-7.28.5.tgz", + "integrity": "sha512-3EwLFhZ38J4VyIP6WNtt2kUdW9dokXA9Cr4IVIFHuCpZ3H8/YFOl5JjZHisrn1fATPBmKKqXzDFvh9fUwHz6CQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/parser": "^7.28.5", + "@babel/types": "^7.28.5", + "@jridgewell/gen-mapping": "^0.3.12", + "@jridgewell/trace-mapping": "^0.3.28", + "jsesc": "^3.0.2" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-compilation-targets": { + "version": "7.27.2", + "resolved": "https://registry.npmjs.org/@babel/helper-compilation-targets/-/helper-compilation-targets-7.27.2.tgz", + "integrity": "sha512-2+1thGUUWWjLTYTHZWK1n8Yga0ijBz1XAhUXcKy81rd5g6yh7hGqMp45v7cadSbEHc9G3OTv45SyneRN3ps4DQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/compat-data": "^7.27.2", + "@babel/helper-validator-option": "^7.27.1", + "browserslist": "^4.24.0", + "lru-cache": "^5.1.1", + "semver": "^6.3.1" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-compilation-targets/node_modules/semver": { + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==", + "dev": true, + "license": "ISC", + "bin": { + "semver": "bin/semver.js" + } + }, + "node_modules/@babel/helper-globals": { + "version": "7.28.0", + "resolved": "https://registry.npmjs.org/@babel/helper-globals/-/helper-globals-7.28.0.tgz", + "integrity": "sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-module-imports": { + "version": "7.27.1", + "resolved": "https://registry.npmjs.org/@babel/helper-module-imports/-/helper-module-imports-7.27.1.tgz", + "integrity": "sha512-0gSFWUPNXNopqtIPQvlD5WgXYI5GY2kP2cCvoT8kczjbfcfuIljTbcWrulD1CIPIX2gt1wghbDy08yE1p+/r3w==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/traverse": "^7.27.1", + "@babel/types": "^7.27.1" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-module-transforms": { + "version": "7.28.3", + "resolved": "https://registry.npmjs.org/@babel/helper-module-transforms/-/helper-module-transforms-7.28.3.tgz", + "integrity": "sha512-gytXUbs8k2sXS9PnQptz5o0QnpLL51SwASIORY6XaBKF88nsOT0Zw9szLqlSGQDP/4TljBAD5y98p2U1fqkdsw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/helper-module-imports": "^7.27.1", + "@babel/helper-validator-identifier": "^7.27.1", + "@babel/traverse": "^7.28.3" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0" + } + }, + "node_modules/@babel/helper-plugin-utils": { + "version": "7.27.1", + "resolved": "https://registry.npmjs.org/@babel/helper-plugin-utils/-/helper-plugin-utils-7.27.1.tgz", + "integrity": "sha512-1gn1Up5YXka3YYAHGKpbideQ5Yjf1tDa9qYcgysz+cNCXukyLl6DjPXhD3VRwSb8c0J9tA4b2+rHEZtc6R0tlw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-string-parser": { + "version": "7.27.1", + "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz", + "integrity": "sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-validator-identifier": { + "version": "7.28.5", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.28.5.tgz", + "integrity": "sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-validator-option": { + "version": "7.27.1", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-option/-/helper-validator-option-7.27.1.tgz", + "integrity": "sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helpers": { + "version": "7.28.4", + "resolved": "https://registry.npmjs.org/@babel/helpers/-/helpers-7.28.4.tgz", + "integrity": "sha512-HFN59MmQXGHVyYadKLVumYsA9dBFun/ldYxipEjzA4196jpLZd8UjEEBLkbEkvfYreDqJhZxYAWFPtrfhNpj4w==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/template": "^7.27.2", + "@babel/types": "^7.28.4" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/parser": { + "version": "7.28.5", + "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.28.5.tgz", + "integrity": "sha512-KKBU1VGYR7ORr3At5HAtUQ+TV3SzRCXmA/8OdDZiLDBIZxVyzXuztPjfLd3BV1PRAQGCMWWSHYhL0F8d5uHBDQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/types": "^7.28.5" + }, + "bin": { + "parser": "bin/babel-parser.js" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@babel/plugin-transform-react-jsx-self": { + "version": "7.27.1", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-react-jsx-self/-/plugin-transform-react-jsx-self-7.27.1.tgz", + "integrity": "sha512-6UzkCs+ejGdZ5mFFC/OCUrv028ab2fp1znZmCZjAOBKiBK2jXD1O+BPSfX8X2qjJ75fZBMSnQn3Rq2mrBJK2mw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/helper-plugin-utils": "^7.27.1" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/plugin-transform-react-jsx-source": { + "version": "7.27.1", + "resolved": "https://registry.npmjs.org/@babel/plugin-transform-react-jsx-source/-/plugin-transform-react-jsx-source-7.27.1.tgz", + "integrity": "sha512-zbwoTsBruTeKB9hSq73ha66iFeJHuaFkUbwvqElnygoNbj/jHRsSeokowZFN3CZ64IvEqcmmkVe89OPXc7ldAw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/helper-plugin-utils": "^7.27.1" + }, + "engines": { + "node": ">=6.9.0" + }, + "peerDependencies": { + "@babel/core": "^7.0.0-0" + } + }, + "node_modules/@babel/template": { + "version": "7.27.2", + "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.27.2.tgz", + "integrity": "sha512-LPDZ85aEJyYSd18/DkjNh4/y1ntkE5KwUHWTiqgRxruuZL2F1yuHligVHLvcHY2vMHXttKFpJn6LwfI7cw7ODw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/code-frame": "^7.27.1", + "@babel/parser": "^7.27.2", + "@babel/types": "^7.27.1" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/traverse": { + "version": "7.28.5", + "resolved": "https://registry.npmjs.org/@babel/traverse/-/traverse-7.28.5.tgz", + "integrity": "sha512-TCCj4t55U90khlYkVV/0TfkJkAkUg3jZFA3Neb7unZT8CPok7iiRfaX0F+WnqWqt7OxhOn0uBKXCw4lbL8W0aQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/code-frame": "^7.27.1", + "@babel/generator": "^7.28.5", + "@babel/helper-globals": "^7.28.0", + "@babel/parser": "^7.28.5", + "@babel/template": "^7.27.2", + "@babel/types": "^7.28.5", + "debug": "^4.3.1" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/types": { + "version": "7.28.5", + "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.28.5.tgz", + "integrity": "sha512-qQ5m48eI/MFLQ5PxQj4PFaprjyCTLI37ElWMmNs0K8Lk3dVeOdNpB3ks8jc7yM5CDmVC73eMVk/trk3fgmrUpA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/helper-string-parser": "^7.27.1", + "@babel/helper-validator-identifier": "^7.28.5" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@esbuild/aix-ppc64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.21.5.tgz", + "integrity": "sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/android-arm": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.21.5.tgz", + "integrity": "sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/android-arm64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.21.5.tgz", + "integrity": "sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/android-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.21.5.tgz", + "integrity": "sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/darwin-arm64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.21.5.tgz", + "integrity": "sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/darwin-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.21.5.tgz", + "integrity": "sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/freebsd-arm64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.21.5.tgz", + "integrity": "sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/freebsd-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.21.5.tgz", + "integrity": "sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-arm": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.21.5.tgz", + "integrity": "sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-arm64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.21.5.tgz", + "integrity": "sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-ia32": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.21.5.tgz", + "integrity": "sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-loong64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.21.5.tgz", + "integrity": "sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-mips64el": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.21.5.tgz", + "integrity": "sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-ppc64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.21.5.tgz", + "integrity": "sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-riscv64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.21.5.tgz", + "integrity": "sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-s390x": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.21.5.tgz", + "integrity": "sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.21.5.tgz", + "integrity": "sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/netbsd-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.21.5.tgz", + "integrity": "sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/openbsd-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.21.5.tgz", + "integrity": "sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/sunos-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.21.5.tgz", + "integrity": "sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/win32-arm64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.21.5.tgz", + "integrity": "sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/win32-ia32": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.21.5.tgz", + "integrity": "sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/win32-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.21.5.tgz", + "integrity": "sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@eslint-community/eslint-utils": { + "version": "4.9.0", + "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.9.0.tgz", + "integrity": "sha512-ayVFHdtZ+hsq1t2Dy24wCmGXGe4q9Gu3smhLYALJrr473ZH27MsnSL+LKUlimp4BWJqMDMLmPpx/Q9R3OAlL4g==", + "dev": true, + "license": "MIT", + "dependencies": { + "eslint-visitor-keys": "^3.4.3" + }, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + }, + "peerDependencies": { + "eslint": "^6.0.0 || ^7.0.0 || >=8.0.0" + } + }, + "node_modules/@eslint-community/regexpp": { + "version": "4.12.2", + "resolved": "https://registry.npmjs.org/@eslint-community/regexpp/-/regexpp-4.12.2.tgz", + "integrity": "sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^12.0.0 || ^14.0.0 || >=16.0.0" + } + }, + "node_modules/@eslint/eslintrc": { + "version": "2.1.4", + "resolved": "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-2.1.4.tgz", + "integrity": "sha512-269Z39MS6wVJtsoUl10L60WdkhJVdPG24Q4eZTH3nnF6lpvSShEK3wQjDX9JRWAUPvPh7COouPpU9IrqaZFvtQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "ajv": "^6.12.4", + "debug": "^4.3.2", + "espree": "^9.6.0", + "globals": "^13.19.0", + "ignore": "^5.2.0", + "import-fresh": "^3.2.1", + "js-yaml": "^4.1.0", + "minimatch": "^3.1.2", + "strip-json-comments": "^3.1.1" + }, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/@eslint/eslintrc/node_modules/brace-expansion": { + "version": "1.1.12", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz", + "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==", + "dev": true, + "license": "MIT", + "dependencies": { + "balanced-match": "^1.0.0", + "concat-map": "0.0.1" + } + }, + "node_modules/@eslint/eslintrc/node_modules/minimatch": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz", + "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==", + "dev": true, + "license": "ISC", + "dependencies": { + "brace-expansion": "^1.1.7" + }, + "engines": { + "node": "*" + } + }, + "node_modules/@eslint/js": { + "version": "8.57.1", + "resolved": "https://registry.npmjs.org/@eslint/js/-/js-8.57.1.tgz", + "integrity": "sha512-d9zaMRSTIKDLhctzH12MtXvJKSSUhaHcjV+2Z+GK+EEY7XKpP5yR4x+N3TAcHTcu963nIr+TMcCb4DBCYX1z6Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + } + }, + "node_modules/@humanwhocodes/config-array": { + "version": "0.13.0", + "resolved": "https://registry.npmjs.org/@humanwhocodes/config-array/-/config-array-0.13.0.tgz", + "integrity": "sha512-DZLEEqFWQFiyK6h5YIeynKx7JlvCYWL0cImfSRXZ9l4Sg2efkFGTuFf6vzXjK1cq6IYkU+Eg/JizXw+TD2vRNw==", + "deprecated": "Use @eslint/config-array instead", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@humanwhocodes/object-schema": "^2.0.3", + "debug": "^4.3.1", + "minimatch": "^3.0.5" + }, + "engines": { + "node": ">=10.10.0" + } + }, + "node_modules/@humanwhocodes/config-array/node_modules/brace-expansion": { + "version": "1.1.12", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz", + "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==", + "dev": true, + "license": "MIT", + "dependencies": { + "balanced-match": "^1.0.0", + "concat-map": "0.0.1" + } + }, + "node_modules/@humanwhocodes/config-array/node_modules/minimatch": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz", + "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==", + "dev": true, + "license": "ISC", + "dependencies": { + "brace-expansion": "^1.1.7" + }, + "engines": { + "node": "*" + } + }, + "node_modules/@humanwhocodes/module-importer": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@humanwhocodes/module-importer/-/module-importer-1.0.1.tgz", + "integrity": "sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=12.22" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/nzakas" + } + }, + "node_modules/@humanwhocodes/object-schema": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/@humanwhocodes/object-schema/-/object-schema-2.0.3.tgz", + "integrity": "sha512-93zYdMES/c1D69yZiKDBj0V24vqNzB/koF26KPaagAfd3P/4gUlh3Dys5ogAK+Exi9QyzlD8x/08Zt7wIKcDcA==", + "deprecated": "Use @eslint/object-schema instead", + "dev": true, + "license": "BSD-3-Clause" + }, + "node_modules/@isaacs/cliui": { + "version": "8.0.2", + "resolved": "https://registry.npmjs.org/@isaacs/cliui/-/cliui-8.0.2.tgz", + "integrity": "sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==", + "dev": true, + "license": "ISC", + "dependencies": { + "string-width": "^5.1.2", + "string-width-cjs": "npm:string-width@^4.2.0", + "strip-ansi": "^7.0.1", + "strip-ansi-cjs": "npm:strip-ansi@^6.0.1", + "wrap-ansi": "^8.1.0", + "wrap-ansi-cjs": "npm:wrap-ansi@^7.0.0" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/@isaacs/cliui/node_modules/ansi-regex": { + "version": "6.2.2", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz", + "integrity": "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-regex?sponsor=1" + } + }, + "node_modules/@isaacs/cliui/node_modules/strip-ansi": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.1.2.tgz", + "integrity": "sha512-gmBGslpoQJtgnMAvOVqGZpEz9dyoKTCzy2nfz/n8aIFhN/jCE/rCmcxabB6jOOHV+0WNnylOxaxBQPSvcWklhA==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-regex": "^6.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/strip-ansi?sponsor=1" + } + }, + "node_modules/@jridgewell/gen-mapping": { + "version": "0.3.13", + "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz", + "integrity": "sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/sourcemap-codec": "^1.5.0", + "@jridgewell/trace-mapping": "^0.3.24" + } + }, + "node_modules/@jridgewell/remapping": { + "version": "2.3.5", + "resolved": "https://registry.npmjs.org/@jridgewell/remapping/-/remapping-2.3.5.tgz", + "integrity": "sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/gen-mapping": "^0.3.5", + "@jridgewell/trace-mapping": "^0.3.24" + } + }, + "node_modules/@jridgewell/resolve-uri": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz", + "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@jridgewell/sourcemap-codec": { + "version": "1.5.5", + "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz", + "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==", + "dev": true, + "license": "MIT" + }, + "node_modules/@jridgewell/trace-mapping": { + "version": "0.3.31", + "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz", + "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/resolve-uri": "^3.1.0", + "@jridgewell/sourcemap-codec": "^1.4.14" + } + }, + "node_modules/@nodelib/fs.scandir": { + "version": "2.1.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", + "integrity": "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@nodelib/fs.stat": "2.0.5", + "run-parallel": "^1.1.9" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/@nodelib/fs.stat": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz", + "integrity": "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 8" + } + }, + "node_modules/@nodelib/fs.walk": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz", + "integrity": "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@nodelib/fs.scandir": "2.1.5", + "fastq": "^1.6.0" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/@pkgjs/parseargs": { + "version": "0.11.0", + "resolved": "https://registry.npmjs.org/@pkgjs/parseargs/-/parseargs-0.11.0.tgz", + "integrity": "sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==", + "dev": true, + "license": "MIT", + "optional": true, + "engines": { + "node": ">=14" + } + }, + "node_modules/@remix-run/router": { + "version": "1.23.0", + "resolved": "https://registry.npmjs.org/@remix-run/router/-/router-1.23.0.tgz", + "integrity": "sha512-O3rHJzAQKamUz1fvE0Qaw0xSFqsA/yafi2iqeE0pvdFtCO1viYx8QL6f3Ln/aCCTLxs68SLf0KPM9eSeM8yBnA==", + "license": "MIT", + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/@rolldown/pluginutils": { + "version": "1.0.0-beta.27", + "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-beta.27.tgz", + "integrity": "sha512-+d0F4MKMCbeVUJwG96uQ4SgAznZNSq93I3V+9NHA4OpvqG8mRCpGdKmK8l/dl02h2CCDHwW2FqilnTyDcAnqjA==", + "dev": true, + "license": "MIT" + }, + "node_modules/@rollup/rollup-android-arm-eabi": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.53.2.tgz", + "integrity": "sha512-yDPzwsgiFO26RJA4nZo8I+xqzh7sJTZIWQOxn+/XOdPE31lAvLIYCKqjV+lNH/vxE2L2iH3plKxDCRK6i+CwhA==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ] + }, + "node_modules/@rollup/rollup-android-arm64": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.53.2.tgz", + "integrity": "sha512-k8FontTxIE7b0/OGKeSN5B6j25EuppBcWM33Z19JoVT7UTXFSo3D9CdU39wGTeb29NO3XxpMNauh09B+Ibw+9g==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ] + }, + "node_modules/@rollup/rollup-darwin-arm64": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.53.2.tgz", + "integrity": "sha512-A6s4gJpomNBtJ2yioj8bflM2oogDwzUiMl2yNJ2v9E7++sHrSrsQ29fOfn5DM/iCzpWcebNYEdXpaK4tr2RhfQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@rollup/rollup-darwin-x64": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.53.2.tgz", + "integrity": "sha512-e6XqVmXlHrBlG56obu9gDRPW3O3hLxpwHpLsBJvuI8qqnsrtSZ9ERoWUXtPOkY8c78WghyPHZdmPhHLWNdAGEw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@rollup/rollup-freebsd-arm64": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.53.2.tgz", + "integrity": "sha512-v0E9lJW8VsrwPux5Qe5CwmH/CF/2mQs6xU1MF3nmUxmZUCHazCjLgYvToOk+YuuUqLQBio1qkkREhxhc656ViA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ] + }, + "node_modules/@rollup/rollup-freebsd-x64": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.53.2.tgz", + "integrity": "sha512-ClAmAPx3ZCHtp6ysl4XEhWU69GUB1D+s7G9YjHGhIGCSrsg00nEGRRZHmINYxkdoJehde8VIsDC5t9C0gb6yqA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ] + }, + "node_modules/@rollup/rollup-linux-arm-gnueabihf": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.53.2.tgz", + "integrity": "sha512-EPlb95nUsz6Dd9Qy13fI5kUPXNSljaG9FiJ4YUGU1O/Q77i5DYFW5KR8g1OzTcdZUqQQ1KdDqsTohdFVwCwjqg==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-arm-musleabihf": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.53.2.tgz", + "integrity": "sha512-BOmnVW+khAUX+YZvNfa0tGTEMVVEerOxN0pDk2E6N6DsEIa2Ctj48FOMfNDdrwinocKaC7YXUZ1pHlKpnkja/Q==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-arm64-gnu": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.53.2.tgz", + "integrity": "sha512-Xt2byDZ+6OVNuREgBXr4+CZDJtrVso5woFtpKdGPhpTPHcNG7D8YXeQzpNbFRxzTVqJf7kvPMCub/pcGUWgBjA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-arm64-musl": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.53.2.tgz", + "integrity": "sha512-+LdZSldy/I9N8+klim/Y1HsKbJ3BbInHav5qE9Iy77dtHC/pibw1SR/fXlWyAk0ThnpRKoODwnAuSjqxFRDHUQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-loong64-gnu": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.53.2.tgz", + "integrity": "sha512-8ms8sjmyc1jWJS6WdNSA23rEfdjWB30LH8Wqj0Cqvv7qSHnvw6kgMMXRdop6hkmGPlyYBdRPkjJnj3KCUHV/uQ==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-ppc64-gnu": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.53.2.tgz", + "integrity": "sha512-3HRQLUQbpBDMmzoxPJYd3W6vrVHOo2cVW8RUo87Xz0JPJcBLBr5kZ1pGcQAhdZgX9VV7NbGNipah1omKKe23/g==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-riscv64-gnu": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.53.2.tgz", + "integrity": "sha512-fMjKi+ojnmIvhk34gZP94vjogXNNUKMEYs+EDaB/5TG/wUkoeua7p7VCHnE6T2Tx+iaghAqQX8teQzcvrYpaQA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-riscv64-musl": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.53.2.tgz", + "integrity": "sha512-XuGFGU+VwUUV5kLvoAdi0Wz5Xbh2SrjIxCtZj6Wq8MDp4bflb/+ThZsVxokM7n0pcbkEr2h5/pzqzDYI7cCgLQ==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-s390x-gnu": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.53.2.tgz", + "integrity": "sha512-w6yjZF0P+NGzWR3AXWX9zc0DNEGdtvykB03uhonSHMRa+oWA6novflo2WaJr6JZakG2ucsyb+rvhrKac6NIy+w==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-x64-gnu": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.53.2.tgz", + "integrity": "sha512-yo8d6tdfdeBArzC7T/PnHd7OypfI9cbuZzPnzLJIyKYFhAQ8SvlkKtKBMbXDxe1h03Rcr7u++nFS7tqXz87Gtw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-x64-musl": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.53.2.tgz", + "integrity": "sha512-ah59c1YkCxKExPP8O9PwOvs+XRLKwh/mV+3YdKqQ5AMQ0r4M4ZDuOrpWkUaqO7fzAHdINzV9tEVu8vNw48z0lA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-openharmony-arm64": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.53.2.tgz", + "integrity": "sha512-4VEd19Wmhr+Zy7hbUsFZ6YXEiP48hE//KPLCSVNY5RMGX2/7HZ+QkN55a3atM1C/BZCGIgqN+xrVgtdak2S9+A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ] + }, + "node_modules/@rollup/rollup-win32-arm64-msvc": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.53.2.tgz", + "integrity": "sha512-IlbHFYc/pQCgew/d5fslcy1KEaYVCJ44G8pajugd8VoOEI8ODhtb/j8XMhLpwHCMB3yk2J07ctup10gpw2nyMA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rollup/rollup-win32-ia32-msvc": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.53.2.tgz", + "integrity": "sha512-lNlPEGgdUfSzdCWU176ku/dQRnA7W+Gp8d+cWv73jYrb8uT7HTVVxq62DUYxjbaByuf1Yk0RIIAbDzp+CnOTFg==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rollup/rollup-win32-x64-gnu": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.53.2.tgz", + "integrity": "sha512-S6YojNVrHybQis2lYov1sd+uj7K0Q05NxHcGktuMMdIQ2VixGwAfbJ23NnlvvVV1bdpR2m5MsNBViHJKcA4ADw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rollup/rollup-win32-x64-msvc": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.53.2.tgz", + "integrity": "sha512-k+/Rkcyx//P6fetPoLMb8pBeqJBNGx81uuf7iljX9++yNBVRDQgD04L+SVXmXmh5ZP4/WOp4mWF0kmi06PW2tA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@types/babel__core": { + "version": "7.20.5", + "resolved": "https://registry.npmjs.org/@types/babel__core/-/babel__core-7.20.5.tgz", + "integrity": "sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/parser": "^7.20.7", + "@babel/types": "^7.20.7", + "@types/babel__generator": "*", + "@types/babel__template": "*", + "@types/babel__traverse": "*" + } + }, + "node_modules/@types/babel__generator": { + "version": "7.27.0", + "resolved": "https://registry.npmjs.org/@types/babel__generator/-/babel__generator-7.27.0.tgz", + "integrity": "sha512-ufFd2Xi92OAVPYsy+P4n7/U7e68fex0+Ee8gSG9KX7eo084CWiQ4sdxktvdl0bOPupXtVJPY19zk6EwWqUQ8lg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/types": "^7.0.0" + } + }, + "node_modules/@types/babel__template": { + "version": "7.4.4", + "resolved": "https://registry.npmjs.org/@types/babel__template/-/babel__template-7.4.4.tgz", + "integrity": "sha512-h/NUaSyG5EyxBIp8YRxo4RMe2/qQgvyowRwVMzhYhBCONbW8PUsg4lkFMrhgZhUe5z3L3MiLDuvyJ/CaPa2A8A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/parser": "^7.1.0", + "@babel/types": "^7.0.0" + } + }, + "node_modules/@types/babel__traverse": { + "version": "7.28.0", + "resolved": "https://registry.npmjs.org/@types/babel__traverse/-/babel__traverse-7.28.0.tgz", + "integrity": "sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/types": "^7.28.2" + } + }, + "node_modules/@types/estree": { + "version": "1.0.8", + "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz", + "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/json-schema": { + "version": "7.0.15", + "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.15.tgz", + "integrity": "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/prop-types": { + "version": "15.7.15", + "resolved": "https://registry.npmjs.org/@types/prop-types/-/prop-types-15.7.15.tgz", + "integrity": "sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/react": { + "version": "18.3.26", + "resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.26.tgz", + "integrity": "sha512-RFA/bURkcKzx/X9oumPG9Vp3D3JUgus/d0b67KB0t5S/raciymilkOa66olh78MUI92QLbEJevO7rvqU/kjwKA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/prop-types": "*", + "csstype": "^3.0.2" + } + }, + "node_modules/@types/react-dom": { + "version": "18.3.7", + "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-18.3.7.tgz", + "integrity": "sha512-MEe3UeoENYVFXzoXEWsvcpg6ZvlrFNlOQ7EOsvhI3CfAXwzPfO8Qwuxd40nepsYKqyyVQnTdEfv68q91yLcKrQ==", + "dev": true, + "license": "MIT", + "peerDependencies": { + "@types/react": "^18.0.0" + } + }, + "node_modules/@types/semver": { + "version": "7.7.1", + "resolved": "https://registry.npmjs.org/@types/semver/-/semver-7.7.1.tgz", + "integrity": "sha512-FmgJfu+MOcQ370SD0ev7EI8TlCAfKYU+B4m5T3yXc1CiRN94g/SZPtsCkk506aUDtlMnFZvasDwHHUcZUEaYuA==", + "dev": true, + "license": "MIT" + }, + "node_modules/@typescript-eslint/eslint-plugin": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-6.21.0.tgz", + "integrity": "sha512-oy9+hTPCUFpngkEZUSzbf9MxI65wbKFoQYsgPdILTfbUldp5ovUuphZVe4i30emU9M/kP+T64Di0mxl7dSw3MA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@eslint-community/regexpp": "^4.5.1", + "@typescript-eslint/scope-manager": "6.21.0", + "@typescript-eslint/type-utils": "6.21.0", + "@typescript-eslint/utils": "6.21.0", + "@typescript-eslint/visitor-keys": "6.21.0", + "debug": "^4.3.4", + "graphemer": "^1.4.0", + "ignore": "^5.2.4", + "natural-compare": "^1.4.0", + "semver": "^7.5.4", + "ts-api-utils": "^1.0.1" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependencies": { + "@typescript-eslint/parser": "^6.0.0 || ^6.0.0-alpha", + "eslint": "^7.0.0 || ^8.0.0" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + } + } + }, + "node_modules/@typescript-eslint/parser": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-6.21.0.tgz", + "integrity": "sha512-tbsV1jPne5CkFQCgPBcDOt30ItF7aJoZL997JSF7MhGQqOeT3svWRYxiqlfA5RUdlHN6Fi+EI9bxqbdyAUZjYQ==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "@typescript-eslint/scope-manager": "6.21.0", + "@typescript-eslint/types": "6.21.0", + "@typescript-eslint/typescript-estree": "6.21.0", + "@typescript-eslint/visitor-keys": "6.21.0", + "debug": "^4.3.4" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependencies": { + "eslint": "^7.0.0 || ^8.0.0" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + } + } + }, + "node_modules/@typescript-eslint/scope-manager": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-6.21.0.tgz", + "integrity": "sha512-OwLUIWZJry80O99zvqXVEioyniJMa+d2GrqpUTqi5/v5D5rOrppJVBPa0yKCblcigC0/aYAzxxqQ1B+DS2RYsg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@typescript-eslint/types": "6.21.0", + "@typescript-eslint/visitor-keys": "6.21.0" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + } + }, + "node_modules/@typescript-eslint/type-utils": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/type-utils/-/type-utils-6.21.0.tgz", + "integrity": "sha512-rZQI7wHfao8qMX3Rd3xqeYSMCL3SoiSQLBATSiVKARdFGCYSRvmViieZjqc58jKgs8Y8i9YvVVhRbHSTA4VBag==", + "dev": true, + "license": "MIT", + "dependencies": { + "@typescript-eslint/typescript-estree": "6.21.0", + "@typescript-eslint/utils": "6.21.0", + "debug": "^4.3.4", + "ts-api-utils": "^1.0.1" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependencies": { + "eslint": "^7.0.0 || ^8.0.0" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + } + } + }, + "node_modules/@typescript-eslint/types": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-6.21.0.tgz", + "integrity": "sha512-1kFmZ1rOm5epu9NZEZm1kckCDGj5UJEf7P1kliH4LKu/RkwpsfqqGmY2OOcUs18lSlQBKLDYBOGxRVtrMN5lpg==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + } + }, + "node_modules/@typescript-eslint/typescript-estree": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-6.21.0.tgz", + "integrity": "sha512-6npJTkZcO+y2/kr+z0hc4HwNfrrP4kNYh57ek7yCNlrBjWQ1Y0OS7jiZTkgumrvkX5HkEKXFZkkdFNkaW2wmUQ==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "@typescript-eslint/types": "6.21.0", + "@typescript-eslint/visitor-keys": "6.21.0", + "debug": "^4.3.4", + "globby": "^11.1.0", + "is-glob": "^4.0.3", + "minimatch": "9.0.3", + "semver": "^7.5.4", + "ts-api-utils": "^1.0.1" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + } + } + }, + "node_modules/@typescript-eslint/utils": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/utils/-/utils-6.21.0.tgz", + "integrity": "sha512-NfWVaC8HP9T8cbKQxHcsJBY5YE1O33+jpMwN45qzWWaPDZgLIbo12toGMWnmhvCpd3sIxkpDw3Wv1B3dYrbDQQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@eslint-community/eslint-utils": "^4.4.0", + "@types/json-schema": "^7.0.12", + "@types/semver": "^7.5.0", + "@typescript-eslint/scope-manager": "6.21.0", + "@typescript-eslint/types": "6.21.0", + "@typescript-eslint/typescript-estree": "6.21.0", + "semver": "^7.5.4" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependencies": { + "eslint": "^7.0.0 || ^8.0.0" + } + }, + "node_modules/@typescript-eslint/visitor-keys": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-6.21.0.tgz", + "integrity": "sha512-JJtkDduxLi9bivAB+cYOVMtbkqdPOhZ+ZI5LC47MIRrDV4Yn2o+ZnW10Nkmr28xRpSpdJ6Sm42Hjf2+REYXm0A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@typescript-eslint/types": "6.21.0", + "eslint-visitor-keys": "^3.4.1" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + } + }, + "node_modules/@ungap/structured-clone": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/@ungap/structured-clone/-/structured-clone-1.3.0.tgz", + "integrity": "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==", + "dev": true, + "license": "ISC" + }, + "node_modules/@vitejs/plugin-react": { + "version": "4.7.0", + "resolved": "https://registry.npmjs.org/@vitejs/plugin-react/-/plugin-react-4.7.0.tgz", + "integrity": "sha512-gUu9hwfWvvEDBBmgtAowQCojwZmJ5mcLn3aufeCsitijs3+f2NsrPtlAWIR6OPiqljl96GVCUbLe0HyqIpVaoA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/core": "^7.28.0", + "@babel/plugin-transform-react-jsx-self": "^7.27.1", + "@babel/plugin-transform-react-jsx-source": "^7.27.1", + "@rolldown/pluginutils": "1.0.0-beta.27", + "@types/babel__core": "^7.20.5", + "react-refresh": "^0.17.0" + }, + "engines": { + "node": "^14.18.0 || >=16.0.0" + }, + "peerDependencies": { + "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0" + } + }, + "node_modules/acorn": { + "version": "8.15.0", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz", + "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==", + "dev": true, + "license": "MIT", + "bin": { + "acorn": "bin/acorn" + }, + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/acorn-jsx": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/acorn-jsx/-/acorn-jsx-5.3.2.tgz", + "integrity": "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==", + "dev": true, + "license": "MIT", + "peerDependencies": { + "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" + } + }, + "node_modules/ajv": { + "version": "6.12.6", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.6.tgz", + "integrity": "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==", + "dev": true, + "license": "MIT", + "dependencies": { + "fast-deep-equal": "^3.1.1", + "fast-json-stable-stringify": "^2.0.0", + "json-schema-traverse": "^0.4.1", + "uri-js": "^4.2.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, + "node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "license": "MIT", + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/any-promise": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/any-promise/-/any-promise-1.3.0.tgz", + "integrity": "sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A==", + "dev": true, + "license": "MIT" + }, + "node_modules/anymatch": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/anymatch/-/anymatch-3.1.3.tgz", + "integrity": "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw==", + "dev": true, + "license": "ISC", + "dependencies": { + "normalize-path": "^3.0.0", + "picomatch": "^2.0.4" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/arg": { + "version": "5.0.2", + "resolved": "https://registry.npmjs.org/arg/-/arg-5.0.2.tgz", + "integrity": "sha512-PYjyFOLKQ9y57JvQ6QLo8dAgNqswh8M1RMJYdQduT6xbWSgK36P/Z/v+p888pM69jMMfS8Xd8F6I1kQ/I9HUGg==", + "dev": true, + "license": "MIT" + }, + "node_modules/argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true, + "license": "Python-2.0" + }, + "node_modules/array-union": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/array-union/-/array-union-2.1.0.tgz", + "integrity": "sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/autoprefixer": { + "version": "10.4.22", + "resolved": "https://registry.npmjs.org/autoprefixer/-/autoprefixer-10.4.22.tgz", + "integrity": "sha512-ARe0v/t9gO28Bznv6GgqARmVqcWOV3mfgUPn9becPHMiD3o9BwlRgaeccZnwTpZ7Zwqrm+c1sUSsMxIzQzc8Xg==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/autoprefixer" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "browserslist": "^4.27.0", + "caniuse-lite": "^1.0.30001754", + "fraction.js": "^5.3.4", + "normalize-range": "^0.1.2", + "picocolors": "^1.1.1", + "postcss-value-parser": "^4.2.0" + }, + "bin": { + "autoprefixer": "bin/autoprefixer" + }, + "engines": { + "node": "^10 || ^12 || >=14" + }, + "peerDependencies": { + "postcss": "^8.1.0" + } + }, + "node_modules/balanced-match": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", + "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==", + "dev": true, + "license": "MIT" + }, + "node_modules/baseline-browser-mapping": { + "version": "2.8.28", + "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.8.28.tgz", + "integrity": "sha512-gYjt7OIqdM0PcttNYP2aVrr2G0bMALkBaoehD4BuRGjAOtipg0b6wHg1yNL+s5zSnLZZrGHOw4IrND8CD+3oIQ==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "baseline-browser-mapping": "dist/cli.js" + } + }, + "node_modules/binary-extensions": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.3.0.tgz", + "integrity": "sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/brace-expansion": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz", + "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/braces": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz", + "integrity": "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==", + "dev": true, + "license": "MIT", + "dependencies": { + "fill-range": "^7.1.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/browserslist": { + "version": "4.28.0", + "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.0.tgz", + "integrity": "sha512-tbydkR/CxfMwelN0vwdP/pLkDwyAASZ+VfWm4EOwlB6SWhx1sYnWLqo8N5j0rAzPfzfRaxt0mM/4wPU/Su84RQ==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/browserslist" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/browserslist" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "baseline-browser-mapping": "^2.8.25", + "caniuse-lite": "^1.0.30001754", + "electron-to-chromium": "^1.5.249", + "node-releases": "^2.0.27", + "update-browserslist-db": "^1.1.4" + }, + "bin": { + "browserslist": "cli.js" + }, + "engines": { + "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7" + } + }, + "node_modules/callsites": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/callsites/-/callsites-3.1.0.tgz", + "integrity": "sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/camelcase-css": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/camelcase-css/-/camelcase-css-2.0.1.tgz", + "integrity": "sha512-QOSvevhslijgYwRx6Rv7zKdMF8lbRmx+uQGx2+vDc+KI/eBnsy9kit5aj23AgGu3pa4t9AgwbnXWqS+iOY+2aA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 6" + } + }, + "node_modules/caniuse-lite": { + "version": "1.0.30001754", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001754.tgz", + "integrity": "sha512-x6OeBXueoAceOmotzx3PO4Zpt4rzpeIFsSr6AAePTZxSkXiYDUmpypEl7e2+8NCd9bD7bXjqyef8CJYPC1jfxg==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/browserslist" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/caniuse-lite" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "CC-BY-4.0" + }, + "node_modules/chalk": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", + "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^4.1.0", + "supports-color": "^7.1.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/chalk?sponsor=1" + } + }, + "node_modules/chokidar": { + "version": "3.6.0", + "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.6.0.tgz", + "integrity": "sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw==", + "dev": true, + "license": "MIT", + "dependencies": { + "anymatch": "~3.1.2", + "braces": "~3.0.2", + "glob-parent": "~5.1.2", + "is-binary-path": "~2.1.0", + "is-glob": "~4.0.1", + "normalize-path": "~3.0.0", + "readdirp": "~3.6.0" + }, + "engines": { + "node": ">= 8.10.0" + }, + "funding": { + "url": "https://paulmillr.com/funding/" + }, + "optionalDependencies": { + "fsevents": "~2.3.2" + } + }, + "node_modules/chokidar/node_modules/glob-parent": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz", + "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==", + "dev": true, + "license": "ISC", + "dependencies": { + "is-glob": "^4.0.1" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "color-name": "~1.1.4" + }, + "engines": { + "node": ">=7.0.0" + } + }, + "node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true, + "license": "MIT" + }, + "node_modules/commander": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/commander/-/commander-4.1.1.tgz", + "integrity": "sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 6" + } + }, + "node_modules/concat-map": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", + "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==", + "dev": true, + "license": "MIT" + }, + "node_modules/convert-source-map": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz", + "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==", + "dev": true, + "license": "MIT" + }, + "node_modules/cross-spawn": { + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", + "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", + "dev": true, + "license": "MIT", + "dependencies": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/cssesc": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/cssesc/-/cssesc-3.0.0.tgz", + "integrity": "sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==", + "dev": true, + "license": "MIT", + "bin": { + "cssesc": "bin/cssesc" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/csstype": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.1.3.tgz", + "integrity": "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw==", + "dev": true, + "license": "MIT" + }, + "node_modules/debug": { + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", + "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", + "dev": true, + "license": "MIT", + "dependencies": { + "ms": "^2.1.3" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/deep-is": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/deep-is/-/deep-is-0.1.4.tgz", + "integrity": "sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/didyoumean": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/didyoumean/-/didyoumean-1.2.2.tgz", + "integrity": "sha512-gxtyfqMg7GKyhQmb056K7M3xszy/myH8w+B4RT+QXBQsvAOdc3XymqDDPHx1BgPgsdAA5SIifona89YtRATDzw==", + "dev": true, + "license": "Apache-2.0" + }, + "node_modules/dir-glob": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/dir-glob/-/dir-glob-3.0.1.tgz", + "integrity": "sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==", + "dev": true, + "license": "MIT", + "dependencies": { + "path-type": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/dlv": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/dlv/-/dlv-1.1.3.tgz", + "integrity": "sha512-+HlytyjlPKnIG8XuRG8WvmBP8xs8P71y+SKKS6ZXWoEgLuePxtDoUEiH7WkdePWrQ5JBpE6aoVqfZfJUQkjXwA==", + "dev": true, + "license": "MIT" + }, + "node_modules/doctrine": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/doctrine/-/doctrine-3.0.0.tgz", + "integrity": "sha512-yS+Q5i3hBf7GBkd4KG8a7eBNNWNGLTaEwwYWUijIYM7zrlYDM0BFXHjjPWlWZ1Rg7UaddZeIDmi9jF3HmqiQ2w==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "esutils": "^2.0.2" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/eastasianwidth": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/eastasianwidth/-/eastasianwidth-0.2.0.tgz", + "integrity": "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==", + "dev": true, + "license": "MIT" + }, + "node_modules/electron-to-chromium": { + "version": "1.5.250", + "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.250.tgz", + "integrity": "sha512-/5UMj9IiGDMOFBnN4i7/Ry5onJrAGSbOGo3s9FEKmwobGq6xw832ccET0CE3CkkMBZ8GJSlUIesZofpyurqDXw==", + "dev": true, + "license": "ISC" + }, + "node_modules/emoji-regex": { + "version": "9.2.2", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz", + "integrity": "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==", + "dev": true, + "license": "MIT" + }, + "node_modules/esbuild": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.21.5.tgz", + "integrity": "sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=12" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.21.5", + "@esbuild/android-arm": "0.21.5", + "@esbuild/android-arm64": "0.21.5", + "@esbuild/android-x64": "0.21.5", + "@esbuild/darwin-arm64": "0.21.5", + "@esbuild/darwin-x64": "0.21.5", + "@esbuild/freebsd-arm64": "0.21.5", + "@esbuild/freebsd-x64": "0.21.5", + "@esbuild/linux-arm": "0.21.5", + "@esbuild/linux-arm64": "0.21.5", + "@esbuild/linux-ia32": "0.21.5", + "@esbuild/linux-loong64": "0.21.5", + "@esbuild/linux-mips64el": "0.21.5", + "@esbuild/linux-ppc64": "0.21.5", + "@esbuild/linux-riscv64": "0.21.5", + "@esbuild/linux-s390x": "0.21.5", + "@esbuild/linux-x64": "0.21.5", + "@esbuild/netbsd-x64": "0.21.5", + "@esbuild/openbsd-x64": "0.21.5", + "@esbuild/sunos-x64": "0.21.5", + "@esbuild/win32-arm64": "0.21.5", + "@esbuild/win32-ia32": "0.21.5", + "@esbuild/win32-x64": "0.21.5" + } + }, + "node_modules/escalade": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz", + "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/escape-string-regexp": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz", + "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/eslint": { + "version": "8.57.1", + "resolved": "https://registry.npmjs.org/eslint/-/eslint-8.57.1.tgz", + "integrity": "sha512-ypowyDxpVSYpkXr9WPv2PAZCtNip1Mv5KTW0SCurXv/9iOpcrH9PaqUElksqEB6pChqHGDRCFTyrZlGhnLNGiA==", + "deprecated": "This version is no longer supported. Please see https://eslint.org/version-support for other options.", + "dev": true, + "license": "MIT", + "dependencies": { + "@eslint-community/eslint-utils": "^4.2.0", + "@eslint-community/regexpp": "^4.6.1", + "@eslint/eslintrc": "^2.1.4", + "@eslint/js": "8.57.1", + "@humanwhocodes/config-array": "^0.13.0", + "@humanwhocodes/module-importer": "^1.0.1", + "@nodelib/fs.walk": "^1.2.8", + "@ungap/structured-clone": "^1.2.0", + "ajv": "^6.12.4", + "chalk": "^4.0.0", + "cross-spawn": "^7.0.2", + "debug": "^4.3.2", + "doctrine": "^3.0.0", + "escape-string-regexp": "^4.0.0", + "eslint-scope": "^7.2.2", + "eslint-visitor-keys": "^3.4.3", + "espree": "^9.6.1", + "esquery": "^1.4.2", + "esutils": "^2.0.2", + "fast-deep-equal": "^3.1.3", + "file-entry-cache": "^6.0.1", + "find-up": "^5.0.0", + "glob-parent": "^6.0.2", + "globals": "^13.19.0", + "graphemer": "^1.4.0", + "ignore": "^5.2.0", + "imurmurhash": "^0.1.4", + "is-glob": "^4.0.0", + "is-path-inside": "^3.0.3", + "js-yaml": "^4.1.0", + "json-stable-stringify-without-jsonify": "^1.0.1", + "levn": "^0.4.1", + "lodash.merge": "^4.6.2", + "minimatch": "^3.1.2", + "natural-compare": "^1.4.0", + "optionator": "^0.9.3", + "strip-ansi": "^6.0.1", + "text-table": "^0.2.0" + }, + "bin": { + "eslint": "bin/eslint.js" + }, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/eslint-plugin-react-hooks": { + "version": "4.6.2", + "resolved": "https://registry.npmjs.org/eslint-plugin-react-hooks/-/eslint-plugin-react-hooks-4.6.2.tgz", + "integrity": "sha512-QzliNJq4GinDBcD8gPB5v0wh6g8q3SUi6EFF0x8N/BL9PoVs0atuGc47ozMRyOWAKdwaZ5OnbOEa3WR+dSGKuQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "eslint": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-0" + } + }, + "node_modules/eslint-plugin-react-refresh": { + "version": "0.4.24", + "resolved": "https://registry.npmjs.org/eslint-plugin-react-refresh/-/eslint-plugin-react-refresh-0.4.24.tgz", + "integrity": "sha512-nLHIW7TEq3aLrEYWpVaJ1dRgFR+wLDPN8e8FpYAql/bMV2oBEfC37K0gLEGgv9fy66juNShSMV8OkTqzltcG/w==", + "dev": true, + "license": "MIT", + "peerDependencies": { + "eslint": ">=8.40" + } + }, + "node_modules/eslint-scope": { + "version": "7.2.2", + "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-7.2.2.tgz", + "integrity": "sha512-dOt21O7lTMhDM+X9mB4GX+DZrZtCUJPL/wlcTqxyrx5IvO0IYtILdtrQGQp+8n5S0gwSVmOf9NQrjMOgfQZlIg==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "esrecurse": "^4.3.0", + "estraverse": "^5.2.0" + }, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/eslint-visitor-keys": { + "version": "3.4.3", + "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-3.4.3.tgz", + "integrity": "sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/eslint/node_modules/brace-expansion": { + "version": "1.1.12", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz", + "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==", + "dev": true, + "license": "MIT", + "dependencies": { + "balanced-match": "^1.0.0", + "concat-map": "0.0.1" + } + }, + "node_modules/eslint/node_modules/minimatch": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz", + "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==", + "dev": true, + "license": "ISC", + "dependencies": { + "brace-expansion": "^1.1.7" + }, + "engines": { + "node": "*" + } + }, + "node_modules/espree": { + "version": "9.6.1", + "resolved": "https://registry.npmjs.org/espree/-/espree-9.6.1.tgz", + "integrity": "sha512-oruZaFkjorTpF32kDSI5/75ViwGeZginGGy2NoOSg3Q9bnwlnmDm4HLnkl0RE3n+njDXR037aY1+x58Z/zFdwQ==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "acorn": "^8.9.0", + "acorn-jsx": "^5.3.2", + "eslint-visitor-keys": "^3.4.1" + }, + "engines": { + "node": "^12.22.0 || ^14.17.0 || >=16.0.0" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/esquery": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/esquery/-/esquery-1.6.0.tgz", + "integrity": "sha512-ca9pw9fomFcKPvFLXhBKUK90ZvGibiGOvRJNbjljY7s7uq/5YO4BOzcYtJqExdx99rF6aAcnRxHmcUHcz6sQsg==", + "dev": true, + "license": "BSD-3-Clause", + "dependencies": { + "estraverse": "^5.1.0" + }, + "engines": { + "node": ">=0.10" + } + }, + "node_modules/esrecurse": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/esrecurse/-/esrecurse-4.3.0.tgz", + "integrity": "sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "estraverse": "^5.2.0" + }, + "engines": { + "node": ">=4.0" + } + }, + "node_modules/estraverse": { + "version": "5.3.0", + "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-5.3.0.tgz", + "integrity": "sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=4.0" + } + }, + "node_modules/esutils": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/esutils/-/esutils-2.0.3.tgz", + "integrity": "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/fast-deep-equal": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", + "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/fast-glob": { + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.3.tgz", + "integrity": "sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@nodelib/fs.stat": "^2.0.2", + "@nodelib/fs.walk": "^1.2.3", + "glob-parent": "^5.1.2", + "merge2": "^1.3.0", + "micromatch": "^4.0.8" + }, + "engines": { + "node": ">=8.6.0" + } + }, + "node_modules/fast-glob/node_modules/glob-parent": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz", + "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==", + "dev": true, + "license": "ISC", + "dependencies": { + "is-glob": "^4.0.1" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/fast-json-stable-stringify": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz", + "integrity": "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==", + "dev": true, + "license": "MIT" + }, + "node_modules/fast-levenshtein": { + "version": "2.0.6", + "resolved": "https://registry.npmjs.org/fast-levenshtein/-/fast-levenshtein-2.0.6.tgz", + "integrity": "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==", + "dev": true, + "license": "MIT" + }, + "node_modules/fastq": { + "version": "1.19.1", + "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.19.1.tgz", + "integrity": "sha512-GwLTyxkCXjXbxqIhTsMI2Nui8huMPtnxg7krajPJAjnEG/iiOS7i+zCtWGZR9G0NBKbXKh6X9m9UIsYX/N6vvQ==", + "dev": true, + "license": "ISC", + "dependencies": { + "reusify": "^1.0.4" + } + }, + "node_modules/file-entry-cache": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-6.0.1.tgz", + "integrity": "sha512-7Gps/XWymbLk2QLYK4NzpMOrYjMhdIxXuIvy2QBsLE6ljuodKvdkWs/cpyJJ3CVIVpH0Oi1Hvg1ovbMzLdFBBg==", + "dev": true, + "license": "MIT", + "dependencies": { + "flat-cache": "^3.0.4" + }, + "engines": { + "node": "^10.12.0 || >=12.0.0" + } + }, + "node_modules/fill-range": { + "version": "7.1.1", + "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz", + "integrity": "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==", + "dev": true, + "license": "MIT", + "dependencies": { + "to-regex-range": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/find-up": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-5.0.0.tgz", + "integrity": "sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==", + "dev": true, + "license": "MIT", + "dependencies": { + "locate-path": "^6.0.0", + "path-exists": "^4.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/flat-cache": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/flat-cache/-/flat-cache-3.2.0.tgz", + "integrity": "sha512-CYcENa+FtcUKLmhhqyctpclsq7QF38pKjZHsGNiSQF5r4FtoKDWabFDl3hzaEQMvT1LHEysw5twgLvpYYb4vbw==", + "dev": true, + "license": "MIT", + "dependencies": { + "flatted": "^3.2.9", + "keyv": "^4.5.3", + "rimraf": "^3.0.2" + }, + "engines": { + "node": "^10.12.0 || >=12.0.0" + } + }, + "node_modules/flatted": { + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.3.3.tgz", + "integrity": "sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg==", + "dev": true, + "license": "ISC" + }, + "node_modules/foreground-child": { + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/foreground-child/-/foreground-child-3.3.1.tgz", + "integrity": "sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==", + "dev": true, + "license": "ISC", + "dependencies": { + "cross-spawn": "^7.0.6", + "signal-exit": "^4.0.1" + }, + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/fraction.js": { + "version": "5.3.4", + "resolved": "https://registry.npmjs.org/fraction.js/-/fraction.js-5.3.4.tgz", + "integrity": "sha512-1X1NTtiJphryn/uLQz3whtY6jK3fTqoE3ohKs0tT+Ujr1W59oopxmoEh7Lu5p6vBaPbgoM0bzveAW4Qi5RyWDQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": "*" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/rawify" + } + }, + "node_modules/fs.realpath": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz", + "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==", + "dev": true, + "license": "ISC" + }, + "node_modules/fsevents": { + "version": "2.3.3", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz", + "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/function-bind": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz", + "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/gensync": { + "version": "1.0.0-beta.2", + "resolved": "https://registry.npmjs.org/gensync/-/gensync-1.0.0-beta.2.tgz", + "integrity": "sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/glob": { + "version": "7.2.3", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz", + "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==", + "deprecated": "Glob versions prior to v9 are no longer supported", + "dev": true, + "license": "ISC", + "dependencies": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.1.1", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + }, + "engines": { + "node": "*" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/glob-parent": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-6.0.2.tgz", + "integrity": "sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A==", + "dev": true, + "license": "ISC", + "dependencies": { + "is-glob": "^4.0.3" + }, + "engines": { + "node": ">=10.13.0" + } + }, + "node_modules/glob/node_modules/brace-expansion": { + "version": "1.1.12", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz", + "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==", + "dev": true, + "license": "MIT", + "dependencies": { + "balanced-match": "^1.0.0", + "concat-map": "0.0.1" + } + }, + "node_modules/glob/node_modules/minimatch": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz", + "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==", + "dev": true, + "license": "ISC", + "dependencies": { + "brace-expansion": "^1.1.7" + }, + "engines": { + "node": "*" + } + }, + "node_modules/globals": { + "version": "13.24.0", + "resolved": "https://registry.npmjs.org/globals/-/globals-13.24.0.tgz", + "integrity": "sha512-AhO5QUcj8llrbG09iWhPU2B204J1xnPeL8kQmVorSsy+Sjj1sk8gIyh6cUocGmH4L0UuhAJy+hJMRA4mgA4mFQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "type-fest": "^0.20.2" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/globby": { + "version": "11.1.0", + "resolved": "https://registry.npmjs.org/globby/-/globby-11.1.0.tgz", + "integrity": "sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g==", + "dev": true, + "license": "MIT", + "dependencies": { + "array-union": "^2.1.0", + "dir-glob": "^3.0.1", + "fast-glob": "^3.2.9", + "ignore": "^5.2.0", + "merge2": "^1.4.1", + "slash": "^3.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/graphemer": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/graphemer/-/graphemer-1.4.0.tgz", + "integrity": "sha512-EtKwoO6kxCL9WO5xipiHTZlSzBm7WLT627TqC/uVRd0HKmq8NXyebnNYxDoBi7wt8eTWrUrKXCOVaFq9x1kgag==", + "dev": true, + "license": "MIT" + }, + "node_modules/has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/hasown": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.2.tgz", + "integrity": "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "function-bind": "^1.1.2" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/ignore": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz", + "integrity": "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 4" + } + }, + "node_modules/import-fresh": { + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.1.tgz", + "integrity": "sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "parent-module": "^1.0.0", + "resolve-from": "^4.0.0" + }, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/imurmurhash": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/imurmurhash/-/imurmurhash-0.1.4.tgz", + "integrity": "sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.8.19" + } + }, + "node_modules/inflight": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz", + "integrity": "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==", + "deprecated": "This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.", + "dev": true, + "license": "ISC", + "dependencies": { + "once": "^1.3.0", + "wrappy": "1" + } + }, + "node_modules/inherits": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz", + "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", + "dev": true, + "license": "ISC" + }, + "node_modules/is-binary-path": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/is-binary-path/-/is-binary-path-2.1.0.tgz", + "integrity": "sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw==", + "dev": true, + "license": "MIT", + "dependencies": { + "binary-extensions": "^2.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/is-core-module": { + "version": "2.16.1", + "resolved": "https://registry.npmjs.org/is-core-module/-/is-core-module-2.16.1.tgz", + "integrity": "sha512-UfoeMA6fIJ8wTYFEUjelnaGI67v6+N7qXJEvQuIGa99l4xsCruSYOVSQ0uPANn4dAzm8lkYPaKLrrijLq7x23w==", + "dev": true, + "license": "MIT", + "dependencies": { + "hasown": "^2.0.2" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/is-extglob": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz", + "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/is-glob": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz", + "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-extglob": "^2.1.1" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-number": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz", + "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.12.0" + } + }, + "node_modules/is-path-inside": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/is-path-inside/-/is-path-inside-3.0.3.tgz", + "integrity": "sha512-Fd4gABb+ycGAmKou8eMftCupSir5lRxqf4aD/vd0cD2qc4HL07OjCeuHMr8Ro4CoMaeCKDB0/ECBOVWjTwUvPQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/isexe": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", + "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "dev": true, + "license": "ISC" + }, + "node_modules/jackspeak": { + "version": "3.4.3", + "resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-3.4.3.tgz", + "integrity": "sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==", + "dev": true, + "license": "BlueOak-1.0.0", + "dependencies": { + "@isaacs/cliui": "^8.0.2" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + }, + "optionalDependencies": { + "@pkgjs/parseargs": "^0.11.0" + } + }, + "node_modules/jiti": { + "version": "1.21.7", + "resolved": "https://registry.npmjs.org/jiti/-/jiti-1.21.7.tgz", + "integrity": "sha512-/imKNG4EbWNrVjoNC/1H5/9GFy+tqjGBHCaSsN+P2RnPqjsLmv6UD3Ej+Kj8nBWaRAwyk7kK5ZUc+OEatnTR3A==", + "dev": true, + "license": "MIT", + "bin": { + "jiti": "bin/jiti.js" + } + }, + "node_modules/js-tokens": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", + "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==", + "license": "MIT" + }, + "node_modules/js-yaml": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz", + "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==", + "dev": true, + "license": "MIT", + "dependencies": { + "argparse": "^2.0.1" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/jsesc": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz", + "integrity": "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==", + "dev": true, + "license": "MIT", + "bin": { + "jsesc": "bin/jsesc" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/json-buffer": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/json-buffer/-/json-buffer-3.0.1.tgz", + "integrity": "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/json-schema-traverse": { + "version": "0.4.1", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz", + "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==", + "dev": true, + "license": "MIT" + }, + "node_modules/json-stable-stringify-without-jsonify": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/json-stable-stringify-without-jsonify/-/json-stable-stringify-without-jsonify-1.0.1.tgz", + "integrity": "sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==", + "dev": true, + "license": "MIT" + }, + "node_modules/json5": { + "version": "2.2.3", + "resolved": "https://registry.npmjs.org/json5/-/json5-2.2.3.tgz", + "integrity": "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==", + "dev": true, + "license": "MIT", + "bin": { + "json5": "lib/cli.js" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/keyv": { + "version": "4.5.4", + "resolved": "https://registry.npmjs.org/keyv/-/keyv-4.5.4.tgz", + "integrity": "sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==", + "dev": true, + "license": "MIT", + "dependencies": { + "json-buffer": "3.0.1" + } + }, + "node_modules/levn": { + "version": "0.4.1", + "resolved": "https://registry.npmjs.org/levn/-/levn-0.4.1.tgz", + "integrity": "sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "prelude-ls": "^1.2.1", + "type-check": "~0.4.0" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/lilconfig": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/lilconfig/-/lilconfig-3.1.3.tgz", + "integrity": "sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/antonk52" + } + }, + "node_modules/lines-and-columns": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.2.4.tgz", + "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==", + "dev": true, + "license": "MIT" + }, + "node_modules/locate-path": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz", + "integrity": "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==", + "dev": true, + "license": "MIT", + "dependencies": { + "p-locate": "^5.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/lodash.merge": { + "version": "4.6.2", + "resolved": "https://registry.npmjs.org/lodash.merge/-/lodash.merge-4.6.2.tgz", + "integrity": "sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/loose-envify": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz", + "integrity": "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==", + "license": "MIT", + "dependencies": { + "js-tokens": "^3.0.0 || ^4.0.0" + }, + "bin": { + "loose-envify": "cli.js" + } + }, + "node_modules/lru-cache": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz", + "integrity": "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==", + "dev": true, + "license": "ISC", + "dependencies": { + "yallist": "^3.0.2" + } + }, + "node_modules/lucide-react": { + "version": "0.294.0", + "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-0.294.0.tgz", + "integrity": "sha512-V7o0/VECSGbLHn3/1O67FUgBwWB+hmzshrgDVRJQhMh8uj5D3HBuIvhuAmQTtlupILSplwIZg5FTc4tTKMA2SA==", + "license": "ISC", + "peerDependencies": { + "react": "^16.5.1 || ^17.0.0 || ^18.0.0" + } + }, + "node_modules/merge2": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz", + "integrity": "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 8" + } + }, + "node_modules/micromatch": { + "version": "4.0.8", + "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.8.tgz", + "integrity": "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==", + "dev": true, + "license": "MIT", + "dependencies": { + "braces": "^3.0.3", + "picomatch": "^2.3.1" + }, + "engines": { + "node": ">=8.6" + } + }, + "node_modules/minimatch": { + "version": "9.0.3", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.3.tgz", + "integrity": "sha512-RHiac9mvaRw0x3AYRgDC1CxAP7HTcNrrECeA8YYJeWnpo+2Q5CegtZjaotWTWxDG3UeGA1coE05iH1mPjT/2mg==", + "dev": true, + "license": "ISC", + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=16 || 14 >=14.17" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/minipass": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.2.tgz", + "integrity": "sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=16 || 14 >=14.17" + } + }, + "node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "dev": true, + "license": "MIT" + }, + "node_modules/mz": { + "version": "2.7.0", + "resolved": "https://registry.npmjs.org/mz/-/mz-2.7.0.tgz", + "integrity": "sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "any-promise": "^1.0.0", + "object-assign": "^4.0.1", + "thenify-all": "^1.0.0" + } + }, + "node_modules/nanoid": { + "version": "3.3.11", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz", + "integrity": "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "bin": { + "nanoid": "bin/nanoid.cjs" + }, + "engines": { + "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1" + } + }, + "node_modules/natural-compare": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/natural-compare/-/natural-compare-1.4.0.tgz", + "integrity": "sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==", + "dev": true, + "license": "MIT" + }, + "node_modules/node-releases": { + "version": "2.0.27", + "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.27.tgz", + "integrity": "sha512-nmh3lCkYZ3grZvqcCH+fjmQ7X+H0OeZgP40OierEaAptX4XofMh5kwNbWh7lBduUzCcV/8kZ+NDLCwm2iorIlA==", + "dev": true, + "license": "MIT" + }, + "node_modules/normalize-path": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz", + "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/normalize-range": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/normalize-range/-/normalize-range-0.1.2.tgz", + "integrity": "sha512-bdok/XvKII3nUpklnV6P2hxtMNrCboOjAcyBuQnWEhO665FwrSNRxU+AqpsyvO6LgGYPspN+lu5CLtw4jPRKNA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/object-assign": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", + "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/object-hash": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/object-hash/-/object-hash-3.0.0.tgz", + "integrity": "sha512-RSn9F68PjH9HqtltsSnqYC1XXoWe9Bju5+213R98cNGttag9q9yAOTzdbsqvIa7aNm5WffBZFpWYr2aWrklWAw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 6" + } + }, + "node_modules/once": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz", + "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==", + "dev": true, + "license": "ISC", + "dependencies": { + "wrappy": "1" + } + }, + "node_modules/optionator": { + "version": "0.9.4", + "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.9.4.tgz", + "integrity": "sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==", + "dev": true, + "license": "MIT", + "dependencies": { + "deep-is": "^0.1.3", + "fast-levenshtein": "^2.0.6", + "levn": "^0.4.1", + "prelude-ls": "^1.2.1", + "type-check": "^0.4.0", + "word-wrap": "^1.2.5" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/p-limit": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz", + "integrity": "sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "yocto-queue": "^0.1.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/p-locate": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-5.0.0.tgz", + "integrity": "sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==", + "dev": true, + "license": "MIT", + "dependencies": { + "p-limit": "^3.0.2" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/package-json-from-dist": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/package-json-from-dist/-/package-json-from-dist-1.0.1.tgz", + "integrity": "sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==", + "dev": true, + "license": "BlueOak-1.0.0" + }, + "node_modules/parent-module": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz", + "integrity": "sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==", + "dev": true, + "license": "MIT", + "dependencies": { + "callsites": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/path-exists": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz", + "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/path-is-absolute": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz", + "integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/path-key": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/path-parse": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/path-parse/-/path-parse-1.0.7.tgz", + "integrity": "sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==", + "dev": true, + "license": "MIT" + }, + "node_modules/path-scurry": { + "version": "1.11.1", + "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-1.11.1.tgz", + "integrity": "sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA==", + "dev": true, + "license": "BlueOak-1.0.0", + "dependencies": { + "lru-cache": "^10.2.0", + "minipass": "^5.0.0 || ^6.0.2 || ^7.0.0" + }, + "engines": { + "node": ">=16 || 14 >=14.18" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/path-scurry/node_modules/lru-cache": { + "version": "10.4.3", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.4.3.tgz", + "integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==", + "dev": true, + "license": "ISC" + }, + "node_modules/path-type": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz", + "integrity": "sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/picocolors": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz", + "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==", + "dev": true, + "license": "ISC" + }, + "node_modules/picomatch": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", + "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8.6" + }, + "funding": { + "url": "https://github.com/sponsors/jonschlinkert" + } + }, + "node_modules/pify": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/pify/-/pify-2.3.0.tgz", + "integrity": "sha512-udgsAY+fTnvv7kI7aaxbqwWNb0AHiB0qBO89PZKPkoTmGOgdbrHDKD+0B2X4uTfJ/FT1R09r9gTsjUjNJotuog==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/pirates": { + "version": "4.0.7", + "resolved": "https://registry.npmjs.org/pirates/-/pirates-4.0.7.tgz", + "integrity": "sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 6" + } + }, + "node_modules/postcss": { + "version": "8.5.6", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.6.tgz", + "integrity": "sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/postcss" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "nanoid": "^3.3.11", + "picocolors": "^1.1.1", + "source-map-js": "^1.2.1" + }, + "engines": { + "node": "^10 || ^12 || >=14" + } + }, + "node_modules/postcss-import": { + "version": "15.1.0", + "resolved": "https://registry.npmjs.org/postcss-import/-/postcss-import-15.1.0.tgz", + "integrity": "sha512-hpr+J05B2FVYUAXHeK1YyI267J/dDDhMU6B6civm8hSY1jYJnBXxzKDKDswzJmtLHryrjhnDjqqp/49t8FALew==", + "dev": true, + "license": "MIT", + "dependencies": { + "postcss-value-parser": "^4.0.0", + "read-cache": "^1.0.0", + "resolve": "^1.1.7" + }, + "engines": { + "node": ">=14.0.0" + }, + "peerDependencies": { + "postcss": "^8.0.0" + } + }, + "node_modules/postcss-js": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/postcss-js/-/postcss-js-4.1.0.tgz", + "integrity": "sha512-oIAOTqgIo7q2EOwbhb8UalYePMvYoIeRY2YKntdpFQXNosSu3vLrniGgmH9OKs/qAkfoj5oB3le/7mINW1LCfw==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "camelcase-css": "^2.0.1" + }, + "engines": { + "node": "^12 || ^14 || >= 16" + }, + "peerDependencies": { + "postcss": "^8.4.21" + } + }, + "node_modules/postcss-load-config": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/postcss-load-config/-/postcss-load-config-6.0.1.tgz", + "integrity": "sha512-oPtTM4oerL+UXmx+93ytZVN82RrlY/wPUV8IeDxFrzIjXOLF1pN+EmKPLbubvKHT2HC20xXsCAH2Z+CKV6Oz/g==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "lilconfig": "^3.1.1" + }, + "engines": { + "node": ">= 18" + }, + "peerDependencies": { + "jiti": ">=1.21.0", + "postcss": ">=8.0.9", + "tsx": "^4.8.1", + "yaml": "^2.4.2" + }, + "peerDependenciesMeta": { + "jiti": { + "optional": true + }, + "postcss": { + "optional": true + }, + "tsx": { + "optional": true + }, + "yaml": { + "optional": true + } + } + }, + "node_modules/postcss-nested": { + "version": "6.2.0", + "resolved": "https://registry.npmjs.org/postcss-nested/-/postcss-nested-6.2.0.tgz", + "integrity": "sha512-HQbt28KulC5AJzG+cZtj9kvKB93CFCdLvog1WFLf1D+xmMvPGlBstkpTEZfK5+AN9hfJocyBFCNiqyS48bpgzQ==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "postcss-selector-parser": "^6.1.1" + }, + "engines": { + "node": ">=12.0" + }, + "peerDependencies": { + "postcss": "^8.2.14" + } + }, + "node_modules/postcss-selector-parser": { + "version": "6.1.2", + "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-6.1.2.tgz", + "integrity": "sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg==", + "dev": true, + "license": "MIT", + "dependencies": { + "cssesc": "^3.0.0", + "util-deprecate": "^1.0.2" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/postcss-value-parser": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz", + "integrity": "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/prelude-ls": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz", + "integrity": "sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/punycode": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz", + "integrity": "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/queue-microtask": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz", + "integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT" + }, + "node_modules/react": { + "version": "18.3.1", + "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz", + "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==", + "license": "MIT", + "dependencies": { + "loose-envify": "^1.1.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/react-dom": { + "version": "18.3.1", + "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz", + "integrity": "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==", + "license": "MIT", + "dependencies": { + "loose-envify": "^1.1.0", + "scheduler": "^0.23.2" + }, + "peerDependencies": { + "react": "^18.3.1" + } + }, + "node_modules/react-refresh": { + "version": "0.17.0", + "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.17.0.tgz", + "integrity": "sha512-z6F7K9bV85EfseRCp2bzrpyQ0Gkw1uLoCel9XBVWPg/TjRj94SkJzUTGfOa4bs7iJvBWtQG0Wq7wnI0syw3EBQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/react-router": { + "version": "6.30.1", + "resolved": "https://registry.npmjs.org/react-router/-/react-router-6.30.1.tgz", + "integrity": "sha512-X1m21aEmxGXqENEPG3T6u0Th7g0aS4ZmoNynhbs+Cn+q+QGTLt+d5IQ2bHAXKzKcxGJjxACpVbnYQSCRcfxHlQ==", + "license": "MIT", + "dependencies": { + "@remix-run/router": "1.23.0" + }, + "engines": { + "node": ">=14.0.0" + }, + "peerDependencies": { + "react": ">=16.8" + } + }, + "node_modules/react-router-dom": { + "version": "6.30.1", + "resolved": "https://registry.npmjs.org/react-router-dom/-/react-router-dom-6.30.1.tgz", + "integrity": "sha512-llKsgOkZdbPU1Eg3zK8lCn+sjD9wMRZZPuzmdWWX5SUs8OFkN5HnFVC0u5KMeMaC9aoancFI/KoLuKPqN+hxHw==", + "license": "MIT", + "dependencies": { + "@remix-run/router": "1.23.0", + "react-router": "6.30.1" + }, + "engines": { + "node": ">=14.0.0" + }, + "peerDependencies": { + "react": ">=16.8", + "react-dom": ">=16.8" + } + }, + "node_modules/read-cache": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/read-cache/-/read-cache-1.0.0.tgz", + "integrity": "sha512-Owdv/Ft7IjOgm/i0xvNDZ1LrRANRfew4b2prF3OWMQLxLfu3bS8FVhCsrSCMK4lR56Y9ya+AThoTpDCTxCmpRA==", + "dev": true, + "license": "MIT", + "dependencies": { + "pify": "^2.3.0" + } + }, + "node_modules/readdirp": { + "version": "3.6.0", + "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.6.0.tgz", + "integrity": "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==", + "dev": true, + "license": "MIT", + "dependencies": { + "picomatch": "^2.2.1" + }, + "engines": { + "node": ">=8.10.0" + } + }, + "node_modules/resolve": { + "version": "1.22.11", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.22.11.tgz", + "integrity": "sha512-RfqAvLnMl313r7c9oclB1HhUEAezcpLjz95wFH4LVuhk9JF/r22qmVP9AMmOU4vMX7Q8pN8jwNg/CSpdFnMjTQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-core-module": "^2.16.1", + "path-parse": "^1.0.7", + "supports-preserve-symlinks-flag": "^1.0.0" + }, + "bin": { + "resolve": "bin/resolve" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/resolve-from": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-4.0.0.tgz", + "integrity": "sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=4" + } + }, + "node_modules/reusify": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.1.0.tgz", + "integrity": "sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==", + "dev": true, + "license": "MIT", + "engines": { + "iojs": ">=1.0.0", + "node": ">=0.10.0" + } + }, + "node_modules/rimraf": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-3.0.2.tgz", + "integrity": "sha512-JZkJMZkAGFFPP2YqXZXPbMlMBgsxzE8ILs4lMIX/2o0L9UBw9O/Y3o6wFw/i9YLapcUJWwqbi3kdxIPdC62TIA==", + "deprecated": "Rimraf versions prior to v4 are no longer supported", + "dev": true, + "license": "ISC", + "dependencies": { + "glob": "^7.1.3" + }, + "bin": { + "rimraf": "bin.js" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/rollup": { + "version": "4.53.2", + "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.53.2.tgz", + "integrity": "sha512-MHngMYwGJVi6Fmnk6ISmnk7JAHRNF0UkuucA0CUW3N3a4KnONPEZz+vUanQP/ZC/iY1Qkf3bwPWzyY84wEks1g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "1.0.8" + }, + "bin": { + "rollup": "dist/bin/rollup" + }, + "engines": { + "node": ">=18.0.0", + "npm": ">=8.0.0" + }, + "optionalDependencies": { + "@rollup/rollup-android-arm-eabi": "4.53.2", + "@rollup/rollup-android-arm64": "4.53.2", + "@rollup/rollup-darwin-arm64": "4.53.2", + "@rollup/rollup-darwin-x64": "4.53.2", + "@rollup/rollup-freebsd-arm64": "4.53.2", + "@rollup/rollup-freebsd-x64": "4.53.2", + "@rollup/rollup-linux-arm-gnueabihf": "4.53.2", + "@rollup/rollup-linux-arm-musleabihf": "4.53.2", + "@rollup/rollup-linux-arm64-gnu": "4.53.2", + "@rollup/rollup-linux-arm64-musl": "4.53.2", + "@rollup/rollup-linux-loong64-gnu": "4.53.2", + "@rollup/rollup-linux-ppc64-gnu": "4.53.2", + "@rollup/rollup-linux-riscv64-gnu": "4.53.2", + "@rollup/rollup-linux-riscv64-musl": "4.53.2", + "@rollup/rollup-linux-s390x-gnu": "4.53.2", + "@rollup/rollup-linux-x64-gnu": "4.53.2", + "@rollup/rollup-linux-x64-musl": "4.53.2", + "@rollup/rollup-openharmony-arm64": "4.53.2", + "@rollup/rollup-win32-arm64-msvc": "4.53.2", + "@rollup/rollup-win32-ia32-msvc": "4.53.2", + "@rollup/rollup-win32-x64-gnu": "4.53.2", + "@rollup/rollup-win32-x64-msvc": "4.53.2", + "fsevents": "~2.3.2" + } + }, + "node_modules/run-parallel": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz", + "integrity": "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT", + "dependencies": { + "queue-microtask": "^1.2.2" + } + }, + "node_modules/scheduler": { + "version": "0.23.2", + "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz", + "integrity": "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==", + "license": "MIT", + "dependencies": { + "loose-envify": "^1.1.0" + } + }, + "node_modules/semver": { + "version": "7.7.3", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz", + "integrity": "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==", + "dev": true, + "license": "ISC", + "bin": { + "semver": "bin/semver.js" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/shebang-command": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "dev": true, + "license": "MIT", + "dependencies": { + "shebang-regex": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/shebang-regex": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/signal-exit": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz", + "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/slash": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz", + "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/source-map-js": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz", + "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==", + "dev": true, + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/string-width": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-5.1.2.tgz", + "integrity": "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==", + "dev": true, + "license": "MIT", + "dependencies": { + "eastasianwidth": "^0.2.0", + "emoji-regex": "^9.2.2", + "strip-ansi": "^7.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/string-width-cjs": { + "name": "string-width", + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "license": "MIT", + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/string-width-cjs/node_modules/emoji-regex": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", + "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", + "dev": true, + "license": "MIT" + }, + "node_modules/string-width/node_modules/ansi-regex": { + "version": "6.2.2", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz", + "integrity": "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-regex?sponsor=1" + } + }, + "node_modules/string-width/node_modules/strip-ansi": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.1.2.tgz", + "integrity": "sha512-gmBGslpoQJtgnMAvOVqGZpEz9dyoKTCzy2nfz/n8aIFhN/jCE/rCmcxabB6jOOHV+0WNnylOxaxBQPSvcWklhA==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-regex": "^6.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/strip-ansi?sponsor=1" + } + }, + "node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/strip-ansi-cjs": { + "name": "strip-ansi", + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/strip-json-comments": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz", + "integrity": "sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/sucrase": { + "version": "3.35.0", + "resolved": "https://registry.npmjs.org/sucrase/-/sucrase-3.35.0.tgz", + "integrity": "sha512-8EbVDiu9iN/nESwxeSxDKe0dunta1GOlHufmSSXxMD2z2/tMZpDMpvXQGsc+ajGo8y2uYUmixaSRUc/QPoQ0GA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/gen-mapping": "^0.3.2", + "commander": "^4.0.0", + "glob": "^10.3.10", + "lines-and-columns": "^1.1.6", + "mz": "^2.7.0", + "pirates": "^4.0.1", + "ts-interface-checker": "^0.1.9" + }, + "bin": { + "sucrase": "bin/sucrase", + "sucrase-node": "bin/sucrase-node" + }, + "engines": { + "node": ">=16 || 14 >=14.17" + } + }, + "node_modules/sucrase/node_modules/glob": { + "version": "10.4.5", + "resolved": "https://registry.npmjs.org/glob/-/glob-10.4.5.tgz", + "integrity": "sha512-7Bv8RF0k6xjo7d4A/PxYLbUCfb6c+Vpd2/mB2yRDlew7Jb5hEXiCD9ibfO7wpk8i4sevK6DFny9h7EYbM3/sHg==", + "dev": true, + "license": "ISC", + "dependencies": { + "foreground-child": "^3.1.0", + "jackspeak": "^3.1.2", + "minimatch": "^9.0.4", + "minipass": "^7.1.2", + "package-json-from-dist": "^1.0.0", + "path-scurry": "^1.11.1" + }, + "bin": { + "glob": "dist/esm/bin.mjs" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/sucrase/node_modules/minimatch": { + "version": "9.0.5", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz", + "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==", + "dev": true, + "license": "ISC", + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=16 || 14 >=14.17" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/supports-color": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", + "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", + "dev": true, + "license": "MIT", + "dependencies": { + "has-flag": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/supports-preserve-symlinks-flag": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/supports-preserve-symlinks-flag/-/supports-preserve-symlinks-flag-1.0.0.tgz", + "integrity": "sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/tailwindcss": { + "version": "3.4.18", + "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-3.4.18.tgz", + "integrity": "sha512-6A2rnmW5xZMdw11LYjhcI5846rt9pbLSabY5XPxo+XWdxwZaFEn47Go4NzFiHu9sNNmr/kXivP1vStfvMaK1GQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@alloc/quick-lru": "^5.2.0", + "arg": "^5.0.2", + "chokidar": "^3.6.0", + "didyoumean": "^1.2.2", + "dlv": "^1.1.3", + "fast-glob": "^3.3.2", + "glob-parent": "^6.0.2", + "is-glob": "^4.0.3", + "jiti": "^1.21.7", + "lilconfig": "^3.1.3", + "micromatch": "^4.0.8", + "normalize-path": "^3.0.0", + "object-hash": "^3.0.0", + "picocolors": "^1.1.1", + "postcss": "^8.4.47", + "postcss-import": "^15.1.0", + "postcss-js": "^4.0.1", + "postcss-load-config": "^4.0.2 || ^5.0 || ^6.0", + "postcss-nested": "^6.2.0", + "postcss-selector-parser": "^6.1.2", + "resolve": "^1.22.8", + "sucrase": "^3.35.0" + }, + "bin": { + "tailwind": "lib/cli.js", + "tailwindcss": "lib/cli.js" + }, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/text-table": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/text-table/-/text-table-0.2.0.tgz", + "integrity": "sha512-N+8UisAXDGk8PFXP4HAzVR9nbfmVJ3zYLAWiTIoqC5v5isinhr+r5uaO8+7r3BMfuNIufIsA7RdpVgacC2cSpw==", + "dev": true, + "license": "MIT" + }, + "node_modules/thenify": { + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/thenify/-/thenify-3.3.1.tgz", + "integrity": "sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw==", + "dev": true, + "license": "MIT", + "dependencies": { + "any-promise": "^1.0.0" + } + }, + "node_modules/thenify-all": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/thenify-all/-/thenify-all-1.6.0.tgz", + "integrity": "sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==", + "dev": true, + "license": "MIT", + "dependencies": { + "thenify": ">= 3.1.0 < 4" + }, + "engines": { + "node": ">=0.8" + } + }, + "node_modules/to-regex-range": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz", + "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-number": "^7.0.0" + }, + "engines": { + "node": ">=8.0" + } + }, + "node_modules/ts-api-utils": { + "version": "1.4.3", + "resolved": "https://registry.npmjs.org/ts-api-utils/-/ts-api-utils-1.4.3.tgz", + "integrity": "sha512-i3eMG77UTMD0hZhgRS562pv83RC6ukSAC2GMNWc+9dieh/+jDM5u5YG+NHX6VNDRHQcHwmsTHctP9LhbC3WxVw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=16" + }, + "peerDependencies": { + "typescript": ">=4.2.0" + } + }, + "node_modules/ts-interface-checker": { + "version": "0.1.13", + "resolved": "https://registry.npmjs.org/ts-interface-checker/-/ts-interface-checker-0.1.13.tgz", + "integrity": "sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA==", + "dev": true, + "license": "Apache-2.0" + }, + "node_modules/type-check": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/type-check/-/type-check-0.4.0.tgz", + "integrity": "sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==", + "dev": true, + "license": "MIT", + "dependencies": { + "prelude-ls": "^1.2.1" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/type-fest": { + "version": "0.20.2", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.20.2.tgz", + "integrity": "sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ==", + "dev": true, + "license": "(MIT OR CC0-1.0)", + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/update-browserslist-db": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.1.4.tgz", + "integrity": "sha512-q0SPT4xyU84saUX+tomz1WLkxUbuaJnR1xWt17M7fJtEJigJeWUNGUqrauFXsHnqev9y9JTRGwk13tFBuKby4A==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/browserslist" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/browserslist" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "escalade": "^3.2.0", + "picocolors": "^1.1.1" + }, + "bin": { + "update-browserslist-db": "cli.js" + }, + "peerDependencies": { + "browserslist": ">= 4.21.0" + } + }, + "node_modules/uri-js": { + "version": "4.4.1", + "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz", + "integrity": "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "punycode": "^2.1.0" + } + }, + "node_modules/util-deprecate": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz", + "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==", + "dev": true, + "license": "MIT" + }, + "node_modules/vite": { + "version": "5.4.21", + "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz", + "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==", + "dev": true, + "license": "MIT", + "dependencies": { + "esbuild": "^0.21.3", + "postcss": "^8.4.43", + "rollup": "^4.20.0" + }, + "bin": { + "vite": "bin/vite.js" + }, + "engines": { + "node": "^18.0.0 || >=20.0.0" + }, + "funding": { + "url": "https://github.com/vitejs/vite?sponsor=1" + }, + "optionalDependencies": { + "fsevents": "~2.3.3" + }, + "peerDependencies": { + "@types/node": "^18.0.0 || >=20.0.0", + "less": "*", + "lightningcss": "^1.21.0", + "sass": "*", + "sass-embedded": "*", + "stylus": "*", + "sugarss": "*", + "terser": "^5.4.0" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + }, + "less": { + "optional": true + }, + "lightningcss": { + "optional": true + }, + "sass": { + "optional": true + }, + "sass-embedded": { + "optional": true + }, + "stylus": { + "optional": true + }, + "sugarss": { + "optional": true + }, + "terser": { + "optional": true + } + } + }, + "node_modules/which": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "dev": true, + "license": "ISC", + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "node-which": "bin/node-which" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/word-wrap": { + "version": "1.2.5", + "resolved": "https://registry.npmjs.org/word-wrap/-/word-wrap-1.2.5.tgz", + "integrity": "sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/wrap-ansi": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-8.1.0.tgz", + "integrity": "sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^6.1.0", + "string-width": "^5.0.1", + "strip-ansi": "^7.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, + "node_modules/wrap-ansi-cjs": { + "name": "wrap-ansi", + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", + "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, + "node_modules/wrap-ansi-cjs/node_modules/emoji-regex": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", + "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", + "dev": true, + "license": "MIT" + }, + "node_modules/wrap-ansi-cjs/node_modules/string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "license": "MIT", + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/wrap-ansi/node_modules/ansi-regex": { + "version": "6.2.2", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz", + "integrity": "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-regex?sponsor=1" + } + }, + "node_modules/wrap-ansi/node_modules/ansi-styles": { + "version": "6.2.3", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz", + "integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/wrap-ansi/node_modules/strip-ansi": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.1.2.tgz", + "integrity": "sha512-gmBGslpoQJtgnMAvOVqGZpEz9dyoKTCzy2nfz/n8aIFhN/jCE/rCmcxabB6jOOHV+0WNnylOxaxBQPSvcWklhA==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-regex": "^6.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/strip-ansi?sponsor=1" + } + }, + "node_modules/wrappy": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", + "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==", + "dev": true, + "license": "ISC" + }, + "node_modules/yallist": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz", + "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==", + "dev": true, + "license": "ISC" + }, + "node_modules/yocto-queue": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz", + "integrity": "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 00000000..bbf2c973 --- /dev/null +++ b/package.json @@ -0,0 +1,34 @@ +{ + "name": "microdao-mvp", + "version": "1.0.0", + "description": "MicroDAO MVP - Private AI Agent Network for Small Communities", + "type": "module", + "scripts": { + "dev": "vite", + "build": "tsc && vite build", + "preview": "vite preview", + "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0" + }, + "dependencies": { + "react": "^18.2.0", + "react-dom": "^18.2.0", + "react-router-dom": "^6.20.0", + "lucide-react": "^0.294.0" + }, + "devDependencies": { + "@types/react": "^18.2.43", + "@types/react-dom": "^18.2.17", + "@typescript-eslint/eslint-plugin": "^6.14.0", + "@typescript-eslint/parser": "^6.14.0", + "@vitejs/plugin-react": "^4.2.1", + "autoprefixer": "^10.4.16", + "eslint": "^8.55.0", + "eslint-plugin-react-hooks": "^4.6.0", + "eslint-plugin-react-refresh": "^0.4.5", + "postcss": "^8.4.32", + "tailwindcss": "^3.3.6", + "typescript": "^5.2.2", + "vite": "^5.0.8" + } +} + diff --git a/postcss.config.js b/postcss.config.js new file mode 100644 index 00000000..b4a6220e --- /dev/null +++ b/postcss.config.js @@ -0,0 +1,7 @@ +export default { + plugins: { + tailwindcss: {}, + autoprefixer: {}, + }, +} + diff --git a/push-to-github.sh b/push-to-github.sh new file mode 100755 index 00000000..4d104c34 --- /dev/null +++ b/push-to-github.sh @@ -0,0 +1,77 @@ +#!/bin/bash + +# Скрипт для публікації проєкту на GitHub +# Використання: ./push-to-github.sh YOUR_USERNAME REPO_NAME + +set -e + +USERNAME=${1:-"YOUR_USERNAME"} +REPO_NAME=${2:-"microdao-daarion"} + +echo "🚀 Підготовка до публікації на GitHub..." +echo "" + +# Перевірка SSH ключа +echo "📋 Перевірка SSH підключення..." +if ssh -T git@github.com 2>&1 | grep -q "successfully authenticated"; then + echo "✅ SSH ключ налаштовано!" +else + echo "❌ SSH ключ не налаштовано. Див. GITHUB_SETUP.md" + exit 1 +fi + +# Перевірка remote +echo "" +echo "📋 Перевірка remote..." +if git remote get-url origin > /dev/null 2>&1; then + echo "✅ Remote вже налаштовано:" + git remote -v + read -p "Використати існуючий remote? (y/n) " -n 1 -r + echo + if [[ ! $REPLY =~ ^[Yy]$ ]]; then + echo "Видаляю старий remote..." + git remote remove origin + else + echo "Використовую існуючий remote" + git push -u origin main + exit 0 + fi +fi + +# Додавання remote +echo "" +echo "📋 Додавання remote..." +git remote add origin "git@github.com:${USERNAME}/${REPO_NAME}.git" +echo "✅ Remote додано: git@github.com:${USERNAME}/${REPO_NAME}.git" + +# Додавання файлів +echo "" +echo "📋 Додавання файлів..." +git add . +echo "✅ Файли додані" + +# Коміт +echo "" +echo "📋 Створення коміту..." +if git diff --cached --quiet; then + echo "ℹ️ Немає змін для коміту" +else + git commit -m "chore: initial commit - MicroDAO & DAARION.city + +- Organize documentation structure (microdao, daarion, agents) +- 61 cursor technical docs +- Source code and configuration +- Setup instructions" + echo "✅ Коміт створено" +fi + +# Push +echo "" +echo "📋 Push на GitHub..." +git branch -M main +git push -u origin main + +echo "" +echo "🎉 Готово! Проєкт опубліковано на GitHub!" +echo "🔗 https://github.com/${USERNAME}/${REPO_NAME}" + diff --git a/src/App.tsx b/src/App.tsx new file mode 100644 index 00000000..5e3d1d1a --- /dev/null +++ b/src/App.tsx @@ -0,0 +1,15 @@ +import React from 'react'; +import { Routes, Route } from 'react-router-dom'; +import { OnboardingPage } from './pages/OnboardingPage'; + +function App() { + return ( + + } /> + Home - Coming soon} /> + + ); +} + +export default App; + diff --git a/src/README.md b/src/README.md index efc514ed..cb27e7b3 100644 --- a/src/README.md +++ b/src/README.md @@ -1,51 +1,71 @@ -# MicroDAO Frontend - Структура проекту +# MicroDAO Backend — Source Code Structure -## Структура каталогів +Цей документ описує структуру коду backend-частини MicroDAO/DAARION.city. + +## Структура папок ``` src/ - api/ # API клієнти та типи - client.ts # Базовий API клієнт - auth.ts # Авторизація - teams.ts # Спільноти - channels.ts # Канали - agents.ts # Агенти - components/ # React компоненти - onboarding/ # Компоненти онбордингу - OnboardingStepper.tsx - StepWelcome.tsx - StepCreateTeam.tsx - StepSelectMode.tsx - StepCreateChannel.tsx - StepAgentSettings.tsx - StepInvite.tsx - hooks/ # React hooks - useOnboarding.ts - pages/ # Сторінки - OnboardingPage.tsx - types/ # TypeScript типи - api.ts +├── domain/ # Чисті доменні типи та логіка (без I/O) +│ ├── dao/ # DAO domain types & logic +│ ├── wallet/ # Wallet domain types +│ ├── pdp/ # PDP policy model +│ └── user/ # User domain types +│ +├── services/ # Бізнес-логіка сервісів +│ ├── wallet/ # Wallet Service +│ ├── dao-factory/ # DAOFactory Service +│ ├── registry/ # Registry Service +│ ├── pdp/ # PDP Service +│ └── router/ # Router/Agent runtime (майбутнє) +│ +├── api/ # HTTP API layer +│ ├── http/ # Express routes +│ └── middleware/ # Auth, context middleware +│ +├── infra/ # Інфраструктура +│ ├── db/ # Database access +│ ├── logger/ # Logging +│ └── config/ # Configuration +│ +└── app.ts # Application entry point ``` -## Онбординг +## Принципи архітектури -Онбординг реалізовано як багатокроковий процес з 6 кроками: +1. **Domain Layer** (`domain/`) — чисті типи та бізнес-логіка без залежностей від інфраструктури +2. **Services Layer** (`services/`) — реалізація бізнес-логіки згідно `core-services-mvp.md` +3. **API Layer** (`api/`) — HTTP-рівень, що викликає сервіси +4. **Infrastructure Layer** (`infra/`) — БД, логування, конфігурація -1. **Ласкаво просимо** - привітальний екран -2. **Створити спільноту** - форма з назвою та описом -3. **Режим приватності** - вибір Public/Confidential -4. **Перший канал** - створення каналу -5. **Агент та пам'ять** - налаштування агента -6. **Запросити команду** - посилання-запрошення +## Документація -## API Інтеграція +- `docs/core-services-mvp.md` — специфікація core-сервісів +- `docs/api-mvp.md` — API специфікація +- `docs/pdp_access.md` — PDP та система доступів -Всі API виклики типізовані та обробляють помилки. Базовий URL налаштовується через змінну середовища `VITE_API_URL` (за замовчуванням `https://api.microdao.xyz`). +## Запуск -## Наступні кроки +```bash +npm install +npm run dev +``` -- Додати сторінку налаштувань (Settings) -- Реалізувати чат інтерфейс -- Додати публічний канал landing page -- Інтегрувати WebSocket для real-time оновлень +## MVP Status +Наразі реалізовано: +- ✅ Структура проекту +- ✅ Domain types +- ✅ Wallet Service (stub) +- ✅ DAOFactory Service +- ✅ Registry Service +- ✅ PDP Service +- ✅ HTTP Routes +- ✅ Middleware + +TODO: +- [ ] Інтеграція з реальною БД +- [ ] JWT авторизація +- [ ] On-chain інтеграція для Wallet +- [ ] Agent Runtime +- [ ] Тести diff --git a/src/api/http/agents.routes.ts b/src/api/http/agents.routes.ts new file mode 100644 index 00000000..539b8613 --- /dev/null +++ b/src/api/http/agents.routes.ts @@ -0,0 +1,53 @@ +/** + * Agents Routes (MVP Stub) + * Based on: api-mvp.md + * + * Endpoints: + * - POST /api/v1/dao/{dao_id}/agents/{agent_id}/invoke - Invoke agent + */ + +import { Router } from 'express'; +import { pdpService } from '../../services/pdp/pdp.service'; + +export const agentsRoutes = Router(); + +// POST /api/v1/dao/{dao_id}/agents/{agent_id}/invoke - Invoke agent +agentsRoutes.post('/:daoId/agents/:agentId/invoke', async (req, res) => { + try { + const userId = (req as any).userId; + const { daoId, agentId } = req.params; + const { input, metadata } = req.body; + + // Check PDP policy + const pdpResult = await pdpService.check( + 'policy.agent.run', + { agentId }, + { userId, daoId } + ); + + if (pdpResult.decision !== 'allow') { + res.status(403).json({ + error: 'ACCESS_DENIED', + message: pdpResult.reason || 'PDP denied', + }); + return; + } + + // MVP: Return stub response + // TODO: Implement actual agent invocation + const runId = `run_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`; + + res.json({ + run_id: runId, + status: 'queued', + output: null, + }); + } catch (error: any) { + res.status(500).json({ + error: 'INTERNAL_ERROR', + message: error.message, + }); + } +}); + + diff --git a/src/api/http/dao.routes.ts b/src/api/http/dao.routes.ts new file mode 100644 index 00000000..57702352 --- /dev/null +++ b/src/api/http/dao.routes.ts @@ -0,0 +1,78 @@ +/** + * DAO Routes + * Based on: api-mvp.md + * + * Endpoints: + * - POST /api/v1/dao - Create DAO + * - GET /api/v1/dao/{dao_id} - Get DAO by ID + * - GET /api/v1/dao - List DAOs + */ + +import { Router } from 'express'; +import { daoFactoryService } from '../../services/dao-factory/dao-factory.service'; +import { registryService } from '../../services/registry/registry.service'; +import type { CreateDaoInput } from '../../domain/dao/types'; + +export const daoRoutes = Router(); + +// POST /api/v1/dao - Create DAO +daoRoutes.post('/', async (req, res) => { + try { + const userId = (req as any).userId; + const input: CreateDaoInput = req.body; + + const result = await daoFactoryService.createDao(userId, input); + + res.status(201).json(result); + } catch (error: any) { + res.status(400).json({ + error: error.message || 'BAD_REQUEST', + message: error.message, + }); + } +}); + +// GET /api/v1/dao/{dao_id} - Get DAO by ID +daoRoutes.get('/:daoId', async (req, res) => { + try { + const { daoId } = req.params; + const dao = await registryService.getDaoById(daoId); + + if (!dao) { + res.status(404).json({ + error: 'NOT_FOUND', + message: `DAO ${daoId} not found`, + }); + return; + } + + res.json(dao); + } catch (error: any) { + res.status(500).json({ + error: 'INTERNAL_ERROR', + message: error.message, + }); + } +}); + +// GET /api/v1/dao - List DAOs +daoRoutes.get('/', async (req, res) => { + try { + const { level, type } = req.query; + const filter = { + level: level as string | undefined, + type: type as string | undefined, + }; + + const daos = await registryService.listDaos(filter); + + res.json({ items: daos }); + } catch (error: any) { + res.status(500).json({ + error: 'INTERNAL_ERROR', + message: error.message, + }); + } +}); + + diff --git a/src/api/http/pdp.routes.ts b/src/api/http/pdp.routes.ts new file mode 100644 index 00000000..6dac2de8 --- /dev/null +++ b/src/api/http/pdp.routes.ts @@ -0,0 +1,38 @@ +/** + * PDP Routes + * Based on: api-mvp.md + * + * Endpoints: + * - POST /api/v1/pdp/check - Check policy + */ + +import { Router } from 'express'; +import { pdpService } from '../../services/pdp/pdp.service'; +import type { PdpRequest } from '../../domain/pdp/policy.model'; + +export const pdpRoutes = Router(); + +// POST /api/v1/pdp/check - Check policy +pdpRoutes.post('/check', async (req, res) => { + try { + const userId = (req as any).userId; + const { policy, resource, context }: PdpRequest = req.body; + + const result = await pdpService.check(policy, resource, { + ...context, + userId: context.userId || userId, + }); + + res.json({ + decision: result.decision, + reason: result.reason || null, + }); + } catch (error: any) { + res.status(500).json({ + error: 'INTERNAL_ERROR', + message: error.message, + }); + } +}); + + diff --git a/src/api/http/platforms.routes.ts b/src/api/http/platforms.routes.ts new file mode 100644 index 00000000..42b00f89 --- /dev/null +++ b/src/api/http/platforms.routes.ts @@ -0,0 +1,48 @@ +/** + * Platforms Routes + * Based on: api-mvp.md + * + * Endpoints: + * - POST /api/v1/platforms - Create platform + * - GET /api/v1/platforms - List platforms + */ + +import { Router } from 'express'; +import { daoFactoryService } from '../../services/dao-factory/dao-factory.service'; +import { registryService } from '../../services/registry/registry.service'; +import type { CreatePlatformInput } from '../../domain/dao/types'; + +export const platformsRoutes = Router(); + +// POST /api/v1/platforms - Create platform +platformsRoutes.post('/', async (req, res) => { + try { + const userId = (req as any).userId; + const input: CreatePlatformInput = req.body; + + const result = await daoFactoryService.createPlatform(userId, input); + + res.status(201).json(result); + } catch (error: any) { + res.status(400).json({ + error: error.message || 'BAD_REQUEST', + message: error.message, + }); + } +}); + +// GET /api/v1/platforms - List platforms +platformsRoutes.get('/', async (req, res) => { + try { + const platforms = await registryService.listPlatforms(); + + res.json({ items: platforms }); + } catch (error: any) { + res.status(500).json({ + error: 'INTERNAL_ERROR', + message: error.message, + }); + } +}); + + diff --git a/src/api/http/vendor.routes.ts b/src/api/http/vendor.routes.ts new file mode 100644 index 00000000..8081ce33 --- /dev/null +++ b/src/api/http/vendor.routes.ts @@ -0,0 +1,52 @@ +/** + * Vendor Routes + * Based on: api-mvp.md + * + * Endpoints: + * - POST /api/v1/platforms/{platform_id}/vendors - Register vendor + */ + +import { Router } from 'express'; +import { pdpService } from '../../services/pdp/pdp.service'; + +export const vendorRoutes = Router(); + +// POST /api/v1/platforms/{platform_id}/vendors - Register vendor +vendorRoutes.post('/:platformId/vendors', async (req, res) => { + try { + const userId = (req as any).userId; + const { platformId } = req.params; + const { display_name, contact } = req.body; + + // Check PDP policy + const pdpResult = await pdpService.check( + 'policy.vendor.register', + { platformId }, + { userId, daoId: platformId, daoLevel: 'A2' } + ); + + if (pdpResult.decision !== 'allow') { + res.status(403).json({ + error: 'ACCESS_DENIED', + message: pdpResult.reason || 'PDP denied', + }); + return; + } + + // TODO: Save vendor to database + const vendorId = `vendor_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`; + + res.status(201).json({ + vendor_id: vendorId, + platform_id: platformId, + status: 'approved', + }); + } catch (error: any) { + res.status(500).json({ + error: 'INTERNAL_ERROR', + message: error.message, + }); + } +}); + + diff --git a/src/api/http/wallet.routes.ts b/src/api/http/wallet.routes.ts new file mode 100644 index 00000000..1c23d15b --- /dev/null +++ b/src/api/http/wallet.routes.ts @@ -0,0 +1,72 @@ +/** + * Wallet Routes + * Based on: api-mvp.md + * + * Endpoints: + * - GET /api/v1/wallet/me - Get user balances + * - POST /api/v1/wallet/check-access - Check access for action + */ + +import { Router } from 'express'; +import { walletService } from '../../services/wallet/wallet.service'; +import type { AccessCheck } from '../../domain/wallet/types'; + +export const walletRoutes = Router(); + +// GET /api/v1/wallet/me - Get user balances +walletRoutes.get('/me', async (req, res) => { + try { + const userId = (req as any).userId; + const balances = await walletService.getBalances(userId); + + res.json({ + user_id: userId, + balances, + }); + } catch (error: any) { + res.status(500).json({ + error: 'INTERNAL_ERROR', + message: error.message, + }); + } +}); + +// POST /api/v1/wallet/check-access - Check access +walletRoutes.post('/check-access', async (req, res) => { + try { + const userId = (req as any).userId; + const { check }: AccessCheck = req.body; + + let allowed = false; + let reason: string | undefined; + + switch (check) { + case 'dao.create': + allowed = await walletService.hasEnoughForDaoCreate(userId); + if (!allowed) reason = 'INSUFFICIENT_BALANCE'; + break; + case 'vendor.register': + allowed = await walletService.hasEnoughForVendorRegister(userId); + if (!allowed) reason = 'INSUFFICIENT_STAKED_DAARION'; + break; + case 'platform.create': + allowed = await walletService.hasEnoughForPlatformCreate(userId); + if (!allowed) reason = 'INSUFFICIENT_STAKED_DAARION'; + break; + default: + reason = 'UNKNOWN_CHECK'; + } + + res.json({ + allowed, + reason: allowed ? null : reason, + }); + } catch (error: any) { + res.status(500).json({ + error: 'INTERNAL_ERROR', + message: error.message, + }); + } +}); + + diff --git a/src/api/middleware/auth.middleware.ts b/src/api/middleware/auth.middleware.ts new file mode 100644 index 00000000..f6695ac7 --- /dev/null +++ b/src/api/middleware/auth.middleware.ts @@ -0,0 +1,39 @@ +/** + * Auth Middleware + * Validates Bearer token + * MVP: Simple validation, replace with proper JWT validation later + */ + +import type { Request, Response, NextFunction } from 'express'; + +export function authMiddleware(req: Request, res: Response, next: NextFunction): void { + const authHeader = req.headers.authorization; + + if (!authHeader || !authHeader.startsWith('Bearer ')) { + res.status(401).json({ + error: 'UNAUTHORIZED', + message: 'Missing or invalid Authorization header', + }); + return; + } + + const token = authHeader.substring(7); + + // MVP: Simple validation (just check token exists) + // TODO: Validate JWT token properly + if (!token) { + res.status(401).json({ + error: 'UNAUTHORIZED', + message: 'Invalid token', + }); + return; + } + + // Attach user ID to request (MVP: extract from token) + // TODO: Decode JWT and extract userId + (req as any).userId = 'user_stub'; // Replace with actual user ID from token + + next(); +} + + diff --git a/src/api/middleware/context.middleware.ts b/src/api/middleware/context.middleware.ts new file mode 100644 index 00000000..1a1617a6 --- /dev/null +++ b/src/api/middleware/context.middleware.ts @@ -0,0 +1,18 @@ +/** + * Context Middleware + * Extracts X-DAO-ID header and attaches to request context + */ + +import type { Request, Response, NextFunction } from 'express'; + +export function contextMiddleware(req: Request, res: Response, next: NextFunction): void { + const daoId = req.headers['x-dao-id'] as string | undefined; + + if (daoId) { + (req as any).daoId = daoId; + } + + next(); +} + + diff --git a/src/app.ts b/src/app.ts new file mode 100644 index 00000000..1629dbcd --- /dev/null +++ b/src/app.ts @@ -0,0 +1,45 @@ +/** + * Application Entry Point + * Sets up HTTP server and registers routes + */ + +import express from 'express'; +import { config } from './infra/config/env'; +import { logger } from './infra/logger/logger'; +import { authMiddleware } from './api/middleware/auth.middleware'; +import { contextMiddleware } from './api/middleware/context.middleware'; +import { daoRoutes } from './api/http/dao.routes'; +import { walletRoutes } from './api/http/wallet.routes'; +import { pdpRoutes } from './api/http/pdp.routes'; +import { vendorRoutes } from './api/http/vendor.routes'; +import { platformsRoutes } from './api/http/platforms.routes'; +import { agentsRoutes } from './api/http/agents.routes'; + +const app = express(); + +// Middleware +app.use(express.json()); +app.use(authMiddleware); +app.use(contextMiddleware); + +// Routes +app.use('/api/v1/dao', daoRoutes); +app.use('/api/v1/wallet', walletRoutes); +app.use('/api/v1/pdp', pdpRoutes); +app.use('/api/v1/platforms', platformsRoutes); +app.use('/api/v1/platforms', vendorRoutes); // Vendor routes under platforms +app.use('/api/v1', agentsRoutes); + +// Health check +app.get('/health', (req, res) => { + res.json({ status: 'ok' }); +}); + +// Start server +const port = config.port; +app.listen(port, () => { + logger.info(`Server started on port ${port}`); +}); + +export default app; + diff --git a/src/domain/dao/dao.logic.ts b/src/domain/dao/dao.logic.ts new file mode 100644 index 00000000..5a6e16fc --- /dev/null +++ b/src/domain/dao/dao.logic.ts @@ -0,0 +1,30 @@ +/** + * Pure domain logic for DAO operations + * No I/O, no side effects + */ + +import type { DaoRecord, DaoLevel, FederationMode } from './types'; + +/** + * Check if DAO can become a SuperDAO + */ +export function canBecomeSuperDao(dao: DaoRecord, childCount: number): boolean { + return childCount >= 1 && dao.federationMode === 'none'; +} + +/** + * Check if DAO can join a federation + */ +export function canJoinFederation(dao: DaoRecord, targetLevel: DaoLevel): boolean { + // A3/A4 can join, exceptions for A2 handled by PDP + return (dao.level === 'A3' || dao.level === 'A4') && dao.federationMode === 'none'; +} + +/** + * Check if DAO can leave federation + */ +export function canLeaveFederation(dao: DaoRecord): boolean { + return dao.federationMode === 'member' && dao.parentDaoId !== null; +} + + diff --git a/src/domain/dao/types.ts b/src/domain/dao/types.ts new file mode 100644 index 00000000..f9660e71 --- /dev/null +++ b/src/domain/dao/types.ts @@ -0,0 +1,37 @@ +/** + * Domain types for DAO entities + * Based on: microdao-architecture.md, superdao-federation.md + */ + +export type DaoLevel = 'A1' | 'A2' | 'A3' | 'A4'; +export type DaoType = 'platform' | 'public' | 'private'; +export type FederationMode = 'none' | 'member' | 'superdao'; + +export interface DaoRecord { + daoId: string; + name: string; + description?: string; + level: DaoLevel; + type: DaoType; + parentDaoId?: string | null; + federationMode: FederationMode; + createdAt: string; + updatedAt?: string; +} + +export interface CreateDaoInput { + name: string; + description?: string; + type: 'public' | 'private'; + level: 'A3' | 'A4'; + settings?: Record; +} + +export interface CreatePlatformInput { + name: string; + slug: string; + description?: string; + domain?: string; // 'energy' | 'food' | 'water' | ... +} + + diff --git a/src/domain/pdp/policy.model.ts b/src/domain/pdp/policy.model.ts new file mode 100644 index 00000000..ee9768a7 --- /dev/null +++ b/src/domain/pdp/policy.model.ts @@ -0,0 +1,38 @@ +/** + * PDP Policy Model + * Based on: pdp_access.md, core-services-mvp.md + */ + +export type Decision = 'allow' | 'deny' | 'require-elevation'; + +export type PolicyId = + | 'policy.dao.create' + | 'policy.vendor.register' + | 'policy.platform.create' + | 'policy.federation.join' + | 'policy.federation.leave' + | 'policy.federation.create-superdao' + | 'policy.federation.dissolve' + | 'policy.agent.run'; + +export interface PdpContext { + userId?: string; + daoId?: string; + daoLevel?: 'A1' | 'A2' | 'A3' | 'A4'; + // Additional context: roles, balances, staking, etc. + [key: string]: unknown; +} + +export interface PdpRequest { + policyId: PolicyId; + resource: Record; + context: PdpContext; +} + +export interface PdpResponse { + decision: Decision; + reason?: string; + details?: Record; +} + + diff --git a/src/domain/user/types.ts b/src/domain/user/types.ts new file mode 100644 index 00000000..38c6cc60 --- /dev/null +++ b/src/domain/user/types.ts @@ -0,0 +1,14 @@ +/** + * Domain types for User + */ + +export type UserRole = 'owner' | 'admin' | 'member' | 'guest' | 'agent'; + +export interface User { + userId: string; + email?: string; + name?: string; + roles?: UserRole[]; +} + + diff --git a/src/domain/wallet/types.ts b/src/domain/wallet/types.ts new file mode 100644 index 00000000..ce2867bc --- /dev/null +++ b/src/domain/wallet/types.ts @@ -0,0 +1,27 @@ +/** + * Domain types for Wallet + * Based on: core-services-mvp.md, tokenomics/city-tokenomics.md + */ + +export type TokenSymbol = 'DAAR' | 'DAARION'; + +export interface Balance { + symbol: TokenSymbol; + amount: string; // Decimal as string to avoid precision issues +} + +export interface WalletBalances { + userId: string; + balances: Balance[]; +} + +export interface AccessCheck { + check: 'dao.create' | 'vendor.register' | 'platform.create'; +} + +export interface AccessCheckResult { + allowed: boolean; + reason?: string; +} + + diff --git a/src/index.css b/src/index.css new file mode 100644 index 00000000..e26cf90c --- /dev/null +++ b/src/index.css @@ -0,0 +1,24 @@ +@tailwind base; +@tailwind components; +@tailwind utilities; + +:root { + --primary: #3F51F5; + --success: #43A047; + --error: #E53935; + --gray-100: #F8F9FA; + --gray-200: #ECEFF1; + --gray-800: #263238; +} + +body { + margin: 0; + font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; +} + +#root { + min-height: 100vh; +} + diff --git a/src/infra/config/env.ts b/src/infra/config/env.ts new file mode 100644 index 00000000..2568299e --- /dev/null +++ b/src/infra/config/env.ts @@ -0,0 +1,21 @@ +/** + * Environment Configuration + * Load and validate environment variables + */ + +export const config = { + port: parseInt(process.env.PORT || '3000', 10), + nodeEnv: process.env.NODE_ENV || 'development', + apiBaseUrl: process.env.API_BASE_URL || 'http://localhost:3000', + + // Database + dbUrl: process.env.DATABASE_URL || 'postgresql://localhost:5432/microdao', + + // Auth + jwtSecret: process.env.JWT_SECRET || 'change-me-in-production', + + // Wallet/Chain (future) + chainRpcUrl: process.env.CHAIN_RPC_URL || '', +}; + + diff --git a/src/infra/db/client.ts b/src/infra/db/client.ts new file mode 100644 index 00000000..4afd8bbb --- /dev/null +++ b/src/infra/db/client.ts @@ -0,0 +1,20 @@ +/** + * Database Client + * MVP: Placeholder for future DB connection + * TODO: Replace with actual DB client (PostgreSQL, etc.) + */ + +// MVP: No-op +export const dbClient = { + connect: async () => { + // TODO: Implement actual DB connection + console.log('[DB] Connected (stub)'); + }, + + disconnect: async () => { + // TODO: Implement actual DB disconnection + console.log('[DB] Disconnected (stub)'); + }, +}; + + diff --git a/src/infra/db/dao.repository.ts b/src/infra/db/dao.repository.ts new file mode 100644 index 00000000..26556125 --- /dev/null +++ b/src/infra/db/dao.repository.ts @@ -0,0 +1,44 @@ +/** + * DAO Repository + * Database access layer for DAO records + * MVP: In-memory storage, replace with actual DB later + */ + +import type { DaoRecord } from '../../domain/dao/types'; + +// MVP: In-memory storage +const daoStore: Map = new Map(); + +export const daoRepository = { + async save(record: DaoRecord): Promise { + daoStore.set(record.daoId, record); + }, + + async findById(daoId: string): Promise { + return daoStore.get(daoId) || null; + }, + + async findAll(filter?: { level?: string; type?: string }): Promise { + const all = Array.from(daoStore.values()); + + if (!filter) { + return all; + } + + return all.filter(dao => { + if (filter.level && dao.level !== filter.level) { + return false; + } + if (filter.type && dao.type !== filter.type) { + return false; + } + return true; + }); + }, + + async delete(daoId: string): Promise { + daoStore.delete(daoId); + }, +}; + + diff --git a/src/infra/logger/logger.ts b/src/infra/logger/logger.ts new file mode 100644 index 00000000..475e5e20 --- /dev/null +++ b/src/infra/logger/logger.ts @@ -0,0 +1,27 @@ +/** + * Logger + * MVP: Simple console logger + * Future: Replace with proper logging library (Winston, Pino, etc.) + */ + +type LogLevel = 'info' | 'warn' | 'error' | 'debug'; + +export const logger = { + info: (message: string, ...args: unknown[]) => { + console.log(`[INFO] ${message}`, ...args); + }, + + warn: (message: string, ...args: unknown[]) => { + console.warn(`[WARN] ${message}`, ...args); + }, + + error: (message: string, ...args: unknown[]) => { + console.error(`[ERROR] ${message}`, ...args); + }, + + debug: (message: string, ...args: unknown[]) => { + console.debug(`[DEBUG] ${message}`, ...args); + }, +}; + + diff --git a/src/main.tsx b/src/main.tsx new file mode 100644 index 00000000..70023289 --- /dev/null +++ b/src/main.tsx @@ -0,0 +1,14 @@ +import React from 'react'; +import ReactDOM from 'react-dom/client'; +import { BrowserRouter } from 'react-router-dom'; +import App from './App'; +import './index.css'; + +ReactDOM.createRoot(document.getElementById('root')!).render( + + + + + , +); + diff --git a/src/services/dao-factory/dao-factory.service.ts b/src/services/dao-factory/dao-factory.service.ts new file mode 100644 index 00000000..78bb7026 --- /dev/null +++ b/src/services/dao-factory/dao-factory.service.ts @@ -0,0 +1,109 @@ +/** + * DAOFactory Service (MVP) + * Based on: core-services-mvp.md + * + * Responsibilities: + * - Create new DAO (A3/A4) + * - Create platforms (A2) + * - Validate input + * - Call PDP for access checks + * - Write DAO to Registry + */ + +import type { CreateDaoInput, CreatePlatformInput } from '../../domain/dao/types'; +import { pdpService } from '../pdp/pdp.service'; +import { walletService } from '../wallet/wallet.service'; +import { registryService } from '../registry/registry.service'; + +export class DaoFactoryService { + /** + * Create a new MicroDAO (A3 or A4) + */ + async createDao(userId: string, input: CreateDaoInput): Promise<{ daoId: string }> { + // 1. Check wallet balance + const hasEnough = await walletService.hasEnoughForDaoCreate(userId); + if (!hasEnough) { + throw new Error('INSUFFICIENT_BALANCE: Need 1 DAAR or 0.01 DAARION'); + } + + // 2. Check PDP policy + const pdpResult = await pdpService.check( + 'policy.dao.create', + { type: 'dao' }, + { userId, daoLevel: input.level } + ); + + if (pdpResult.decision !== 'allow') { + throw new Error(`ACCESS_DENIED: ${pdpResult.reason || 'PDP denied'}`); + } + + // 3. Create DAO record + const daoId = this.generateDaoId(); + const daoRecord = { + daoId, + name: input.name, + description: input.description, + level: input.level, + type: input.type, + parentDaoId: null, + federationMode: 'none' as const, + createdAt: new Date().toISOString(), + }; + + // 4. Save to Registry + await registryService.saveDao(daoRecord); + + return { daoId }; + } + + /** + * Create a new platform (A2) + */ + async createPlatform(userId: string, input: CreatePlatformInput): Promise<{ daoId: string }> { + // 1. Check wallet balance + const hasEnough = await walletService.hasEnoughForPlatformCreate(userId); + if (!hasEnough) { + throw new Error('INSUFFICIENT_BALANCE: Need 1 DAARION staked'); + } + + // 2. Check PDP policy + const pdpResult = await pdpService.check( + 'policy.platform.create', + { type: 'platform' }, + { userId, daoLevel: 'A2' } + ); + + if (pdpResult.decision !== 'allow') { + throw new Error(`ACCESS_DENIED: ${pdpResult.reason || 'PDP denied'}`); + } + + // 3. Create platform record + const daoId = this.generateDaoId(); + const daoRecord = { + daoId, + name: input.name, + description: input.description, + level: 'A2' as const, + type: 'platform' as const, + parentDaoId: null, + federationMode: 'none' as const, + createdAt: new Date().toISOString(), + }; + + // 4. Save to Registry + await registryService.saveDao(daoRecord); + + return { daoId }; + } + + private generateDaoId(): string { + // MVP: Simple UUID-like generation + // TODO: Use proper UUID library + return `dao_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`; + } +} + +// Singleton instance +export const daoFactoryService = new DaoFactoryService(); + + diff --git a/src/services/pdp/pdp.service.ts b/src/services/pdp/pdp.service.ts new file mode 100644 index 00000000..f541c303 --- /dev/null +++ b/src/services/pdp/pdp.service.ts @@ -0,0 +1,100 @@ +/** + * PDP Service (MVP) + * Based on: pdp_access.md, core-services-mvp.md + * + * Responsibilities: + * - Centralized access decision making + * - Interpret policies from pdp_access.md + * - Provide simple API for other services + */ + +import type { PdpRequest, PdpResponse, PolicyId, PdpContext } from '../../domain/pdp/policy.model'; +import { policiesConfig } from './policies.config'; +import { walletService } from '../wallet/wallet.service'; + +export class PdpService { + /** + * Check policy and return decision + */ + async check( + policyId: PolicyId, + resource: Record, + context: PdpContext + ): Promise { + const policy = policiesConfig[policyId]; + + if (!policy) { + return { + decision: 'deny', + reason: `Policy ${policyId} not found`, + }; + } + + // Evaluate policy conditions + const result = await this.evaluatePolicy(policy, resource, context); + + return result; + } + + private async evaluatePolicy( + policy: any, + resource: Record, + context: PdpContext + ): Promise { + // MVP: Simple evaluation + // Future: More complex condition evaluation + + // Example: policy.dao.create + if (policy.id === 'policy.dao.create') { + const hasEnough = await walletService.hasEnoughForDaoCreate(context.userId || ''); + if (!hasEnough) { + return { + decision: 'deny', + reason: 'INSUFFICIENT_BALANCE', + details: { + required: { DAAR: 1.0, DAARION: 0.01 }, + }, + }; + } + return { decision: 'allow' }; + } + + // Example: policy.platform.create + if (policy.id === 'policy.platform.create') { + const hasEnough = await walletService.hasEnoughForPlatformCreate(context.userId || ''); + if (!hasEnough) { + return { + decision: 'deny', + reason: 'INSUFFICIENT_BALANCE', + details: { + required: { DAARION: 1.0 }, + }, + }; + } + return { decision: 'allow' }; + } + + // Example: policy.vendor.register + if (policy.id === 'policy.vendor.register') { + const hasEnough = await walletService.hasEnoughForVendorRegister(context.userId || ''); + if (!hasEnough) { + return { + decision: 'deny', + reason: 'INSUFFICIENT_STAKED_DAARION', + details: { + required: { DAARION: 0.01 }, + }, + }; + } + return { decision: 'allow' }; + } + + // Default: allow (for MVP, can be more restrictive later) + return { decision: 'allow' }; + } +} + +// Singleton instance +export const pdpService = new PdpService(); + + diff --git a/src/services/pdp/policies.config.ts b/src/services/pdp/policies.config.ts new file mode 100644 index 00000000..fcaf26c0 --- /dev/null +++ b/src/services/pdp/policies.config.ts @@ -0,0 +1,76 @@ +/** + * Policies Configuration + * Based on: pdp_access.md + * + * Initial set of policies for MVP + */ + +export const policiesConfig = { + 'policy.dao.create': { + id: 'policy.dao.create', + description: 'Створення нового MicroDAO', + conditions: [ + { + type: 'or', + rules: [ + { type: 'balance', token: 'DAAR', gte: 1 }, + { type: 'balance', token: 'DAARION', gte: 0.01 }, + ], + }, + ], + }, + 'policy.vendor.register': { + id: 'policy.vendor.register', + description: 'Реєстрація вендора на платформі', + conditions: [ + { type: 'staked', token: 'DAARION', gte: 0.01 }, + ], + }, + 'policy.platform.create': { + id: 'policy.platform.create', + description: 'Створення платформи', + conditions: [ + { type: 'staked', token: 'DAARION', gte: 1 }, + ], + }, + 'policy.federation.join': { + id: 'policy.federation.join', + description: 'Вступ DAO до SuperDAO', + conditions: [ + { type: 'role', value: 'owner' }, + { type: 'target', property: 'federation_mode', value: 'superdao' }, + ], + }, + 'policy.federation.leave': { + id: 'policy.federation.leave', + description: 'Вихід DAO з SuperDAO', + conditions: [ + { type: 'role', value: 'owner' }, + ], + }, + 'policy.federation.create-superdao': { + id: 'policy.federation.create-superdao', + description: 'Створення SuperDAO', + conditions: [ + { type: 'role', value: 'owner' }, + { type: 'dao', property: 'child_count', gte: 1 }, + ], + }, + 'policy.federation.dissolve': { + id: 'policy.federation.dissolve', + description: 'Розформування федерації', + conditions: [ + { type: 'role', value: 'owner' }, + { type: 'dao', property: 'level', ne: 'A1' }, + ], + }, + 'policy.agent.run': { + id: 'policy.agent.run', + description: 'Запуск агента', + conditions: [ + { type: 'agent', property: 'registered', value: true }, + ], + }, +} as const; + + diff --git a/src/services/registry/registry.service.ts b/src/services/registry/registry.service.ts new file mode 100644 index 00000000..346f3a1f --- /dev/null +++ b/src/services/registry/registry.service.ts @@ -0,0 +1,47 @@ +/** + * Registry Service (MVP) + * Based on: core-services-mvp.md + * + * Responsibilities: + * - Store all DAO information + * - Mark DAO as platform (A2) or MicroDAO (A3/A4) + * - Provide public catalog of DAO/platforms + */ + +import type { DaoRecord } from '../../domain/dao/types'; +import { daoRepository } from '../../infra/db/dao.repository'; + +export class RegistryService { + /** + * Save DAO record to registry + */ + async saveDao(record: DaoRecord): Promise { + await daoRepository.save(record); + } + + /** + * Get DAO by ID + */ + async getDaoById(daoId: string): Promise { + return daoRepository.findById(daoId); + } + + /** + * List DAOs with optional filters + */ + async listDaos(filter?: { level?: string; type?: string }): Promise { + return daoRepository.findAll(filter); + } + + /** + * List all platforms (A2, type=platform) + */ + async listPlatforms(): Promise { + return daoRepository.findAll({ level: 'A2', type: 'platform' }); + } +} + +// Singleton instance +export const registryService = new RegistryService(); + + diff --git a/src/services/wallet/wallet.adapter.ts b/src/services/wallet/wallet.adapter.ts new file mode 100644 index 00000000..190793ea --- /dev/null +++ b/src/services/wallet/wallet.adapter.ts @@ -0,0 +1,36 @@ +/** + * Wallet Adapter (MVP Stub) + * + * On MVP: returns mock data or reads from DB/stub + * Future: integrate with on-chain data + */ + +import type { Balance } from '../../domain/wallet/types'; + +/** + * Get balances from external source (on-chain / DB / stub) + */ +export async function getBalances(userId: string): Promise { + // MVP: Return mock data + // TODO: Replace with actual DB/on-chain integration + return [ + { symbol: 'DAAR', amount: '0.0' }, + { symbol: 'DAARION', amount: '0.0' }, + ]; +} + +/** + * Get staked DAARION amount + */ +export async function getStakedDaarion(userId: string): Promise { + // MVP: Return mock data + // TODO: Replace with actual DB/on-chain integration + return 0.0; +} + +export const walletAdapter = { + getBalances, + getStakedDaarion, +}; + + diff --git a/src/services/wallet/wallet.interface.ts b/src/services/wallet/wallet.interface.ts new file mode 100644 index 00000000..b4b0c3a7 --- /dev/null +++ b/src/services/wallet/wallet.interface.ts @@ -0,0 +1,15 @@ +/** + * Wallet Service Interface + * Based on: core-services-mvp.md + */ + +import type { Balance } from '../../domain/wallet/types'; + +export interface WalletService { + getBalances(userId: string): Promise; + hasEnoughForDaoCreate(userId: string): Promise; + hasEnoughForVendorRegister(userId: string): Promise; + hasEnoughForPlatformCreate(userId: string): Promise; +} + + diff --git a/src/services/wallet/wallet.service.ts b/src/services/wallet/wallet.service.ts new file mode 100644 index 00000000..5f67cca8 --- /dev/null +++ b/src/services/wallet/wallet.service.ts @@ -0,0 +1,61 @@ +/** + * Wallet Service (MVP) + * Based on: core-services-mvp.md + * + * Responsibilities: + * - Read DAAR / DAARION balances + * - Provide helper functions for access checks + */ + +import type { WalletService as IWalletService } from './wallet.interface'; +import { walletAdapter } from './wallet.adapter'; +import type { Balance, TokenSymbol } from '../../domain/wallet/types'; + +export class WalletService implements IWalletService { + /** + * Get user balances for DAAR and DAARION + */ + async getBalances(userId: string): Promise { + return walletAdapter.getBalances(userId); + } + + /** + * Check if user has enough tokens to create a DAO + * Requires: 1 DAAR OR 0.01 DAARION + */ + async hasEnoughForDaoCreate(userId: string): Promise { + const balances = await this.getBalances(userId); + + const daar = balances.find(b => b.symbol === 'DAAR'); + const daarion = balances.find(b => b.symbol === 'DAARION'); + + // Check: 1 DAAR OR 0.01 DAARION + const hasEnoughDaar = daar && parseFloat(daar.amount) >= 1.0; + const hasEnoughDaarion = daarion && parseFloat(daarion.amount) >= 0.01; + + return hasEnoughDaar || hasEnoughDaarion; + } + + /** + * Check if user has enough staked DAARION for vendor registration + * Requires: 0.01 DAARION staked + */ + async hasEnoughForVendorRegister(userId: string): Promise { + const staked = await walletAdapter.getStakedDaarion(userId); + return staked >= 0.01; + } + + /** + * Check if user has enough staked DAARION for platform creation + * Requires: 1 DAARION staked + */ + async hasEnoughForPlatformCreate(userId: string): Promise { + const staked = await walletAdapter.getStakedDaarion(userId); + return staked >= 1.0; + } +} + +// Singleton instance +export const walletService = new WalletService(); + + diff --git a/supabase/migrations/000001_init.sql b/supabase/migrations/000001_init.sql new file mode 100644 index 00000000..871a0754 --- /dev/null +++ b/supabase/migrations/000001_init.sql @@ -0,0 +1,24 @@ +-- 000001_init.sql +-- Up + +create extension if not exists "uuid-ossp"; +create extension if not exists "pgcrypto"; +create extension if not exists "vector"; + +create table if not exists users ( + id text primary key, -- u_... + email text unique not null, + created_at timestamptz not null default now(), + last_login_at timestamptz +); + +create table if not exists sessions ( + session_id text primary key, + user_id text not null references users(id) on delete cascade, + created_at timestamptz not null default now(), + expires_at timestamptz +); + +-- Down +drop table if exists sessions cascade; +drop table if exists users cascade; diff --git a/supabase/migrations/000002_microdao_core.sql b/supabase/migrations/000002_microdao_core.sql new file mode 100644 index 00000000..a5056646 --- /dev/null +++ b/supabase/migrations/000002_microdao_core.sql @@ -0,0 +1,75 @@ +-- 000002_microdao_core.sql +-- Up + +create table if not exists teams ( + id text primary key, -- t_... + name text not null, + slug text unique not null, + mode text not null check (mode in ('public','confidential')), + created_at timestamptz not null default now() +); + +create table if not exists team_members ( + team_id text not null references teams(id) on delete cascade, + user_id text not null references users(id) on delete cascade, + role text not null check (role in ('Owner','Guardian','Member')), + viewer_type text not null check (viewer_type in ('reader','commenter','contributor')), + created_at timestamptz not null default now(), + primary key (team_id, user_id) +); + +create index if not exists idx_team_members_user_id + on team_members(user_id); + +create table if not exists channels ( + id text primary key, -- c_... + team_id text not null references teams(id) on delete cascade, + name text not null, + created_at timestamptz not null default now() +); + +create index if not exists idx_channels_team_id + on channels(team_id); + +create table if not exists messages ( + id text primary key, -- m_... + channel_id text not null references channels(id) on delete cascade, + user_id text references users(id) on delete set null, + body text, + metadata jsonb default '{}'::jsonb, + created_at timestamptz not null default now() +); + +create index if not exists idx_messages_channel_id_created_at + on messages(channel_id, created_at); + +create table if not exists followups ( + id text primary key, -- f_... + message_id text not null references messages(id) on delete cascade, + type text, -- agent/tool/summary/... + payload jsonb default '{}'::jsonb, + created_at timestamptz not null default now() +); + +create index if not exists idx_followups_message_id + on followups(message_id); + +create table if not exists comemory_items ( + id text primary key, + team_id text not null references teams(id) on delete cascade, + embeddings vector(1536), + summary text, + source_message text, + created_at timestamptz not null default now() +); + +create index if not exists idx_comemory_items_team_id + on comemory_items(team_id); + +-- Down +drop table if exists comemory_items cascade; +drop table if exists followups cascade; +drop table if exists messages cascade; +drop table if exists channels cascade; +drop table if exists team_members cascade; +drop table if exists teams cascade; diff --git a/supabase/migrations/000003_projects_tasks.sql b/supabase/migrations/000003_projects_tasks.sql new file mode 100644 index 00000000..aee11817 --- /dev/null +++ b/supabase/migrations/000003_projects_tasks.sql @@ -0,0 +1,37 @@ +-- 000003_projects_tasks.sql +-- Up + +create table if not exists projects ( + id text primary key, -- p_... + team_id text not null references teams(id) on delete cascade, + name text not null, + description text, + status text not null default 'active' check (status in ('active','archived')), + created_at timestamptz not null default now(), + updated_at timestamptz +); + +create index if not exists idx_projects_team_id + on projects(team_id); + +create table if not exists tasks ( + id text primary key, -- task_... + project_id text not null references projects(id) on delete cascade, + title text not null, + description text, + status text not null default 'todo' + check (status in ('todo','in_progress','done','cancelled')), + assignee text references users(id) on delete set null, + created_at timestamptz not null default now(), + updated_at timestamptz +); + +create index if not exists idx_tasks_project_id + on tasks(project_id); + +create index if not exists idx_tasks_assignee + on tasks(assignee); + +-- Down +drop table if exists tasks cascade; +drop table if exists projects cascade; diff --git a/supabase/migrations/000004_agents.sql b/supabase/migrations/000004_agents.sql new file mode 100644 index 00000000..6035928a --- /dev/null +++ b/supabase/migrations/000004_agents.sql @@ -0,0 +1,34 @@ +-- 000004_agents.sql +-- Up + +create table if not exists agents ( + id text primary key, -- ag_... + team_id text not null references teams(id) on delete cascade, + name text not null, + description text, + config jsonb not null default '{}'::jsonb, + created_at timestamptz not null default now(), + updated_at timestamptz +); + +create index if not exists idx_agents_team_id + on agents(team_id); + +create table if not exists agent_runs ( + id text primary key, -- run_... + agent_id text not null references agents(id) on delete cascade, + user_id text references users(id) on delete set null, + input jsonb not null, + output jsonb, + status text not null default 'pending' + check (status in ('pending','running','completed','failed')), + created_at timestamptz not null default now(), + updated_at timestamptz +); + +create index if not exists idx_agent_runs_agent_id_created_at + on agent_runs(agent_id, created_at); + +-- Down +drop table if exists agent_runs cascade; +drop table if exists agents cascade; diff --git a/supabase/migrations/000005_wallet_staking_payouts.sql b/supabase/migrations/000005_wallet_staking_payouts.sql new file mode 100644 index 00000000..f268d85d --- /dev/null +++ b/supabase/migrations/000005_wallet_staking_payouts.sql @@ -0,0 +1,40 @@ +-- 000005_wallet_staking_payouts.sql +-- Up + +create table if not exists wallets ( + user_id text primary key references users(id) on delete cascade, + address text unique, + created_at timestamptz not null default now(), + metadata jsonb default '{}'::jsonb +); + +create table if not exists staking_ringk ( + id text primary key, + user_id text not null references users(id) on delete cascade, + amount numeric(30, 8) not null check (amount > 0), + lock_until timestamptz, + status text not null default 'locked' check (status in ('locked','unlocked')), + created_at timestamptz not null default now() +); + +create index if not exists idx_staking_ringk_user_id + on staking_ringk(user_id); + +create table if not exists payouts ( + id text primary key, + user_id text not null references users(id) on delete cascade, + amount numeric(30, 8) not null check (amount > 0), + symbol text not null, -- KWT, 1T, DAAR… + status text not null default 'pending' + check (status in ('pending','claimed','cancelled')), + created_at timestamptz not null default now(), + claimed_at timestamptz +); + +create index if not exists idx_payouts_user_id_status + on payouts(user_id, status); + +-- Down +drop table if exists payouts cascade; +drop table if exists staking_ringk cascade; +drop table if exists wallets cascade; diff --git a/supabase/migrations/000006_rwa.sql b/supabase/migrations/000006_rwa.sql new file mode 100644 index 00000000..16c67734 --- /dev/null +++ b/supabase/migrations/000006_rwa.sql @@ -0,0 +1,18 @@ +-- 000006_rwa.sql +-- Up + +create table if not exists rwa_inventory ( + id text primary key, -- rwa_... + team_id text not null references teams(id) on delete cascade, + type text not null check (type in ('energy','food','water','essence','generic')), + quantity numeric(30, 8) not null check (quantity >= 0), + unit text not null default 'unit', + metadata jsonb default '{}'::jsonb, + updated_at timestamptz not null default now() +); + +create index if not exists idx_rwa_inventory_team_type + on rwa_inventory(team_id, type); + +-- Down +drop table if exists rwa_inventory cascade; diff --git a/supabase/migrations/000007_embassy.sql b/supabase/migrations/000007_embassy.sql new file mode 100644 index 00000000..5670e76a --- /dev/null +++ b/supabase/migrations/000007_embassy.sql @@ -0,0 +1,48 @@ +-- 000007_embassy.sql +-- Up + +create table if not exists embassy_identities ( + id text primary key, -- emb_... + external_id text not null, + platform text not null check ( + platform in ('energy_union','greenfood','water_union','essence_stream','daarion_core','daarwizz') + ), + user_id text references users(id) on delete set null, + team_id text references teams(id) on delete set null, + metadata jsonb default '{}'::jsonb, + created_at timestamptz not null default now() +); + +create index if not exists idx_embassy_identities_platform_external + on embassy_identities(platform, external_id); + +create table if not exists embassy_webhooks ( + id text primary key, -- hook_... + platform text not null check ( + platform in ('energy_union','greenfood','water_union','essence_stream','daarion_core','daarwizz') + ), + url text not null, + secret text not null, + is_active boolean not null default true, + created_at timestamptz not null default now() +); + +create index if not exists idx_embassy_webhooks_platform_active + on embassy_webhooks(platform, is_active); + +create table if not exists oracles ( + id text primary key, + platform text not null check ( + platform in ('energy_union','greenfood','water_union','essence_stream') + ), + payload jsonb not null, + created_at timestamptz not null default now() +); + +create index if not exists idx_oracles_platform_created_at + on oracles(platform, created_at); + +-- Down +drop table if exists oracles cascade; +drop table if exists embassy_webhooks cascade; +drop table if exists embassy_identities cascade; diff --git a/supabase/migrations/000008_access_keys_capabilities.sql b/supabase/migrations/000008_access_keys_capabilities.sql new file mode 100644 index 00000000..b3210f53 --- /dev/null +++ b/supabase/migrations/000008_access_keys_capabilities.sql @@ -0,0 +1,58 @@ +-- 000008_access_keys_capabilities.sql +-- Up + +create table if not exists access_keys ( + id text primary key, -- ak_... + subject_kind text not null + check (subject_kind in ('user','agent','integration','embassy')), + subject_id text not null, -- u_/ag_/... + team_id text references teams(id) on delete set null, + name text not null, + status text not null check (status in ('active','revoked','expired')), + created_at timestamptz not null default now(), + expires_at timestamptz, + last_used_at timestamptz +); + +create index if not exists idx_access_keys_subject + on access_keys(subject_kind, subject_id); + +create index if not exists idx_access_keys_team + on access_keys(team_id); + +create table if not exists capabilities ( + id text primary key, -- cap_... + code text not null unique, -- chat.message.send, wallet.stake.ringk, ... + description text not null +); + +create table if not exists access_key_caps ( + key_id text not null references access_keys(id) on delete cascade, + cap_id text not null references capabilities(id) on delete cascade, + primary key (key_id, cap_id) +); + +create index if not exists idx_access_key_caps_cap_id + on access_key_caps(cap_id); + +create table if not exists bundles ( + id text primary key, -- bundle_... + name text not null unique, -- role.Member / plan.Premium / agent.default + created_at timestamptz not null default now() +); + +create table if not exists bundle_caps ( + bundle_id text not null references bundles(id) on delete cascade, + cap_id text not null references capabilities(id) on delete cascade, + primary key (bundle_id, cap_id) +); + +create index if not exists idx_bundle_caps_cap_id + on bundle_caps(cap_id); + +-- Down +drop table if exists bundle_caps cascade; +drop table if exists bundles cascade; +drop table if exists access_key_caps cascade; +drop table if exists capabilities cascade; +drop table if exists access_keys cascade; diff --git a/supabase/migrations/000009_audit_outbox.sql b/supabase/migrations/000009_audit_outbox.sql new file mode 100644 index 00000000..f42b8140 --- /dev/null +++ b/supabase/migrations/000009_audit_outbox.sql @@ -0,0 +1,32 @@ +-- 000009_audit_outbox.sql +-- Up + +create table if not exists audit_log ( + id text primary key, + user_id text references users(id) on delete set null, + team_id text references teams(id) on delete set null, + action text not null, + resource_kind text, + resource_id text, + data jsonb default '{}'::jsonb, + created_at timestamptz not null default now() +); + +create index if not exists idx_audit_log_team_created_at + on audit_log(team_id, created_at); + +create table if not exists outbox_events ( + id text primary key, -- evt_... + topic text not null, + payload jsonb not null, + created_at timestamptz not null default now(), + processed boolean not null default false, + processed_at timestamptz +); + +create index if not exists idx_outbox_events_processed + on outbox_events(processed, created_at); + +-- Down +drop table if exists outbox_events cascade; +drop table if exists audit_log cascade; diff --git a/supabase/migrations/README.md b/supabase/migrations/README.md new file mode 100644 index 00000000..503e222a --- /dev/null +++ b/supabase/migrations/README.md @@ -0,0 +1,89 @@ +# Database Migrations (MicroDAO) + +SQL-міграції для схеми бази даних microDAO/DAARION.city + +--- + +## Структура + +Міграції розташовані в хронологічному порядку: + +1. `000001_init.sql` - Users, Sessions, базові extensions +2. `000002_microdao_core.sql` - Teams, Channels, Messages, Follow-ups, Co-Memory +3. `000003_projects_tasks.sql` - Projects, Tasks +4. `000004_agents.sql` - Agents, Agent Runs +5. `000005_wallet_staking_payouts.sql` - Wallets, Staking, Payouts +6. `000006_rwa.sql` - RWA Inventory +7. `000007_embassy.sql` - Embassy Module (identities, webhooks, oracles) +8. `000008_access_keys_capabilities.sql` - Access Keys, Capabilities, Bundles +9. `000009_audit_outbox.sql` - Audit Log, Outbox Events +10. `seeds.sql` - Seed data для bundles, capabilities та bundle mappings (запускати після всіх міграцій) + +--- + +## Використання + +### З Supabase CLI + +```bash +# Застосувати всі міграції локально +supabase db reset + +# Застосувати seed data після міграцій +psql -d microdao -f supabase/migrations/seeds.sql + +# Або застосувати конкретну міграцію +supabase migration up 000001_init +``` + +### З PostgreSQL напряму + +```bash +# Застосувати всі міграції по порядку +psql -d microdao -f 000001_init.sql +psql -d microdao -f 000002_microdao_core.sql +# ... і так далі до 000009_audit_outbox.sql + +# Після всіх міграцій застосувати seed data +psql -d microdao -f seeds.sql +``` + +--- + +## Порядок застосування + +**Важливо:** Міграції повинні застосовуватися строго в порядку нумерації, оскільки вони залежать одна від одної. + +--- + +## Seed Data + +Файл `seeds.sql` містить: + +- Базові capabilities (chat, wallet, agent, projects, RWA, embassy, governance, comemory) +- Прив'язку capabilities до bundle.role.* (Owner, Guardian, Member, Visitor) +- Прив'язку capabilities до bundle.plan.* (Freemium, Casual, Premium, Platformium) + +--- + +## Rollback + +Кожна міграція містить секцію `-- Down` для відкочення змін. + +**Увага:** +- Outbox events не відкочуються +- RWA-поведінка не rollback'иться ніколи +- На prod rollback дозволено тільки для staging, forward-fix для prod + +--- + +## Посилання + +- Повна специфікація: `docs/cursor/27_database_schema_migrations.md` +- Access Keys System: `docs/cursor/24_access_keys_capabilities_system.md` + +--- + +**Версія:** 1.0 +**Останнє оновлення:** 2024-11-14 + diff --git a/supabase/migrations/seeds.sql b/supabase/migrations/seeds.sql new file mode 100644 index 00000000..76e601b3 --- /dev/null +++ b/supabase/migrations/seeds.sql @@ -0,0 +1,147 @@ +-- seeds.sql +-- базові bundles та capabilities для microDAO / DAARION.city +-- Запускати після всіх міграцій + +-- 1) Bundles +insert into bundles (id, name) +values + ('bundle_role_owner', 'role.Owner'), + ('bundle_role_guardian', 'role.Guardian'), + ('bundle_role_member', 'role.Member'), + ('bundle_role_visitor', 'role.Visitor'), + ('bundle_plan_freemium', 'plan.Freemium'), + ('bundle_plan_casual', 'plan.Casual'), + ('bundle_plan_premium', 'plan.Premium'), + ('bundle_plan_platformium', 'plan.Platformium') +on conflict (id) do nothing; + +-- 2) Capabilities +insert into capabilities (id, code, description) values + -- chat / channels + ('cap_chat_read', 'chat.message.read', 'Читання повідомлень у каналах'), + ('cap_chat_send', 'chat.message.send', 'Надсилання повідомлень у каналах'), + ('cap_chat_edit', 'chat.message.edit', 'Редагування власних повідомлень'), + ('cap_chat_delete', 'chat.message.delete', 'Видалення повідомлень'), + ('cap_channel_create', 'channel.create', 'Створення каналів у команді'), + ('cap_channel_manage', 'channel.manage', 'Керування каналами в команді'), + + -- co-memory / docs + ('cap_comem_read', 'comemory.item.read', 'Читання елементів Co-Memory'), + ('cap_comem_write', 'comemory.item.write', 'Створення/оновлення елементів Co-Memory'), + + -- projects / tasks + ('cap_project_create', 'project.create', 'Створення проєктів'), + ('cap_project_manage', 'project.manage', 'Керування проєктами команди'), + ('cap_task_create', 'task.create', 'Створення задач у проєктах'), + ('cap_task_manage', 'task.manage', 'Керування задачами'), + + -- agents / router + ('cap_agent_run', 'agent.run.invoke', 'Запуск агентів (Agent Runs)'), + ('cap_agent_config', 'agent.config.manage', 'Керування конфігурацією агентів'), + ('cap_router_invoke', 'router.invoke', 'Виклики роутера DAARWIZZ/Swarm-OS'), + + -- wallet / staking / payouts + ('cap_wallet_view', 'wallet.balance.view', 'Перегляд балансів гаманця'), + ('cap_wallet_stake', 'wallet.stake.ringk', 'Стейкінг токенів RINGK'), + ('cap_wallet_payout_v', 'wallet.payout.view', 'Перегляд доступних виплат'), + ('cap_wallet_payout_c', 'wallet.payout.claim', 'Забір (claim) виплат'), + + -- RWA / Embassy + ('cap_rwa_update', 'rwa.inventory.update', 'Оновлення інвентарю RWA'), + ('cap_emb_rwa_claim', 'embassy.rwa.claim', 'Обробка заявок на RWA через Embassy'), + ('cap_emb_energy_upd', 'embassy.energy.update', 'Оновлення енергетичних даних через Embassy'), + ('cap_emb_intent_read', 'embassy.intent.read', 'Читання intent-подій через Embassy'), + + -- Governance + ('cap_gov_proposal', 'governance.proposal.create', 'Створення governance-пропозицій'), + ('cap_gov_vote', 'governance.vote.cast', 'Голосування за пропозиції'), + ('cap_gov_policy', 'governance.policy.manage', 'Керування політиками/бандлами доступу') +on conflict (id) do nothing; + +-- 3) Прив'язка capabilities до role-bundles + +-- Owner: максимум прав +insert into bundle_caps (bundle_id, cap_id) +select 'bundle_role_owner', id +from capabilities +on conflict (bundle_id, cap_id) do nothing; + +-- Guardian: все, крім, наприклад, повної політики, якщо хочеш — тут залишимо теж усе +insert into bundle_caps (bundle_id, cap_id) +select 'bundle_role_guardian', id +from capabilities +on conflict (bundle_id, cap_id) do nothing; + +-- Member: обмежений, без критичних governance/policy й agent-config +insert into bundle_caps (bundle_id, cap_id) +values + ('bundle_role_member', 'cap_chat_read'), + ('bundle_role_member', 'cap_chat_send'), + ('bundle_role_member', 'cap_chat_edit'), + ('bundle_role_member', 'cap_comem_read'), + ('bundle_role_member', 'cap_comem_write'), + ('bundle_role_member', 'cap_project_create'), + ('bundle_role_member', 'cap_project_manage'), + ('bundle_role_member', 'cap_task_create'), + ('bundle_role_member', 'cap_task_manage'), + ('bundle_role_member', 'cap_agent_run'), + ('bundle_role_member', 'cap_router_invoke'), + ('bundle_role_member', 'cap_wallet_view'), + ('bundle_role_member', 'cap_wallet_stake'), + ('bundle_role_member', 'cap_wallet_payout_v'), + ('bundle_role_member', 'cap_wallet_payout_c') +on conflict (bundle_id, cap_id) do nothing; + +-- Visitor: тільки читання +insert into bundle_caps (bundle_id, cap_id) +values + ('bundle_role_visitor', 'cap_chat_read'), + ('bundle_role_visitor', 'cap_comem_read') +on conflict (bundle_id, cap_id) do nothing; + +-- 4) Прив'язка capabilities до plan-bundles (Entitlements) + +-- Freemium: базовий чат + читання + один агент +insert into bundle_caps (bundle_id, cap_id) +values + ('bundle_plan_freemium', 'cap_chat_read'), + ('bundle_plan_freemium', 'cap_chat_send'), + ('bundle_plan_freemium', 'cap_comem_read'), + ('bundle_plan_freemium', 'cap_agent_run') +on conflict (bundle_id, cap_id) do nothing; + +-- Casual: + wallet, router, tasks +insert into bundle_caps (bundle_id, cap_id) +values + ('bundle_plan_casual', 'cap_chat_read'), + ('bundle_plan_casual', 'cap_chat_send'), + ('bundle_plan_casual', 'cap_comem_read'), + ('bundle_plan_casual', 'cap_comem_write'), + ('bundle_plan_casual', 'cap_agent_run'), + ('bundle_plan_casual', 'cap_router_invoke'), + ('bundle_plan_casual', 'cap_wallet_view'), + ('bundle_plan_casual', 'cap_wallet_stake'), + ('bundle_plan_casual', 'cap_wallet_payout_v'), + ('bundle_plan_casual', 'cap_wallet_payout_c'), + ('bundle_plan_casual', 'cap_task_create'), + ('bundle_plan_casual', 'cap_task_manage') +on conflict (bundle_id, cap_id) do nothing; + +-- Premium: + RWA/Embassy, governance (без policy.manage) +insert into bundle_caps (bundle_id, cap_id) +values + ('bundle_plan_premium', 'cap_rwa_update'), + ('bundle_plan_premium', 'cap_emb_rwa_claim'), + ('bundle_plan_premium', 'cap_emb_energy_upd'), + ('bundle_plan_premium', 'cap_emb_intent_read'), + ('bundle_plan_premium', 'cap_gov_proposal'), + ('bundle_plan_premium', 'cap_gov_vote') +on conflict (bundle_id, cap_id) do nothing; + +-- Platformium: повний набір включно з governance.policy.manage +insert into bundle_caps (bundle_id, cap_id) +select 'bundle_plan_platformium', id +from capabilities +on conflict (bundle_id, cap_id) do nothing; + + diff --git a/tailwind.config.js b/tailwind.config.js new file mode 100644 index 00000000..55384ed3 --- /dev/null +++ b/tailwind.config.js @@ -0,0 +1,18 @@ +/** @type {import('tailwindcss').Config} */ +export default { + content: [ + "./index.html", + "./src/**/*.{js,ts,jsx,tsx}", + ], + theme: { + extend: { + colors: { + primary: '#3F51F5', + success: '#43A047', + error: '#E53935', + }, + }, + }, + plugins: [], +} + diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 00000000..c64399c3 --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,30 @@ +{ + "compilerOptions": { + "target": "ES2020", + "useDefineForClassFields": true, + "lib": ["ES2020", "DOM", "DOM.Iterable"], + "module": "ESNext", + "skipLibCheck": true, + "strict": true, + "noUnusedLocals": true, + "noUnusedParameters": true, + "noFallthroughCasesInSwitch": true, + + /* Bundler mode */ + "moduleResolution": "bundler", + "allowImportingTsExtensions": true, + "resolveJsonModule": true, + "isolatedModules": true, + "noEmit": true, + "jsx": "react-jsx", + + /* Path aliases */ + "baseUrl": ".", + "paths": { + "@/*": ["./src/*"] + } + }, + "include": ["src"], + "references": [{ "path": "./tsconfig.node.json" }] +} + diff --git a/tsconfig.node.json b/tsconfig.node.json new file mode 100644 index 00000000..e428d506 --- /dev/null +++ b/tsconfig.node.json @@ -0,0 +1,11 @@ +{ + "compilerOptions": { + "composite": true, + "skipLibCheck": true, + "module": "ESNext", + "moduleResolution": "bundler", + "allowSyntheticDefaultImports": true + }, + "include": ["vite.config.ts"] +} + diff --git a/vite.config.ts b/vite.config.ts new file mode 100644 index 00000000..b4de1de2 --- /dev/null +++ b/vite.config.ts @@ -0,0 +1,11 @@ +import { defineConfig } from 'vite'; +import react from '@vitejs/plugin-react'; + +export default defineConfig({ + plugins: [react()], + server: { + port: 3000, + open: true, + }, +}); +