CSuite — Agent Loop v1 (Spec Oficial)

Propósito
Padronizar como o CSuite captura Sinais → Contexto → Decisões → Execuções → Outcomes → Memória, com governança, auditabilidade e capacidade de evolução (autonomia progressiva).

---

0) Princípios (não-negociáveis)

1. Decision-first: tudo gira em torno de decision_log_id.
2. Context freeze: toda decisão relevante tem snapshot imutável do contexto (ctx_decision_context_snapshot).
3. Execution separation: decidir ≠ executar (ledger separado).
4. Outcome closure: toda execução relevante deve produzir outcome observável.
5. Matching auditável: qualquer vínculo retrospectivo tem score, método e debug.
6. Memory causal: memória é derivada de Decision Timeline, não de texto solto.

---

1) Léxico (entidades oficiais)

1.1 Signal

Um evento bruto que dispara avaliação.

• Ex.: inbound WhatsApp, mudança de estoque, atraso SLA, drift de desconto.

1.2 Context Snapshot

Estado do mundo “no instante” da decisão.

• Deve permitir reconstruir por que a decisão foi tomada.

1.3 Decision

Registro da decisão, seus gates e justificativas.

• Fonte de verdade: pg_decision_log.

1.4 Execution Action

Uma ação executável (tool-call humano/sistema).

• Fonte de verdade: execution_action_ledger.

1.5 Outcome

Resultado observado (antes/depois), com delta.

• Fonte de verdade: ctx_policy_outcomes.

1.6 Memory Item (Precedent)

Resumo causal de uma decisão com outcome observado.

• Fonte de verdade: mm_item (layer PRECEDENTS).

---

2) Contratos de dados (IDs e links obrigatórios)

2.1 ID canônico do loop

• decision_log_id é o anchor universal.

2.2 Links mínimos

• Snapshot: (org_id, decision_log_id) único
• Execution: (org_id, decision_log_id) esperado (1..N)
• Outcome: deve preferir (org_id, decision_log_id) e fallback por action_id

---

3) Tabelas oficiais do loop (mínimo canônico)

3.1 Decision Log (source of truth)

• csuite_executive.pg_decision_log

Campos mínimos esperados (conceituais):

• org_id
• decision_log_id (PK)
• created_at
• decision_id (code)
• decision_type
• subject_type, subject_ref
• outcome (ALLOW/RECOMMEND/ESCALATE/DENY)
• reasons_json
• latency_ms

---

3.2 Context Snapshot (freeze)

• csuite_context.ctx_decision_context_snapshot

Regras:

• 1 snapshot por decisão (UNIQUE(org_id, decision_log_id))
• Imutável por padrão (ou “metadados-only patch”)

Campos chave:

• decision_log_id
• policy_ref, agent_code, source_app
• entity_type, entity_ref
• snapshot_json, context_hash

---

3.3 Execution Ledger (doing)

• csuite_execution.execution_action_ledger

Regras:

• 0..N actions por decisão
• action_id recomendado para join forte com outcomes

Campos chave:

• action_id
• decision_log_id
• action_type, target_type, target_id
• status, executed_at, failure_reason

---

3.4 Outcomes (closure)

• csuite_context.ctx_policy_outcomes

Regras:

• sp_ctx_record_outcome é o caminho canônico de gravação
• Backfill existe apenas para histórico

Campos chave (hardening v1):

• decision_log_id (preferencial)
• action_id (fallback/link forte)
• match_method, match_score, matched_at, matched_by, match_debug_json
• metric_before, metric_after, delta_score
• expected_outcome, observed_outcome
• action_taken_at

---

3.5 Decision Timeline View (flight recorder)

• csuite_context.vw_decision_timeline

Regras:

• Única fonte para UI de timeline + feeding de memória
• Deve expor: decisão, snapshot, execução e outcome com joins determinísticos

---

3.6 Memory (precedents)

• csuite_memory.mm_item (layer_code = PRECEDENTS)
• Procedimento: csuite_memory.sp_ctx_feed_memory_from_timeline

