Status da linguagem
Esta página é a referência canônica sobre quais superfícies do Aggrega podem ser usadas hoje, quais estão documentadas mas ainda não são tratadas pelo compilador e quais estão planejadas para uma iteração futura. Ela complementa os capítulos por domínio ao reunir em um só lugar o estado de maturidade de toda a linguagem.
Dois grupos de leitores consultam esta página. Autores iniciantes verificam a página antes de escrever para uma superfície que não conhecem, para confirmar que a superfície produz hoje uma saída renderizada. Quem busca referência verifica a página quando uma superfície que está usando se comporta de forma inesperada — por exemplo, quando o YAML passa na validação, mas nenhuma saída é produzida, a página é o primeiro lugar onde consultar o status da superfície. Leitores que retornam também consultam a página para identificar superfícies que mudaram de rótulo de status desde a última leitura. Os capítulos por domínio e as referências de entidades descrevem como a superfície deve funcionar; esta página descreve se ela já funciona.
Taxonomia de status
Cada superfície da linguagem nesta página tem um de quatro rótulos de status:
-
disponível. O esquema aceita a superfície; o compilador a consome; o comportamento corresponde ao contrato documentado. Autores que usam uma superfície
availablerecebem o contrato documentado. -
aceita mas inerte. O esquema aceita a superfície — escrever para ela passa na validação —, mas o compilador ainda não a trata. Escrever uma superfície
accepted but inertproduz um build sintaticamente válido sem nenhum efeito renderizado para essa superfície; o compilador pode emitir um aviso que nomeia a superfície inerte (o padrão recomendado), ou algumas superfícies atuais são ignoradas silenciosamente, sem aviso. As entradas por seção abaixo indicam o comportamento específico. -
aceita mas bloqueada. O esquema aceita a superfície — escrever para ela passa na validação —, mas o compilador interrompe o build em vez de renderizá-la. Escrever para uma superfície
accepted but blockedfalha na renderização com um erro explícito que indica o que escrever em seu lugar. Um bloqueio pode ser permanente, quando o que foi escrito é uma ambiguidade que o compilador não resolverá por você, porque escolher uma interpretação por você poderia entregar algo que você não pediu; ou pode durar apenas até que o comportamento por trás da superfície seja lançado. O que o rótulo promete é o mesmo nos dois casos: o esquema a aceita, o build a recusa e o erro diz como corrigir. -
planejada. A superfície está documentada conforme projetada, mas nem o esquema nem o compilador a aceitam ainda. Escrever para uma superfície
plannedfalha na validação do esquema. A página mostra os itens planejados para que os autores possam se planejar considerando sua ausência, em vez de descobrir a lacuna no momento do build.
Os rótulos de status são avaliados em relação ao compilador atual. Superfícies em desenvolvimento ativo podem passar de um rótulo a outro; as entradas por seção descrevem o plano de transição quando ele é conhecido.
Tipos de entrada da Recipe
Uma Recipe compõe sua saída a partir de três tipos de entrada — de origem, sintetizado e artefatos — descritos em 16-recipe-input-composition.md. Status por tipo de entrada:
-
source:+valuesMapping:(de origem) — disponível. O compilador resolve o URIsource:, avalia o templatevaluesMapping(inline,$import:de arquivo ou$import:de biblioteca) e entrega o resultado ao provider de destino para renderização. Consumido pelos providers helm, helm-chart, compose, terraform e cloudformation. -
workload:(sintetizado) — disponível. A Recipe declaraworkload:inline (um escalar de bloco com o YAML do Workload) ou via$import:(caminho de arquivo). O compilador analisa o Workload com template, o valida em relação ao esquema Workload incorporado e o despacha para o sintetizador de workload do provider de destino. Consumido pelos providers helm e compose. O provider helm-chart redireciona explicitamente os autores para o provider helm para manifests K8s sintetizados. Uma Recipe que declaraworkload:para um provider que não implementa a síntese de workload é interrompida na renderização com umCATALOG_ERROR. -
artifacts:(artefatos) — disponível. O campo é um mapa de entradas nomeadas; cada entrada é escrita inline ou carregada via um$import:por entrada. As entradas são avaliadas depois que o Workload é analisado e a origem é resolvida, de modo que o contexto de templates completo — incluindo.workloade.source— está disponível para elas; elas recebem a procedência mesclada emmetadata.labelsemetadata.annotationsnos documentos que têm metadados (as chaves não seguras para o conjunto de caracteres — recipe-uri, boundary-path, sync-wave — como anotações, a mesma divisão que os providers helm aplicam), e são emitidas como arquivos separados ao lado da saída da Recipe renderizada a partir da origem ou sintetizada a partir do workload. Despacho por Provider — o provider helm plano emite arquivos independentes em um diretório com o nome do componente que os declarou, dentro do diretório de saída do boundary, porque a chave dá nome ao arquivo e não diz nada sobre qual componente o escreveu; o provider compose encaminha suas emissões pelo mesclador de fim de Release; o provider helm-chart avalia cada entrada com os delimitadores[[ ]]do Aggrega, para que a sintaxe{{ }}do Helm no mesmo arquivo sobreviva até a renderização posterior, e então posiciona cada entrada conforme a forma em que foi escrita — uma entrada carregada com$import:emboundaries/<bp>/charts/<nodeID>/templates/<authored-key>(os arquivos de um bundle aninhados sob essa chave), ao lado dos templates próprios do chart de origem, e uma entrada de conteúdo inline emboundaries/<bp>/charts/<nodeID>/<authored-key>, a raiz do chart, onde os templates próprios do chart a leem via.Files.Get/.Files.Glob; o provider terraform grava cada entrada sem alterações no diretório próprio do componente sob a árvoremodules/do boundary; o provider cloudformation mescla cada entrada, um fragmento de stack, no único stack montado para esse diretório de saída. Colisões de nomes de arquivo entre origens de tipos de entrada (saída renderizada a partir da origem, sintetizada a partir do workload ou emitida como artefato) são detectadas no momento da renderização pelo detector de colisões entre origens e produzem um CATALOG_ERROR que nomeia cada contribuinte.
Consulte entities/recipe.md para a superfície de autoria da Recipe e as regras de composição de tipos de entrada; errors/fatal-halts.md para as regras de forma da Recipe; e a seção Providers abaixo para a matriz por provider.
Linguagens de mapeamento
As Recipes (e as FeatureRecipes) se vinculam a um único campo de mapeamento para traduzir o contexto do Aggrega no dicionário de valores que o provider subjacente consome. O campo valuesMapping: aceita três modos de autoria, escolhidos conforme a forma do conteúdo:
valuesMapping:— Modos 1-3 disponíveis. Modo 1: template Go inline (escalar de bloco). Modo 2:$import:de arquivo (um mapa que contém apenas$import:com um caminho de arquivo local). Modo 3:$import:de biblioteca (um mapa que contém apenas$import:com uma referência de identidade por nome simples a uma entrada de uma MappingLibrary,<Library>#/mappings/<entry>, opcionalmente com um piso:<version>). O compilador escolhe conforme a forma do conteúdo — escalar de bloco para o Modo 1,$import:com um caminho de arquivo para o Modo 2,$import:com uma referência de biblioteca por nome simples para o Modo 3. Os três avaliam o template Go resolvido em relação ao contexto de templates da Recipe durante o mapeamento de valores (a biblioteca de helpers Sprig é pré-registrada); o Modo 3 resolve a entrada em relação ao catálogo local mais quaisquer bibliotecas fixadas no lockfile, e uma referência que contém um host é rejeitada. Consulteentities/recipe.md“O campovaluesMapping— três modos de autoria” para o mecanismo de despacho e exemplos completos.
Consulte entities/recipe.md para a superfície de autoria da Recipe e o design da linguagem de mapeamento, e entities/mappinglibrary.md para a entidade de biblioteca em que o Modo 3 se baseia.
Sintaxe de inject
O bloco inject: tem uma única sintaxe em toda posição — o inject próprio de um componente, o de uma conexão uses e o de um anexo.
-
Uma lista de entradas por mecanismo (
[{in: ..., from: ...}],[{in: ..., value: ...}]) — disponível. Cada mecanismo de entrega é uma lista; cada entrada nomeia seu identificador local (nome da variável de ambiente, caminho de arquivo, flag de argumento) comin:e carrega exatamente um entrefrom:(referência a uma chave de provides) evalue:(string literal). Um mecanismo escrito como mapa em vez de lista, ou uma entrada que carrega as duas palavras-chave, interrompe o build no envelope do documento do Aggregate, nomeando o caminho. -
value:apenas noinjectpróprio de um componente. Um literal pertence aoinjectpróprio do componente, que o entrega. Em uma conexãouses, umvalue:interrompe o build, como descreve Aninject:entry on a connection carries a literal (Uma entrada em uma conexão carrega um literal), e noinjectpróprio de um anexo ele também interrompe o build, como descreve Aninject:entry on an attached Feature carries a literal (Uma entrada em uma Feature anexada carrega um literal): ambos entregam apenas chaves que outra entidade publica, nomeadas comfrom:.
Consulte vocabulary/topology-triad.md para a especificação completa do Injection Contract, incluindo a semântica do contexto de estado duplo, as regras de colisão de chaves e exemplos completos.
Mecanismo de templates
O mecanismo de templates Go do Aggrega avalia os templates de Recipe e FeatureRecipe em relação ao contexto de templates na fase por local que a Matriz de expansão de templates documenta. A biblioteca de helpers Sprig é pré-registrada junto com os helpers próprios do Aggrega em toda superfície que o renderizador avalia, com uma exceção: resolver uma coordenada source: estruturada registra apenas os helpers do Aggrega — optional e capitalizedWords estão disponíveis ali e as funções do Sprig não, de modo que uma chamada ao Sprig em um campo source:, ou em uma entrada locals: de uma entidade que tem um source: estruturado, é interrompida na análise. Consulte errors/fatal-halts.md, que dedica a essa superfície uma seção própria. Avaliação, análise e integração com o Sprig estão disponíveis hoje.
Comportamento com chaves ausentes — tolerado em templates de valor; missingkey=error estrito em templates de caminho, em asserções e em uma coordenada source:. Os templates de valor são avaliados com a opção missingkey=zero do Go, de modo que um template que referencia uma chave não vinculada (por exemplo, .values.unset_field) não gera erro e a leitura não renderiza nada. Idiomas de catálogo como {{ .values.optional_field | default "fallback" }} continuam funcionando sob essa política, porque um valor não definido conta como vazio para default. Os templates de caminho (directory: / subDirectory: nos boundaries da Release) são avaliados com missingkey=error em relação a uma allowlist fechada — falhas silenciosas de caminho produzem layouts de sistema de arquivos quebrados que os operadores só descobrem depois do build, e o rigor detecta o erro mais cedo. Duas outras superfícies seguem a mesma política estrita, pelo mesmo motivo: ali uma renderização vazia produziria um veredito errado ou um pin errado em vez de um campo que o autor possa reler. Trata-se de uma entrada assertions: em um Component, uma Feature, uma Recipe ou uma FeatureRecipe, e dos campos com template de um bloco source: estruturado em uma Recipe ou uma FeatureRecipe. errors/fatal-halts.md apresenta a política de cada superfície, uma a uma, e fornece as formas sensíveis à presença que funcionam sob a política estrita.
Fallback sensível à presença via optional. Quando um autor de Recipe precisa distinguir “chave ausente” de “chave presente com valor zero / vazio / false” — a distinção que o default do Sprig não consegue fazer —, o renderizador expõe o helper optional: {{ optional .infra "replicas" 1 }} retorna o infra.replicas escrito (incluindo um 0 escrito) quando presente, e recorre a 1 apenas quando a chave está ausente. Consulte templates/sprig-functions.md para a semântica completa.
Composição de nomes via capitalizedWords. Onde um destino aceita apenas letras e dígitos nos nomes com que endereça recursos, {{ capitalizedWords .context.instance_id }} lê o id como palavras separadas por qualquer caractere fora desse alfabeto e coloca em maiúscula a primeira letra de cada palavra, de modo que payments-db resulta em PaymentsDb. A transformação remove todos os separadores, então dois ids que diferem apenas na pontuação chegam ao mesmo nome; um build que emitiria dois recursos com um mesmo nome é interrompido e nomeia os dois ids. Consulte templates/sprig-functions.md para a semântica completa.
Aplicação do contrato de parâmetros na camada de declaração. Parâmetros obrigatórios que a Release não fornece produzem erros explícitos na camada do contrato de parâmetros, a primeira coisa que a resolução verifica, com uma procedência file:line que nomeia o parâmetro e o contrato. Violações de tipo / restrição aparecem da mesma forma. Essa é a aplicação substancial de chaves ausentes: a tipagem é verificada onde reside a intenção do desenvolvedor (a declaração parameters: do Aggregate), e não no momento da avaliação dos templates posteriores. Consulte entities/aggregate.md §“Contratos de parâmetros tipados”.
Uma única gramática de declaração para os parameters: do Aggregate. Cada slot de parâmetro é escrito como um objeto de contrato tipado (key: { type: <type>, default: <value>, ... }). A forma abreviada de escalar simples (key: <value>) é rejeitada no envelope do documento do Aggregate, com um erro que nomeia o parâmetro e diz que era esperado um objeto. O vocabulário do contrato tipado torna explícita a semântica de type:, required: e das restrições na camada de declaração; o preenchimento pela Release continua usando valores escalares conforme o tipo declarado no contrato.
Consulte templates/expansion-matrix.md para a matriz de avaliação por local de template e 05-templates.md para a visão geral de templates.
Fases do pipeline de compilação
O pipeline de compilação do Aggrega está documentado em ../architecture/10-compilation-pipeline.md. Status por fase:
- Resolução, construção da topologia, finalização do grafo, análise estática e renderização — disponíveis.
- Inject mapping (interceptação antes da renderização
injectMapping) e todas as subetapas da renderização base — publicação de locals, mapeamento de valores, síntese de workload, avaliação de artefatos, renderização do provider, renderização de features e geração de recursos da FeatureRecipe de credenciais — disponíveis. - O pipeline de plugins (execução Wasm de
pipeline:) — disponível. Em uma Recipe ou FeatureRecipe que declara etapaspipeline:não vazias, cada etapa é executada na ordem declarada: o compilador despacha o plugin Wasm nomeado pela etapa sobre a saída renderizada, aplica as operações JSON Patch retornadas aos documentos endereçados e emite os efeitos colaterais da etapa. Uma etapa cuja condiçãowhen:é renderizada como falsa é ignorada como passagem direta, deixando o conjunto de documentos inalterado. Autores que buscam mutações no estilo JSONPatch (injeção de sidecar do Envoy, VolumeMount de secret etc.) as obtêm por meio desta superfície.
Providers
A biblioteca padrão do Aggrega inclui cinco providers de renderização — helm, helm-chart, compose, terraform e cloudformation. Status por provider:
helm— disponível. Tanto o modo de origem (renderização de charts Helm via SDK do Helm) quanto o modo sintetizado (Workload → um objeto controlador escolhido peloformdo Workload — Deployment, StatefulSet, DaemonSet, Job ou CronJob — mais Services e PVCs) estão disponíveis.helm-chart— disponível. O modo de origem (composição com umbrella chart) está disponível. O tipo de entrada sintetizado não se aplica a este provider; autores que precisam de síntese de manifests K8s usam o providerhelmcomworkload:.compose— disponível. Tanto o modo de origem (sobreposição de fragmentos compose) quanto o modo sintetizado (Workload → serviço compose + volumes + redes) estão disponíveis. A saídadocker-compose.yamlpor boundary é montada pelo compositor no nível da Release.terraform— disponível. Tanto o modo de origem quanto os artefatos estão disponíveis; cada boundary recebe uma configuração raiz,aggrega.modules.tf, que declara cada componente como um blocomodulecujos arquivos ficam em um diretório próprio sobmodules/. O tipo de entrada sintetizado não se aplica a este provider.cloudformation— disponível. Tanto o modo de origem quanto os artefatos (fragmentos de stack) estão disponíveis; todos os componentes renderizados em um mesmo diretório de saída são montados em um único template de stack, emitido como JSON puro. O tipo de entrada sintetizado não se aplica a este provider.
A renderização Provider é fornecida por um Plugin com pluginType: provider; consulte entities/plugin.md para a superfície de autoria do Plugin de renderização de providers e 06-providers.md para as páginas de referência por provider.
Expansão orientada por anotações
Os Manifests têm uma seção de vinculação features.annotations: que mapeia chaves de anotação para tipos de Feature, mais uma tabela de roteamento agrupada por pilar (maps.infra / maps.values) que indica quais propriedades do esquema da Feature cada vinculação pode preencher. Documentado em entities/manifest.md e providers/well-known-annotations.md; posicionamento no pipeline em ../architecture/10-compilation-pipeline.md; mecânica no carregamento do catálogo e no momento da inspeção em ../architecture/13-catalog-and-registry.md §“Expansão de Feature orientada por anotações”.
- Vinculações
features.annotationsdo Manifest — disponíveis. A subetapa de expansão de anotações da resolução está disponível de ponta a ponta. Ela percorre os boundaries da Release (de fora para dentro) e os subsistemas do Aggregate (de fora para dentro), calcula o conjunto efetivo de anotações por componente via cascata + substituição com exclusão por null do valor inteiro e por subchave, analisa cada valor de anotação como um escalar, um mapa estruturado ou umnullexplícito, encaminha por subchave pela declaraçãomapsda vinculação aplicando a restrição de lado versus pilar (o lado Aggregate acionamaps.values; o lado Release acionamaps.infra), valida os tipos de cada folha em relação aospec.schemada Feature de destino e injeta anexos de Feature sintéticos, que o grafo IR marca comorigin: annotation. A composição entre os lados mescla por pilar e por campo no momento da construção da IR, com o valor explícito prevalecendo campo a campo;aggrega inspectmostra a procedência entre colchetes para cada folha. A validação dos destinos de vinculação no carregamento do catálogo, o lint de sobreposição de pilares do esquema e o lint de sobreposição de mapas de vinculação protegem o caminho. O prefixo simplesaggrega.ai/é rejeitado no carregamento do Manifest quando usado como chave de vinculação — esse prefixo é reservado para anotações nativas da plataforma; as vinculações usamfeature.aggrega.ai/ou um domínio personalizado.
Correspondência de versões
As Recipes e as FeatureRecipes declaram a interface de Component ou de Feature que implementam por meio da palavra-chave implements:. implements: nunca seleciona uma Recipe: quem faz isso é o mapeamento do Manifest, e uma instância cujo tipo nenhum mapeamento cobre é interrompida com um erro que lista como candidatas as Recipes cujo implements: pode implementar esse tipo. O que implements: determina é a verificação de que a Recipe de cada entrada de mapeamento do Manifest implementa o tipo mapeado, ou uma base que esse tipo estende com extends. O tipo mapeado é a chave da entrada e, para uma chave components.type, também o tipo de cada instância de componente que a chave alcança em uma versão que a chave não nomeia — cada instância que ela alcança, para uma chave escrita sem versão — na versão com que o build compila essa instância: a versão que a instância nomeia ou, para uma instância que não nomeia nenhuma, a versão mais alta desse Component que o catálogo contém. Status por forma:
- Exata (
core/api-server:1.0.0) — disponível. O tipo mapeado precisa ser essa versão. - Intervalo compatível com a versão principal (
core/api-server:^1.0.0) — disponível. A forma com circunflexo é uma restrição SemVer (>=1.0.0, <2.0.0no exemplo); a versão do tipo mapeado precisa satisfazê-la. - Sem versão (
core/api-server) — disponível. Qualquer versão do tipo a satisfaz.
Uma entrada de mapeamento cujo implements: da Recipe não corresponde nem ao tipo mapeado nem a nenhuma das suas bases interrompe o build com um OPS_ERROR que nomeia a entrada, a Recipe e seu valor de implements:. Uma instância de componente que uma chave alcança em outra versão, cuja versão o implements: da Recipe não satisfaz, interrompe o build com o mesmo OPS_ERROR, nomeando a instância, seu tipo — e, para uma instância que não nomeia nenhuma versão, a versão com que foi compilada —, a chave, a Recipe e seu valor de implements:. A forma com circunflexo é a superfície de autoria canônica para a correspondência compatível com a versão principal.
Consulte vocabulary/inheritance-and-interface.md para a superfície de design de implements: e entities/manifest.md para a forma do nível de mapeamento por Manifest.
Envelope de metadados
Os envelopes das entidades de catálogo têm metadata.labels, metadata.annotations e (na Release) metadata.environment. Status por superfície:
Disponibilidade de metadata.labels e metadata.annotations — em sete tipos. Os envelopes de entidade que têm esses campos são Component (rótulos obrigatórios, com a chave obrigatória component.aggrega.ai/type, anotações opcionais), Feature (ambos opcionais), os quatro tipos de biblioteca SchemaLibrary, MappingLibrary, WorkloadLibrary e ArtifactLibrary (ambos opcionais) e Aggregate (apenas rótulos, opcionais). As entidades restantes — Recipe, FeatureRecipe, Manifest, Release, Plugin — não aceitam metadata.labels nem metadata.annotations no nível do envelope.
metadata.environment na Release — obrigatório. O esquema da Release lista environment como campo metadata obrigatório; o build carimba seu valor na saída renderizada como o rótulo aggrega.ai/environment. Consulte entities/release.md para os cinco casos de uso práticos da seção Environment Metadata (atribuição de custos OTel/FinOps, filtragem de traces/logs OTel, direcionamento de operadores Kubernetes, diferenciação de produção em várias regiões, delimitação do escopo de conformidade).
Consulte 02-naming-conventions.md para a disciplina de capitalização de campos que se aplica às chaves metadata, e as páginas de referência de cada entidade para as formas de envelope que cada entidade aceita hoje.
Comandos da CLI
A CLI do Aggrega registra o pipeline de build mais a introspecção. Status por comando:
aggrega build— disponível. Lê um arquivo de Release, resolve o Aggregate + o Manifest, executa o pipeline de compilação e grava os artefatos renderizados nos diretórios de saída dos boundaries. Quando há um lockfile, verifica as dependências em relação a ele; quando não há, é interrompido pedindo um pull, ou o preenche primeiro onde--auto-pullouauto_pullpede.aggrega inspect— disponível. Inspeciona uma entidade de catálogo, um arquivo de entidade, uma entidade publicada em um registry ou uma Release, e informa sua forma resolvida. Consultecli/aggrega-inspect.md.aggrega pull— disponível. Resolve todas as dependências de uma Release e grava um lockfile por Release que fixa cada entidade de catálogo e cada artefato de origem a uma versão e a um digest de conteúdo, e cada entrada externa solicitada pela renderização da Release a um digest de conteúdo; armazena em cache o conteúdo obtido em.aggrega/cache.--verifyverifica um lockfile existente em relação ao estado atual. Consultecli/aggrega-pull.md.aggrega push— disponível. Publica uma entidade de catálogo em um registry OCI;aggrega push --list-kindsinforma quais tipos ele aceita. Consultecli/aggrega-push.md.aggrega lint— disponível. Executa as regras de disciplina de publicação com severidadewarnem todo o catálogo, no fechamento de dependências de uma Release ou em uma única entidade; em uma única entidade,--pre-publishadiciona uma verificação do incremento de versão em relação à versão atualmente publicada da entidade, e uma divergência causa uma interrupção. As regras são distribuídas como um plugin Wasm opcional. Consultecli/aggrega-lint.md.aggrega serve— disponível. Um daemon de compilador como serviço de longa duração que fala JSON-RPC 2.0 por stdin/stdout, para integração com editores e IDEs. Consultecli/aggrega-serve.mdpara os métodos que ele oferece.aggrega version— disponível. Imprime a versão da CLI;-o jsonemite um objeto de versão legível por máquina.aggrega validate— disponível. Verifica a correção em todo o catálogo, em uma Release ou em uma única entidade, informando diagnósticos sem renderizar artefatos.aggrega search— disponível. Procura entidades publicadas no índice local dos registries configurados; o índice é criado e atualizado poraggrega registry update.aggrega registry— disponível. Gerencia os registries e sua política de confiança de assinaturas;registry addregistra um registry, eregistry updatecria o índice local queaggrega searchconsulta.aggrega push-artifact— disponível. Publica um artefato de dados independente (como um pacote de documentação) em um registry OCI, ao lado dopush, que publica entidades.aggrega sign— disponível. Assina um ou mais artefatos já publicados e anexa suas assinaturas.aggrega deprecate— disponível. Anexa um marcador de descontinuação assinado a um artefato já publicado.aggrega logineaggrega logout— disponíveis. Autenticam-se em um registry OCI e armazenam a credencial, ou removem uma credencial armazenada.aggrega auth— disponível. Gerencia a identidade de assinatura local usada para assinar artefatos.aggrega config— disponível. Inspeciona e gerencia a configuração do workspace; os subcomandos mostram a configuração efetiva mesclada e de onde veio cada ajuste, inicializam uma configuração funcional com um registry e sua política de confiança de assinaturas, e congelam no workspace a configuração efetiva crítica para o build, para que ele seja compilado de forma idêntica sem depender da configuração global da máquina.aggrega get-schema— disponível. Imprime o JSON Schema de um tipo de entidade ou de contrato.aggrega plugin— disponível. Inspeciona os plugins Wasm que a CLI consegue resolver; os subcomandos os listam, adicionam e removem plugins configurados, sincronizam os registros mantidos pela máquina de um plugin e geram uma visão de catálogo deles.aggrega cache— disponível. Inspeciona e mantém os caches em disco; os subcomandos informam o status, podam, removem entradas e limpam.aggrega mcp— disponível. Executa um servidor Model Context Protocol por stdio, ou por HTTPS para um cliente em outra máquina, expondo a introspecção do compilador para integrações com assistentes de IA.aggrega completion— disponível. Gera o script de autocompletar do shell para a CLI.- Subcomandos de extensão da CLI — disponíveis. Um plugin Wasm publicado como convidado
pluginType: clié resolvido e registrado como subcomando deaggrega, de modo que uma extensão instalada é executada comoaggrega <extension>junto com os comandos integrados. aggrega import— disponível. Transforma uma origem declarativa externa de definição de agentes (Langflow, Flowise, n8n) em rascunhos de arquivos de autoria de Aggregate e Component, com uma decisão determinística de reutilização do catálogo, pontuada por confiança, registrada para cada nó. O mapeamento específico do formato é fornecido por um plugin importador que o workspace resolve para o formato de origem — um que o seu catálogo contém, ou um dos importadores de Langflow, Flowise e n8n do compilador, que são compilados e publicados com cada release do compilador. O binário traz as entidades Plugin deles, mas não os seus módulos, de modo que eles atendem a seus formatos em todos os workspaces: o primeiro import que precisa de um que a máquina não tem o busca no registry padrão do workspace, o verifica e o mantém no cache de conteúdo para todos os imports seguintes. Uma origem é analisada pelo parser que o catálogo do workspace fornece para sua sintaxe ou, quando o catálogo não fornece nenhum, pelo que o compilador traz, de modo que um workspace cujo catálogo não contém nenhum parser importa por meio de um ou de outro.aggrega scaffold— disponível. Rascunha um documento inicial para qualquer tipo de entidade a partir do schema desse tipo — cada campo que ele exige, com um placeholder onde um valor é necessário — e o grava na saída padrão; com--example, grava em um novo diretório um dos exemplos executáveis da documentação, lido do pacote de documentação assinado.aggrega explain— disponível. Explica a condição de interrupção que um código curto (comoE0007) ou um código descritivo nomeia.aggrega edit-document— disponível. Aplica a um documento uma única edição estruturada e delimitada — adicionar um componente, anexar uma Feature, ligar uma conexão ou definir um valor — preservando cada byte que não toca.aggrega pin— disponível. Registra, noentity.lockao lado de uma Recipe ou FeatureRecipe, o pin de conteúdo de cada entrada que a entidade lê de fora do seu próprio documento.aggrega skills— disponível. Instala a skill do Aggrega em um assistente de IA.
Consulte 07-cli.md para a visão geral da CLI e o índice da referência da linguagem para todas as páginas de referência por comando.
Editores e outros frontends
Todo frontend mostra o que o binário aggrega compilou; nenhum traz um compilador próprio. Status por superfície:
- Contrato do grafo IR — disponível. O esquema do grafo IR, o contrato com base no qual todo frontend lê o grafo, é distribuído como parte da distribuição de esquemas do Aggrega; veja a referência do esquema IR.
- Ler o grafo a partir de um comando — disponível.
aggrega buildaceita--ir-graph, assim comoaggrega inspectquando recebe uma Release eaggrega validate --release; a flag grava no stdout, como JSON, o grafo resolvido por aquela execução, além do que o comando já produz. Uma sessão do daemon lê o mesmo grafo emaggrega/irGraph, e as ferramentascli-inspect,cli-buildecli-validatedo servidor MCP o recebem como seu argumentoir_graph. - Grafo da topologia no Visual Studio Code — disponível. A extensão do Aggrega para o Visual Studio Code desenha o grafo IR da Release selecionada como um grafo interativo e vincula Features a partir dele, pedindo ambos ao daemon
aggrega serve. - Modo de streaming headless da CLI — planejado. O modo headless emite o grafo IR como JSON delimitado por quebras de linha no stdout para que um frontend o consuma à medida que a topologia muda. O que está disponível hoje é um documento por invocação, e não um stream: nenhum comando emite uma sequência de grafos em um único stdout à medida que uma topologia muda.
Veja ../architecture/15-editors-assistants-and-frontends.md para saber como o editor, o assistente e o daemon chegam ao compilador.
Direções de design
A taxonomia de status acima classifica o estado por superfície em toda a linguagem; esta seção registra o status de direções de design mais amplas documentadas nos capítulos de arquitetura.
A conformidade em todo o parque não é uma direção planejada: definir uma regra de governança uma única vez para que ela se aplique a todos os builds do workspace está disponível hoje por meio do socket de governança. Um plugin conectado à chave plugins.governance da configuração do workspace avalia cada build nesse workspace — um papel de veredito que rejeita um grafo ou um artefato renderizado que viola a regra, um papel de transformação que fornece metadados derivados que um desenvolvedor nunca digita. Consulte ../architecture/11-governance-and-compliance.md.
- Interface Parity & Auto-Implementation — disponível. Uma Recipe escrita para um Component base atende a todo Component que o estende, em qualquer profundidade da cadeia, sem que o Architect precise escrever uma Recipe duplicada. O Component que estende escreve
schema: inherited, portanto não adiciona avalues/infra/providesnenhuma chave raiz que a Recipe da base não conseguiria consumir; um Component que declaraextendscom um schema próprio é recusado no envelope do seu documento. O Manifest continua mapeando o tipo que estende com uma entrada própria, e a verificação do mapeamento a aceita quando oimplementsda Recipe mapeada nomeia o tipo ou qualquer base que ele estende. Documentado em../architecture/02-ecosystem-philosophy.md. - Ghost Infrastructure Tracker — disponível. Uma proteção na fase de renderização emite um aviso quando uma chave que um autor declarou chega a um nó e nenhum template que a Recipe vinculada declara a lê, de modo que um valor declarado pelo autor e descartado silenciosamente pelo template é nomeado em vez de perdido. É a metade da fase de renderização do mesmo design de correspondência de formas. Consulte
errors/warnings.md.
Os capítulos de arquitetura descrevem as superfícies de design; esta página acompanha o status de implementação.