Runtime Events

O GFRM agora emite um stream ordenado de runtime events para cada execução.

Para que serve

Runtime events servem para:

• observabilidade de runtime
• asserções de teste
• atualizações de progresso da GUI em tempo real

Eles complementam os artefatos voltados a operadores, mas não substituem summary.json, failed-tags.txt, migration-log.jsonl nem gfrm resume.

Ordenação e sinks

• a ordenação dos eventos é autoritativa dentro de cada execução
• sinks suportados nesta entrega: console, JSONL, in-memory e reducer
• a formatação específica de cada sink fica fora do publisher ordenado
• sinks agora declaram um modo explícito de falha: optional ou mandatory

O sink JSONL é uma implementação consumidora de runtime events. O artefato público da execução para operadores continua sendo migration-log.jsonl.

Política de falha

• sinks optional operam em best-effort: falhas são registradas e a execução continua
• sinks mandatory falham a execução imediatamente quando não conseguem consumir um evento

Use mandatory só quando o consumidor fizer parte do contrato obrigatório de runtime da camada que embute o GFRM.

RunState derivado

O sink reducer pode derivar um snapshot tipado de RunState a partir do stream ordenado de eventos.

O modelo atual do snapshot inclui:

• status de lifecycle
• fase ativa
• resumo de preflight
• contadores de tags e releases
• entradas de progresso por tag e por release
• caminhos de artefatos
• comando de retry e status final de conclusão
• contexto da falha mais recente

Esse estado serve para GUI, testes e diagnósticos in-process. Ele permanece provider-agnostic e seguro para replay porque é derivado apenas dos runtime events canônicos acima.

Run Progress no desktop

A tela desktop Run Progress exibe lifecycle, fase ativa e contadores separados de tags/releases para itens criados, que seriam criados (dry-run), existentes ignorados e falhos. A tabela exibe as entradas de progresso tipadas. O status de conclusão e a falha mais recente permanecem visíveis ao final da execução.

A tela lê o snapshot atual de DesktopRunController ao entrar e acompanha seu stream de snapshots, mapeado a partir do RunState compartilhado. Não interpreta saída de terminal nem avança contadores por timer. Sem execução, exibe estado vazio; uma falha do stream exibe aviso de atualização e mantém o snapshot atual.

Iniciar migração pelo wizard ainda está indisponível. Esta tela observa execuções iniciadas pelo controller desktop tipado; ações de retry/cancelamento são trabalhos separados.

Migration Results no desktop

A tela desktop Results lê o mesmo snapshot atual e stream. Antes do fim de uma execução, exibe um estado vazio ou em andamento. Quando o lifecycle é completed ou failed, mostra o lifecycle final, o resultado de conclusão quando informado, o total de tags e tags com falha, além dos contadores separados de resultados de tags/releases. Lifecycle concluído não significa sucesso: uma execução com partial_failure mantém esse resultado visível. Os detalhes de falha incluem código, fase e mensagem informados, inclusive falhas anteriores à geração de artefatos. Entradas de tags/releases com falha também mostram a identificação e a mensagem informada, mesmo quando uma falha parcial não tem uma exceção no nível da execução.

Os caminhos de summary.json, failed-tags.txt e migration-log.jsonl aparecem apenas quando informados pelo runtime. A tela exibe caminhos selecionáveis sem abrir arquivos nem verificar se ainda existem. A orientação de retry aparece apenas quando o snapshot final fornece um comando de resume não vazio; a contagem de falhas sozinha não cria um comando. Você pode selecionar esse comando para usá-lo no terminal. Executar retries e abrir artefatos pela GUI continuam sendo trabalhos separados.

Entrar em Results após a conclusão mostra o snapshot atual sem aguardar outro evento. Erros do stream exibem um aviso e preservam os resultados atuais; iniciar uma nova execução substitui os resultados anteriores pelo estado pendente. Esta tela não lê saída de terminal nem reconstrói resultados a partir dos arquivos de artefatos.

Famílias de eventos

Exemplos de runtime events expostos nesta entrega:

• run_started
• preflight_completed
• tag_migrated
• release_migrated
• artifact_written
• run_completed
• run_failed

Esses eventos podem espelhar estado de progresso e caminhos de artefatos gravados, incluindo summary.json e failed-tags.txt.

Estrutura do Evento run_started

O evento run_started é emitido como parte do stream ordenado de runtime events. No sink JSONL, é encapsulado em um RuntimeEventEnvelope:

{
  "event_type": "run_started",
  "timestamp": "2026-04-20T20:30:00.000Z",
  "payload": {
    "source_provider": "github",
    "target_provider": "gitlab",
    "mode": "migrate",
    "dry_run": false,
    "skip_tags": false,
    "skip_releases": false,
    "skip_release_assets": false,
    "settings_profile": "my-profile"
  }
}

Estrutura do envelope:

• event_type: Sempre "run_started"
• timestamp: Timestamp ISO 8601 quando o evento foi emitido
• payload: Dados específicos do evento (veja campos abaixo)

Campos do payload:

• source_provider: Forge de origem (github, gitlab, bitbucket)
• target_provider: Forge de destino (github, gitlab, bitbucket)
• mode: Nome do comando (migrate ou resume)
• dry_run: Se a execução está em modo dry-run
• skip_tags: Se a migração de tags está pulada (de --skip-tags)
• skip_releases: Se a migração de releases está pulada (de --skip-releases)
• skip_release_assets: Se a migração de assets de releases está pulada (de --skip-release-assets)
• settings_profile: Nome opcional do perfil de configuração (se fornecido)

Contrato público

Use runtime events quando você precisar de visibilidade ordenada do runtime dentro da aplicação, testes ou futuras camadas de GUI. Use summary.json, failed-tags.txt, migration-log.jsonl e gfrm resume quando precisar do contrato operacional público para triagem e recuperação.