T-302 - Publicar na trilha o resultado e a variante das etapas de simulação e sugestão

• Componente: codegen.
• Depende de: T-300 no develop e T-301 implantada antes desta.
• Data máxima: 09/11/2026
• Estimativa: 5 pontos (Fibonacci)

Entregável

• NoConcluido com resultado_id e ConclusaoDaTrilha com modo_geracao, motivo_sugestao, desfecho_busca e candidatas_simuladas.
• Decisão e sugestão publicando o resultado sobre o qual agiram, e a sugestão publicando o motivo.
• Encerramento da busca da meta publicando a vencedora, o desfecho e a quantidade de candidatas.
• Geração publicando o modo, com o resultado que falhou na correção e o resultado de origem na derivação.
• Testes dos nós, do grafo e da mensageria cobrindo os campos novos.

Descrição

Os nós que publicam no-concluido no fluxo de simulação e sugestão não informam sobre qual resultado agiram nem qual variante da etapa executaram. Depois desta tarefa, cada linha da trilha gravada pela API (T-301) aponta o resultado e diz se o código foi gerado, derivado ou corrigido, qual foi o motivo da sugestão e como terminou a busca da meta.

Contexto e decisões tomadas

• Os nós já têm o resultado em mãos. A decisão e a sugestão o usam para montar evento_id com id_do_evento_de_trilha, e a busca da meta guarda a vencedora em busca["vencedora"]. Na correção do código, code_generation lê o resultado que falhou em state["resultado_id"] quando state["encaminhamento"] vale ENCAMINHAMENTO_CORRECAO (code_generation.py, linha 64).
• A linha de geração é publicada por extract_code quando o modelo produz o código e por derive_code quando o código é derivado. code_generation não publica a trilha.
• derive_code encontra o código de origem com buscar_codigo_simulado, cuja consulta já junta resultados_simulacao com status = 'sucesso' e proposito = 'simulacao', mas não devolve o id desse resultado.
• A linha que encerra a busca continua com no = "decisao" e com a chave própria uuid5(NAMESPACE_URL, f"synapse:{job_id}:{regra_id}:busca_meta"). A API reconhece o fim da busca por essa linha.
• A delegação não muda. As execuções candidatas da busca continuam sem linha própria, e a quantidade delas vai para a linha que encerra a busca.
• evento_id não muda em nenhum nó, para que a reentrega de um evento publicado antes desta mudança continue deduplicada.

Escopo

Dentro do escopo

• app/contratos/mensagens.py, app/repositorio/artefatos.py e os nós decision.py, suggest_adaptation.py, search_sales_target.py, extract_code.py e derive_code.py.
• Testes desses nós, do grafo, da busca da meta e da mensageria.

Fora do escopo

• dispatch_execution.py e a chave da delegação.
• Extração, reextração e validação.
• Etapas de interpretação do resultado e de explicação.
• Qualquer número de simulação na conclusão. A meta não é repetida, porque a linha a alcança pelo resultado.

Requisitos

Mensagem

1. Em NoConcluido, acrescentar resultado_id: UUID | None = None.
2. Em ConclusaoDaTrilha, acrescentar modo_geracao, motivo_sugestao e desfecho_busca como Literal com os valores do schema (T-300), opcionais, e candidatas_simuladas: int | None com mínimo 0. Os tipos ficam junto dos demais aliases de mensagens.py.

Decisão e sugestão

3. Em decision.py, publicar resultado_id com o mesmo resultado usado em id_do_evento_de_trilha.
4. Em suggest_adaptation.py, publicar resultado_id com o mesmo resultado usado em id_do_evento_de_trilha e motivo_sugestao igual a alternativa.motivo.

Encerramento da busca da meta

5. Em publish_sales_target (search_sales_target.py), publicar resultado_id igual à vencedora quando ela existe e ausente quando a busca termina sem solução.
6. Publicar desfecho_busca, igual a encontrada com vencedora e igual a busca["motivo"] sem ela.
7. Calcular a quantidade de candidatas uma única vez, com a expressão usada hoje na observação de busca_meta_candidatos (len(busca["pontos"]) - 1 + (motivo == "falha_execucao")), e usar o mesmo valor na métrica e em candidatas_simuladas.

Geração

8. Em extract_code.py, publicar modo_geracao igual a correcao quando state.get("encaminhamento") vale ENCAMINHAMENTO_CORRECAO, o mesmo teste de code_generation.py. Nesse caso, publicar resultado_id igual a state["resultado_id"] e um resumo próprio, que diga que o código foi corrigido a partir do código que falhou no worker. Nos demais casos, publicar modo_geracao igual a gerado, sem resultado_id, com o resumo atual.
9. Em artefatos.py, acrescentar resultado_id a CodigoSimulado e devolver rs.id na consulta _BUSCAR_CODIGO_SIMULADO.
10. Em derive_code.py, publicar modo_geracao igual a derivado e resultado_id igual ao resultado de origem devolvido por buscar_codigo_simulado. O prompt_id continua o da origem.

