Catálogo de arquétipos

Status: proposta para discussão. Nada aqui está implementado. Data: 2026-08-28 Depende de: VISION.md — em especial §7.2 (recurso), §7.3 (cobertura) e §7.4 (o invariante cano-transporta-bloco-transforma)

Se o pacote de modelo é dado, o catálogo de arquétipos é o teto do projeto: nenhuma aplicação pode ser expressada além do que os kind sabem fazer. Este documento tenta esgotar o catálogo antes de construir, porque descobrir arquétipo faltando depois de três pacotes escritos custa reescrever os três.

1. A gramática, antes dos arquétipos

Emprestada de Factorio, e o motivo é que ela se aprende sem tutorial: cinta transporta, máquina transforma, e o fio de circuito carrega sinal, não item.

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

A quinta coisa é a carga: a mensagem que viaja. O kind dela é vocabulário do domínio, não do motor.

1.1 A distinção que falta hoje: processador contra controlador

A spec atual tem uma família de bloco só. Mas um árbitro de recurso, um relógio e um disjuntor não estão no caminho do dado — eles influenciam quem está. Tratá-los como processador obrigaria a inventar um fluxo que não existe, que é exatamente o erro que a placa (static) foi criada para evitar.

Factorio já resolve isso e vale copiar a solução: duas espécies de linha.

Com isso, a pergunta “por onde o dado passa?” se responde olhando só as linhas grossas. É o mesmo ganho de legibilidade do invariante da §7.4 da visão, aplicado à topologia.

1.2 O invariante visual, e como ele vira teste

A forma da carga muda exclusivamente na saída de um transform.

Isso é a §7.4 tornada verificável. Dá um property test direto, no espírito do teste 2 da spec do motor:

para toda aresta de dado, em todo tick:
  kind(mensagem na origem) == kind(mensagem no destino)
  exceto quando a origem é um transform

Se esse teste passa, o modelo não consegue mentir sobre onde a transformação acontece. É a diferença entre uma convenção de desenho e uma garantia.

2. Os oito de hoje

O que já existe em packages/depth-core/src/model.ts, relido sob a gramática acima.

Nota sobre pipeline e composite: eles não processam nada — organizam. Talvez mereçam ser uma família própria (contêiner) em vez de bloco, já que não têm comportamento por definição. É decisão de desenho, não de motor.

3. Onda 1 — necessários para a v0

Critério de entrada: paga em dois alvos ou mais e algum cenário banal do OTel já precisa dele.

transform

Muda a forma da carga. O único arquétipo autorizado a fazer isso.

tee — removido em 2026-08-29

Fan-out virou nativo da porta, e tee seria um segundo mecanismo para o mesmo fenômeno. A entrada fica aqui riscada em vez de apagada: quem reler o catálogo precisa achar a discussão, não um buraco.

O que ele propunha — “a mesma carga para N saídas” — é hoje o que n fios saindo de uma porta fazem: n cópias, cada uma um item em trânsito próprio, out: contando uma emissão e cada destino contando o seu in:. A régua da §3 (um arquétipo entra pagando em dois alvos) o reprova agora: ele não paga em nenhum, porque a junção já existe sem ele. E num esquemático, desenhar um bloco em cada junção de fio destruiria o desenho.

O que valia na nota original continua valendo, e por isso fica: router não resolve fan-out. Router escolhe uma porta; o leque usa todas. Confundir os dois ensinaria que enviar para dois destinos é uma escolha, quando é uma duplicação — e o custo de recurso é completamente diferente.

O que se perdeu junto e é dívida declarada: a política de falha parcial (“exige todas, ou basta uma”) e o medidor por saída. Hoje o leque entrega a todos, sempre. Quando backpressure chegar (F1), é ali que essa política tem que aparecer — no regime da aresta, não num bloco.

merge

Fan-in: N entradas para uma saída, com política de ordem declarada.

