TextNLPClassifierApp/docs/structured_extraction/06_Runbook_Producao_Runtime.md

# Runbook de produção — Runtime de consolidação de artigos

**Versão:** 1.0  
**Data:** 23 de agosto de 2026  
**Escopo:** operação do runtime; self-healing excluído

**Regra mestre:** operar e recuperar todos os requisitos de produção com procedimentos mínimos, explícitos e auditáveis, sem soluções emergenciais que aumentem a complexidade ou violem os contratos.

## 1. Objetivo

Orientar implantação, operação, diagnóstico, recuperação, reprocessamento e rollback manual do runtime.

## 2. Princípios operacionais

- Não publicar saída que falhou em grounding, ECP ou persistência.
- Não corrigir produção alterando prompt diretamente.
- Não trocar modelo sem certificação Promptfoo.
- Não recalcular `selected_extractor` no runtime.
- Não usar modelo potente para recuperar artigo.
- Não introduzir regex ou regra textual emergencial.
- Preservar entrada, estado, versões, evidências e logs antes de qualquer reprocessamento.
- Preferir recuperação idempotente a edição manual de arquivos.

## 3. Artefatos operacionais

- pacote executável versionado;
- arquivo de configuração funcional versionado;
- secrets externos ao pacote;
- prompts versionados e seus hashes;
- schemas versionados;
- SQLite de estado;
- diretório de saída;
- logs estruturados;
- configuração Langfuse;
- relatório Promptfoo da versão;
- relatório de staging e SLOs aprovados.

## 4. Responsabilidades

| Papel | Responsabilidade |
| --- | --- |
| Orquestrador | Fornecer artigo/ECP, controlar concorrência e consumir manifesto |
| Operação | Implantar, monitorar, recuperar e executar rollback |
| Engenharia | Corrigir código, prompt, schema ou integração via processo normal |
| Curadoria/Eval | Manter golden set e aprovar qualidade |

## 5. Pré-requisitos do ambiente

- versão suportada do Python definida pelo repositório;
- dependências instaladas a partir de lockfile;
- acesso de escrita ao SQLite e diretórios de saída/temporários;
- espaço em disco monitorado;
- relógio do sistema sincronizado;
- credenciais válidas para providers baratos e Langfuse;
- acesso ao classificador ECP e schema canônico;
- prompts e configuração da mesma release;
- nenhuma configuração de modelo potente nos papéis do runtime.

## 6. Configuração obrigatória

### 6.1 Funcional

- versão do contrato de artigo;
- versão do contrato de manifesto;
- versão compatível do ECP;
- versão dos prompts;
- provider/modelo de `runtime_primary`;
- provider/modelo de `runtime_fallback`;
- parâmetros de cada chamada lógica;
- timeouts e limite de retry técnico;
- política de conteúdo em traces;
- diretórios de estado e saída.

### 6.2 Secrets

- credenciais dos providers;
- credenciais Langfuse;
- demais credenciais exigidas pelo ambiente.

Secrets não podem ser passados como argumento visível de linha de comando, gravados em configuração versionada ou impressos em logs.

### 6.3 Valores definidos após staging

Antes do go-live, preencher e aprovar:

- custo máximo por artigo;
- custo máximo por Markdown aprovado;
- latência p50/p95/p99 esperada;
- timeout de cada provider;
- limite aceitável de fallback;
- limite de crescimento do SQLite;
- limites de uso de disco;
- concorrência máxima autorizada pelo orquestrador.

## 7. Checklist de release

### 7.1 Código e documentação

- PRD e arquitetura compatíveis;
- ADRs aceitas;
- schemas versionados;
- nenhuma alteração de self-healing incluída;
- nenhuma dependência não justificada;
- análise AST confirma ausência de regex no pipeline textual.

### 7.2 Testes

- unitários aprovados;
- contratos aprovados;
- integração simulada aprovada;
- regressão dos 20 casos iniciais aprovada;
- Promptfoo reduzido aprovado;
- golden set completo aprovado;
- gates críticos em zero;
- slices de idiomas, domínios e extratores dentro das metas;
- fault injection aplicável aprovado.

