[FEAT] POST /api/ingest/watermarks — a run que não emite métrica

[cpenaforte-clickbus]

User story

Como o worker de coleta, eu quero registrar o ciclo de um repositório que não tinha nada a analisar,
para que o digest dele não fique sem registro e ele não volte pendente em todo ciclo, para sempre.

Acceptance criteria

• POST /api/ingest/watermarks — mesmo caminho do GET, outro verbo, porque o recurso é o mesmo
• Recebe repository, window_days e refs_digest
• Autentica pelo token de ingestão, como a /api/ingest/usage já faz
• Grava a linha de analysis_runs com commits_total zero e responde 200 — ou 200 com
  duplicate: true, pelo mesmo índice único
• Não escreve em metrics — e por construção, não por validação: não tem caminho para isso
• Não cria repositório: responde 404 para nome desconhecido. O DD chama isso de "nome que o
  censo não conhece", mas a checagem é contra a tabela repositories — que o censo da Fase 4 passa a
  preencher para a organização inteira. Nesta fase ela contém só o que já ingeriu alguma vez, e isso
  basta: esta issue não depende do censo existir.
• Não aceita commits_total, github_user nem active_users do cliente

Por que rota separada, e não uma segunda forma de payload no /api/ingest

O que isso compra é que o corpo do /api/ingest continua tendo uma forma só, ganhando apenas o
campo refs_digest: o agente local não vê diferença nenhuma, e não há união de payloads para validar
nem para errar.

O que o poder desta rota realmente é

O que sobra é o que o token de ingestão já podia fazer de qualquer forma: avançar o watermark de um
repositório da própria organização e com isso fazer o worker saltar uma análise. É negação de dado,
não vazamento.

O dashboard continua honesto sem esforço

O repo_metric_summaries da migration 022 lê de metrics, então a run sem métrica não infla a
contagem de execuções nem move a data da última.

Se encaixa em qual estágio?

Stage 2 — Ingestion: reliability, token auth, idempotency.

Implementation notes

Sem esta rota, a análise que não encontra nada na janela termina sem emitir métrica e o repositório
volta pendente em todo ciclo, indefinidamente — custando um clone por ciclo para sempre.

Links

• DD 0010 §3.2: https://github.com/RocketBus/clickbus-rfc-design-docs/blob/main/design-docs/DD0010-Coleta-Centralizada-de-Atribuicao-do-Iris.md
• Parte de: Fase 1 — Watermark e ingestão idempotente #209

Bloqueado por

A coluna refs_digest e o índice único: #217. Sem eles a rota existe mas erra em runtime — nada em uso quebra, porque ninguém a chama ainda.