Nota: hoje o motor não define o que acontece quando duas arestas chegam na mesma porta. A ordem seria implícita — e ordem implícita é exatamente o tipo de coisa que muda de comportamento em refactor sem ninguém perceber.

batch

Agrupa N cargas em uma carga de peso N.

buffer fica sendo só retenção: entra um, sai um, com capacidade e política de estouro. O BatchSpanProcessor real é buffer mais batch, e mostrar isso separado é ganho didático — o leitor vê que fila e lote são decisões diferentes.

clock

Controlador. Dispara em intervalo.

Hoje o disparo por tempo está escondido dentro do buffer e do source. Explicitá-lo responde a pergunta “quem disparou isso?”, que é impossível de responder hoje.

arbiter

Controlador. Concede o que é finito.

É a peça que fecha três lacunas com um arquétipo. 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.

4. Onda 2 — o segundo alvo (Kafka)

log

Registro append-only com cursor independente por leitor.

buffer não serve: buffer esvazia ao ser consumido, log retém e é lido. A diferença não é detalhe — é o que faz o Kafka ser Kafka, e é o fenômeno mais estranho ao TracerProvider. Por isso o Kafka continua sendo um alvo certo (§7.3 da visão) — embora, desde 29/08/2026, não mais o segundo: a CPU passou na frente (roadmap.md F6).

deliver

Entrega com confirmação e reenvio.

Alternativa a considerar: isso pode ser política do channel em vez de arquétipo. A favor de ser arquétipo: duplicata gerada por reenvio é um fenômeno didático de primeira grandeza — é a razão de idempotência existir — e merece um lugar visível. A favor de ser política: menos peças. Decidir junto com backpressure, porque os dois mexem em emissão que pode falhar.

supervisor

Controlador. Mata e recria.

É o arquétipo que faz o estouro de memória ensinar: a fila enche, o bloco morre, e o que estava na fila desaparece. Sem ele, estourar recurso não tem consequência visível — e consequência invisível não ensina nada.

5. Onda 3 — Prometheus e o contraste push contra pull

store

Retém com consulta e expiração.

Diferença de buffer e de log: buffer é consumido, log é percorrido, store é consultado. Três verbos, três arquétipos.

Antecipado para hoje (30/08/2026). store saiu da onda 3 e entrou no motor antes do resto dela, e a razão foi de desenho e não de aplicação: memória, banco de registradores e pilha eram todos buffer, e um buffer é desenhado como quem processa. A pergunta “o que tem aí dentro agora?” não tinha forma, e sem forma a caixa fica lisa exatamente na vista em que se quer ver o que ela guarda. A parte que não veio junto é a porta de consulta como requisição e resposta: hoje quem quer um valor manda carga e o store responde, que é o que o caminho de dados já fazia. Expiração e medidores de acerto continuam na onda 3. Lacuna declarada, e não esquecimento.

probe

Controlador. Requisita e correlaciona a resposta — o modelo pull.

Hoje todo o motor é push: a folha emite quando quer. Sem probe, é impossível ensinar a diferença entre OTel e Prometheus — que é justamente o que mais confunde quem opera as duas ferramentas. E a diferença tem consequência prática: no push, o produtor decide o ritmo e o coletor sofre; no pull, o coletor decide e o alvo precisa estar acessível.

6. Candidatos não aprovados

Registrados para não serem redescobertos, e fora do catálogo até passarem a trava de custo.

7. Resumo

Mais três mudanças em arquétipo existente, todas consequência do que está acima:

1. channel perde a transformação e ganha capacidade com política de recusa
2. sink perde a transformação
3. buffer perde o agrupamento

Dezenove arquétipos para cobrir cinco aplicações reais parece pouco, e é o argumento central do projeto: uma aplicação é uma configuração desses objetos. Se o número crescer proporcionalmente ao catálogo de aplicações, a tese está errada e é melhor descobrir no segundo alvo do que no quinto.

8. O que ainda não está resolvido