### 7.3 Staging

- 100 artigos por hora sem perda ou duplicação;
- custo e latência medidos;
- SLOs aprovados;
- SQLite sem corrupção ou saturação;
- filesystem sem arquivos finais parciais;
- Langfuse recebe ou recupera telemetria;
- rollback ensaiado.

### 7.4 Configuração

- primário e fallback certificados;
- prompts correspondem aos hashes aprovados;
- secrets válidos;
- permissões mínimas;
- diretórios corretos;
- retenção e backup definidos;
- ambiente marcado corretamente no Langfuse.

## 8. Implantação

1. Pausar novas execuções no orquestrador.
2. Aguardar ou encerrar de forma controlada execuções existentes.
3. Preservar backup consistente do SQLite e configuração vigente.
4. Implantar pacote, prompts e schemas da mesma release.
5. Aplicar migração de estado, quando houver, em cópia testada primeiro.
6. Executar preflight local sem artigo real.
7. Executar smoke test com fixture aprovada.
8. Confirmar manifesto, Markdown, estado e trace.
9. Liberar concorrência reduzida.
10. Verificar erros, fallback, custo e latência.
11. Liberar volume normal.

## 9. Preflight

O preflight deve validar sem chamada editorial real:

- leitura da configuração;
- existência e compatibilidade dos prompts;
- hashes esperados;
- schemas;
- acesso ao SQLite;
- escrita e rename atômico no diretório de saída;
- permissões de diretório;
- presença das credenciais;
- configuração dos providers;
- ausência de modelo potente nos papéis runtime;
- configuração Langfuse;
- acesso ao classificador/schema ECP;
- espaço mínimo de disco conforme limite aprovado.

## 10. Smoke test

Usar fixture versionada e não conteúdo de produção desconhecido.

Confirmar:

- fingerprint;
- transições de estado;
- chamada LLM esperada;
- ECP;
- manifesto;
- Markdown, quando esperado;
- trace completo;
- custo e latência dentro da faixa de staging;
- reexecução idempotente.

## 11. Operação normal

Para cada execução, o orquestrador fornece:

- caminho ou payload do artigo unitário;
- caminho ou payload do ECP;
- diretório de saída autorizado;
- configuração da release.

O retorno operacional deve distinguir:

- sucesso textual;
- rejeição ECP;
- falha de validação;
- falha de processamento;
- resultado já existente.

Rejeição ECP é resultado esperado e não incidente.

## 12. Monitoramento

### 12.1 Saúde

- recebidos, concluídos, rejeitados e falhos;
- throughput;
- latência;
- custo;
- retry e fallback;
- locks SQLite;
- disco;
- telemetria pendente.

### 12.2 Qualidade

- schema;
- grounding;
- reparos aplicados e rejeitados;
- ECP;
- enriquecimento;
- versões de prompt/modelo.

### 12.3 Sinais para análise futura

Monitorar `prompt_review_signal_total`, mas não iniciar automaticamente nenhuma mudança de prompt. Alertas específicos e self-healing pertencem ao projeto futuro.

## 13. Logs e correlação

Para investigar um artigo, usar:

1. fingerprint;
2. `run_id`;
3. trace ID;
4. estado persistido;
5. manifesto;
6. versões de prompt/modelo/ECP;
7. códigos de erro.

Não pesquisar métricas por URL ou título. Esses valores ficam em trace/log com acesso controlado.

## 14. Reprocessamento

### 14.1 Mesma configuração

Reexecutar normalmente. O fingerprint deve retornar o resultado existente ou retomar estado incompleto.

### 14.2 Configuração diferente

Mudança de prompt, modelo, ECP ou regra funcional gera fingerprint distinguível. A saída anterior não deve ser sobrescrita silenciosamente.

### 14.3 Proibição

Não editar manualmente manifesto, Markdown ou SQLite para “forçar” sucesso. Corrigir causa, implantar versão e reprocessar.

## 15. Falha de validação de entrada

### Sintomas

