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

Inventariar os documentos que hoje falam pela arquitetura do runtime.
Definir uma taxonomia minima de documentos para o repositorio:
- normativo;
- especificacao;
- roadmap;
- historico;
- pedagogico.
Escolher o documento canonico e migrar para ele apenas as invariantes que realmente governam o sistema.
Rebaixar, fundir ou remover o documento stub e qualquer outro texto que gere concorrencia de autoridade.
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.

3.4 KiB Raw Blame History