Compatibilidade: o que uma versão promete
Uma atualização do Aggrega pode alterar várias superfícies sobre as quais você constrói: os esquemas com base nos quais seus documentos são escritos, os comandos e opções que seus scripts chamam, as ferramentas que um assistente de IA chama, os códigos de erro que você registra e os kits de plugin com os quais um plugin é construído. Esta página informa, para cada uma delas, o que uma versão pode alterar e o que não altera. Uma superfície que esta página não menciona não traz nenhuma promessa além do que sua própria página de referência afirma. A última seção indica onde uma versão informa que uma delas mudou. As promessas desta página valem a partir da versão 0.9.0. As Releases anteriores à versão 0.9.0 não têm suporte: o registro do hub, hub.aggrega.ai, não disponibiliza nenhuma versão de Plugin feita para elas, e os compiladores delas não conseguem ler o catálogo desse registro, cujos documentos declaram aggrega.ai/v1beta1.
O Aggrega é lançado em versões 0.x.y: uma versão de patch incrementa o último número, uma versão secundária, o do meio. A própria metadata.version de uma entidade de catálogo é uma questão à parte — seu autor a escolhe, segundo os critérios de incremento de versão que aggrega lint --pre-publish verifica, e Resolução de versões descreve como uma referência seleciona uma delas.
Esquemas
Todo esquema que o Aggrega publica pertence a uma versão de API, aggrega.ai/v1beta1 — o valor que um documento de entidade declara em seu apiVersion. A regra abaixo abrange cada um deles: os tipos de entidade, os payloads dos plugins e os esquemas do espaço de trabalho e os demais — a IR, a configuração do espaço de trabalho, os arquivos de bloqueio e o resto —, todos listados na Referência de esquemas. A versão de API é separada do número da versão: muitas versões leem a mesma versão de API.
O que pode mudar dentro de v1beta1
Dentro de uma versão de API, um esquema muda apenas de forma aditiva, como o Kubernetes muda suas próprias versões de API. Uma versão pode:
- alterar uma descrição;
- adicionar um campo, quando o campo é opcional.
Todo documento que era válido antes de tal alteração continua válido depois dela e significa a mesma coisa. Um programa que lê um documento escrito pelo compilador, como a IR ou um arquivo de bloqueio, precisa aceitar um campo que não conhece, porque um campo opcional adicionado pode aparecer nessa saída dentro de v1beta1.
O que exige v1beta2
Cada uma destas alterações exige uma nova versão de API, aggrega.ai/v1beta2:
- remover ou renomear um campo;
- tornar um campo obrigatório;
- restringir um tipo, ou o conjunto de valores que um campo aceita;
- alterar o que um valor significa.
Uma nova versão de API é uma alteração incompatível, agendada e anunciada como tal na versão que a introduz.
Um novo campo opcional chega a um catálogo junto com o compilador que o conhece
O compilador recusa um campo que seu esquema não declara. Esse rigor é o que detecta uma chave digitada errada, e tem uma consequência que um leitor não adivinharia: uma entidade de catálogo só pode começar a usar um campo opcional recém-adicionado em uma versão que traga um compilador que conheça esse campo.
Por exemplo, suponha que uma versão adicione um campo opcional ao esquema do Component — chame-o de spec.newField:
- Todo Component escrito antes dessa versão continua válido; nenhum deles define o campo.
- Um autor de catálogo publica uma nova versão de um Component que define
spec.newField. - Um compilador dessa versão, ou de uma posterior, valida e constrói o Component.
- Um compilador de uma versão anterior o recusa, porque seu próprio esquema não declara o campo: a validação relata
spec.newField: unexpected propertye indica a linha.
Portanto, quem constrói com base nessa versão do catálogo atualiza primeiro para a versão que adicionou o campo, e um catálogo só publica uma entidade que usa o campo depois que essa versão é lançada. Como uma Release travada mantém as versões que resolveu está descrito em Resolução de versões.
A linha de comando e as ferramentas do assistente
Scripts, pipelines de CI e configurações de assistente chamam comandos aggrega, opções e ferramentas do assistente pelo nome. Nas versões 0.x:
- Uma versão de patch nunca remove nem renomeia um comando, uma opção ou uma ferramenta do assistente.
- Uma versão secundária pode remover ou renomear um deles, e seu registro de alterações informa isso em Removed ou Changed.
- Adições — um novo comando, opção ou ferramenta — podem vir em qualquer versão.
As ferramentas do assistente são as ferramentas que aggrega mcp oferece a um assistente conectado. A própria resposta do servidor é a lista completa delas, e O que seu assistente pode fazer com o Aggrega explica como solicitá-la. Uma ferramenta que executa um comando recebe o nome a partir do caminho de invocação do comando, portanto renomear um comando renomeia sua ferramenta. A Visão geral da CLI lista todos os comandos.
Códigos de erro
Toda condição de interrupção traz um código curto — a letra E e quatro dígitos, como em [DEVELOPER_ERROR E0007] — impresso no início do seu diagnóstico. Os códigos curtos são um contrato público: um código é atribuído uma única vez, nunca é renumerado e nunca é dado a uma condição diferente. O código de uma condição desativada permanece desativado, de modo que um código registrado em um runbook, uma regra de CI ou uma issue identifica a mesma condição após cada atualização.
Sentinelas de erro explica os identificadores que uma condição carrega — o código curto que uma pessoa cita, o código descritivo que um programa registra e o acessor Go com o qual um programa faz a correspondência —, o que cada um promete e como se impede que um número desativado seja atribuído novamente. A sua tabela de todas as condições resolve cada código curto, incluindo os desativados, e aggrega explain resolve um deles no terminal.
Kits de Plugin
Os kits de desenvolvimento de plugins — github.com/aggrega-ai/aggrega-pdk/go, aggrega-pdk-rust e @aggrega-ai/aggrega-pdk-typescript — e os codecs aggrega-abi que eles reexportam seguem o versionamento semântico a partir de 0.9.0. As três linguagens dos kits compartilham um número de versão, e as três linguagens dos codecs compartilham outro.
- Um plugin construído com base em uma versão continua sendo construído com base em todas as versões posteriores da mesma linha. Dentro de
0.9.x, uma versão pode adicionar funções, tipos e constantes exportados, e nunca remove nem altera nenhum deles. - Uma alteração incompatível em uma API exportada só é lançada em uma nova versão secundária (de
0.9.xpara0.10.0), e uma versão de patch nunca quebra a compatibilidade. Os kits e os codecs passam para1.0.0junto com a própria1.0.0do Aggrega, depois do que uma alteração incompatível incrementa o número principal. - Uma alteração incompatível nos codecs é uma alteração incompatível nos kits, que incrementam com ela sua própria versão secundária, porque reexportam os tipos dos codecs.
- Se um campo ou membro adicionado a um tipo existente conta como uma adição depende da linguagem. O README de cada kit, publicado com o pacote, descreve o caso de sua linguagem em “Compatibility”.
Essa promessa abrange a API que o código-fonte de um plugin nomeia. O que trafega entre o compilador e um plugin em execução é regido, em vez disso, pela versão de ABI dos plugins: dentro de uma versão de ABI, um socket ganha apenas descrições e campos opcionais, de modo que um plugin construído com base nela continua sendo carregado. O contrato de plugins descreve os sockets, e o guia do desenvolvedor de plugins, o fluxo de trabalho em torno deles.
O que o registro de alterações de uma versão informa
As notas de cada versão, na página de versões, trazem seu registro de alterações, agrupado sob títulos como Added, Changed, Removed e Fixed. Para as superfícies desta página:
- Um comando, uma opção ou uma ferramenta do assistente removidos ou renomeados são listados em Removed ou Changed, na versão secundária que faz a alteração.
- Uma nova versão de API de esquema é anunciada como alteração incompatível na versão que a introduz.
- Uma alteração incompatível nos kits de plugin ou nos codecs aparece no número de versão deles: é uma nova versão secundária abaixo de
1.0.0. - Um código de erro nunca muda de significado, portanto nenhuma versão tem um a anunciar.