81 lines
3.4 KiB
Markdown
81 lines
3.4 KiB
Markdown
# PR-017 [ARCHITECTURE]: Establish Single Canonical Runtime Architecture
|
|
|
|
## Briefing
|
|
|
|
O runtime hoje tem mais de um documento tentando orientar a arquitetura, com niveis diferentes de autoridade e maturidade. Na pratica, isso cria um problema de governanca tecnica: contribuidores podem consultar documentos distintos, chegar a conclusoes diferentes e ainda assim parecer "alinhados com a arquitetura".
|
|
|
|
Esta PR fecha essa ambiguidade. O objetivo nao e produzir mais texto, e sim definir um unico documento canonico de arquitetura do runtime e rebaixar, fundir ou remover o que hoje compete com ele.
|
|
|
|
## Problema
|
|
|
|
- ha mais de um documento arquitetural relevante no repositorio;
|
|
- pelo menos um deles ainda se apresenta como `stub`, enquanto outro se declara baseline autoritativo;
|
|
- a fronteira entre:
|
|
- arquitetura normativa;
|
|
- roadmap;
|
|
- documento de apoio;
|
|
- material pedagogico;
|
|
nao esta explicitamente fechada;
|
|
- sem um documento canonico, a arquitetura deixa de ser guardrail e vira opiniao distribuida.
|
|
|
|
## Alvo
|
|
|
|
- documentos arquiteturais do runtime no raiz e em `docs/`;
|
|
- definicao de autoridade documental para runtime/VM/ABI/scheduler/GC/verifier;
|
|
- governanca minima para futuras PRs arquiteturais.
|
|
- todo conteudo em ingles.
|
|
-
|
|
|
|
## Escopo
|
|
|
|
- Escolher um unico documento canonico para a arquitetura do runtime.
|
|
- Definir o papel explicito dos demais documentos relacionados:
|
|
- canonico;
|
|
- derivado;
|
|
- historico;
|
|
- roadmap;
|
|
- pedagogico.
|
|
- Consolidar ou remover o documento `stub` que hoje compete com o baseline.
|
|
- Garantir que as invariantes arquiteturais centrais tenham um unico lar.
|
|
- Registrar a regra de manutencao: mudanca arquitetural exige atualizacao do documento canonico no mesmo PR.
|
|
|
|
## Fora de Escopo
|
|
|
|
- Reorganizar todo o diretorio `docs/`.
|
|
- Reescrever todas as specs detalhadas do projeto.
|
|
- Revisar estilo textual de todo material pedagogico.
|
|
- Introduzir mudancas comportamentais na VM, runtime ou firmware.
|
|
|
|
## Abordagem
|
|
|
|
1. Inventariar os documentos que hoje falam pela arquitetura do runtime.
|
|
2. Definir uma taxonomia minima de documentos para o repositorio:
|
|
- normativo;
|
|
- especificacao;
|
|
- roadmap;
|
|
- historico;
|
|
- pedagogico.
|
|
3. Escolher o documento canonico e migrar para ele apenas as invariantes que realmente governam o sistema.
|
|
4. Rebaixar, fundir ou remover o documento `stub` e qualquer outro texto que gere concorrencia de autoridade.
|
|
5. Deixar links e notas de transicao claros para evitar pontos cegos.
|
|
|
|
## Criterios de Aceite
|
|
|
|
- Existe exatamente um documento canonico de arquitetura do runtime.
|
|
- O papel dos demais documentos arquiteturais esta explicito.
|
|
- O documento `stub` deixa de competir por autoridade:
|
|
- removido; ou
|
|
- convertido em indice/redirecionamento sem ambiguidade.
|
|
- As invariantes centrais do runtime ficam localizadas no documento canonico.
|
|
- Fica documentada a regra de que PR arquitetural deve atualizar o documento canonico quando alterar invariantes.
|
|
|
|
## Tests
|
|
|
|
- Revisao estrutural dos links e referencias entre documentos afetados.
|
|
- Confirmacao manual de que nao restaram dois documentos com claims conflitantes de autoridade.
|
|
- Se a PR mover ou renomear arquivos, validar que referencias internas em `README`, `ARCHITECTURE` e `docs/` continuam corretas.
|
|
|
|
## Risco
|
|
|
|
Medio. O risco principal e produzir consolidacao superficial, deixando ambiguidade semantica mesmo depois da reorganizacao. A PR deve ser severa: se dois documentos ainda puderem ser lidos como "fonte final", a mudanca falhou.
|