# 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.