82 lines
2.4 KiB
Markdown
82 lines
2.4 KiB
Markdown
# 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.
|