# Drift detected

Há dois sub-tipos de drift. O sintoma determina qual você está vendo.

# Sub-tipo A: Compose drift

Sintoma:

[FAIL] meu-app  compose drift detected
  docker-compose.yml hash: abc123...
  manifest hash:           def456... (mismatch)

# Causa

O docker-compose.yml foi editado no repo depois que o wizard gerou o .deploy.yml. O Runner compara os hashes na hora do deploy e bloqueia se divergirem — evita deploy de manifest desatualizado.

# Diagnóstico

runner status meu-app             # confirma estado de bloqueio
runner debug last-error meu-app   # erro estruturado com diff resumido
runner reconcile meu-app          # mostra o diff sem aplicar

# Fix

runner reconcile meu-app --apply

O reconcile roda o wizard de novo com as respostas existentes, gera novo .deploy.yml e atualiza o state. Push + próximo fetch --deploy segue normalmente.

# Sub-tipo B: Mapper drift (v2.26.7+)

Sintoma:

[FAIL] meu-app  manifest drift detected (mapper output diverged)

# Causa

O Runner valida que o output do mapper (compose → manifest) ainda bate com o .deploy.yml commitado. Se o runner foi atualizado via self-update e o novo mapper gera output diferente do que está no repo, ele bloqueia o deploy.

# Diagnóstico

runner debug last-error meu-app   # mostra campos que divergiram
runner reconcile meu-app          # mostra diff completo

# Fix

Mesmo do sub-tipo A:

runner reconcile meu-app --apply

# Quando NÃO usar reconcile

Se você editou o .deploy.yml manualmente para fazer um override específico, o reconcile vai sobrescrever essa edição.

Alternativas:

• Faça o override no docker-compose.yml em vez de no .deploy.yml.
• Ou commite seu .deploy.yml diretamente sem passar pelo wizard.

# Campos que NÃO entram no drift check

O Runner não checa divergência em campos que o operador pode customizar livremente após o wizard:

• secrets
• hosts
• config_templates
• env_sync
• source_dir

Esses campos são operator-customizable e estão fora do output do mapper. Editá-los não dispara drift.

# Como prevenir

• Rode runner reconcile meu-app antes de commitar mudanças no docker-compose.yml para ver o diff antecipado.
• Em CI, runner reconcile --json retorna exit 1 se há drift — use como gate antes de push.

# Ver também

• Manifest — anatomia
• Wizard — state machine
• Rollback manual: ver rollback.md (em breve)
• Falha com bundle criptografado: ver bundle-decrypt-fail.md (em breve)