0016 — A hospedeira do arquivo-fato

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-16 · Decidido em: 2026-07-16

Contexto

A 0014 mandou o dono publicar o arquivo-fato e o consumidor importá-lo no build. A receita dizia que o fato "vive em docs/public/ como qualquer página" e leva not_in_nav:. As duas metades não fecham: sem uma página que o embuta, o fato existe no raw/ (consumível por máquina) e não aparece no site do dono para gente nenhuma.

E not_in_nav: não faz o que a receita supunha. Ele não esconde — só cala o aviso de órfã do --strict. O fragmento continua sendo buildado, e o resultado (verificado, não deduzido) é pior do que "uma página a mais":

• ganha um H1 inventado do nome do arquivo — a órfã se chama "Xadm ingest";
• fica alcançável por URL;
• entra no índice de busca: procurar "Envelope" devolve a hospedeira e a órfã, com o mesmo texto. O fato compete com a página que o mostra.

O dev do hub, sem a receita prescrever nada, inventou a hospedeira por conta (docs/public/contratos/index.md) — a solução certa, descoberta duas vezes.

O mesmo defeito estava no lado do consumidor, e ninguém tinha olhado: _importado/ em not_in_nav: faz o site do consumidor servir o contrato do dono como se fosse página dele — a cópia que a §1.9 existe para matar, de volta pela porta dos fundos.

Havia ainda duas convenções para página pública: o templates/public-api.md sem frontmatter, a hospedeira do hub com frontmatter completo. O valida-frontmatter não cobra nenhuma das duas (só mapeia public/manual), então ambas passavam e nada arbitrava.

Decisão

Publicar inclui hospedar. O arquivo-fato é fragmento, não página: sai do build com exclude_docs: e quem o mostra é uma página hospedeira do dono — no nav:, com frontmatter, embutindo os fatos com --8<--. É o padrão do projeto/index.md embutindo o modelagem.md, agora escrito. Vale para os dois lados: _importado/ também é exclude_docs:.

not_in_nav: fica para o que deve sair no site sem estar no índice — o Javadoc gerado em dev/api/. Não é sinônimo de exclude_docs:, e trocá-los tem consequência visível.

Página em docs/public/ leva frontmatter, inclusive a da API (o template foi corrigido). Governança por documento (§6) não tem exceção por a página ser pública, e para quem consome um contrato o cabeçalho é justamente o que importa: atualizado: diz se o contrato está vivo, status: se dá para confiar, responsavel: a quem perguntar. O hook expõe o nome, nunca o e-mail.

Consequências

• O --8<-- e o raw/ seguem funcionando com exclude_docs: — os dois leem do disco, não do build (verificado: build --strict limpo, hospedeira transclui, órfã some da busca).
• O checa-nav.py tinha dois bugs que só apareceram agora, e que teriam transformado a hospedeira numa órfã silenciosa: o veredito parava no primeiro glob que casava (ignorando a negação !), e os globs vinham num set — sem ordem, num formato em que a ordem decide (última que casa vence, como no .gitignore). Corrigidos, com três casos novos de regressão. Um terceiro: o regex que varre o mkdocs.yml capturava os próprios globs de exclusão como "menção de nav", o que dava passe livre a fatos não cobertos por exclude nenhum.
• Migração: quem já publica fato (o hub) troca not_in_nav: por exclude_docs: e ganha a hospedeira — que ele já tinha escrito sozinho. Sem a troca, nada quebra: só continua servindo a órfã.