Observabilidade

11. Nenhuma métrica nova e nenhum label novo. busca_meta_candidatos continua recebendo o mesmo valor.
12. Os logs atuais dos nós continuam sem resumo, prompt, resposta ou código. Se um log passar a citar o resultado, ele entra como identificador no extra, nunca em label de métrica.

Testes

13. Em tests/app/test_mensageria.py, incluir os exemplos no-concluido-geracao-derivada e no-concluido-encerramento-busca no teste de publicação que exige payload igual ao exemplo (test_producer_publica_payload_validado_na_rota_correta). O teste hoje usa o mesmo nome para o arquivo do exemplo e para a rota, então a parametrização passa a separar os dois, e os exemplos novos são publicados na rota no-concluido.
14. Nos testes dos nós e do grafo, conferir o evento publicado. Decisão e sugestão trazem o resultado da chave, e a sugestão traz o motivo. A busca com vencedora traz o resultado, encontrada e a contagem, e a busca sem solução traz o desfecho e a contagem, sem resultado. A geração comum traz gerado, a correção traz correcao e o resultado erro_codigo, e a derivação traz derivado e o resultado de sucesso da origem.
15. Em tests/app/test_rabbitmq_integracao.py ou tests/app/test_busca_meta_integracao.py, validar contra o schema oficial um evento publicado com os campos novos.

Contexto técnico

• Entradas: estado do grafo (resultado_id, encaminhamento, busca_meta) e o resultado de origem consultado no Postgres.
• Saídas: eventos no-concluido com resultado_id e os campos novos da conclusão.
• Componentes afetados: codegen/app/contratos/mensagens.py, codegen/app/repositorio/artefatos.py, codegen/app/graph/nodes/decision.py, codegen/app/graph/nodes/suggest_adaptation.py, codegen/app/graph/nodes/search_sales_target.py, codegen/app/graph/nodes/extract_code.py, codegen/app/graph/nodes/derive_code.py.
• Restrições: evento_id inalterado; nenhum nome de etapa novo; um serviço por PR.
• Referências: graph (codegen/.agents/skills/graph/SKILL.md), testing (codegen/.agents/skills/testing/SKILL.md), logging (codegen/.agents/skills/logging/SKILL.md), metrics (codegen/.agents/skills/metrics/SKILL.md), codegen/tests/app/graph/nodes/test_decision.py, codegen/tests/app/graph/nodes/test_suggest_adaptation.py, codegen/tests/app/graph/nodes/test_artifact_nodes.py, codegen/tests/app/graph/test_busca_meta.py, codegen/tests/app/graph/test_correcao_do_codigo.py, codegen/tests/app/graph/test_derivacao_do_codigo.py, codegen/tests/app/test_busca_meta_integracao.py.

Critérios de aceitação

• Uma regra inviável percorre decisão e sugestão, e as duas linhas apontam o mesmo resultado inviável.
• Uma busca com vencedora publica a linha de encerramento com a vencedora, encontrada e a contagem igual à observada em busca_meta_candidatos.
• Uma busca sem solução publica a linha de encerramento sem resultado_id, com o motivo em desfecho_busca.
• Um código que falha no worker e é corrigido gera uma linha geracao_codigo com correcao e o resultado erro_codigo.
• Uma alternativa derivada gera uma linha geracao_codigo com derivado, o resultado de sucesso da origem e o prompt_id da origem.
• A reexecução de um nó republica o mesmo evento_id.

Definição de concluído (DoD)

• make pre-commit no codegen sem falha.
• Testes do grafo exercitando sugestão, busca da meta, correção e derivação, com o evento publicado validado contra o schema oficial.
• Registry de busca_meta_candidatos conferido nos testes da busca, e logs serializados sem conteúdo.
• Encerramento informando que a gravação na API depende da T-301 implantada.

Observações

• Depois de implantadas a T-301 e esta tarefa, executar no ambiente local três jobs: uma regra inviável que recebe sugestão de adaptação, uma regra que abre a busca da meta maior e uma regra cujo primeiro código gerado falha no worker. Para cada job, consultar trilhas_auditoria ordenada por concluido_em, juntando resultados_simulacao por resultado_id.
• Toda linha de decisão, de sugestão e de encerramento da busca deve apontar um resultado do mesmo job. A geração corrigida aponta um resultado erro_codigo, e a geração derivada aponta o resultado de sucesso da versão de origem.
• O número de candidatas da linha que encerra a busca deve conferir com as linhas de resultados_simulacao com proposito = 'busca_meta' e o mesmo codigo_gerado_id da simulação daquela versão.