Decisões e ideias consolidadas

Avaliações, 19/10/2026: a jornada de estudo inclui checkpoint por lab e avaliação final por handbook. São conteúdo portável com objetivos, gabaritos, resoluções, fontes, pontos e revisão editorial, independentes dos motores. As predições/exercícios imediatos permanecem durante o lab; a avaliação revela as resoluções após a entrega. Bundles v2 transportam os bancos; o leitor mantém v1. O capítulo Interactive assessments descreve os cinco tipos iniciais e a fronteira entre prática local e gestão autenticada de turmas.

Contratos e entregas, 19/10/2026: conteúdo (handbook/v1, bundle/v1), implementação (lab/v1) e execução/distribuição (host-template/v1, delivery/v1) têm contratos separados. flow exige o Mermaid canônico; state exige seu runtime de estado; direct usa manipulação dedicada. O Studio monta ZIPs executáveis com versões e integridade verificadas. O capítulo Runnable handbook deliveries registra o contrato e os limites.

Studio alpha, 18/10/2026: a primeira interface local de autoria reutiliza o contrato do SDK, edita currículo/artigos, preserva rascunhos inválidos e exporta fontes ou bundle validado. O briefing assistido é preparado para compartilhar com Claude/outro assistente, sem chamada automática de modelo. O capítulo Handbook Studio, no índice de autoria, descreve os fluxos e os limites.

Atualização de 18/10/2026: a autoria independente tem artefatos alpha instaláveis de handbook-format e interactive-core, com prova de consumo fora do monorepo. O bundle v1 transporta conteúdo; as implementações de labs são dependências explícitas do host. O capítulo Independent handbook authoring, no índice de autoria, descreve o caminho e seus limites.

Atualização de 16/10/2026: o framework admite interações além do motor de fluxos. Mermaid continua contrato canônico dos cenários de fluxo; estado, reconciliação e manipulação direta têm contratos próprios. O Pod lifecycle inaugura o Kubernetes Visual Handbook sem importar o motor de fluxos. Detalhes e limites no capítulo Framework interativo e Pod lifecycle, no índice “Escrever um lab”.

Data: 2026-08-28, com o enquadramento revisto em 2026-08-29 Papel deste documento: ponto de entrada. As ideias que sobreviveram, as que foram recusadas, e as réguas que decidem discussão futura. Os outros documentos aprofundam; este resolve.

Ordem de leitura para quem chega: este → VISION.md → kinds.md → depth.md → model-format.md → why-simulate.md → roadmap.md. theory.md é opcional e fora da ordem: é o motor descrito nos formalismos de que ele é instância (grafo hierárquico, redes de Petri coloridas, cadeias de Markov) e, principalmente, a lista do que ele não modela. Cada handbook tem a sua spec, e ela tem precedência sobre todos estes em matéria de conteúdo e currículo — nunca sobre o motor: otel.model em superpowers/specs/2026-08-28-otel-visual-handbook-design.md, cpu.model em superpowers/specs/2026-08-29-cpu-model-design.md.

O enquadramento: OpenLabs

Revisto em 2026-08-29. Vem antes das seções numeradas porque muda o que elas significam, e não o que elas decidem — nenhuma decisão abaixo foi revogada.

O nome deixou de descrever o projeto no dia em que a CPU entrou no roteiro antes do OTel. Um repositório chamado OTel Visual Handbook cujo próximo entregável é um datapath RV32I mente no título — e a mentira não é cosmética: sugere que o motor é de telemetria, quando o motor é justamente o que não sabe o que é um span.

• OpenLabs é a casa: um framework de handbooks interativos, com motor composicional, runtime de estado e implementações de manipulação direta
• Cada handbook reúne conteúdo e labs, que podem usar modelos distintos. otel.model (F4) e cpu.model (F6) compartilham o motor composicional; Kubernetes usa estado/reconciliação. O domínio continua fora dos runtimes, com fronteiras verificadas pelo CI
• Todo handbook tem a mesma anatomia, e é ela que dá a página: roadmap (a ordem em que os conceitos se sustentam) · artigos (o texto que explica) · labs (o modelo que roda). Um handbook sem as três não está pronto, e a página diz isso em vez de esconder
• O reuso deixa de ser hipótese e vira o teste. A §3 mandava recusar generalidade sem dois casos; agora há dois casos, e o segundo é de outro mundo — bit e sinal, não span e pipeline. O que o cpu.model pedir ao motor e o otel.model não usar é suspeito de ser domínio vazado

