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