prometeu-runtime/docs/runtime/agendas/007-single-canonical-architecture.md

Agenda - Single Canonical Architecture

Problema

Hoje a arquitetura do runtime está fragmentada em documentos com níveis diferentes de autoridade.

Na prática existem pelo menos dois problemas:

• mais de um documento tenta falar pela arquitetura;
• um deles ainda se apresenta como stub, enquanto outro se declara baseline canônico.

Dor

• Contribuidores perdem tempo tentando descobrir qual documento manda.
• PR arquitetural pode ser validada por um texto e contrariar outro.
• A documentação deixa de servir como guardrail e passa a gerar ambiguidade.
• O projeto perde disciplina exatamente na camada que deveria fixar invariantes.

Alvo da Discussao

Definir um único documento canônico de arquitetura do runtime, com papel explícito para cada outro documento remanescente.

O alvo é matar a ambiguidade, não só mover arquivos.

Ao final da discussão deve ficar claro:

• qual documento é canônico;
• quais docs são derivativos, históricos ou de apoio;
• o que deve ser removido, fundido ou rebaixado de autoridade.

O Que Precisa Ser Definido

1. Documento canônico. Onde vive a arquitetura mandatória do runtime.

2. Escopo do documento. Quais invariantes ele deve cobrir:

   • execution model
   • memory model
   • safepoints
   • scheduler
   • verifier
   • syscall ABI
   • firmware/runtime boundary

3. Papel dos demais docs. O que é:

   • arquitetura normativa
   • roadmap
   • histórico
   • specification detalhada
   • material pedagógico

4. Política de atualização. Mudança arquitetural deve exigir atualização do doc canônico no mesmo PR?

5. Estratégia de remoção do stub. Se será apagado, redirecionado ou transformado em índice.

O Que Necessita Para Resolver

• inventário dos docs que hoje competem por autoridade;
• decisão de taxonomia documental;
• definição do local canônico;
• plano de migração de conteúdo sem perder contexto útil;
• regra de governança para futuras PRs arquiteturais.

Fora de Escopo

• reorganização completa de todo o diretório docs/;
• rewrite estilístico de todo material pedagógico;
• padronização editorial fina além do necessário para eliminar ambiguidade.

Critério de Saida Desta Agenda

Pode virar PR quando houver:

• definição do documento canônico;
• lista do que será removido, fundido ou rebaixado;
• regra explícita de atualização futura;
• plano curto de migração sem deixar lacuna documental.