microdao-daarion/docs/NATS_SUBJECTS.md

NATS Subjects Standards

Версія: 1.0
Статус: Canonical

---

Subject Naming Convention

Формат: {domain}.{event}.{qualifier}

---

1. Messages

message.created.{channel_id}      # Нове повідомлення
message.edited.{channel_id}       # Редагування
message.deleted.{channel_id}      # Видалення
message.reaction.{channel_id}     # Реакція

---

2. Attachments

attachment.created.image          # Завантажено зображення
attachment.created.video          # Завантажено відео
attachment.created.audio          # Завантажено аудіо
attachment.created.document       # Завантажено документ

attachment.parsed.image           # Оброблено (vision)
attachment.parsed.audio           # Оброблено (STT)
attachment.parsed.document        # Оброблено (parser)

attachment.indexed.{type}         # Проіндексовано в Qdrant

---

3. Agent Operations

agent.run.requested.{agent_id}    # Запит на виконання
agent.run.started.{agent_id}      # Почато виконання
agent.run.progress.{agent_id}     # Прогрес (для довгих задач)
agent.run.completed.{agent_id}    # Завершено успішно
agent.run.failed.{agent_id}       # Помилка

# Handoff (orchestration)
agent.handoff.requested.{from}.{to}   # Запит на передачу
agent.handoff.accepted.{from}.{to}    # Прийнято
agent.handoff.completed.{from}.{to}   # Завершено
agent.handoff.rejected.{from}.{to}    # Відхилено

---

4. Memory Operations

memory.fact.created.{scope}       # scope: user|team|public
memory.fact.updated.{scope}
memory.fact.deleted.{scope}

memory.vector.indexed.{scope}     # Проіндексовано в Qdrant
memory.graph.updated.{scope}      # Оновлено в Neo4j

---

5. Quota & Billing

quota.consumed.{user_id}          # Використано ресурс
quota.blocked.{user_id}           # Заблоковано (ліміт)
quota.reset.{user_id}             # Скинуто (новий період)
quota.warning.{user_id}           # Попередження (80%+)

---

6. Audit (append-only)

audit.gateway.request             # Вхідний запит
audit.router.decision             # Рішення маршрутизації
audit.agent.invocation            # Виклик агента
audit.tool.execution              # Виконання інструменту
audit.memory.access               # Доступ до пам'яті
audit.auth.event                  # Auth події

---

7. Ops & Health

ops.health.{service}              # Health check result
ops.alert.critical.{service}      # Критична помилка
ops.alert.warning.{service}       # Попередження
ops.metric.{service}              # Метрика

---

8. Workflows (CrewAI)

workflow.started.{workflow_id}    # Почато workflow
workflow.step.{workflow_id}       # Крок workflow
workflow.completed.{workflow_id}  # Завершено
workflow.failed.{workflow_id}     # Помилка

---

JetStream Streams Configuration

streams:
  - name: MESSAGES
    subjects: ["message.>"]
    retention: limits
    max_msgs: 1000000
    max_bytes: 10GB
    max_age: 7d
    
  - name: ATTACHMENTS
    subjects: ["attachment.>"]
    retention: limits
    max_msgs: 100000
    max_bytes: 1GB
    max_age: 30d
    
  - name: AGENT_OPS
    subjects: ["agent.>"]
    retention: limits
    max_msgs: 500000
    max_bytes: 5GB
    max_age: 7d
    
  - name: AUDIT
    subjects: ["audit.>"]
    retention: limits
    max_msgs: -1  # unlimited
    max_bytes: 100GB
    max_age: 365d  # 1 рік
    
  - name: OPS
    subjects: ["ops.>"]
    retention: limits
    max_msgs: 100000
    max_bytes: 1GB
    max_age: 7d

---

Consumer Groups

consumers:
  # Parser pipeline
  - name: parser-pipeline
    stream: ATTACHMENTS
    filter: "attachment.created.>"
    deliver_policy: all
    ack_policy: explicit
    max_deliver: 3
    
  # RAG indexer
  - name: rag-indexer
    stream: ATTACHMENTS
    filter: "attachment.parsed.>"
    deliver_policy: all
    ack_policy: explicit
    max_deliver: 3
    
  # CrewAI workers
  - name: crewai-workers
    stream: AGENT_OPS
    filter: "agent.run.requested.>"
    deliver_policy: all
    ack_policy: explicit
    max_deliver: 5

---

Dead Letter Queue (DLQ)

dlq:
  stream: DLQ
  subjects: ["dlq.>"]
  retention: limits
  max_age: 30d
  
  # Routing rule: після 3 retries → DLQ
  # Format: dlq.{original_subject}.{error_type}

---

Останнє оновлення: 2026-01-19