# Matriz de Migração — Contas -> agent_framework_oci

| Capacidade | Destino novo | Reuso framework | Código de domínio novo | Dependência anterior |
|---|---|---:|---:|---:|
| LangGraph | `app/workflows/agent_graph.py` | Sim | composição mínima | Não |
| Router | EnterpriseRouter | Sim | routing.yaml | Não |
| Stickiness | framework | Sim | configuração | Não |
| Supervisor | framework | Sim | configuração | Não |
| Confirmação | AgentRuntimeMixin | Sim | tool policy | Não |
| Clarificação | AgentRuntimeMixin/MCP mapping | Sim | schemas/mapping | Não |
| Sessions | framework repository | Sim | Não | Não |
| Message memory | framework | Sim | Não | Não |
| Summary memory | framework | Sim | Não | Não |
| LTM | framework | Sim | Não | Não |
| Checkpoint | framework | Sim | Não | Não |
| RAG | RagService | Sim | conteúdo/config | Não |
| Guardrails | GuardrailPipeline | Sim | config | Não |
| Output Supervisor | framework | Sim | Não | Não |
| Judges | JudgePipeline | Sim | config | Não |
| MCP router | framework | Sim | tool catalog | Não |
| Faturas | MCP/domain | Não aplicável | Sim | Não |
| Billing Analysis | MCP/domain | Não aplicável | Sim | Não |
| Consulta/Histórico VAS | MCP/domain | Não aplicável | Sim | Não |
| Bloqueio/Cancelamento VAS | MCP/domain | confirmação no framework | Sim | Não |
| Contestação | MCP/domain | confirmação/estado no framework | Sim | Não |
| Protocol/Status/Tracking | MCP/domain | contexto no framework | Sim | Não |
| SMS | MCP/domain | contexto no framework | Sim | Não |
| Secure PDF | MCP/domain | contexto no framework | Sim | Não |
| Langfuse | framework | Sim | Não | Não |
| Pub/Sub/sequence | framework | Sim | configuração | Não |
| OCI Streaming | framework | Sim | configuração | Não |
| OTEL | framework | Sim | configuração | Não |

## Regra

O pacote anterior não é uma biblioteca do novo projeto. Se uma regra específica for necessária, ela deve ser portada e testada dentro de `app/domain/contas`; infraestrutura genérica deve ser eliminada em favor do framework.


## Contratos TIM validados por regressão

| Integração | Paridade coberta | Estado |
|---|---|---|
| CompleteInvoices | método/payload/header `ClientID` | ✅ |
| Query VAS | URL por MSISDN, `clientId=AIAAGENTCR`, auth | ✅ |
| VAS History | query `msisdn`, `clientId`, `messageId`, auth | ✅ |
| Block VAS | payload PMid + fallbacks e headers | ✅ |
| Cancel VAS | DELETE, channel, protocol, headers, messageId | ✅ |
| Contract Information | GET por MSISDN, `clientId`, auth | ✅ |
| Profile/Line Info | GET e header `ClientID` | ✅ |
| Billing Analysis | GET por MSISDN + channel | ✅ |
| Bill PDF | POST detalhado + criptografia | ✅ |
| Secure PDF | GET com parâmetros criptografados | ✅ |
| Customer Contestation | payload/headers principais | ✅ |
| Service Request Status | envelope `serviceRequest` | ✅ |
| Tracking Activities | customer/invoice/activity/user | ✅ |
| Protocol V2 | envelope Siebel + headers corporativos | ✅ |
| SMS Barcode | payload completo + retry/RCT | ✅ |

## Jornadas compostas e comportamento conversacional

