Observability Contract

Контракт: какие артефакты агент обязан оставить после выполнения задачи. Без этих данных невозможно отлаживать, оценивать качество и считать стоимость.

---

Обязательные поля в task.result

Каждый агент после выполнения задачи записывает result со следующей структурой:

1. Input Snapshot

{
  "input": {
    "question": "original question from payload",
    "context": "additional context if provided",
    "parameters": {}
  }
}

Зачем: воспроизводимость. Можно повторить задачу с тем же input.

2. Decision Trace

{
  "decision": {
    "action": "delegate_to_director | direct_answer | escalate | ...",
    "reasoning": "1-3 sentences: why this action",
    "confidence": 0.75
  }
}

Зачем: аудит. Понять почему агент сделал то что сделал.

3. Cost / Tokens / Duration Meta

{
  "_meta": {
    "cost_usd": 0.1234,
    "tokens": 15000,
    "input_tokens": 10000,
    "output_tokens": 5000,
    "duration_ms": 12345,
    "model": "claude-sonnet-4-6",
    "web_searches": 4
  }
}

Обязательные поля: cost_usd, tokens, duration_ms. Желательные: input_tokens, output_tokens, model, web_searches.

Зачем: бюджетирование, оптимизация, аномалии.

4. Output

Зависит от типа задачи. Минимум:

• Research: executive_summary + key_findings или competitors list
• Code: changes_made или commit hash
• Decision: decision + alternatives_considered

5. Failure Log (если что-то пошло не так)

{
  "error": "json_parse_failed",
  "message": "Expecting property name at char 13449",
  "partial_result": {},
  "retry_count": 3
}

Правило: даже при failure, _meta ДОЛЖЕН быть записан. Стоимость потраченных tokens не исчезает при ошибке.

---

Artifact Storage

Где хранится

Артефакт	Хранение	Формат
task.result	PostgreSQL tasks.result (JSONB)	JSON
Runs (per LLM call)	PostgreSQL runs table	JSON
Audit events	PostgreSQL audit_log table	JSON
Reports (для человека)	reports/{context}/{slug}.md	Markdown
Meta files	reports/{context}/{slug}.meta.json	JSON
Full raw data	reports/{context}/{slug}_full.json	JSON

Naming Convention

reports/
  week3_repro/
    run1_openclaw_competitors.md          # Human-readable report
    run1_openclaw_competitors.meta.json   # Machine-readable metrics
    run1_openclaw_competitors_full.json   # Full raw data (debug)
    SUMMARY.md                            # Cross-run analysis

Pattern: {run_id}_{slug}.{ext}

Обязательные поля meta.json

{
  "run": 1,
  "slug": "openclaw_competitors",
  "domain": "Browser automation / AI agents",
  "timestamp": "2026-04-15T02:47:00Z",
  "pipeline_duration_s": 430,
  "total_cost_usd": 0.7076,
  "total_tokens": 152604,
  "competitors_found": 26,
  "aggregate_success": false,
  "aggregate_error": "JSON parse failed",
  "stages": {
    "ceo": {"cost_usd": 0.015, "tokens": 2491},
    "scout": {"cost_usd": 0.42, "tokens": 88173, "duration_ms": 147228},
    "researcher": {"cost_usd": 0.28, "tokens": 61940, "duration_ms": 106191},
    "aggregate": {"cost_usd": 0.0, "tokens": 0}
  }
}

---

Retention

Данные	Retention	Причина
task.result	Permanent	Business value, audit
runs	90 days detail, aggregates permanent	Cost tracking
audit_log	Permanent	Compliance, debugging
reports/*.md	Permanent (git)	Deliverables
reports/*_full.json	Permanent (git)	Debug data — kept per finalized retention policy

Retention policy (finalized): текущая стратегия — indefinite local + git. Archival пересмотр при триггере:

• Storage > 10GB на synth-nova-prod, OR
• Week 8 (whichever comes first)

При триггере: оценить Cloudflare R2 archival (R2 уже доступен через MCP connector). До триггера — не усложняем инфраструктуру.

---

Compliance Checks

Automated (сейчас)

• mark_task_done() sets status to judging — human reviews
• Dashboard shows tasks without _meta as warnings

Automated (после 3.2)

• Judge agent validates ObservabilityContract compliance before marking done
• Missing _meta → auto-fail with "error": "observability_contract_violation"

Связанные документы

• INV-2 — artifact trail обязателен
• INV-3 — стоимость логируется
• Observability — архитектура наблюдаемости
• DefinitionOfDone — DoD использует данные из этого контракта