Agno publicou a v3.0.3 em 30 de agosto às 20:45:21 UTC, introduzindo um conjunto de ferramentas de gestão do conhecimento. Publicou a v3.0.4 às 22:40:41 UTC — uma hora e cinquenta e cinco minutos depois — e usou esse release de patch para reescrever a interface pública do conjunto de ferramentas.
O que mudou em um patch
Três coisas que não pertencem a uma versão de patch. O caminho do módulo foi movido, sem deixar nenhuma camada de compatibilidade. Os quatro flags do construtor foram renomeados. E o tratamento do construtor para argumentos nomeados desconhecidos significa que os nomes antigos não são rejeitados — eles são silenciosamente ignorados.
Por que o silêncio é pior que o erro
Esse último detalhe é o que importa. Se a renomeação de um flag gera erro, toda implantação afetada falha de forma explícita na inicialização e alguém corrige o problema em minutos. Se o nome antigo é descartado sem aviso, o construtor recorre ao seu próprio padrão — e um operador que definiu um flag especificamente para desativar uma capacidade passa a ter essa capacidade ativada após a atualização, sem erro, sem aviso e sem linha no log. A atualização parece ter sido bem-sucedida. A configuração que ela carregava não sobrevive a ela.
O bullet de bug que é uma correção de segurança
O mesmo release corrige um bug de padrão que vinha removendo a etapa de confirmação da única ferramenta do conjunto capaz de destruir conteúdo armazenado. Trata-se de uma correção relevante para a segurança. Nas notas, ela aparece como um bullet comum de bug, ao lado de itens cosméticos, sem nada que a marque como o motivo para um operador querer atualizar com urgência.
O que a leitura comum erra
O versionamento semântico é amplamente lido como um contrato: um aumento de patch significa que é seguro aplicar. Aqui, o dígito de patch cobre a movimentação de um módulo sem camada de compatibilidade, quatro flags renomeados e uma mudança no padrão efetivo — a definição de uma mudança incompatível. E o projeto conhecia o princípio: um release anterior no mesmo dia defendia rejeitar argumentos nomeados silenciosamente ignorados, em vez de simplesmente engoli-los. A posição foi afirmada e, horas depois, não foi aplicada à própria renomeação.
Como fazer a atualização
Não trate a passagem de 3.0.3 para 3.0.4 como uma atualização rotineira. Procure pelos nomes antigos dos flags e pelo caminho antigo do módulo antes de atualizar, porque nem o instalador nem o runtime vão informar que eles deixaram de significar alguma coisa.