[FEAT] Ciclo: seleção, clone paralelo, análise e push

[cpenaforte-clickbus]

User story

Como a plataforma do Iris, eu quero receber as métricas de todo repositório que mudou, para que o
dado do produto não dependa de hook instalado na máquina de ninguém.

Acceptance criteria

• Seleção: pendente é o repositório cujo digest lido agora difere do refs_digest que a última
  análise dele gravou, por GET /api/ingest/watermarks. Ausência de linha significa pendente.
• Clone completo, 8 ao mesmo tempo (medido: 51,9 s com 8, contra 84,2 s com 4, sem uma falha e
  sem limite secundário)
• iris <clone> --windows 7,15,30,60,90 — cinco janelas na mesma execução, um repositório por vez
• Push com --refs-digest e com o author_velocity desligado
• Repositório sem nada a analisar na janela → POST /api/ingest/watermarks, para o digest não ficar sem registro
• Censo best-effort: o ciclo publica o retrato da organização em POST /api/ingest/repo-state;
  falha ou rota ausente loga e segue, sem abortar o ciclo
• Ciclo sem pendente termina sem fazer nada — é normal, não falha
• Repositório que falha é contado e reportado, nunca excluído da seleção
• O clone é efêmero e descartado no fim do job

Por que o clone é completo, e não shallow

Por causa de durability, que usa git blame para saber quando cada linha viva nasceu. Em clone
shallow o blame para no commit de fronteira e credita a ele todas as linhas antigas — que entram na
janela e inflam a métrica, sem erro nenhum.

Por que um iris por repositório, e não o caminho --org

Medido campo por campo no mesmo commit: o --org concorda com o outro em tudo que emite, mas omite
131 chaves em 21 grupos — entre eles provenance_by_origin e todo o grupo de duplicação — e não faz
push. O laço um-a-um custa ~1,14× de tempo e resolve os dois. Há um terceiro motivo: o --org tira o
nome do repositório do diretório (org_runner.py:65), e não do remote, que é de onde a plataforma o
resolve.

Por que o censo é best-effort

A rota POST /api/ingest/repo-state chega na Fase 4. O DD é explícito de que censo velho não cega o
watchdog — é a checagem 2, que só olha linha nova, que transforma silêncio em alerta. Então o ciclo não
depende da rota existir para funcionar, e esta issue pode ser mergeada antes da Fase 4.

Se encaixa em qual estágio?

Stage 2 — Ingestion: reliability of CLI → /api/ingest pipeline.

Implementation notes

Estende o scripts/iris-cycle.sh da issue de descoberta. O ciclo custa 61 s + 7,1 s × pendentes:
passar de 30 min pediria 245 pendentes e estourar o timeout-minutes: 60 pediria 498 — contra
os 49 e 82 medidos, que são 8% e 14% da organização.

Links

• DD 0010 §3.1, §3.3 e §3.5: https://github.com/RocketBus/clickbus-rfc-design-docs/blob/main/design-docs/DD0010-Coleta-Centralizada-de-Atribuicao-do-Iris.md
• Parte de: Fase 2 — Worker de coleta #210

Bloqueado por

Esta é a issue de integração: ela consome quase tudo o que as fases anteriores entregam. Cinco
dependências reais, e nenhuma é opcional.

Precisa de	Para quê
#221	o scripts/iris-cycle.sh e o workflow que esta issue estende
#218	GET /api/ingest/watermarks — sem ele não há como saber o que é pendente
#219	POST /api/ingest/watermarks — o caminho da run que não emite métrica
#223	--refs-digest e a flag do author_velocity — sem elas o push não fecha o contrato
#220	a autenticação do CLI em CI — o worker empurra de um runner, sem iris login

Só a publicação do censo é best-effort e não bloqueia: se POST /api/ingest/repo-state
(#225) ainda não existir, o ciclo loga e segue.

Detalhes que a seleção e o clone carregam

• A query de seleção usa o pushedAt como ordenação — quem decide o que é pendente é o digest,
  mas a ordem em que o ciclo ataca o conjunto vem da data de push
• O disco do run cabe no runner: o clone de um ciclo típico ocupa 1,47 GiB, e o ciclo de partida
  é projetado em 5,3 a 7,1 GiB contra os 14 GB de SSD do runner hospedado de repositório privado

Otimização de clone deixada de fora, e por quê

Cache de mirror bare com git fetch incremental não entra: medido, o clone é 14% do ciclo contra
70% do engine. Otimizar 14% traz gestão de chave e eviction de cache. Volta à mesa se o conjunto
pendente crescer muito — hoje ele é 8% a 14% da organização.

O clone é completo e descartável, e é isso que mantém o git blame correto.