| Capacidade original | Implementação migrada | Reuso do framework | Regressão |
|---|---|---:|---:|
| Cancelamento VAS -> contestação | dois workflows encadeados no MCP | `WorkflowRuntime` | ✅ |
| Composição final cancelamento | `app/domain/contas/vas_cancellation_message.py` | domínio determinístico | ✅ 19 casos originais |
| Fallback VAS History | `ContasDomainService.cancelar_vas_avulso` | transporte via adapter | ✅ |
| Cancelamento parcial em lote | action expõe cancelados/falhas/candidatos | WorkflowRuntime + IdempotencyStore | ✅ |
| Idempotência transacional | `create_idempotency_store()` | framework | ✅ |
| Replay pós-finalização | Channel short-circuit | framework | ✅ |
| Idle nudge replay | Channel short-circuit | framework | ✅ |
| Processing interruption | replay + classificador LLM fail-safe | `LLMProvider` framework | ✅ |
| Correção Fim/Mim -> Sim | channel transcription | framework | ✅ |
| Finalização status/summary | regra pura de domínio | workflow framework | ✅ |
| Protocolo informacional final | action + ProtocolV2 | WorkflowRuntime | ✅ |

### Bootstrap MCP

`WorkflowRuntime`, checkpointer e `IdempotencyStore` são inicializados de forma lazy. Isto evita dependência de Oracle/Redis para endpoints de diagnóstico e garante que o backend durável só seja aberto quando um workflow realmente precisar ser executado.

## Incrementos de paridade - baseline 420

| Capacidade original | Implementação migrada | Responsabilidade | Estado |
|---|---|---|---:|
| InvoiceContextProvider / prefetch | `InvoiceContextService` + `agent_framework.cache.Cache` | domínio escolhe evidências; framework fornece cache | ✅ |
| Isolamento de invoice context por sessão | chave `session_id:msisdn:invoice_id` | framework cache | ✅ |
| Plano família titular/dependente | normalização antes do workflow + contestação única no titular | domínio + WorkflowRuntime | ✅ |
| Correção de linha por invoice detail | normalização determinística | domínio | ✅ |
| CVAL fail-stop | edge `success=false -> END` | WorkflowRuntime | ✅ |
| Snapshot parcial em falha | `WorkflowRuntime` recupera último state do LangGraph | framework | ✅ |
| Retry Billing Analysis / RCT 079-084 | metadata `_transport` + `RCTPolicy` | domínio define códigos; observer publica | ✅ |
| Finalização invoice explanation | protocolo informacional somente após workflow executado | domínio + WorkflowRuntime | ✅ |
| VEB fechado / force RT15 | reuso ou novo protocolo conforme flags | domínio | ✅ |
| Inicialização AgentWorkflow | router/agentes/grafo dentro de `__init__` | aplicação/framework | ✅ |

### Incrementos de paridade — baseline 435

| Capacidade original | Implementação migrada | Responsabilidade | Status |
|---|---|---|---|
| Invoice prefetch single-flight | `InvoiceContextService` + `agent_framework.cache.Cache` | domínio escolhe evidências; framework fornece cache | ✅ |
| CVN de prefetch sem duplicação | `business_events` + cache markers | domínio define código; observer framework publica | ✅ |
| Latch invoice/workflow já executado | `AgentRuntimeMixin.business_workflows_executed` | framework | ✅ |
| Batch cancellation max 5 | action async + semaphore | domínio action sobre WorkflowRuntime | ✅ |
| Protocolo por linha antes de cancelar | action `cancelamento_vas_avulso_batch` | domínio + adapter TIM | ✅ |
| Erro estruturado de workflow | `WorkflowRunResult.error_details` | framework | ✅ |
| Provider error de contestação | MCP mapping sobre `error_details` | domínio/MCP fino | ✅ |


## Baseline 440 testes - continuação

- 440 testes de migração passando; 2 skipped por dependências indisponíveis neste runtime (`langgraph`/`jellyfish`).
- Cancelamento VAS: falha de bloqueio/cancelamento pode permanecer candidata à contestação sem mascarar sucesso.
- Resposta composta preserva protocolos de cancelamento por linha + protocolo de contestação e sinaliza finalização sugerida.
- Plano família: protocolo de cancelamento em dependente resolve `socialSecNo` via LineInfo da própria linha.
- Registro de protocolo aceita aliases de resposta `interactionProtocol`, `protocolNumber`, `protocol` e `protocolo`.
- Finalização informacional recalcula Bundle/Estratégico/Avulso pela evidência de `invoice_detail`/Billing Analysis quando disponível.

