O Sábado em Que o Build Parou de Discutir

As correções que não rendem uma captura de tela são as que decidem se o seu runtime vai para produção. A RakuAI passou uma semana eliminando os pontos fracos para que os próximos oito meses de construção nunca mais discutam com o build.

Existe uma categoria de trabalho que não produz uma captura de tela. Ela produz um build que fica verde em máquinas que costumavam deixá-lo vermelho. Ela produz uma execução de CI que para de estourar o tempo. Ela produz um stack trace que não se materializa mais porque o ponteiro nulo que o causava agora é capturado na fronteira. A semana que terminou neste sábado foi desse tipo.

Dezoito DLLs verdes no Linux

O runtime é entregue como dezoito DLLs nativas. Até duas semanas atrás, essas DLLs compilavam de forma limpa no Windows e compilavam de forma limpa no macOS e quebravam no Linux com um erro de visibilidade de símbolo. A correção chegou no PR #1463 em 11 de abril.

A história é do tipo nada glamoroso. O GCC, por padrão, torna todo símbolo visível em bibliotecas compartilhadas. O MSVC, por padrão, torna todo símbolo oculto a menos que seja exportado. O código do runtime foi escrito assumindo o padrão do MSVC, com __declspec(dllexport) nos símbolos que precisavam cruzar a fronteira da DLL. No Linux, essas declarações são no-ops, o que significa que todo símbolo ficava visível, o que significa que o linker não conseguia descobrir as vinculações intra-DLL corretas, o que significa que várias das dezoito DLLs não compilavam.

A correção é -fvisibility=hidden como flag do compilador para os builds GCC, com atributos explícitos de visibilidade nos símbolos que precisam ser exportados. O diff é pequeno. O raio de impacto é grande. O build Linux agora é um alvo de primeira classe. O agente que entrega uma mudança no runtime agora pode tê-la testada no Linux automaticamente pela matriz de CI. Implantações em servidor, imagens de contêiner, fazendas de build em nuvem, tudo isso agora está ao alcance.

Esse é o tipo de correção que parece uma dedução fiscal. Não move o produto para frente. Também não o bloqueia mais. Isso já basta.

Proteções de comprimento de prompt em todo chamador de LLM

O outro commit de abril que vale a pena registrar é a varredura de proteção de comprimento de prompt. O runtime agora invoca o Claude em vários lugares: o cérebro de comportamento de NPC, o modelo de diálogo, o narrador de eventos do mundo, o semeador de conteúdo procedural. Cada um desses chamadores constrói um prompt concatenando contexto, instruções e o estado atual. Cada um desses chamadores pode produzir um prompt que excede a janela de entrada do modelo se o contexto crescer o suficiente.

O modo de falha ingênuo é que a chamada de LLM retorna um erro. O modo de falha perigoso é que a chamada de LLM retorna uma resposta truncada, o chamador não detecta o truncamento, e o engine age sobre uma resposta malformada. NPCs que param no meio de uma frase. Árvores de diálogo que bifurcam para o nada. Eventos de mundo que disparam com os parâmetros errados.

O PR #1465 adicionou uma proteção a todo chamador de LLM: estimar a contagem de tokens antes da chamada, recusar o envio se a contagem exceder o orçamento, e emitir um erro estruturado com o qual o chamador pode reagir. O PR #1466 auditou toda a base de código para verificar que a proteção está presente em todo ponto de chamada. O PR #1467 adicionou documentação para que o próximo chamador conheça a disciplina.

O motivo pelo qual isso importa é que chamadas de IA dentro de um runtime não são ocasionais. Acontecem muitas vezes por frame no pico. Um bug na construção do prompt que cresce um prompt em alguns tokens por chamada é invisível por cem frames e catastrófico em mil. A proteção torna a falha alta e limitada em vez de silenciosa e ilimitada.

Estabilização do namespace da API

O terceiro commit é o mais silencioso dos três e possivelmente o mais consequente. O runtime expõe uma API REST para ferramentas externas, painéis e o SDK conversarem. Essa API viveu sob /api/v2/ nos últimos seis meses porque sucedeu uma /api/v1/ anterior que era apenas interna.

/api/v2/ é o nome errado. Ele implica que a v1 era pública e foi substituída, o que não é o caso. Também implica que uma v3 está a caminho, o que não é o caso. O PR #1464 percorreu toda referência na base de código e toda referência na documentação e renomeou o namespace de /api/v2/ para /api/raku/. O nome agora é estável. Não há número de versão para negociar depois. Compatibilidade retroativa dentro do namespace é o contrato.

Esse é o tipo de renomeação que precisa acontecer exatamente uma vez e precisa acontecer antes que qualquer desenvolvedor externo escreva código contra o namespace. Pegamos a tempo. Na próxima vez que alguém fora da equipe escrever um script que acesse a API, verá /api/raku/ e não terá que refazer o trabalho em seis meses.

Segurança contra ponteiro nulo como varredura

O commit mais recente no runtime, há dois dias em 30 de abril, é 58c3a806: “fix(build): resolve all build errors, warnings, and null-pointer safety.” A frase “null-pointer safety” carrega bastante peso nesse título. A mudança por trás dela é uma varredura pela base de código em busca de todo lugar onde um ponteiro poderia ser nulo e estava sendo desreferenciado sem verificação.

O padrão que disparou a varredura foi um relatório de crash de uma das aplicações de exemplo. Um carregador de textura recebia um ponteiro nulo para o manifesto de ativos, o desreferenciava, e travava. A correção foi uma verificação no ponto de entrada. A auditoria foi a pergunta: quantos outros lugares na base de código têm o mesmo padrão.

A resposta foi várias dezenas. Nem todos eram exploráveis. Muitos eram caminhos de código que nunca tinham sido acionados porque o código chamador, por acaso, nunca passava um nulo. Isso não é uma defesa. A defesa é a verificação na fronteira.

A varredura adicionou as verificações. Não mudou o comportamento no caminho feliz. Adicionou um valor de retorno (RAKU_ERR_INVALID_PARAM) e uma linha de log para o caminho de falha. O runtime agora é mais barulhento nos casos que antes eram crashes silenciosos. Barulhento é melhor que silencioso. Crashes silenciosos em um runtime de AR são o pior tipo de bug.

Por que esse tipo de semana é o tipo certo de se ter

A tentação, quando você está tocando um projeto de engine em cadência de fim de semana com uma frota de agentes, é continuar entregando novas funcionalidades. Toda manhã de sábado a fila se reabastece. Todo sábado à noite o diff é maior do que era na semana anterior. A cadência recompensa o movimento para frente.

A cadência também tolera dívida técnica. Todo PR que foi mesclado ao longo dos últimos oito meses fez uma pequena suposição sobre o ambiente de build, a superfície da API, a janela de entrada do LLM, ou o contrato de segurança contra nulo. Nenhuma dessas suposições estava errada por si só. Juntas, eram uma lista de pontos fracos que, eventualmente, racharia.

Uma semana parando o movimento para frente para corrigir os pontos fracos não é tempo perdido. É a semana depois da qual os próximos oito meses de movimento para frente podem acontecer sem discutir com o build, com a API, com a entrada do LLM, ou com o ponteiro nulo. A discussão é o que desperdiça o tempo. A discussão é o que a limpeza encerrou.

O que vem a seguir

Os agentes estão de volta à fila neste fim de semana. A próxima rodada de issues é a que estou registrando nesta manhã de sábado. Não são mais issues de limpeza. São issues de funcionalidade. O build não vai discutir com elas.

Isso é o que um build limpo compra para você. Não uma captura de tela. Permissão para entregar.