Agendamento, retry, DLQ e reconciliação

Estado: Preview. Regras (backoff/DLQ/reconciliação) provadas determinísticas; execução real em fila de nuvem = NÃO MEDIDO.

Leia antes: README.md. Camadas em pipeline-medalhao.md.

Agendamento#

• O horário da agenda é escolhido e mostrado em horário de Brasília, na tela do pipeline (ETL/ELT → Pipelines → o pipeline → Agenda). Veja Agenda e fuso.
• O sistema confere as agendas a cada 15 minutos: um pipeline marcado para 07:00 começa entre 07:00 e 07:15.
• A próxima execução já fica calculada assim que você salva ou edita a agenda — é ela que aparece na tela do pipeline.
• Execuções que travarem são encerradas sozinhas e contam como falha (entram nas regras de nova tentativa abaixo).

Retry / backoff#

Política central pura (sem I/O); quem grava no banco são os dispatchers com updateMany condicionado (claim atômico). Sem coluna nova (schema congelado): o estado de retry vive em marcadores no campo error que já existe:

[tentativa N] [apos <ISO>] <mensagem original>

• [tentativa N] — marcador vigente do reaper (formato preservado byte a byte).
• [apos <ISO>] — "não execute antes de" (implementa backoff sem coluna de agenda).

Teto de tentativas por tipo (semântica difere por herança dos modelos):

Backoff: exponencial base × 2^(n-1) com jitter determinístico (hash FNV-1a do seed, ex. runId). Base = 5 min (1 tick do cron), teto = 1 h, jitter até 25%. Determinístico de propósito: o teste prova o valor exato e produção não depende de Math.random.

Classificação da falha:

• poison (config/validação — retry não conserta) → DLQ direto, sem queimar tentativas. Padrões conservadores: not found, syntax error, unrecognized name, invalid_grant, access/permission denied, unauthorized, forbidden, sem saldo de créditos, sem consultas configuradas.
• retryable (transiente/desconhecida) → tenta de novo até o teto (o desconhecido fica retryable; o teto protege).

A decisão pós-falha devolve {acao:"retry", tentativa, delayMs, executarApos} ou {acao:"dlq", motivo}.

DLQ — Dead Letter Queue#

DLQ = status "dlq" (novo valor de status). Um run em DLQ sai de todos os filtros executáveis (dispatchers leem queued, reaper lê running) e só volta pela mão de um humano: o reprocessamento a partir da DLQ é uma intervenção manual de um operador, com auditoria — nunca automática.

Um run vai para DLQ quando: erro poison, ou teto de tentativas atingido.

Reconciliação de camadas (só diagnóstico)#

Um kill no meio deixa buraco entre camadas (bronze carregada sem silver, gold anterior à silver, bronze prometida que nunca chegou). O produto compara os três rastros (execução do pipeline, tabelas Bronze e transformações) e produz um relatório acionável — a correção fica com o operador (zero correção automática nesta onda).

Regras (sempre condicionadas a haver expectativa real):

• Bronze — fonte com run ok + tabela selecionada: nunca processada → buraco; carga anterior ao início do último run ok → carga velha.
• Silver — há bronze processada: transform nunca executada → buraco bronze→silver; anterior à bronze mais recente → desatualizada.
• Gold — há silver processada: transform nunca executada → buraco silver→gold; anterior à silver mais recente → desatualizada.

A coleta do estado é toda escopada por workspaceId (invariante: carimbo de um cliente nunca lê o de outro).

Observabilidade por conector#

Agrega os eventos de extração (uma linha por operação) em execuções, taxa de erro, p50/p95, última execução e freshness:

Sem nenhum evento → parado.

Ficha (template dos 9 campos)#

1. Estado — Preview. Regras (agendamento, backoff, DLQ, reconciliação) provadas determinísticas; execução real em fila de nuvem = NÃO MEDIDO.
2. O que faz — agenda cargas, re-tenta falhas transientes com backoff, isola falhas permanentes em DLQ e diagnostica buracos entre camadas.
3. Como funciona — Postgres + crons de 5 min; nextRunAt pré-computado; marcadores no campo error; DLQ = status terminal; reconciliação read-only por workspace.
4. Plano · Permissão — núcleo · verificação de acesso · chaves de desligamento para execução de ingestão / execução de relatórios / atualização de painéis.
5. Custo — retry/backoff reduz custo de re-execução cega; jitter evita martelar. Sem custo de plataforma no cálculo. Custo real = NÃO MEDIDO.
6. Limites — tentativas: dashboard 2 / report 3 / pipeline 2; backoff base 5 min, teto 1 h, jitter 25%.
7. Segurança — claim atômico (updateMany condicionado) evita corrida; DLQ exige intervenção humana auditada; reconciliação escopada por workspace.
8. Como validar — no console, agende uma carga e acompanhe o nextRunAt e o histórico de execuções; force uma falha transiente e confirme o re-agendamento com backoff; uma falha de configuração vai direto para a DLQ, de onde só sai por ação manual auditada.
9. Estado real / claim permitido — "Idempotência, retry com backoff determinístico, DLQ e reconciliação de camadas provados; execução real em fila = nuvem (pendente)."