Regras:

• Memory é derivada somente de outcomes observados com confiança suficiente.
• match_score deve influenciar “peso” do precedente.

---

4) Fluxo canônico (runtime)

4.1 Emissão de Signal

1. Ingestão cria evento/sinal (fora do escopo do v1, mas obrigatório existir).

4.2 Decision

1. Policy Engine avalia e grava pg_decision_log (sempre).

4.3 Snapshot

1. Imediatamente após a decisão:

2. gravar ctx_decision_context_snapshot via sp_ctx_snapshot_decision_context(...)

4.4 Execution (se aplicável)

1. Se outcome permitir/mandar ação:

2. criar 1..N em execution_action_ledger

3. garantir decision_log_id presente

4.5 Outcome (fechamento)

1. Ao observar resultado:

2. gravar via sp_ctx_record_outcome(org_id, decision_log_id, action_id, ...)

4.6 Memory

1. Job periódico:

2. sp_ctx_feed_memory_from_timeline(org_id, days_back, limit, actor)

---

5) Backfill & Matching (histórico)

5.1 Quando usar

• Apenas para outcomes antigos sem decision_log_id e/ou action_id.

5.2 Ordem de matching (v2 scoring)

1. ACTION_ID (score 100)
2. Entidade + Policy + Time window (score >= min_score, padrão 80)
3. Sem match → permanece NULL (não inventar)

5.3 Auditoria obrigatória

Todo match retrospectivo deve preencher:

• match_method, match_score, match_debug_json, matched_at, matched_by

---

6) SLOs do loop (qualidade operacional)

6.1 SLO-01 Snapshot Coverage

• ≥ 99% das decisões relevantes têm snapshot em até X minutos.

6.2 SLO-02 Outcome Closure

• ≥ 95% das execuções com status EXECUTED possuem outcome em até Y horas.

6.3 SLO-03 Matching Quality

• avg_match_score ≥ 90 e matched_via_action_id tende a crescer ao longo do tempo.

---

7) Autonomia progressiva (como liberar sem risco)

Níveis por policy/decision_type:

• L0: recomendação (humano executa)
• L1: execução automática com guardrails + audit
• L2: execução automática + tuning automático limitado
• L3: autonomia plena com monitoramento e rollback

Critérios para subir nível:

• taxa de sucesso alta
• baixa reversão
• outcomes fechados
• match_score alto
• baixo ruído de atenção/escalations

---

8) Interface canônica (UI)

8.1 Decision Timeline (1 tela)

Fonte: vw_decision_timeline

Filtros mínimos:

• data
• policy_code / decision_code
• entity_type/entity_ref
• outcome
• execution_status
• observed_outcome
• match_method / match_score

Blocos:

• “Decision card” (reasons_json, gates, latency)
• “Context card” (snapshot_json key facts)
• “Execution card” (action ledger)
• “Outcome card” (before/after/delta)
• “Memory card” (precedents relacionados)

---

9) Regras de evolução do spec

• Toda mudança de schema deve aumentar schema_version no snapshot.
• Toda mudança na timeline deve ser backward-compatible (a UI depende dela).
• Matching deve registrar método/score sempre.

---

10) Checklist de conformidade (Agent Loop v1)

• [ ] Todas decisões relevantes gravam em pg_decision_log
• [ ] Snapshot existe (UNIQUE org_id+decision_log_id)
• [ ] Execution ledger referencia decision_log_id
• [ ] Outcome gravado via sp_ctx_record_outcome
• [ ] Backfill usa v2 scoring + audit fields
• [ ] vw_decision_timeline é fonte única da UI
• [ ] Memory é alimentada a partir da timeline
• [ ] SLOs monitorados (coverage/closure/quality)

---

Se você quiser, eu mando a versão “docs/AGENT_LOOP_V1_SPEC.md” pronta (com heading padrão do seu repositório) e um diagrama Mermaid do loop (Decision → Snapshot → Execution → Outcome → Memory) pra virar documentação oficial do CSuite.