## Finalização - paridade adicional (baseline 533)

| Capability original | Implementação migrada | Framework reutilizado | Evidência |
|---|---|---|---|
| CVN aceite/recusa no encerramento | `finalizar_atendimento_action` | `business_events` + `AgentObserver` | testes de finalização estendida |
| Protocolo RT-15 informacional | action de domínio + TIM client | WorkflowRuntime/observer/idempotência | RCT.085/086 + CVN.010/011 |
| Nota de invoice explanation | valor canônico `Explicação dos valores da fatura` | workflow latch do framework | regressão |
| Handoff/retention suppression | flags no state/domain action | estado persistido do framework | regressão |
| SAD decision tree | `SAD.001/002/003/004/005/006/007` como business events | AgentObserver | regressão |
| Classificação VAS sem invoice detail | aliases determinísticos de domínio | nenhuma engine paralela | regressão |
| Regressão offline de workflow | `WorkflowRuntime(... allow_deterministic_fallback=True)` somente em teste | DSL/actions do framework | 18 casos históricos executados |

## Atualização de paridade - baseline 550

| Capability | Original | Migrado | Evidência |
|---|---|---|---|
| Finalização com prefetch de fatura | CVN lookup + RT-15 quando aplicável | Implementado | regressão de finalização |
| Supressão após transição para negócio | não reemite CVN/MPI | Implementado | regressão dedicada |
| VEB terminal | não duplica RT-15/CVN | Implementado | regressão dedicada |
| Precedência de tipo pela fatura | total/parcial/sem match | Implementado | regressão dedicada |
| Protocolo já existente | não duplica RT-15 | Implementado | regressão dedicada |
| Matcher fonético/transcrição | catálogo real | Implementado sem xfails | suíte de transcrição |

## VAA — rastreabilidade de cancelamento/contestação

| Capability histórica | Implementação migrada | Framework reutilizado | Estado |
|---|---|---|---|
| VAA.001–004 cancelamento | `cancelamento_vas_avulso_batch` retorna `business_events` | AgentObserver / analytics | OK |
| VAA.005–009 contestação/boleto | `abrir_contestacao_cliente` retorna `business_events` | AgentObserver / analytics | OK |
| VAA.012–015 SMS | `enviar_sms` retorna `business_events` e mantém fluxo em erro | AgentObserver / analytics | OK |
| VAA.016–017 status SR | `atualizar_status_sr` retorna `business_events` | AgentObserver / analytics | OK |


## Baseline 560 testes - metadata corporativa TIM

- 560 testes de migração passando, sem skips/xfails.
- Business events preservam contexto corporativo: `agentProtocolId`, `adjustedProtocol`, `billingId`, `uraCallId`, `channelId`, `sessionId`, `messageId` e `agentSpecificData`.
- Contestação VAA.005-009 preserva itens/valores ajustados e protocolo.
- Finalização CVN.010/011 preserva protocolo TIM/URA e billing context.
- RCTs derivados de retry HTTP carregam `apiUrl`, `apiStatusCode`, `apiResponsePayload` e `latencyMs`.
- SMS e Service Request Status carregam metadata de transporte e contexto de protocolo.
- `tim_payload_mapper` aceita o formato histórico `agentSpecificData` JSON-string e o converte para o objeto canônico TIM no payload final.

### Paridade de eventos conversacionais — baseline 565

| Família | Paridade adicionada |
|---|---|
| VEB | ordem dos branches de VAS estratégico e metadata do turno/URA |
| MPI | contexto de invoice explanation, pró-rata e cancelamento |
| CVN | contexto conversacional/protocolo no encerramento |
| SAD | `llmResponse`, `messageId`, sessão/canal e `sessionEndAt` normalizado |

