~/studies/work 2026-11-17 · published 2026-11-21

APIs de canal: o que uma matriz de 29 produtos não decidiu

Um estudo de APIs de canal de chat para pessoas e agentes: 62 características em 29 produtos, três spikes que foram só type checks, e um resultado que não separou nosso próprio vocabulário do Matrix. Com os níveis de prova.

A pergunta

Dois estudos ligados, 2026-11-16 e 2026-11-17. O primeiro perguntou o que um canal deveria ser em um engine de agentes para que a mesma tela funcione com pessoas e vários agentes dentro. O segundo perguntou qual modelo de recursos e quais semânticas a API de canal deveria expor sobre o wire existente do engine.

Ponto de partida, observado no código: uma tela de canal funcionava contra um runtime anterior, o novo engine só servia a ela uma mensagem direta por agente, e o núcleo do engine não tinha conceito de canal.

Quanta evidência, e de que tipo

O registro guarda quatro níveis de prova por célula: read (código ou pacote de tipos), specified (uma descrição de API publicada), run e hypothesis. Após a rodada 5 do segundo estudo, derivado por um script em 2026-11-17:

ItemQuantidade
Produtos29 (15 diretos, 14 indiretos)
Características62, das quais 27 marcadas como decisivas
Células de características1,308
Células em read / specified / run / hypothesis316 / 929 / 0 / 63
Matriz de vocabulário de API9 candidatos, 15 eixos, 135 células

Zero células em run é a manchete honesta. Os três spikes (57 cenários sobre 5 vocabulários, com type checks e 58 testes verdes) rodaram apenas como type checks da própria transcrição do estudo de cada wire de fornecedor, em um modelo em processo. Não tocaram nenhum servidor de fornecedor, nenhum SDK de fornecedor nem o nosso engine.

O erro de auditoria terminou em 0,065 contra uma meta abaixo de 5 por cento, então esse critério não foi atingido. Cada célula de mercado tem uma fonte, e a demanda de integradores é, nas palavras do registro, uma hipótese.

O resultado

Observado: a matriz e os spikes não separam nosso próprio vocabulário do do Matrix, e o do Discord pontua quatro pontos pior. É uma afirmação sobre esta pontuação, que não validei de forma independente.

O owner decidiu em 2026-11-17: um modelo de recursos próprio sobre o wire existente, com nomes emprestados de arquivos de especificação de fornecedores (Matrix, Discord, Zulip), e um feed por pessoa de dicas de mudança sem id e sem replay, construído depois do channel log. Projetado, não construído.

O primeiro estudo havia recomendado uma room com timeline e uma conversa filha por agente e por thread, em quatro fases. O segundo estudo descobriu que os caminhos baseados em room e o caminho de acesso não se sustentavam e recomendou um novo channel log com a mesma mecânica.

Perguntas ainda abertas

  • Editar, apagar e eliminar definitivamente em um log append-only. Recomendação: edições e exclusões são eventos, apagar oculta, e a eliminação definitiva precisa de um erase em nível de evento que chegue junto com o channel log.
  • Permissões no estilo Discord. Recomendação: não publicar nenhum objeto de permissão até que um único authorizer o aplique, e então começar com tuplas só-allow sobre um recurso de canal.
  • Onde vive o timeline de um canal: um novo channel log acessado por um tipo de recurso de canal no único authorizer.
  • Se a sessão de um agente é por thread (recomendado) ou por canal, e quem responde a uma mensagem que não nomeia nenhum agente: o agente da thread, senão o agente de resposta automática da room, senão ninguém.

As quatro são recomendações aguardando decisão, não decisões.

O que eu levaria adiante

Uma matriz larga é barata de preencher e cara de confiar. A parte útil foi a separação por nível de prova: ela tornou visível que 929 de 1,308 células se apoiavam na descrição publicada de uma interface, não em rodar algo. Uma decisão entre dois vocabulários que pontuam a poucos pontos de distância é uma decisão sobre o encaixe com o seu próprio wire, e a matriz não consegue tomá-la.

Hipótese, minha: um spike executável contra um servidor real de um fornecedor teria valido mais que a segunda metade da matriz. Não testei isso.