# 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

```yaml
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

```yaml
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)

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

---

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