- `INVALID_ARTICLE_SCHEMA`;
- `INVALID_ECP_SCHEMA`;
- erro de `selected_extractor`;
- ausência de URL, título ou conteúdo textual.

### Ação

1. Confirmar versão do produtor.
2. Comparar com schema da release.
3. Verificar se o objeto é um artigo unitário, não o wrapper de lote.
4. Não chamar LLM manualmente.
5. Corrigir o produtor ou contrato por release normal.

## 16. Falha do provider primário

### Comportamento esperado

- retry apenas para falha técnica autorizada;
- fallback barato;
- trace com tentativas separadas.

### Investigação

- status HTTP categorizado;
- timeout;
- rate limit;
- latência;
- credencial;
- disponibilidade;
- taxa de fallback.

### Escalada

Se o fallback mantiver processamento dentro dos limites, acompanhar o provider primário. Se ambos falharem, pausar novas execuções quando a taxa ultrapassar o limite operacional aprovado.

Não configurar modelo potente emergencialmente.

## 17. Falha semântica ou de grounding

### Sintomas

- schema inválido;
- ID inexistente;
- URL sem origem;
- tentativa de reescrita;
- reparo inválido;
- falha após fallback.

### Ação

1. Preservar trace e entrada.
2. Confirmar prompt/modelo/hash.
3. Confirmar que o harness rejeitou a saída.
4. Não editar prompt em produção.
5. Criar caso de regressão no processo normal de engenharia.
6. Executar Promptfoo e golden set antes de nova release.

Esses eventos alimentam métricas para futura análise de self-healing, mas nenhuma ação automática ocorre.

## 18. Falha do ECP

### Comportamento esperado

- ECP inválido: falha inicial;
- classificador indisponível ou resultado inválido: falha de processamento;
- nenhum Markdown.

### Ação

1. Verificar schema e versão.
2. Verificar disponibilidade do classificador.
3. Preservar o documento intermediário conforme política.
4. Reprocessar após recuperação usando idempotência.

Não contornar o gate.

## 19. Falha de enriquecimento

Se primário e fallback falharem, nenhum Markdown deve ser emitido porque sentimento e tags são obrigatórios.

Investigar schema, grounding, provider, modelo e prompt. Não inserir sentimento ou tags manualmente no arquivo.

## 20. Falha do Langfuse

### Comportamento esperado

- artigo continua;
- evento mínimo fica em SQLite;
- log local registra `TELEMETRY_PENDING`;
- flush é tentado no encerramento.

### Recuperação

1. Confirmar disponibilidade e credenciais.
2. Executar operação de reenvio de telemetria pendente.
3. Verificar deduplicação por ID de evento.
4. Confirmar que o contador pendente voltou a zero.

Não reprocessar o artigo somente para recriar trace.

## 21. Falha do SQLite

### Sintomas

- lock excedido;
- corrupção;
- filesystem indisponível;
- migração incompatível.

### Ação para lock

1. Verificar concorrência real contra limite aprovado.
2. Identificar transação longa.
3. Reduzir concorrência no orquestrador.
4. Não aumentar timeout indefinidamente.

### Ação para corrupção

1. Pausar novas execuções.
2. Preservar arquivo para análise.
3. Restaurar último backup consistente.
4. Reconciliar manifestos/Markdown por fingerprint e hash.
5. Reprocessar apenas entradas sem estado terminal confiável.

## 22. Falha de filesystem ou disco

### Sintomas

- sem espaço;
- permissão negada;
- rename falha;
- hash divergente;
- temporário órfão.

### Ação

1. Pausar novas execuções se houver risco de perda.
2. Recuperar espaço sem apagar SQLite ou saídas confirmadas sem política aprovada.
3. Corrigir permissões.
4. Remover somente temporários identificados por fingerprint e sem estado concluído.
5. Reexecutar idempotentemente.

## 23. Custo acima do limite

1. Confirmar versão do modelo e prompt.
2. Separar aumento de volume de aumento por artigo.
3. Verificar tokens de contexto, fallback e retries.
4. Confirmar que nenhum payload bruto desnecessário entrou no contexto.
5. Pausar promoção ou reduzir concorrência se necessário.
6. Corrigir em release testada pelo Promptfoo.

