Estado da linguagem
Esta página é a referência canónica sobre que superfícies do Aggrega são utilizáveis hoje, quais estão documentadas mas o compilador ainda não lhes dá seguimento, e quais estão previstas para uma iteração futura. Complementa os capítulos por domínio, reunindo num único sítio o estado de prontidão de toda a linguagem.
Dois grupos de leitores consultam esta página. Os autores estreantes consultam-na antes de escrever contra uma superfície desconhecida, para confirmar que a superfície produz hoje saída renderizada. Os leitores à procura de referência consultam-na quando uma superfície que usam se comporta de forma inesperada — por exemplo, quando o YAML é validado mas não é produzida nenhuma saída, esta página é o primeiro sítio onde consultar o estado da superfície. Os leitores que regressam também consultam a página para identificar superfícies que mudaram de etiqueta de estado 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 já funciona.
Taxonomia de estados
Cada superfície da linguagem nesta página tem uma de quatro etiquetas de estado:
-
available. O esquema aceita a superfície; o compilador consome-a; o comportamento corresponde ao contrato documentado. Os autores que usam uma superfície
availablerecebem o contrato documentado. -
accepted but inert. O esquema aceita a superfície — escrever contra ela passa a validação — mas o compilador ainda não age sobre ela. Escrever uma superfície
accepted but inertproduz um build sintaticamente válido sem efeito renderizado para a 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 secção abaixo nomeiam o comportamento específico. -
accepted but blocked. O esquema aceita a superfície — escrever contra ela passa a validação — mas o compilador interrompe o build em vez de a renderizar. Escrever contra uma superfície
accepted but blockedfalha na renderização com um erro explícito que nomeia o que escrever em vez disso. Um bloqueio pode ser permanente, quando o que foi escrito é uma ambiguidade que o compilador não resolverá pelo autor, porque escolher uma leitura por ele poderia entregar algo que não pediu; ou pode durar apenas até o comportamento por trás da superfície ser disponibilizado. O que a etiqueta promete é o mesmo em ambos os casos: o esquema aceita-a, o build recusa-a e o erro indica como corrigir. -
planned. A superfície está documentada tal como foi desenhada, mas nem o esquema nem o compilador a aceitam ainda. Escrever contra uma superfície
plannedfalha na validação de esquema. A página apresenta os itens planeados para que os autores possam planear tendo em conta a sua ausência, em vez de descobrirem a lacuna no momento do build.
As etiquetas de estado são avaliadas face ao compilador atual. As superfícies em desenvolvimento ativo podem mudar de etiqueta; as entradas por secção descrevem o plano de transição quando é conhecido.
Tipos de entrada da Recipe
Uma Recipe compõe a sua saída a partir de três tipos de entrada — sourced, synthesized e artifacts — descritos em 16-recipe-input-composition.md. Estado por tipo de entrada:
-
source:+valuesMapping:(sourced) — available. O compilador resolve o URI desource:, avalia o templatevaluesMapping(inline,$import:de ficheiro 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:(synthesized) — available. A Recipe declaraworkload:inline (block scalar que contém o YAML do Workload) ou via$import:(caminho de ficheiro). O compilador analisa o Workload em template, valida-o face ao esquema do Workload incorporado e despacha-o para o sintetizador de cargas de trabalho do provider de destino. Consumido pelos providers helm e compose. O provider helm-chart redireciona explicitamente os autores para o provider helm para manifestos K8s sintetizados. Uma Recipe que declareworkload:para um provider que não implemente a síntese de cargas de trabalho interrompe-se na renderização com umCATALOG_ERROR. -
artifacts:(artefactos) — disponível. O campo é um mapa de entradas com nome; cada entrada é escrita inline ou carregada através de$import:por entrada. As entradas são avaliadas depois de o Workload ser analisado e a fonte resolvida, pelo que o contexto de template completo — incluindo.workloade.source— lhes está disponível; recebem a proveniência fundida emmetadata.labelsemetadata.annotationsnos documentos que transportam metadados (as chaves inseguras quanto ao conjunto de caracteres — recipe-uri, boundary-path, sync-wave — como anotações, a mesma divisão que os fornecedores helm aplicam) e são emitidas como ficheiros separados ao lado da saída da Recipe renderizada a partir da fonte ou sintetizada a partir da carga de trabalho. Despacho de Provider — o fornecedor helm plano emite ficheiros autónomos num diretório com o nome do componente que os declarou, dentro do diretório de saída da fronteira, porque a chave dá nome ao ficheiro e nada diz sobre qual componente o escreveu; o fornecedor compose encaminha as suas emissões através do fusor do final da Release; o fornecedor helm-chart avalia cada entrada com os delimitadores Aggrega[[ ]]para que a sintaxe{{ }}do Helm no mesmo ficheiro sobreviva até à renderização a jusante e depois coloca cada entrada segundo a forma em que foi escrita — uma entrada carregada por$import:emboundaries/<bp>/charts/<nodeID>/templates/<authored-key>(os ficheiros de um pacote aninhados sob essa chave), ao lado dos templates do próprio chart de origem, e uma entrada de conteúdo inline emboundaries/<bp>/charts/<nodeID>/<authored-key>, a raiz do chart, onde os templates do próprio chart a leem através de.Files.Get/.Files.Glob; o fornecedor terraform escreve cada entrada tal como está no diretório próprio do componente sob a árvoremodules/da fronteira; o fornecedor cloudformation funde cada entrada, um fragmento de stack, no único stack montado para esse diretório de saída. As colisões de nomes de ficheiro entre origens de tipos de entrada (saída renderizada a partir da fonte, sintetizada a partir da carga de trabalho ou emitida como artefacto) são detetadas no momento da renderização pelo detetor de colisões entre origens e produzem um CATALOG_ERROR que nomeia todos os contribuidores.
Ver entities/recipe.md para a superfície de autoria da Recipe e as regras de composição dos tipos de entrada; errors/fatal-halts.md para as regras de forma da Recipe; e a secção Providers abaixo para a matriz por provider.
Linguagens de mapeamento
As Recipes (e as FeatureRecipes) associam-se a um único campo de mapeamento para traduzir o contexto Aggrega no dicionário de valores que o provider subjacente consome. O campo valuesMapping: suporta três modos de autoria, despachados segundo a forma do conteúdo:
valuesMapping:— modos 1-3 available. Modo 1: template Go inline (block scalar). Modo 2:$import:de ficheiro (um mapa que contém apenas$import:com um caminho de ficheiro 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 MappingLibrary,<Library>#/mappings/<entry>, opcionalmente com um mínimo:<version>). O compilador despacha segundo a forma do conteúdo — block scalar para o modo 1,$import:com um caminho de ficheiro 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 face ao contexto de template da Recipe durante o mapeamento de valores (a biblioteca de helpers Sprig está pré-registada); o modo 3 resolve a entrada face ao catálogo local mais quaisquer bibliotecas fixadas no lockfile, e uma referência que inclua um host é rejeitada. Verentities/recipe.md«O campovaluesMapping— três modos de autoria» para o mecanismo de despacho e exemplos trabalhados.
Ver entities/recipe.md para a superfície de autoria da Recipe e o desenho da linguagem de mapeamento, e entities/mappinglibrary.md para a entidade de biblioteca que suporta o modo 3.
Sintaxe de inject
O bloco inject: tem uma única sintaxe em todas as posições — o inject próprio de um componente, o de uma ligação uses e o de uma associação.
-
Uma lista de entradas por mecanismo (
[{in: ..., from: ...}],[{in: ..., value: ...}]) — available. Cada mecanismo de entrega é uma lista; cada entrada nomeia o seu identificador local (nome da variável de ambiente, caminho de ficheiro, flag de argumento) comin:e transporta exatamente um defrom:(referência a uma chave de provides) ouvalue:(cadeia literal). Um mecanismo escrito como mapa em vez de lista, ou uma entrada que transporte ambas as 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. Numa ligaçãouses, umvalue:interrompe o build, como descreve Aninject:entry on a connection carries a literal (Uma entrada numa ligação transporta um literal), e noinjectpróprio de uma associação também interrompe o build, como descreve Aninject:entry on an attached Feature carries a literal (Uma entrada numa Feature associada transporta um literal): ambos entregam apenas chaves que outra entidade publica, nomeadas comfrom:.
Ver vocabulary/topology-triad.md para a especificação completa do contrato de injeção, incluindo a semântica do contexto de estado duplo, as regras de colisão de chaves e exemplos trabalhados.
Motor de templates
O motor de templates Go do Aggrega avalia os templates de Recipe e FeatureRecipe face ao contexto de template na fase por local que a Matriz de expansão de templates documenta. A biblioteca de helpers Sprig está pré-registada ao lado dos helpers próprios do Aggrega em todas as superfícies que o renderizador avalia, com uma exceção: a resolução de uma coordenada source: estruturada regista apenas os helpers do Aggrega — optional e capitalizedWords estão aí disponíveis e as funções Sprig não, pelo que uma chamada Sprig num campo source:, ou numa entrada locals: de uma entidade que tenha uma source: estruturada, interrompe-se no momento da análise. Ver errors/fatal-halts.md, que dá a essa superfície uma secção própria. A avaliação, a análise e a integração Sprig estão disponíveis hoje.
Comportamento com chaves em falta — tolerado em templates de valores; missingkey=error estrito em templates de caminhos, em asserções e numa coordenada source:. Os templates de valores são avaliados com a opção missingkey=zero do Go, pelo que um template que referencie uma chave não associada (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 a funcionar com esta política, porque um valor não definido conta como vazio para default. Os templates de caminhos (directory: / subDirectory: nas fronteiras da Release) são avaliados com missingkey=error face a uma lista de permissões fechada — falhas silenciosas de caminhos produzem estruturas de sistema de ficheiros incorretas que os operadores só descobrem depois do build, e o rigor deteta o erro mais cedo. Duas outras superfícies adotam a mesma política estrita, pela mesma razão: uma renderização vazia aí produziria um veredicto errado ou uma fixação errada, em vez de um campo que o autor possa reler. São uma entrada assertions: num Component, Feature, Recipe ou FeatureRecipe, e os campos em template de um bloco source: estruturado numa Recipe ou FeatureRecipe. errors/fatal-halts.md explica a política de cada superfície, uma a uma, e apresenta as formas sensíveis à presença que funcionam com a política estrita.
Recurso sensível à presença através de optional. Quando um autor de Recipe precisa de distinguir «chave ausente» de «chave presente com um valor zero / vazio / falso» — a distinção que o default do Sprig não consegue fazer —, o renderizador expõe o helper optional: {{ optional .infra "replicas" 1 }} devolve o infra.replicas escrito (incluindo um 0 escrito) quando existe, e recorre a 1 apenas quando a chave está ausente. Ver templates/sprig-functions.md para a semântica completa.
Conversão de nomes através de capitalizedWords. Quando um destino só aceita letras e dígitos nos nomes pelos quais endereça recursos, {{ capitalizedWords .context.instance_id }} lê o ID como palavras separadas por qualquer coisa fora desse alfabeto e põe em maiúscula a primeira letra de cada palavra, pelo que payments-db dá PaymentsDb. A conversão elimina todos os separadores, pelo que dois IDs que só diferem na pontuação chegam a um mesmo nome; um build que emitiria dois recursos com um mesmo nome interrompe-se e nomeia ambos os IDs. Ver templates/sprig-functions.md para a semântica completa.
Imposição do contrato de parâmetros na camada de declaração. Os 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 proveniência ficheiro:linha que nomeia o parâmetro e o contrato. As violações de tipo / restrições surgem da mesma forma. Esta é a verdadeira imposição de chaves em falta: a tipagem é verificada onde vive a intenção do programador (a declaração parameters: do Aggregate), e não no momento posterior da avaliação dos templates. Ver entities/aggregate.md §«Contratos de parâmetros tipados».
Gramática de declaração única para os parameters: do Aggregate. Cada slot de parâmetro é escrito como um objeto de contrato tipado (key: { type: <type>, default: <value>, ... }). A abreviatura 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 de contrato tipado torna explícita na camada de declaração a semântica de type:, required: e das restrições; a satisfação pela Release continua a usar valores escalares segundo o tipo declarado pelo contrato.
Ver templates/expansion-matrix.md para a matriz de avaliação por local de template e 05-templates.md para a visão geral dos templates.
Fases do pipeline de compilação
O pipeline de compilação do Aggrega está documentado em ../architecture/10-compilation-pipeline.md. Estado por fase:
- Resolução, construção da topologia, finalização do grafo, análise estática e renderização — available.
- Mapeamento de inject (interceção pré-renderização com
injectMapping) e todas as subfases da renderização base — publicação de locals, mapeamento de valores, síntese de cargas de trabalho, avaliação de artefactos, renderização do provider, renderização de features e geração de recursos da FeatureRecipe de credenciais — available. - O pipeline de plugins (execução Wasm de
pipeline:) — available. Uma Recipe ou FeatureRecipe que declare passospipeline:não vazios tem cada passo executado pela ordem declarada: o compilador despacha o plugin Wasm nomeado pelo passo sobre a saída renderizada, aplica as operações JSON Patch devolvidas aos documentos endereçados e emite os efeitos secundários do passo. Um passo cuja barreirawhen:renderize um valor falso é ignorado como pass-through, deixando o conjunto de documentos inalterado. Os autores que pretendam mutações ao estilo JSONPatch (injeção de sidecar Envoy, VolumeMount de segredos, etc.) conseguem-nas através desta superfície.
Providers
A biblioteca padrão do Aggrega disponibiliza cinco providers de renderização — helm, helm-chart, compose, terraform e cloudformation. Estado por provider:
helm— available. O modo sourced (renderização de charts Helm através do SDK do Helm) e o modo synthesized (Workload → um objeto controlador escolhido peloformdo Workload — Deployment, StatefulSet, DaemonSet, Job ou CronJob — mais Services e PVCs) são ambos disponibilizados.helm-chart— available. O modo sourced (composição em umbrella chart) é disponibilizado. O tipo de entrada synthesized não se aplica a este provider; os autores que precisem de síntese de manifestos K8s usam o providerhelmcomworkload:.compose— available. O modo sourced (sobreposição de fragmentos compose) e o modo synthesized (Workload → serviço compose + volumes + redes) são ambos disponibilizados. A saídadocker-compose.yamlpor fronteira é montada através do compositor ao nível da Release.terraform— available. O modo sourced e os artefactos são ambos disponibilizados; cada fronteira recebe uma configuração raiz,aggrega.modules.tf, que declara cada componente como um blocomodulecujos ficheiros ficam num diretório próprio sobmodules/. O tipo de entrada synthesized não se aplica a este provider.cloudformation— available. O modo sourced e os artefactos (fragmentos de stack) são ambos disponibilizados; todos os componentes renderizados para um mesmo diretório de saída são montados num único template de stack, emitido como JSON puro. O tipo de entrada synthesized não se aplica a este provider.
A renderização de Provider é servida por um Plugin com pluginType: provider; consulte entities/plugin.md para a superfície de autoria do Plugin de renderização de fornecedores e 06-providers.md para as páginas de referência por fornecedor.
Expansão orientada por anotações
Os Manifests contêm uma secção de associações features.annotations: que mapeia chaves de anotação para tipos de Feature, mais uma tabela de encaminhamento agrupada por pilar (maps.infra / maps.values) que nomeia que propriedades do esquema da Feature cada associação pode preencher. Documentado em entities/manifest.md e providers/well-known-annotations.md; a colocação no pipeline em ../architecture/10-compilation-pipeline.md; a mecânica no carregamento do catálogo e no momento do inspect em ../architecture/13-catalog-and-registry.md §«Expansão de Feature orientada por anotações».
- Associações
features.annotationsdo Manifest — available. A subfase de expansão de anotações da resolução é disponibilizada de ponta a ponta. Percorre as fronteiras da Release (de fora para dentro) e os subsistemas do Aggregate (de fora para dentro), calcula o conjunto efetivo de anotações por componente através de cascata + sobreposição com exclusão por null do valor inteiro e por subchave, analisa cada valor de anotação como escalar, mapa estruturado ounullexplícito, encaminha por subchave através da declaraçãomapsda associação com imposição de lado vs. pilar (o lado do Aggregate acionamaps.values; o lado da Release acionamaps.infra), valida os tipos por folha face aospec.schemada Feature de destino e injeta associações de Feature sintéticas, que o grafo IR marca comorigin: annotation. A composição entre lados funde por pilar e por campo no momento da construção do IR, prevalecendo o explícito em cada campo;aggrega inspectapresenta parênteses de proveniência por folha. A validação dos alvos de associação no carregamento do catálogo, o lint de sobreposição de pilares do esquema e o lint de sobreposição de mapas de associação protegem o caminho. O prefixoaggrega.ai/simples é rejeitado no carregamento do Manifest quando usado como chave de associação — esse prefixo está reservado para anotações nativas da plataforma; as associaçõ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 através da palavra-chave implements:. implements: nunca seleciona uma Recipe: quem o faz é o mapeamento do Manifest, e uma instância cujo tipo nenhum mapeamento abrange é 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 numa versão que a chave não nomeia — todas as instâncias que 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 nomeie nenhuma, a versão mais alta desse Component que o catálogo contém. Estado por forma:
- Exata (
core/api-server:1.0.0) — available. O tipo mapeado tem de ser essa versão. - Intervalo compatível com a major (
core/api-server:^1.0.0) — available. A forma com acento circunflexo é uma restrição SemVer (>=1.0.0, <2.0.0no exemplo); a versão do tipo mapeado tem de a satisfazer. - Não versionada (
core/api-server) — available. Qualquer versão do tipo a satisfaz.
Uma entrada de mapeamento cujo implements: da Recipe não corresponda nem ao tipo mapeado nem a nenhuma das suas bases interrompe o build com um OPS_ERROR que nomeia a entrada, a Recipe e o seu valor de implements:. Uma instância de componente que uma chave alcança noutra versão, cuja versão o implements: da Recipe não satisfaça, interrompe o build com o mesmo OPS_ERROR, nomeando a instância, o seu tipo — e, para uma instância que não nomeie nenhuma versão, a versão com que foi compilada —, a chave, a Recipe e o seu valor de implements:. A forma com acento circunflexo é a superfície de autoria canónica para a correspondência compatível com a major.
Ver vocabulary/inheritance-and-interface.md para a superfície de desenho 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 contêm metadata.labels, metadata.annotations e (na Release) metadata.environment. Estado por superfície:
Disponibilidade de metadata.labels e metadata.annotations — em sete tipos. Os envelopes de entidade que contêm estes campos são o Component (labels obrigatórias, com a chave obrigatória component.aggrega.ai/type, annotations opcionais), a Feature (ambos opcionais), os quatro tipos de biblioteca SchemaLibrary, MappingLibrary, WorkloadLibrary e ArtifactLibrary (ambos opcionais) e o Aggregate (apenas labels, opcionais). As restantes entidades — Recipe, FeatureRecipe, Manifest, Release, Plugin — não aceitam metadata.labels nem metadata.annotations ao nível do envelope.
metadata.environment na Release — obrigatório. O esquema da Release lista environment como campo obrigatório de metadata; o build aplica o seu valor na saída renderizada como a etiqueta aggrega.ai/environment. Ver entities/release.md para os cinco casos de uso práticos da secção Environment Metadata (atribuição de custos OTel/FinOps, filtragem de traces/registos OTel, direcionamento de operadores Kubernetes, diferenciação de produção multirregião, delimitação de conformidade).
Ver 02-naming-conventions.md para a disciplina de capitalização de campos que se aplica às chaves de 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 regista o pipeline de build mais a introspeção. Estado por comando:
aggrega build— available. Lê um ficheiro de Release, resolve o Aggregate + Manifest, executa o pipeline de compilação e escreve os artefactos renderizados nos diretórios de saída das fronteiras. Quando existe um lockfile, verifica as dependências face a ele; quando não existe, interrompe-se pedindo um pull, ou preenche-o primeiro quando--auto-pullouauto_pullo pedem.aggrega inspect— available. Inspeciona uma entidade de catálogo, um ficheiro de entidade, uma entidade publicada num registo ou uma Release, e indica a sua forma resolvida. Vercli/aggrega-inspect.md.aggrega pull— available. Resolve todas as dependências de uma Release e escreve um lockfile por Release que fixa cada entidade de catálogo e artefacto de origem a uma versão e a um digest de conteúdo, e cada entrada externa que a renderização da Release pede a um digest de conteúdo; guarda o conteúdo obtido em cache em.aggrega/cache.--verifyverifica um lockfile existente face ao estado atual. Vercli/aggrega-pull.md.aggrega push— available. Publica uma entidade de catálogo num registo OCI;aggrega push --list-kindsindica que tipos aceita. Vercli/aggrega-push.md.aggrega lint— available. Aplica as regras de disciplina de publicação com severidadewarna todo o catálogo, ao fecho de dependências de uma Release ou a uma única entidade; numa única entidade,--pre-publishacrescenta uma verificação do incremento de versão face à versão atualmente publicada da entidade, e uma discrepância provoca uma interrupção. As regras são disponibilizadas como um plugin Wasm opcional. Vercli/aggrega-lint.md.aggrega serve— available. Um daemon de compilador como serviço de longa duração que fala JSON-RPC 2.0 sobre stdin/stdout, para integração com editores e IDEs. Vercli/aggrega-serve.mdpara os métodos que serve.aggrega version— available. Imprime a versão da CLI;-o jsonemite um objeto de versão legível por máquina.aggrega validate— available. Verifica a correção em todo o catálogo, numa Release ou numa única entidade, reportando diagnósticos sem renderizar artefactos.aggrega search— available. Pesquisa entidades publicadas no índice local dos registos configurados; o índice é construído e atualizado poraggrega registry update.aggrega registry— available. Gere os registos e a sua política de confiança de assinaturas;registry addregista um registo, eregistry updateconstrói o índice local queaggrega searchconsulta.aggrega push-artifact— available. Publica um artefacto de dados autónomo (como um pacote de documentação) num registo OCI, ao lado dopushde publicação de entidades.aggrega sign— available. Assina um ou mais artefactos já publicados e anexa as suas assinaturas.aggrega deprecate— available. Anexa um marcador de descontinuação assinado a um artefacto já publicado.aggrega logineaggrega logout— available. Autenticam-se num registo OCI e guardam a credencial, ou removem uma credencial guardada.aggrega auth— available. Gere a identidade de assinatura local usada para assinar artefactos.aggrega config— available. Inspeciona e gere a configuração do workspace; os subcomandos mostram a configuração efetiva fundida e de onde veio cada definição, inicializam uma configuração funcional com um registo e a sua política de confiança de assinaturas, e congelam no workspace a configuração efetiva crítica para o build, para que este seja construído de forma idêntica sem depender da configuração global da máquina.aggrega get-schema— available. Imprime o JSON Schema de um tipo de entidade ou de contrato.aggrega plugin— available. Inspeciona os plugins Wasm que a CLI consegue resolver; os subcomandos listam-nos, acrescentam e removem plugins configurados, sincronizam os registos de um plugin geridos pela máquina e geram uma vista de catálogo deles.aggrega cache— available. Inspeciona e mantém as caches em disco; os subcomandos reportam o estado, podam, expulsam e limpam.aggrega mcp— available. Executa um servidor Model Context Protocol sobre stdio, ou sobre HTTPS para um cliente noutra máquina, expondo a introspeção do compilador a integrações com assistentes de IA.aggrega completion— available. Gera o script de conclusão automática da shell para a CLI.- Subcomandos de extensão de CLI — available. Um plugin Wasm publicado como guest
pluginType: clié resolvido e registado como subcomando deaggrega, pelo que uma extensão instalada corre comoaggrega <extension>ao lado dos comandos incorporados. aggrega import— available. Converte uma origem declarativa externa de definição de agentes (Langflow, Flowise, n8n) em ficheiros de autoria Aggregate e Component em rascunho, com uma decisão determinística de reutilização do catálogo, pontuada por confiança, registada por nó. O mapeamento específico do formato é fornecido por um plugin importador que o workspace resolve para o formato da origem — um que o seu catálogo contenha, ou um dos importadores Langflow, Flowise e n8n do compilador, que são construídos e publicados com cada versão do compilador. O binário contém as suas entidades Plugin, mas não os seus módulos, pelo que servem os seus formatos em todos os workspaces: a primeira importação que precise de um que a máquina não tenha obtém-no a partir do registo predefinido do workspace, verifica-o e guarda-o na cache de conteúdos para todas as importações posteriores. Uma origem é analisada através do parser que o catálogo do workspace serve para a sua sintaxe ou, quando o catálogo não serve nenhum, através do que o compilador transporta, pelo que um workspace cujo catálogo não contenha nenhum parser importa através de qualquer um deles.aggrega scaffold— available. Redige um documento inicial para qualquer tipo de entidade a partir do esquema desse tipo — todos os campos que exige, com um marcador de posição onde é necessário um valor — e escreve-o na saída padrão; com--example, escreve num novo diretório um dos exemplos executáveis da documentação, lido a partir do pacote de documentação assinado.aggrega explain— available. Explica a condição de interrupção que um código curto (comoE0007) ou um código descritivo nomeia.aggrega edit-document— available. Aplica a um documento uma única edição estruturada e delimitada — adicionar um componente, associar uma Feature, ligar uma ligação ou definir um valor — preservando todos os bytes em que não toca.aggrega pin— available. Regista, noentity.lockao lado de uma Recipe ou FeatureRecipe, a fixação de conteúdo de cada entrada que a entidade lê de fora do seu próprio documento.aggrega skills— available. Instala a skill do Aggrega num assistente de IA.
Ver 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 de cada comando.
Editores e outros frontends
Cada frontend mostra o que o binário aggrega compilou; nenhum traz um compilador próprio. Estado por superfície:
- Contrato do grafo IR — available. O esquema do grafo IR, o contrato com base no qual cada frontend lê o grafo, é disponibilizado como parte da distribuição de esquemas do Aggrega; ver a referência do esquema IR.
- Ler o grafo a partir de um comando — available.
aggrega buildaceita--ir-graph, tal comoaggrega inspectquando recebe uma Release eaggrega validate --release; a flag escreve no stdout, em JSON, o grafo que essa execução resolveu, 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 recebem-no como o 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 anexa Features a partir dele, pedindo ambos ao daemon
aggrega serve. - Modo de streaming da CLI headless — planned. O modo headless emite o grafo IR como JSON delimitado por mudanças de linha para o stdout, para que um frontend o consuma à medida que a topologia muda. O que é hoje disponibilizado é um documento por invocação e não um fluxo: nenhum comando emite uma sequência de grafos num único stdout à medida que uma topologia muda.
Ver ../architecture/15-editors-assistants-and-frontends.md para saber como o editor, o assistente e o daemon chegam ao compilador.
Direções de desenho
A taxonomia de estados acima classifica o estado por superfície em toda a linguagem; esta secção regista o estado de direções de desenho mais amplas documentadas nos capítulos de arquitetura.
A conformidade em todo o património não é uma direção planeada: enunciar uma regra de governação uma única vez para que se aplique a todos os builds do workspace está available hoje através do socket de governação. Um plugin associado na chave plugins.governance da configuração do workspace avalia todos os builds desse workspace — um papel de veredicto que rejeita um grafo ou um artefacto renderizado que viole a regra, um papel de transformação que fornece metadados derivados que um programador nunca escreve. Ver ../architecture/11-governance-and-compliance.md.
- Interface Parity & Auto-Implementation — available. Uma Recipe escrita para um Component base serve todos os Components que o estendem, a qualquer profundidade da cadeia, sem que o arquiteto tenha de escrever uma Recipe duplicada. O Component que estende escreve
schema: inherited, pelo que não acrescenta avalues/infra/providesnenhuma chave raiz que a Recipe da base não conseguisse consumir; um Component que declareextendscom um esquema próprio é recusado no envelope do seu documento. O Manifest continua a mapear o tipo que estende com uma entrada própria, e a verificação do mapeamento aceita-a quando oimplementsda Recipe mapeada nomeia o tipo ou qualquer base que este estenda. Documentado em../architecture/02-ecosystem-philosophy.md. - Ghost Infrastructure Tracker — available. Uma salvaguarda da fase de renderização emite um aviso quando uma chave que um autor declarou chega a um nó e nenhum template que a Recipe associada declara a lê, pelo que um valor declarado pelo autor e descartado silenciosamente pelo template é nomeado em vez de se perder. É a metade da fase de renderização do mesmo desenho de correspondência de formas. Ver
errors/warnings.md.
Os capítulos de arquitetura descrevem as superfícies de desenho; esta página acompanha o estado da implementação.