## Incremento de paridade — baseline 570

| Funcionalidade original | Implementação migrada | Responsabilidade |
|---|---|---|
| Cancelamento solicitado para item estratégico/bundle | `InvoiceResolver` redireciona para workflow `vas_estrategico` | Domínio + WorkflowRuntime |
| Invoice explanation SIM | recomenda `resolvido` pelo último node do workflow | MCP adapter fino sobre WorkflowRuntime |
| Invoice explanation NÃO sem VAS variado | recomenda `nao_resolvido` | MCP adapter fino sobre WorkflowRuntime |
| Pró-rata aceito / sem Plano Controle | recomenda `resolvido` | MCP adapter fino sobre WorkflowRuntime |
| Orientação de cancelamento de VAS estratégico por parceiro | action declara `requires_rag/rag_queries`; `AgentRuntimeMixin` chama `RagService` | Framework |
| Gate padrão de regressão | `pytest -q` -> `tests/` | Projeto migrado |

## Baseline 578 - wrapper cancelamento + LLM composition

- 593 testes passando; zero skipped/xfail.
- Cancelamento preserva `auto_finalize_on_failure` em falha técnica de contestação.
- Item já contestado não mascara cancelamento concluído como falha sistêmica.
- `cancelamento_vas_protocol` e todos os protocolos de resposta são preservados.
- Plano família contesta titular + dependentes em uma única `contestacao_tool`.
- Lote com muitos no-match continua contestando exatamente os candidatos elegíveis.
- Pró-rata usa `requires_llm_composition` do framework em vez de gateway LLM de domínio.


### Paridade de wrappers históricos — baseline 593

| Comportamento original | Implementação migrada | Estado |
|---|---|---|
| `tipo_atendimento=contestacao` | `_workflow_payload(contestacao_tool)` | ✅ |
| Contexto do turno no workflow | payload MCP preserva IDs/canal/mensagem | ✅ |
| CPF como alias de socialSecNo | normalização no wrapper composto | ✅ |
| `cancelados` sem `results.success` | fallback agregado do wrapper | ✅ |
| `itens_para_contestacao` | alias de `contestation_candidates` | ✅ |
| falha block/cancel ainda elegível a RT-02 | composição de dois WorkflowRuntime | ✅ |
| SMS falha sem derrubar jornada | `sms_not_send_error` | ✅ |
| Bundle + Estratégico + NÃO | protocolo deferido + RAG obrigatório | ✅ |

## Complemento de paridade — baseline 599

| Comportamento histórico | Implementação migrada | Prova |
|---|---|---|
| Itens já contestados | normalização em `abrir_contestacao_cliente` + compositor determinístico | teste de wrapper 1:1 |
| Itens contestados/não contestados | classificação na action de domínio | regressão de contestação |
| Total contestado somente dos itens aceitos | cálculo determinístico no domínio | regressão de contestação |
| Contestação retorna valor zero | fallback para total efetivamente cancelado | teste de wrapper 1:1 |
| Valor na fala em pt-BR | normalização na borda MCP | teste `R$ 14,99` |
| `next_subject` | ignorado pelo compositor determinístico | teste de wrapper 1:1 |
| Billing Analysis indisponível | fraseologia canônica e `auto_finalize_on_failure=false` | regressão invoice explanation |

### Cobertura 1:1 de wrappers — baseline 615

Além dos testes de domínio/actions/workflows, a suíte passa a reproduzir diretamente
outcomes históricos dos wrappers `cancelar_vas_single` e `finalize_support`, cobrindo
no-match, candidatos explícitos, falhas parciais RT-01→RT-02, SMS, protocolos,
`protocol_closed`, plano família/titular-dependente e protocolo informacional deferido.

Esses testes são classificados como **paridade explícita de contrato externo**, e não
apenas cobertura indireta por actions internas.