O que não muda: os pacotes seguem no escopo @ovh/. Renomear quebra CI e imports por um ganho só de fachada; o nome que o leitor vê já está certo. A renomeação técnica sai de graça quando o motor for para repositório próprio — a decisão aberta nº 7 da §7.

O que mudou: o repositório passou a se chamar CabriniJr/open-labs (o nome antigo redireciona, e o clone local ainda se chama otel-visual-handbook — pasta é nome de pasta). Os links que o site publica apontam para o nome novo, e há teste cobrando isso: link que o leitor clica não pode depender de redirecionamento de terceiro continuar existindo.

Onde isto poderia mentir em silêncio: o catálogo (apps/site/src/data/handbooks.ts) é a promessa da capa, e um artigo ou lab apontando para uma fase inexistente sumiria da página sem aviso. Por isso a página lança em vez de pular, e o teste do catálogo recusa fase inexistente, fase vazia e id repetido.

1. A ideia-mãe: a gramática de Factorio

Tudo se organiza em torno de uma gramática que se aprende sem tutorial, e ela é emprestada de Factorio:

A cinta transporta. A máquina transforma. O fio de circuito carrega sinal, não item.

Traduzida, dá quatro famílias e uma distinção que a spec do motor ainda não fazia.

Consequência visual direta, e também de Factorio: duas espécies de linha. Dado em traço grosso; controle em tracejado fino. A pergunta “por onde o dado passa?” se responde olhando só as linhas grossas.

1.1 O que Factorio dá, e o que não dá

Vale ser preciso, porque a referência foi aplicada fora do domínio dela uma vez nesta discussão.

Para drill-down, as referências certas são Logisim (subcircuito que abre) e Ptolemy II (composição hierárquica de atores, com regime de execução declarado por nível).

2. As sete ideias que sobreviveram

Cada uma com o problema que resolve, porque ideia sem problema é enfeite.

2.1 O invariante cano-transforma-bloco

A forma da carga muda exclusivamente na saída de um transform. Resolve: onde a transformação acontece deixa de ser convenção e passa a ser garantia, porque vira property test — para toda aresta, o kind da carga é igual nas duas pontas, exceto saindo de um transform.

2.2 A família controlador

Árbitro, relógio e supervisor não ficam no caminho do dado. Resolve: sem essa família, seria preciso inventar fluxo onde não existe — o mesmo erro que a placa (static) foi criada para evitar.

2.3 Recurso como porta

Um arbiter que é folha recebe pedidos e devolve concessões. Resolve três lacunas com uma peça: recurso finito, atribuição dinâmica, e — porque negar concessão é frear quem pede — backpressure. Conceder memória e atribuir partição a um consumidor são a mesma forma com política diferente.

2.4 Os quatro níveis são tipos de coisa, não graus de contenção

L0 e L1 abrem um bloco; L2 abre um cano; L3 abre uma carga. E model.ts já tem exatamente essas roles: node, channel, message. Resolve dois problemas de uma vez: a recursão convive com níveis nomeados, e o conflito “o channel pode transformar a carga?” desaparece — com L2 sendo o canal aberto, o enquadramento HTTP/2 é um bloco dentro do cano.

2.5 Três eixos de profundidade, não um

Execução é bottom-up (só folha tem comportamento). Autoria é top-down (declarar raso, refinar depois). Currículo é bottom-up, à Factorio. Resolve: a pergunta “bottom-up ou top-down?” era três perguntas, e por isso não tinha resposta.

E o currículo bottom-up se implementa movendo a raiz do lab, sem tocar no motor.

2.6 O teste de refinamento

Trocar uma folha aproximada por uma subárvore exige equivalência na fronteira, com a mesma semente. Resolve: aprofundar deixa de ser aposta. E quando a equivalência falha, a informação é preciosa — significa que a aproximação de cima estava mentindo.

Bônus: ligar dois model um dia é este mesmo teste aplicado à raiz. Nenhum mecanismo novo.

2.7 Seguir a carga