• Contêiner é família própria? pipeline e composite não processam nada
• deliver é arquétipo ou política do canal? (§4)
• rate e scale são arquétipos ou variações? (§6)
• Regime de execução por composto. Nada aqui exige laço de realimentação, porque a plataforma saiu do escopo. Se voltar, volta com essa necessidade
• Portas tipadas. A §14 da spec do motor promete encaixe tipado. Com transform explícito, o tipo da porta passa a ser verificável de verdade — e o property test da §1.2 depende disso

9. Onda 4 — o que este catálogo ainda não cobre

Status: proposta, 2026-08-28. Escrita depois de conferir os arquétipos previstos contra os alvos declarados e contra a §6 da DECISIONS.md (“ver o mesmo dado atravessar os quatro níveis, até o frame e o byte”). Cada entrada paga em dois alvos, pela mesma trava da §3.

O padrão do que falta: os previstos cobrem bem 1→1 e N→1, e quase não cobrem identidade que se divide e se remonta. o leque replica (as cópias são independentes), batch agrupa (o lote é uma carga nova), merge funde (a identidade de origem se perde). Nenhum dos três descreve uma carga que vira pedaços e volta a ser ela mesma — que é literalmente o L2. Sem isso, o diferencial do projeto não tem arquétipo.

9.1 O par que falta: fragment e reassemble

Não é leque de porta (cópias independentes), não é batch (agrupa em carga nova), não é transform (1→1). É 1→N pedaços que continuam sendo a mesma carga, e depois N→1 de volta.

O par é indivisível: fragment sem reassemble ensina que cortar é grátis.

9.2 mux e demux — muitos fluxos lógicos num caminho físico

merge funde e perde a origem. Multiplexar preserva a identidade do fluxo para que o outro lado possa separar de novo. É a diferença entre juntar e entrelaçar, e é o coração do HTTP/2.

Sem mux, “abrir o canal e entender o gRPC” — o exemplo que motivou o projeto — não tem como ser desenhado com honestidade.

9.3 enrich — muda o conteúdo sem mudar a forma

O invariante da §1.2 diz que a forma da carga só muda saindo de um transform. Mas a maioria dos processadores reais não muda a forma: eles acrescentam campo. Tratar isso como transform faria o invariante mentir — o desenho mostraria a carga mudando de aparência onde ela não muda.

9.4 aggregate — N cargas viram uma medida, não um lote

batch agrupa N em uma carga de peso N: os itens continuam lá dentro. Agregar descarta os itens e guarda uma medida. A diferença é a coisa mais confusa de métrica, e o catálogo atual não tem como desenhá-la.

Delta contra cumulativa desenhadas lado a lado é, sozinho, um lab que vale o projeto.

9.5 correlate — casa duas cargas por chave

merge junta sem casar. Correlacionar espera o par e expira se ele não vier. É o que falta para amostragem por cauda, e a §5 já precisou disso à mão dentro do probe.

Repare que isto reescreve o probe da §5: ele deixa de correlacionar à mão e vira clock + emissor + correlate. Um arquétipo que simplifica outro é o melhor sinal de que faltava mesmo.

9.6 partition — a mesma chave sempre na mesma saída

router escolhe porta por política, e nada o obriga a ser estável. Particionar promete estabilidade por chave, e é dela que vem a garantia de ordem. Sem isso não dá para ensinar por que Kafka ordena dentro da partição e não entre partições.

9.7 Resumo revisado

9.8 O que muda nas ondas anteriores

1. probe encolhe: passa a ser composição de clock + emissor + correlate (§9.5).
2. enrich sai de dentro de transform, e o invariante da §1.2 fica verdadeiro em vez de quase verdadeiro: forma muda só no transform, conteúdo muda também no enrich.
3. A onda 1 ganha prioridade nova. aggregate paga na Entrega 4 inteira (Meter Provider), que já está no roteiro — provavelmente deveria subir para a onda 1.

9.9 Continua fora, e por quê