File Queue Orchestration

Fila de tarefas com gate de revisão

Para automação onde um modelo produz alterações sem alguém olhando em tempo real. O problema não é o modelo errar — é o erro chegar em produção sem ninguém ver.

Por que arquivo, e não fila de verdade

Redis ou SQS são melhores em throughput. Mas para orquestrar IA, fila em arquivo ganha em:

• Inspecionável — cat no job mostra o estado. Debug sem ferramenta.
• Durável de graça — sobrevive a reboot sem configuração.
• Versionável — o diretório inteiro entra no git.
• Sem dependência — nada para instalar, subir ou monitorar.

Throughput raramente é o gargalo: o modelo leva segundos ou minutos por tarefa. Se você precisa de milhares por segundo, este padrão não é o seu.

Estrutura

fila/
  in/<id>.json       tarefa a executar
  out/<id>.json      resultado + status
  logs/
sandbox/
  jobs/<id>/
    input/           cópia intocada — referência para o diff
    work/            onde o worker escreve
    TASK.md          prompt e contexto
    DIFF.patch       gerado ao final

A separação input/ e work/ é o núcleo: sem cópia original, não há diff confiável, e sem diff não há revisão possível.

Ciclo

1. Tarefa aparece em in/
2. Cria diretório do job; copia os arquivos alvo para input/ e work/
3. Escreve TASK.md com prompt e contexto
4. Roda o worker com cwd no diretório do job
5. Commita o resultado e gera DIFF.patch entre input/ e work/
6. Grava out/<id>.json com status needs_review
7. Para. Humano lê o diff e decide aplicar

O passo 7 é o ponto do padrão. Sem ele, é só automação com etapas extras.

Isolamento

O worker roda preso ao diretório do job:

• cwd no diretório do job, nunca na raiz do projeto
• Sem permissão ampla — nada de pular todos os prompts de permissão
• Regras de negação para caminhos sensíveis
• Timeout obrigatório: worker travado consome recurso indefinidamente

Assuma que o worker vai tentar sair da caixa por engano — ler um caminho absoluto, escrever fora do escopo. Estruture para que a tentativa falhe em vez de depender de ele não tentar.

Troca de motor

Parametrize qual modelo executa o job em vez de fixar no código:

{ "prompt": "...", "engine": "a", "model": "...", "timeout": 180000 }

Ganhos: comparar motores na mesma tarefa, cair para outro quando um esgota a cota, e usar o barato no mecânico. O custo é uma camada fina de tradução de argumentos — cada CLI tem a sua sintaxe de modo não-interativo.

Erros que este padrão previne

Quando não usar

• Tarefa precisa de resposta imediata — revisão adiciona latência humana
• Volume alto o bastante para a revisão virar gargalo
• Operação puramente de leitura, sem efeito colateral