Selecione uma carga e o foco desce sozinho quando ela cruza a fronteira de um bloco, e sobe quando ela sai. É a câmera acompanhando o item — em Factorio você faz com os olhos porque o mundo é plano; aqui o nível muda junto.

Resolve o argumento mais difícil do projeto: isso é impossível com um visualizador dedicado por conceito, porque exige a mesma carga existindo em dois níveis ao mesmo tempo, derivada.

3. As réguas que decidem discussão futura

Somam-se aos cinco princípios da spec do handbook, não os substituem.

4. Vocabulário — fechado

.modler e .modlet estão mortos. Sufixo proposto: <slug>.model.yaml.

5. O que foi recusado, e por quê

Registrado para não ser redescoberto.

6. O diferencial, em uma frase

Ver o mesmo dado atravessar os quatro níveis, até o frame e o byte.

L0 e L1 todo mundo faz. Ninguém desce ao frame HTTP/2 e ao campo do protobuf mantendo a identidade do dado. A exigência não é ter quatro vistas — é serem a mesma coisa, e é isso que exige o motor.

7. Estado das decisões

Fechadas

Nomenclatura · a ferramenta ensina e não opera · model é ilha com porto · reuso não é requisito · playground é editor de grafo com regras · segue com o motor · a gramática · os quatro níveis como tipos de coisa · o motor é pilar e não é obrigatório (§9) · o projeto é OpenLabs, e cada handbook tem roadmap, artigos e labs com contratos de interação próprios (o enquadramento, no topo).

Abertas, e nesta ordem de urgência

1. Licença. LICENSE (Apache-2.0) e LICENSE-content (CC BY-SA). Repositório público sem licença é todos os direitos reservados — hoje nada disto pode ser reusado por ninguém
2. entrega-1 contra main como branch default
3. Recurso, backpressure e transform desenhados juntos. Contenção de recurso é backpressure; separar produziria dois mecanismos concorrentes
4. Unidade de recurso. Se sair MB e vCPU, a ferramenta será usada para dimensionar
5. Equivalência de fronteira para o teste de refinamento
6. Realimentação e conservação — registrar como lacuna declarada, não construir
7. Quando o motor sai para repositório próprio — depois de dois casos, não antes

8. As três coisas baratas que faltam, e nenhuma exige o motor

1. Predição antes da revelação. Perguntar o que a pessoa acha que vai acontecer antes de rodar. É o achado mais replicado da pesquisa em simulação didática.

   Virou duas peças (08/09/2026). A Predicao pergunta o que vai acontecer; o Exercicio pergunta o que eu escrevo aqui — a decisão que a pessoa toma no trabalho, no meio do código em que ela é tomada. As duas dividem a mesma regra: a resposta não se refaz, porque o compromisso é o mecanismo. E as duas só põem a explicação no DOM depois da resposta, e não escondida por CSS

2. O mal-entendido que cada lab desfaz. “As pessoas acham que o span vai direto para o backend.” Vira campo no teaches, e força escrever para quem já tem ideia errada — que é o caso real

3. docs/authoring.md como interface pública. O teste de “ser base para outros handbooks” é um handbook escrito por outra pessoa, e o que habilita isso é o guia, não o motor

9. O motor é um pilar — e não é obrigatório

Decidido em 2026-09-08, no meio da rodada que ia migrar a landing para o motor novo.

Duas afirmações que só valem juntas. Separadas, cada uma vira um erro que o projeto já esteve perto de cometer.

A primeira: o depth-core é pilar do projeto, e não infraestrutura. Ele é um motor de grafos com profundidade — representar fluxo de forma dinâmica, com camadas de abstração, e descer de uma para a de baixo sem que as duas sejam desenhos diferentes da mesma coisa. Isso, nesta forma e com estes conceitos, não existe no mercado. É por isso que ele recebe atenção desproporcional ao tamanho: cada rodada de refino nele (o túnel, as vistas fundas, o roteador, a gramática do Factorio) é investimento no único ativo do projeto que ninguém mais tem. Ele nunca é “o jeito rápido de fazer o lab”; ele é o motivo de o projeto existir.