Não reduzir contexto removendo evidências obrigatórias sem eval.

## 24. Latência acima do SLO

1. Identificar etapa dominante no trace.
2. Separar espera de provider, ECP, lock e filesystem.
3. Verificar taxa de fallback e timeout.
4. Comparar com baseline da mesma versão.
5. Aplicar mitigação operacional aprovada.
6. Alterações de modelo, prompt ou contexto passam por Promptfoo e staging.

## 25. Violação crítica de grounding

Qualquer texto, URL, imagem ou alteração crítica sem origem é incidente de qualidade.

1. Suspender promoção da versão.
2. Se estiver em produção, pausar novas execuções da configuração afetada.
3. Identificar outputs produzidos pela mesma versão.
4. Impedir consumo dos manifestos afetados quando possível.
5. Preservar evidências.
6. Executar rollback manual para última versão certificada.
7. Criar caso de regressão obrigatório.

## 26. Rollback manual

### Gatilhos

- violação crítica;
- regressão acima dos gates;
- falha operacional não mitigável;
- custo ou latência fora dos limites;
- incompatibilidade de contrato.

### Procedimento

1. Pausar novas execuções.
2. Identificar release, prompts, modelos e schemas afetados.
3. Restaurar pacote e configuração conhecida como saudável.
4. Restaurar schema/migração somente por procedimento compatível.
5. Executar preflight e smoke test.
6. Liberar volume reduzido.
7. Confirmar métricas.
8. Reprocessar entradas afetadas com nova identidade de configuração quando necessário.

Rollback manual de release não é self-healing.

## 27. Troca planejada de modelo ou provider

1. Criar configuração candidata no gateway.
2. Confirmar que o modelo é barato e compatível com structured output.
3. Executar contratos e Promptfoo reduzido.
4. Executar golden set completo.
5. Comparar qualidade, custo e latência.
6. Executar staging com volume acordado.
7. Aprovar limites.
8. Promover como nova versão funcional.
9. Manter configuração anterior disponível para rollback.

Não trocar somente o nome do modelo mantendo certificação antiga.

## 28. Rotação de credenciais

1. Criar nova credencial com privilégio mínimo.
2. Atualizar secret no ambiente.
3. Executar preflight e smoke test.
4. Confirmar ausência de erros e exposição.
5. Revogar credencial antiga.
6. Registrar mudança operacional sem alterar fingerprint funcional quando o comportamento permanecer igual.

## 29. Backup e retenção

Devem existir políticas aprovadas para:

- backup consistente do SQLite;
- retenção de manifestos e Markdown;
- retenção de logs;
- retenção de traces conforme privacidade;
- limpeza de temporários;
- restauração testada.

Backup do SQLite deve usar mecanismo consistente com banco ativo, não cópia bruta durante escrita.

## 30. Reconciliação

Periodicamente ou após incidente, verificar:

- estado concluído com arquivos existentes e hashes corretos;
- arquivos finais sem estado correspondente;
- temporários órfãos;
- telemetria pendente;
- fingerprints duplicados;

Reconciliação detecta e reporta. Correções usam rotinas idempotentes; não alteram conteúdo manualmente.

## 31. Encerramento controlado

Ao receber sinal de encerramento:

1. parar de aceitar nova unidade;
2. concluir ou persistir estado seguro da unidade atual;
3. fechar transações;
4. flush de arquivos;
5. tentar flush de telemetria;
6. preservar pendências;
7. encerrar com código coerente.

## 32. Critérios de prontidão operacional

- release passou todos os gates;
- SLOs de custo e latência foram aprovados;
- preflight e smoke test funcionam;
- rollback foi ensaiado;
- backup e restauração foram testados;
- reprocessamento é idempotente;
- falha de Langfuse é degradável;
- falhas de provider, ECP, SQLite e disco têm procedimento;
- nenhuma operação depende de modelo potente;
- nenhuma operação recomenda regex ou regra textual emergencial;
- nenhum componente de self-healing está implantado.