A segunda: nem todo assunto é um fluxo com camadas. O motor foi construído para grafo e profundidade, e há assunto que simplesmente não é isso. O caso que trouxe a decisão à tona é a escada fixa de quatro níveis na anatomia de um trace: abrir uma CPU até o fio é uma descida de verdade, e um trace não tem dentro — ele tem uma árvore espalhada por quatro processos que só se encontram no Collector. Forçar o assunto na forma do motor produziria um lab pior que um lab simples, e ainda mentiria sobre o assunto.

A regra, e ela decide sozinha

O assunto é um fluxo com camadas de abstração e lógica? Sim → usa o motor. Sem discussão, sem “seria mais rápido à mão”: é para isto que pagamos as rodadas de refino. Não → lab separado, enxuto, exclusivo do assunto — uma experiência mais mockada mesmo, desde que represente melhor. Mais perto do PhET do que do Factorio.

E o lab pequeno é mais barato que o motor — este é o outro lado, e ele importa tanto quanto: o motor é bom, funciona, e adentrar nele é a melhor coisa que o projeto tem, mas isso é razão para usá-lo onde ele ganha, e não para forçá-lo onde o assunto não é fluxo. Um lab especializado, isolado e bem feito ensina mais que uma rua construída para explicar uma porta, e custa menos.

O critério de qualidade não cai no segundo caso: pequeno e dedicado não é rascunho. Um lab PhET-like continua devendo o mesmo que qualquer outro — uma pergunta concreta, resposta derivada do estado e não de texto, o mal-entendido que ele desfaz, contraparte real quando ele afirma algo sobre o mundo, e teste que cai quando o lab para de ensinar o que promete. O que ele não deve é profundidade: sem árvore de composição, sem palco, sem kinds.

O corte real: a fábrica ou o item?

Afiado por ele em 2026-09-08, logo depois: “mesmo que se encaixe na nossa lógica de fluxos, o foco é o item e não a fábrica — o nosso sistema de grafos funciona muito bem quando o foco é a fábrica, mas no span o foco é o item; ou melhoramos o foco pro item, ou criamos um lab mais PhET.”

“Fluxo com camadas” era a pergunta certa e não era a pergunta suficiente. Um trace é um fluxo com camadas, e mesmo assim o motor não o serve bem — porque o motor é centrado na fábrica. O protagonista dele é o grafo: as máquinas, as esteiras, o que tem dentro de cada caixa. O item é carga que atravessa; desde “seguir a carga” dá para clicar nele e ler o corpo, mas ele continua sendo um ponto pequeno numa esteira, com o painel de lado.

Num span, o protagonista é o item: importa aquela coisa, o que ela virou em cada parada, e onde ela terminou. A fábrica é cenário. Aplicar o motor sem enxergar isso produz um lab que desenha a tubulação com capricho e trata de raspão o assunto.

O tema do lab é quem nomeia o protagonista — e não a gente. A formulação dele, e ela resolve o caso sozinha:

“É que nem estarmos fazendo um lab sobre motorista e focar nas ruas, e um lab de ruas e focar no motorista. E num de porta de carros, não vamos montar uma rua para explicar.”

O protagonista não é escolha de desenho: ele já está dito no assunto, e a única maneira de errar é não perguntar. Lab de oleoduto → a fábrica protagoniza. Lab de span → o item protagoniza. Lab de porta de carro → nem um nem outro, e montar a rua em volta para explicar a porta é gastar caro para ensinar pior.

E ela é assumidamente subjetiva. Isso não a enfraquece: a alternativa é a omissão, que decide igual e decide sempre a favor do motor, porque o motor está pronto.

Então a régua tem duas perguntas, nesta ordem:

1. É um fluxo com camadas de abstração e lógica? Não → lab separado, PhET-like.
2. Quem é o protagonista, a fábrica ou o item? Fábrica → motor, é o caso para o qual ele foi feito. Item → decisão explícita entre duas saídas, e nunca por omissão: ou a rodada melhora o foco no item no motor — e aí é investimento no pilar, com dono e escopo —, ou o lab é separado e PhET-like. O que não pode acontecer é usar o motor como está e deixar o item de coadjuvante num assunto que é sobre ele.

O que isto revoga, e o que não

Não revoga nada da §3: “só precisa ser simulado o que vai ser apresentado” e “model que não cabe num handbook é dois model” continuam valendo, e esta regra é irmã das duas. Revoga uma expectativa que nunca foi escrita mas estava no ar — a de que todo lab de todo handbook nasceria do .model. Não nasce. O handbook é a casa; o motor é o inquilino principal, não o único.

Onde isto poderia mentir em silêncio: um lab PhET-like desenhado à mão pode afirmar o que nenhum modelo sustenta, que é o defeito mais caro do projeto. A trava é a mesma dos outros: contraparte real. Se o lab diz algo sobre o mundo, o repositório tem de ter como conferir contra a coisa de verdade — e sem modelo por baixo, essa dívida fica maior, não menor.

10. Handbook é submissão, e o contrato tem versão

Decidido em 2026-10-16. O caminho para quem submete está em handbooks.md; esta seção decide, e cria a régua.

O problema

Publicar um handbook exigia editar TypeScript dentro do site: apps/site/src/data/handbooks.ts, mais o mapa, mais um arquivo de tema. Isso faz duas coisas ruins ao mesmo tempo, e as duas são estruturais:

• quem domina um assunto precisa aprender a casa inteira antes de escrever a primeira linha. O custo de entrada não é o conteúdo, é o monorepo;
• quem mantém a casa fica dono de conteúdo que não é dele. Um handbook de terceiro no meio do nosso código é código nosso para sempre.

A decisão

Um handbook é um diretório com um manifesto, e o manifesto tem dono declarado. handbooks/<id>/handbook.yaml, contrato em arquivo, zero TypeScript. O CODEOWNERS é derivado dos manifestos — submeter é também assumir a propriedade.

Três consequências que valem estar escritas, porque cada uma foi uma escolha contra uma alternativa mais arrumada:

1. Os artigos de uma submissão moram onde moram os nossos (apps/site/src/content/articles/<id>/), e não dentro do diretório do autor. A pasta do autor ficaria mais arrumada; o preço seria conteúdo submetido com guardas mais fracas que o nosso — fonte citada nas duas direções, degrau de drill-down, catálogo e disco concordando. Arrumação não paga promessa enfraquecida.
2. O manifesto não descreve comportamento, e isso fica dito. Lab que roda é modelo, e modelo é TypeScript. Inventar um formato que descrevesse comportamento pela metade seria pior que recusar: o autor descobriria o limite depois de escrever.
3. O map é a razão honesta de OTel e CPU seguirem em TypeScript. Ele é desenho com coordenadas, e o contrato em arquivo não desenha. Escrito, em vez de descoberto por quem tentar migrar.

A régua nova: compatibilidade é mecanismo, não boa vontade

A release que introduz uma versão nova do contrato continua lendo a anterior. A régua que isso cria, e que decide discussão futura sobre formato:

Toda versão suportada tem exemplar de conformidade, e o exemplar carrega em cada suíte. Uma versão só sai da lista quando existe migração automática para a seguinte.

O que a régua impede, concretamente: a limpeza silenciosa. “Ninguém mais usa aquele formato” é uma frase que alguém diz num refactor, e o custo cai em quem não está na sala. Com a régua, apagar o leitor de uma versão listada derruba a suíte nomeando a versão — a decisão de aposentar passa a ser deliberada, que é o que ela tem de ser.

E a recusa separa as duas direções, que erram diferente: quem escreveu contra uma versão mais nova está com o site velho e é mandado atualizar a casa (nada no arquivo dele está errado); quem escreveu contra uma aposentada é mandado migrar. “Versão inválida” manda os dois procurarem no lugar errado.

Por que duas versões já existem hoje

Porque a promessa só vale se for verificável agora, e não sobre um v2 futuro que ninguém pode testar. Os três handbooks originais são objetos TypeScript escritos à mão — essa é, literalmente, a versão anterior deste contrato, e ela está na lista com esse nome: não é “o jeito antigo”, é typescript, estado anterior, com data.

A prova é uma igualdade medida: o algorithms migrou para openlabs/handbook/v1, e o objeto que estava escrito no site ficou congelado em handbooks.test.ts como expectativa, comparado campo por campo com o que o leitor produz. Cor, fase, href, status: idênticos. É o que faz “migrar é mecânico” ser um fato e não uma frase.

Onde isto poderia mentir em silêncio

Um manifesto válido descreve um handbook que não ensina nada — fases bem-numeradas, itens todos coming, tema bonito. O formato não tem como cobrar currículo, e não deve tentar: a régua da §9 e a exigência de fonte primária continuam sendo trabalho de revisão humana. O que o formato garante é que nada desaparece em silêncio; o que ele não garante é que valha a pena ler. Essa distinção precisa estar na cabeça de quem revisa um PR de handbook, e é a última seção de handbooks.md justamente por isso.

11. Um terceiro motor, para o que é coreografia

Decidido em 2026-11-03.

A §9 separou dois casos: fluxo com camadas vai para o motor de grafos; o resto vira lab PhET-like, enxuto e próprio. Faltava um terceiro, e ele aparece toda vez que o assunto é um protocolo: atores fixos, mensagens que viajam numa ordem, e uma pergunta que é sobre o que atravessa cada salto. Propagação de contexto, um handshake, uma reconciliação.

Isso não é fluxo com camadas — não há dentro em um header. E também não é um lab de estado com botões: o que ensina é ver a coisa andar, com a câmera indo aonde ela está. Escrever isso à mão em cada lab é o caminho por que o projeto já passou com as cores (§ do catálogo): cada um escolhe bem por conta própria até o dia em que não escolhe.

A decisão: @ovh/motion, um palco animado agnóstico — geometria, linha do tempo pura, ferramentas de coreografia e um player com capítulos. Ele vale as mesmas três regras dos outros motores:

1. Fronteira vigiada. Está em pnpm boundaries e em check-catalogo: não conhece domínio e não escreve tinta.
2. Derivado, não roteirizado. Um filme é função de um modelo do domínio. O filme do lab de propagação sai de propagar(), e o teste interroga o quadro, não o desenho.
3. Dado puro. O Film é amostrável em qualquer instante. Voltar, pular e mudar uma opção no meio não perdem a posição nem dão quadros diferentes para o mesmo instante.

O que ele não é: substituto do depth-core. Um assunto que tem camadas e que se abre continua lá. Se um dia um filme precisar descer para dentro de uma peça, o caminho é o palco de fluxos, não um zoom de câmera que finge profundidade.

12. Ícones são do handbook; rótulos cedem; o roteiro é contrato de conteúdo

Ícone. O motor aceita icon: Glyph em qualquer peça e não traz desenho nenhum. O catálogo de ícones é da identidade do handbook (ICONES_OTEL, ICONES_K8S, ICONES_CPU), e um papel tem o mesmo ícone em todos os labs do handbook. É o que deixa o leitor reconhecer o Collector de um lab para o outro sem ler o rótulo. Um ícone no motor seria um assunto no motor, e a fronteira (check-boundaries) existe para impedir isso.

Rótulo que cede. No isométrico, rótulos que no plano tinham folga se empilhavam. Apertar o layout de cada filme para caber no 3D tornava o plano pior. A regra fica no palco 3D: o rótulo de prioridade menor some enquanto cobriria outro. A prioridade é aceso, depois a peça maior.

Janela à esquerda, andamento à direita. Empilhados, a narração caía abaixo da dobra e quem assistia o filme não via o que o capítulo dizia. O layout é do MotionPlayer (container query), não de cada lab.

Roteiro. docs/roteiros/<handbook>.md diz, por lab, a pergunta, o mal-entendido, a mídia, os capítulos, o significado da altura no 3D, os ícones e as correlações. É o contrato de conteúdo. O da forma é a skill. Os dois são atualizados no PR que muda o lab.

Verbo antes de byte. O protobuf teve dois showcases recusados. Um era um filme de fichas voando do objeto para um fio de blocos. O outro mostrava um buffer em hexa crescendo em etapas. Os dois mostravam a máquina por dentro antes de contar a história. O que ficou é o formato do hero antigo, modernizado no filme: o span é um papelzinho que pula de app em app (com ícone), e uma tela ao lado soma, em verbos curtos, o que cada um fez com ele. A profundidade é descer dentro do papel (campos, depois um campo). A interatividade são escolhas que refazem o filme (protobuf/JSON, um atributo a mais). O hexa e os offsets ficam na simulação, para quem quer cavar. O motor de fluxos (depth-ui) não é obrigatório, e este lab não o usa.