Contrato de plugins Wasm
O pipeline de compilação do Aggrega inclui pontos de socket designados em que plugins WebAssembly (Wasm) estendem o comportamento do compilador: os quatro papéis do socket de governança, entre eles um Mutation Gate na construção da topologia e um Validation Gate na análise estática; um pipeline de plugins pós-renderização para etapas de FeatureRecipe e Recipe; um socket de renderização de provedores; um socket de analisador; um socket de importador; e um socket de linting fora de banda. Esta página documenta o contrato público de plugins Wasm: quais sockets existem, o que cada socket consome e produz, onde cada socket fica no pipeline de compilação e o sandbox dentro do qual cada plugin é executado.
Esta página trata dos sockets — os pontos do pipeline e suas formas de entrada/saída. Para o plugin — a entidade Plugin, as declarações de capacidades por export, os limites de execução e o ciclo de vida publish→pull→build — veja o guia do desenvolvedor de plugins Wasm.
O Aggrega incorpora um runtime host Wasm — Extism sobre o mecanismo Wazero — que carrega e executa plugins por trás de um firewall de pureza AOT: o host não concede a um guest nenhuma capacidade ambiente — sem rede, sem sistema de arquivos, sem ambiente, stdio descartado, um relógio de parede observável congelado em um instante invariante entre builds — de modo que um plugin não pode quebrar as garantias ahead-of-time do compilador. A superfície completa de capacidades — a regra de módulos de importação no carregamento, as negações no momento da instanciação e as funções de host selecionadas — é o contrato do sandbox mais abaixo. Os autores de Plugin têm o host como alvo por meio do PDK em três linguagens (Go, Rust, TypeScript). aggrega lint aciona o socket do linter — o linter de publicação padrão — por meio do host. aggrega build aciona os papéis de tempo de build do socket de governança quando um espaço de trabalho os configura: o papel annotation-transform durante a resolução e o papel label-transform na construção da topologia (ambos moldam a saída), além do veredito de IR na análise estática e do veredito de renderização sobre os artefatos renderizados. Cada um é uma operação nula quando nenhum plugin está vinculado a esse papel, de modo que um build sem configuração de governança fica inalterado. aggrega build também aciona o pipeline: da FeatureRecipe e da Recipe no pipeline de plugins que encerra a renderização — cada etapa declarada é executada por meio do host sobre o conjunto de documentos renderizados, aplicando os patches RFC 6902 da etapa e emitindo seus efeitos colaterais. Veja Status da linguagem → Fases do pipeline de compilação.
O contrato do sandbox
Cada socket aciona seu plugin por meio do mesmo sandbox do host. O sandbox tem duas camadas independentes — uma verificação estrutural no carregamento e a negação de capacidades na instanciação — e, juntas, elas definem o que um plugin pode alcançar, o que não pode alcançar e pelo que é responsável.
A regra de módulos de importação (no carregamento). O carregador percorre a seção de importações do binário do plugin e admite importações de funções apenas sob três namespaces de módulo: wasi_snapshot_preview1 (o runtime WASI preview-1 ao qual o runtime de uma linguagem guest é ligado), extism:host/env (a ABI do runtime Extism — os intrínsecos de memória e E/S do próprio PDK) e extism:host/user (as funções de host selecionadas do Aggrega). Um guest pode importar qualquer nome de função sob um módulo permitido; uma importação sob qualquer outro módulo nomeia uma superfície que o host não fornece, e o plugin é rejeitado no carregamento com um diagnóstico que nomeia o módulo e a importação. A regra deliberadamente não censura nomes individuais de funções WASI: o runtime de uma linguagem ligado estaticamente importa funções de sistema de arquivos e de sockets que seus caminhos de código ativos nunca chamam — trazidas transitivamente por dependências — e nomear uma importação não concede nada. É a negação de capacidades na instanciação, e não a censura de importações, que garante a ausência de E/S.
Nenhuma capacidade ambiente (instanciação). O host instancia o guest com um comportamento WASI real e nenhuma autoridade ambiente:
- sem sistema de arquivos — sem diretórios pré-abertos, de modo que uma chamada ao sistema de arquivos falha na fronteira da chamada;
- sem sockets de rede;
- um ambiente vazio;
- stdio descartado — nada do que o guest escreve em stdout ou stderr chega aos fluxos do host;
- um relógio de parede observável congelado, fixado em um instante invariante entre builds, de modo que um guest que lê a hora não pode vazar a hora do build para sua saída;
- um relógio monotônico real e que avança — o runtime de uma linguagem guest precisa de um para inicializar, e o tempo monotônico mede uma duração decorrida, não um instante do relógio de parede;
- entropia real do host — uma entropia fixada estabilizaria a semente de hash interna do runtime de uma linguagem e mascararia o não determinismo do guest em vez de deixá-lo aparecer como saídas diferentes;
- um único nome de programa sintético como argv.
Uma chamada de E/S que um guest realmente faz — abrir um arquivo, conectar-se a um socket — falha na fronteira da chamada. Esse é o próprio modelo de segurança baseado em capacidades do WASI: o sandbox nega a capacidade em vez de policiar o código.
As entradas chegam apenas pelo payload e pelas funções de host selecionadas. Um plugin recebe tudo o que renderiza ou avalia no payload que seu socket transporta — projeções do grafo e dos nós, valores e contexto de renderização. A codificação em que um payload chega é fixada por socket e indicada na seção própria desse socket mais abaixo; cada tipo de payload publicado traz um ponto de entrada de codificação e um de decodificação para a codificação de seu socket, de modo que um guest chama uma função em vez de escolher um analisador. Para uma renderização de provedor com fonte, o payload transporta uma listagem da fonte em vez dos bytes da fonte: um conjunto ordenado de entradas {path, is_dir} sob a raiz da fonte do nó, sem nenhuma interpretação do layout do provedor pelo host. O guest aplica sua própria lógica de layout — selecionar o único arquivo compose, descer até a raiz de um chart, exigir um Chart.yaml, fazer vendoring de um módulo recursivamente — e lê de volta exatamente a fatia que seleciona por meio de um callback do host. Além do payload, o host disponibiliza um conjunto selecionado de funções de host de privilégio mínimo, e concede a um plugin exatamente aquelas que seu binário importa:
aggrega_log— uma linha de log no destino de log do host.aggrega_emit_warning— um aviso estruturado que o host exibe após a chamada.aggrega_fetch_external_input— o canal de busca de entradas externas (abaixo).aggrega_pack_source— o callback de seleção da fonte: o guest nomeia uma seleção{file | dir | tree, path}sob a raiz da fonte e o host lê e empacota exatamente isso sob um sandbox que resolve caminhos sob a raiz e rejeita...aggrega_read_source_file— uma leitura do conteúdo de um único arquivo sob o mesmo sandbox, para uma seleção da fonte que depende do conteúdo.aggrega_parse_source— o callback de consumo de produtores: o guest nomeia um formato sintático e entrega os bytes da fonte, e o host resolve um analisador para esse formato, executa-o e retorna a árvore canônica que ele produziu. É assim que um consumidor obtém a saída de um produtor por meio do host em vez de invocar ele próprio um guest produtor, e o host o limita a um único nível — um produtor alcançado dessa forma que o chama de novo é negado — de modo que um consumidor o chama uma vez por fonte e pode consumir muitas fontes em sequência.
O host deriva o conjunto que um plugin importa a partir de seu binário .wasm, valida-o contra a lista de permissões selecionada e o confronta com as funções de host que o describe() do guest declara. aggrega plugin sync registra o conjunto no spec.runtime.hostFunctions da entidade, e uma publicação recusa uma entidade cujo registro difere do binário, de modo que a superfície de host de cada plugin é visível no catálogo e não pode divergir do binário.
Falhas de callback carregam um código comparável por máquina, sob hostfunc_error_code. Os callbacks do host que retornam uma resposta — aggrega_fetch_external_input, aggrega_pack_source, aggrega_read_source_file e o callback de consumo de produtores aggrega_parse_source — entregam a falha em banda: o envelope de resposta carrega uma mensagem legível por pessoas e, ao lado dela, um código opcional comparável por máquina sob hostfunc_error_code, tirado de um vocabulário fechado. A mensagem é prosa livre para uma pessoa; o código é a identidade estável com base na qual um guest ramifica sem analisar a mensagem. Em caso de sucesso, o código está ausente; em caso de falha, o host define ambos. O PDK expõe o par como um erro tipado cujo texto é a mensagem e cujo campo de código um guest compara com as constantes de código reexportadas da linguagem. Um guest tolera um código ausente e um código que não reconhece recorrendo à mensagem — portanto, comparar um código é um refinamento de melhor esforço sobreposto à mensagem sempre presente, nunca um substituto dela. O conjunto fechado de valores é o esquema de códigos de erro das funções de host.
🔴 Dois vocabulários diferentes nomeiam uma falha nesta fronteira, e a chave que você lê diz qual deles você tem em mãos. Confundi-los é o único erro que vale a pena destacar aqui, porque um valor de qualquer um dos dois é uma string simples e nem o host nem o guest verificam de qual conjunto ele veio.
hostfunc_error_code, em uma resposta que o host envia a um guest. Seu valor é um membro do catálogo fechado referenciado acima — uma lista fixa, que muda lentamente, das maneiras como um callback do host pode falhar. Como o conjunto é fechado, um guest pode comparar um valor com uma constante nomeada que seu kit reexporta e ramificar com base no resultado.condition_codeao lado decondition_short_code, em uma saída de socket que um guest retorna ao host. Esses são os dois identificadores de uma condição de interrupção que o próprio guest levantou, e eles vêm do conjunto aberto e crescente de condições que o compilador registra, e não do catálogo.condition_codeé o código descritivo sob o qual a condição está registrada;condition_short_codeé a forma compacta — a letraEe quatro dígitos — que um leitor cita, busca e cola em um relato. O host imprime o código curto no cabeçalho entre colchetes do diagnóstico que renderiza, de modo que uma condição levantada por um guest pode ser citada exatamente como uma levantada pelo compilador. Ele não deriva nenhum dos dois valores, mas os verifica: um código curto que não se resolve em nenhuma condição que este compilador declara, ou que se resolve em uma cujo número foi aposentado, interrompe o build em vez de chegar a um leitor como um identificador que não se resolve em nada.
Os dois identificadores do lado do guest são relatados juntos: um guest que define um e não o outro nomeou uma condição que o host não pode resolver, e o host então relata, em vez disso, sua própria condição genérica de falha de plugin, com a mensagem ainda carregando a falha inteira. E um condition_code nunca é membro do catálogo de funções de host, de modo que compará-lo com uma constante reexportada nunca encontra correspondência — e é por isso que cada chave nomeia seu próprio vocabulário em vez da falha em geral.
Os slots de cada callback carregam uma codificação declarada, e todo slot que contém um documento de payload o contém em binário. Todo argumento que um callback do host recebe é um ponteiro para a memória do guest, exceto o nível numérico de aggrega_log; um callback que retorna uma resposta também responde com um ponteiro. O que cada um desses slots contém é fixado por callback:
| Callback | Slots de argumento | Slot de resposta |
|---|---|---|
aggrega_log, aggrega_emit_warning | Texto UTF-8 — nenhum documento de payload | sem resposta |
aggrega_fetch_external_input | uma URL UTF-8 simples — nenhum documento de payload | CBOR canônico |
aggrega_pack_source, aggrega_read_source_file, aggrega_parse_source | CBOR canônico (RFC 8949 §4.2.1) | CBOR canônico |
A tabela se divide pelo que cada slot contém, e não pela identidade do callback: um slot que contém um documento de payload carrega CBOR canônico, e um slot que contém uma string simples — uma linha de log, um campo de diagnóstico, uma URL — carrega texto UTF-8. aggrega_fetch_external_input é o único cujos dois slots diferem: seu argumento é uma URL simples, lida como texto UTF-8, e sua resposta é um documento de payload em CBOR canônico.
O que um guest faz em um slot que carrega payload, e o que não deve fazer. 🔴 Um slot que contém um documento de payload contém uma sequência de bytes opaca, não texto UTF-8 — portanto, essa é a forma que um guest declara, não apenas os bytes que coloca ali. Um guest que aloca tal requisição como string, ou lê tal resposta como string, não interopera: uma conversão de texto em qualquer direção corrompe bytes binários. A falha é explícita em vez de parcial — uma requisição que o host não consegue decodificar volta como um envelope de resposta que carrega o código request_undecodable, na mesma forma em banda de qualquer outra falha de callback, de modo que o guest a relata em vez de prosseguir com um payload lido pela metade. Os tipos de payload são SourcePackRequest e SourcePackResponse para aggrega_pack_source, SourceFileRequest e SourceFileResponse para aggrega_read_source_file, ParseInput e ParseSourceResponse para aggrega_parse_source, e apenas o tipo de resposta FetchExternalInputResponse para aggrega_fetch_external_input, cuja URL é alocada como texto. Concretamente, por kit:
- Go — construa a requisição com
EncodeCBOR()do tipo de requisição, aloque-a compdk.AllocateBytes(nãopdk.AllocateString) e leia a resposta comReadBytes()na memória para a qual o ponteiro da resposta se resolve, paraDecodeCBORdo tipo de resposta. A URL de busca é a exceção do lado da requisição, alocada compdk.AllocateString; sua resposta é lida como qualquer outra. A declaração//go:wasmimporté um ponteiro de qualquer forma, então nada na assinatura mostra a forma — ela está na alocação e na leitura. - Rust — a declaração
#[host_fn]informa a forma diretamente: cada um dos três callbacks de payload éfn <callback>(request: Vec<u8>) -> Vec<u8>;, e o callback de busca éfn aggrega_fetch_external_input(url: String) -> Vec<u8>;. Construa a requisição comencode_cbor()do tipo de requisição e leia a resposta comdecode_cbor(&raw)do tipo de resposta. - TypeScript — construa a requisição com a função
encodeCBOR…do tipo de requisição, aloque-a comMemory.fromBuffer(nãoMemory.fromString) e leia a resposta comreadBytes()para a funçãodecodeCBOR…do tipo de resposta. A URL de busca é alocada comMemory.fromString; sua resposta é lida comreadBytes()como as demais. Assim como em Go, a entradadeclare moduleé um ponteiro de qualquer forma.
Um guest que chama um wrapper do PDK não precisa de nada disso. Os wrappers — FetchExternalInput, PackSource, ReadSourceFile e ParseSource, na grafia própria de cada linguagem — fazem a alocação e a codificação, e nenhuma de suas assinaturas nomeia um tipo de transmissão, de modo que um guest que chega a esses callbacks por meio de seu kit não aloca nem decodifica nada por conta própria; um guest que declara e chama as funções de host por conta própria aloca e lê sua memória como descrito acima. Uma requisição alocada como texto é recusada em vez de atendida pela metade, e uma resposta lida como texto não pode ser decodificada, de modo que uma divergência entre os dois lados é explícita em vez de silenciosa.
Duas propriedades em que vale a pena confiar. A resposta carrega a mesma codificação quer tenha sucesso, quer falhe: um guest lê um único slot e não pode saber antes de decodificar qual dos dois casos ele contém, de modo que um único ponto de entrada de decodificação lê ambos, e o código de erro e a mensagem descritos acima chegam por ele. E um guest preenche um campo de valor em bytes no tipo de campo próprio de seu kit — uma slice de bytes em Go, uma string base64 em Rust e TypeScript — porque a conversão para a sequência de bytes bruta que a codificação binária transporta é trabalho do codificador gerado, feita na saída e revertida na entrada. Isso abrange os bytes da fonte de ParseInput, o conteúdo do arquivo que aggrega_read_source_file retorna, o conteúdo que aggrega_fetch_external_input buscou e o conteúdo de cada arquivo empacotado em uma resposta pack-source: esses bytes atravessam a fronteira uma vez em vez de duplamente codificados, e nenhum guest codifica em base64 algo que o codificador está prestes a decodificar de base64. O campo content das respostas read-source-file e fetch é omitido quando está vazio, de modo que a resposta para um arquivo vazio ou um payload buscado de comprimento zero não carrega conteúdo algum; tal resposta continua sendo um sucesso, porque uma falha sempre carrega sua mensagem e seu código, e o wrapper de cada kit retorna bytes vazios para ela. A árvore que aggrega_parse_source retorna trafega como uma sequência de bytes que contém seu próprio documento JSON literalmente; o host não a lê nem a remodela. Um analisador lê o mesmo ParseInput, na mesma codificação, em seu próprio export parse — veja o socket de analisador.
Canônico significa que uma entrada idêntica produz bytes idênticos em todos os lados, o que permite comparar um payload entre os três kits de plugins em vez de apenas fazê-lo passar por uma ida e volta, e é por isso que a saída de um build permanece idêntica byte a byte. Nenhuma biblioteca CBOR é necessária em um guest e nada analisa bytes à mão: cada tipo de payload publicado traz os pontos de entrada de codificação e decodificação de que a codificação de seu slot precisa.
O determinismo é responsabilidade do autor do plugin. O host consome os bytes de saída de um guest literalmente e não executa nenhum serializador sobre eles, de modo que o contrato que todo plugin deve cumprir é: uma entrada idêntica produz bytes de saída idênticos. O sandbox remove as fontes ambientes de não determinismo — hora do relógio de parede, ambiente, estado do sistema de arquivos — mas deliberadamente não mascara o resto: um guest que codifica entropia ou tempo monotônico decorrido em sua saída produz bytes visivelmente diferentes entre execuções em vez de um defeito escondido de forma estável.
O canal de busca de entradas externas. aggrega_fetch_external_input é o único canal sancionado para conteúdo remoto, e ele é mediado pelo host, não um acesso do guest à rede: o guest nomeia uma URL, e o host serve os bytes sob a disciplina de fixação de entradas externas. Uma URL fixada no arquivo de bloqueio da Release é servida a partir do armazenamento local endereçado por conteúdo e verificada contra seu digest registrado; uma URL não fixada é recusada com um diagnóstico que nomeia a URL e a etapa que a fixa, porque uma renderização consome o fecho que seu arquivo de bloqueio registra e nunca o amplia. As fixações são escritas quando as dependências da Release são resolvidas, que é o único momento em que algo é fixado. O guia do desenvolvedor traz as instruções de criação e a disciplina de fixação na íntegra.
Mapas que mantêm sua ordem
Alguns mapas que um payload transporta são marcados como mapas que preservam a ordem no schema do seu socket, porque a ordem de suas entradas faz parte do que eles transportam: os nós de um build, os rótulos de um nó, as vinculações de um nó, as entradas e saídas de uma etapa do pipeline, os espaços de chaves que um provedor declara. Os tipos de payload publicados guardam cada um desses mapas em um contêiner que mantém suas entradas na ordem em que foram definidas:
| Kit | Contêiner |
|---|---|
| Go | aggrega.OrderedMap[V] — o nome que o kit dá a abi.OrderedMap[V] do pacote ABI |
| Rust | OrderedMap<V> do crate aggrega-abi, reexportado pelo kit |
| TypeScript | o Map<string, V> próprio da linguagem |
Os contêineres de Go e Rust oferecem as operações de um mapa — procurar uma chave, defini-la, excluí-la, ler as chaves, percorrer as entradas em ordem, contá-las. Definir uma chave que o contêiner já contém substitui seu valor e mantém sua posição; uma chave nova vai depois de todas as existentes.
A ordem sobrevive às duas codificações. Na codificação binária, um mapa marcado é escrito como uma lista ordenada de entradas — cada entrada uma lista de dois elementos, a chave e depois o valor — na ordem do contêiner, onde a codificação canônica escreveria, de outro modo, um mapa com as chaves ordenadas. Na codificação de texto, é um objeto JSON cujos membros são escritos na ordem do contêiner. Um decodificador, em qualquer das duas codificações, recusa um mapa que repete uma chave, nomeando a chave. Um mapa que o schema não marca mantém a forma de mapa ordenado por chave na codificação binária e o tipo de mapa comum de uma linguagem nos tipos publicados.
Três consequências para um guest:
- A ordem é saída. Como um mapa marcado é escrito na ordem em que foi preenchido, um guest que preenche um a partir de uma fonte sem ordem fixa — iterando um mapa nativo de Go, por exemplo — escreve bytes que diferem entre execuções com entrada idêntica. Preencha-o em uma ordem fixa.
- A ordem só se mantém enquanto o mapa fica em seu contêiner. Um guest que converte um payload em um tipo de valor genérico da sua própria linguagem obtém, em vez disso, a ordem desse tipo: um
map[string]anyde Go não tem nenhuma, e oserde_json::Valuede Rust mantém as chaves de objeto ordenadas, a menos que o crate seja compilado com sua funcionalidadepreserve_order. - Em TypeScript, leia e escreva por meio das funções geradas. Um tipo que contém um mapa marcado decodifica seu JSON membro a membro, de modo que uma chave que se lê como um índice de array, como
"8080", mantém sua posição ondeJSON.parsea moveria para o início do objeto; e seu codificador escreve cadaMapcomo um objeto, ondeJSON.stringifyescreve umMapcomo{}.Object.keysde umMaptambém é vazio: leia as chaves de umMapcom o seu própriokeys().
Valores que uma entrada marca como sensíveis
Um plugin nunca cita, em uma recusa ou em um aviso que retorna, um valor que sua entrada marca como sensível — por sua chave, ou como parte de um payload marcado como um todo. Uma recusa é o error que uma saída carrega; um aviso é um Diagnostic que a saída carrega, qualquer que seja sua severidade, ou um emitido por meio de aggrega_emit_warning. O host repassa esse texto sem alteração onde quer que o relate — a linha de comando, o servidor de linguagem e a lista de problemas do editor, as ferramentas do assistente — e não lê nenhum valor dele, então o plugin é a única parte capaz de manter o valor de fora. Em vez disso, nomeie a chave, a configuração ou a posição: a partir daí um leitor encontra o valor.
A regra cobre o texto que uma biblioteca escreve para o plugin tanto quanto o texto que o próprio plugin escreve. Um mecanismo de templates relata os dados que estava avaliando, um validador de schema cita um valor que não satisfaz um pattern, um analisador cita o token que não conseguiu ler. Onde uma falha assim ocorreu sobre um valor que a entrada marca, relate-a sem o valor — por exemplo, execute de novo a mesma etapa com cada valor marcado substituído por um marcador de posição, relate a falha dessa execução quando ela falhar no mesmo lugar e, caso contrário, diga que o texto da falha foi retido. Sob um payload marcado como um todo, cada valor nesse payload é um valor marcado, enquanto suas chaves — a forma do documento — continuam legíveis.
Onde uma entrada marca uma chave ou um payload como sensível, escrito como os dados transmitidos o nomeiam:
| Socket e export | Onde a marcação é lida |
|---|---|
provedor render_node e validate_node_input (RenderNodeInput) | node.sensitive_rendered_keys: cada chave nomeia uma entrada de node.values quando esses valores são os do próprio Component, indexados pelas folhas que ele declara — o valuesMapping de uma Recipe escreve chaves que nenhuma declaração nomeia, então nenhuma delas é marcada aqui — ou uma entrada do mapa attachments do contêiner de uma carga de trabalho que lê um slot declarado sensível. node.sensitive_values marca node.values como um todo: é true quando um valuesMapping — o da Recipe, ou o da FeatureRecipe de uma vinculação — produziu esses valores e lê um valor que um autor declarou sensível. workload_projection.sensitive_workload marca da mesma forma cada valor da carga de trabalho quando o template da carga de trabalho lê um deles, e cada entrada de artifacts_projection.entries carrega sensitive_content para o seu próprio conteúdo, incluindo a mensagem de um analisador sobre esse conteúdo. Cada entrada de omits carrega sensitive quando o template que produz o seu kind, o seu nome ou o seu namespace lê um deles, e então cada campo dessa entrada é um valor marcado. Cada entrada de node.features carrega a marcação da sua própria vinculação: sensitive_payload_leaves (as folhas values.<path> e infra.<path> que sua Feature declara sensíveis), sensitive_inject (as chaves de entrega inject que leem uma chave provides que sua Feature declara sensível) e sensitive (se a vinculação lida ou não com material declarado sensível). |
governança ir-verdict (PolicyInput) | graph: as sensitive_payload_leaves de cada nó, e as sensitive_payload_leaves, sensitive_inject e sensitive de cada vinculação. Cada valor que essas marcações nomeiam já chega como o marcador de retenção {"aggrega_withheld": "declared"}, de modo que o próprio valor nunca chega ao plugin. |
Nenhuma outra entrada de socket, e nenhuma entrada de outro export de provedor, carrega uma marcação. Uma marcação de chave nomeia apenas o que ela liga exatamente a uma declaração, então uma chave ausente nunca significa que um valor pode ser citado com segurança: significa que nenhuma declaração pôde ser ligada a essa chave. Uma marcação de payload é lida a partir das referências do template que produziu o payload — uma referência que alcança um valor declarado, o template que repassa a totalidade dos seus dados, ou um template que não pode ser analisado — e nunca a partir de um valor, então sua ausência significa que esse template não leu nenhum valor declarado, até onde suas referências mostram, ou que nenhum template produziu o payload; não é uma afirmação de que o payload não carrega nada sensível.
Posicionamento dos sockets Wasm no pipeline
O pipeline de compilação reserva os seguintes pontos de socket. Os rótulos de forma seguem a taxonomia de quatro rótulos da página de status.
| Socket | Posicionamento no pipeline | Status atual |
|---|---|---|
Socket de governança, papel annotation-transform | Resolução (antes da expansão de anotações) | disponível — acionado quando um espaço de trabalho vincula um plugin annotation-transform; injeta anotações que a expansão transforma em vinculações de Feature |
Socket de governança, papel label-transform | Construção da topologia (o construtor de topologia) | disponível — acionado quando um espaço de trabalho vincula um plugin label-transform; adiciona automaticamente rótulos aos nós por meio de JSON Patch |
Socket de governança, papel ir-verdict | Análise estática (o analisador estático, sobre o grafo IR) | disponível — acionado quando um espaço de trabalho vincula um plugin ir-verdict; um veredito halt interrompe o build |
Socket de governança, papel render-verdict | Renderização (sobre os artefatos renderizados) | disponível — acionado quando um espaço de trabalho vincula um plugin render-verdict; um veredito halt interrompe o build |
Plugins de pipeline: da FeatureRecipe e da Recipe | O pipeline de plugins (mutação pós-renderização) | disponível — cada etapa declarada é executada sobre o conjunto de documentos renderizados, aplicando patches RFC 6902 e emitindo efeitos colaterais |
| Plugins de renderização de Provider (helm, helm-chart, compose, terraform, cloudformation) | Renderização base (os provedores) | disponível — cada provedor renderiza por meio do seu guest Wasm; a renderização é somente Wasm, sem renderizador de fallback dentro do host |
Plugins de analisador (parse:<format>) | Renderização, para uma política render-verdict; e fora de banda, para uma importação | disponível — chamado para um artefato em um formato que uma política render-verdict não lê nativamente, para um importador por meio de aggrega_parse_source, e para reconhecer o formato de uma importação que não indica nenhum |
Plugins de importador (import:<format>) | Fora de banda (aggrega import) | disponível — acionado por aggrega import, pela sessão do editor e pela ferramenta voltada ao assistente |
Plugins de linter (linter/publishing) | Fora de banda (aggrega lint) | disponível — o linter de publicação é distribuído e executado por meio do host com aggrega lint |
A subfase de expansão de Feature orientada por anotações, parte da resolução, é uma passagem nativa em Go do pipeline, não um socket Wasm. Ela valida os valores de anotação em relação ao spec.schema da Feature de destino e injeta vinculações de Feature sintéticas no momento do build do IR. Veja vocabulary/labels-and-annotations.md para as seis superfícies que carregam anotações e rótulos e providers/well-known-annotations.md para a forma das associações e as orientações para escrevê-las.
Contrato de forma de saída — o que existe hoje
O socket de governança oferece uma superfície de contrato tipada em cada um dos seus quatro papéis, e é o papel que determina qual. Os autores de Plugin implementam código do lado do guest que produz as formas documentadas; o host as lê em tempo de build, uma vez por plugin configurado, quando um espaço de trabalho vincula um plugin a esse papel. As subseções abaixo seguem a ordem em que o pipeline os aciona.
O papel annotation-transform — saída de injeção de anotações
Posicionamento no pipeline. Resolução, depois que os componentes são resolvidos e antes que a expansão de Feature orientada por anotações seja executada.
Forma de entrada (host → guest). Um documento AnnotationTransformInput contendo:
targets— os destinos da injeção: os componentes resolvidos que o guest pode anotar — aqueles que uma fronteira nomeia diretamente, e cada componente que uma entrada de roteamento sob osaggregates:de uma fronteira faz entrar, quer a entrada o nomeie ou não — cada um carregando seuboundary_path, seucomponent_name(para um componente roteado, seu id com pontos no grafo de build, comometrics.query) e asannotationsque a Release escreve nele, de modo que um guest pode decidir o que adicionar sem deslocar um valor escrito pelo autor. Cada valor de anotação chega como foi escrito — uma string, um objeto de subchaves, ounullonde o componente abre mão de uma anotação que herdaria — e cada chave que o componente carrega está presente, qualquer que seja o seu valor. Ordenados de forma determinística pelo host.binding_keys— as chaves de anotação para as quais o Manifest registra uma associação, na ordem do autor. Uma injeção sob uma chave registrada passa a se expandir em uma vinculação de Feature, então um guest lê esta lista para injetar chaves que terão efeito. O host não exige que uma injeção nomeie uma chave registrada: uma anotação injetada não registrada se comporta exatamente como uma anotação escrita pelo autor sem associação.sources— os arquivos de definição que a vinculação declarou sobwith.sources, cada um carregando seu caminho de nome base e seu conteúdo, ordenados por caminho.settings— o objeto de configurações de forma livre que a vinculação declarou sobwith.settings, entregue ao guest sem alteração.
settings e sources são o mesmo canal with, agnóstico em relação ao mecanismo, que todos os outros papéis leem, e ambos ficam ausentes quando a vinculação não declara nenhum. Como a saída deste papel molda o build, as configurações e o conteúdo das fontes da vinculação são fixados no arquivo de bloqueio da release no pull e reconstruídos a partir dele no build.
Forma de saída (guest → host). Um documento AnnotationTransformOutput contendo:
injections— as anotações a adicionar, em ordem. Cada uma nomeia uma coordenada de destino existente (boundary_pathecomponent_name) mais aannotation_keye o seuannotation_value: uma string, ou um objeto de subchaves, que alimenta uma associação que roteia várias subchaves de uma vez.
O host aplica somente adições de anotações, a coordenadas que ele mesmo forneceu, cada uma com um valor que um autor poderia escrever naquela anotação. Ele lê um valor injetado exatamente como lê o mesmo valor escrito na Release — as subchaves de um objeto na ordem em que o guest as escreveu — de modo que a expansão o encontra como encontra um valor escrito pelo autor. Uma injeção que nomeia uma coordenada que o payload não carrega, ou que carrega null, uma lista, um número, um booleano ou um objeto sem subchaves, interrompe o build com uma mensagem que nomeia a coordenada e a anotação, em vez de ser descartada ou aplicada silenciosamente; toda a saída é verificada antes que qualquer parte dela seja aplicada. Esse confinamento é o que delimita o papel: um operador que vincula um plugin aqui declarou injeção de anotações e nada além disso. Onde o build recusa mais tarde uma anotação injetada pela forma como ela roteia, por um valor de subchave que o schema da Feature associada não admite, ou por um pilar que uma anotação do lado da Release não pode usar, sua mensagem nomeia o plugin que a injetou e o papel ao qual ele está vinculado.
Codificação de transmissão. O payload e o resultado deste papel trafegam como CBOR canônico (RFC 8949 §4.2.1), nas duas direções. Um guest os lê e os escreve por meio dos pontos de entrada que os tipos de payload carregam — DecodeCBOR e EncodeCBOR em Go, decode_cbor e encode_cbor em Rust, decodeCBORAnnotationTransformInput e encodeCBORAnnotationTransformOutput em TypeScript — de modo que nenhuma biblioteca CBOR é necessária e nada analisa bytes à mão. Em Rust, o export recebe e retorna Vec<u8>; em TypeScript, ele lê Host.inputBytes() e escreve Host.outputBytes(...). As annotations de cada destino são um mapa que o schema marca como mapa que preserva a ordem, então elas trafegam como uma lista ordenada de entradas na ordem em que o destino as guarda, e um guest as lê por meio do contêiner do seu kit que mantém a ordem; cada valor trafega como os bytes do seu JSON, como faz o annotation_value de uma injeção na outra direção. settings trafega como os bytes do seu documento JSON, que um guest analisa como JSON para examinar o conteúdo. Uma resposta que não é um AnnotationTransformOutput nesta codificação — uma escrita como JSON, ou uma que carrega um campo de nível superior que a forma não declara — interrompe o build, nomeando o plugin e o seu export, em vez de ser lida como uma lista vazia de injeções. Chamado diretamente com aggrega plugin run-local --export transform_annotations, um guest recebe o payload JSON escrito pelo autor convertido para esta codificação, e sua resposta é lida como a forma de saída do export e impressa como JSON — uma resposta que não tem essa forma é recusada, nomeando o export, assim como um build a recusa.
Definições de tipos. Os tipos de transmissão de annotation-transform — AnnotationTransformInput, AnnotationTransformOutput, AnnotationTarget, AnnotationInjection, AnnotationSource — são publicados nos três pacotes ABI, gerados a partir de um único codec para que os três permaneçam sincronizados.
O papel label-transform — saída JSONPatch
Posicionamento no pipeline. Construção da topologia, depois que o grafo é achatado e antes que o grafo IR seja construído, de modo que os seletores de socket e de Feature que o analisador avalia leem os rótulos que o papel deixa.
Forma de entrada (host → guest). Um documento MutatorInput contendo:
compilation_context— a identidade da release (release_name,environment).graph— uma projeçãoMutatorGraphdos nós da topologia: de cada nó, seu Component, a versão resolvida, os rótulos e osvaluesque sua instância declara.settings— o objeto de configurações de forma livre que a vinculação declarou sobwith.settings, entregue ao guest sem alteração.sources— os arquivos de definição que a vinculação declarou sobwith.sources, cada um carregando seu caminho de nome base e seu conteúdo, de modo que um mutador pode ser guiado por um arquivo de regras ou de mapeamento versionado em vez de configurações inline.
O grafo é uma projeção, e não o grafo IR: cada nó carrega seu conjunto de rótulos resolvido e os valores que sua instância declara no Aggregate, enquanto as arestas e os payloads das funcionalidades permanecem dentro do compilador. Os valores são os do próprio Aggregate, com seus templates já avaliados em relação aos seus parâmetros, de modo que um valor elevado a um parâmetro chega como o valor que a Release forneceu; um valor padrão que o schema do Component declara, e qualquer coisa que uma Recipe ou uma Feature contribua, não estão entre eles, e um nó que não declara valores não carrega nenhuma chave values. Um valor que o Component do nó declara sensível é retido exatamente como o veredito sobre o grafo o retém — ele é lido como {"aggrega_withheld": "declared"} — enquanto cada valor irmão que nenhuma declaração alcança chega como foi escrito. É isso que permite que uma configuração declarada pelo desenvolvedor decida um rótulo — um banco de dados cujos valores habilitam uma extensão vetorial promovido a datastore.aggrega.ai/engine: vector, por exemplo. settings e sources são o mesmo canal with, agnóstico em relação ao mecanismo, que os papéis de veredito leem; o host os repassa e nunca interpreta seu conteúdo. Como a saída de um mutador molda o build, as configurações e o conteúdo das fontes da vinculação são fixados no arquivo de bloqueio da release no pull e reconstruídos a partir dele no build, de modo que a entrada do mutador é invariante a uma mudança em qualquer um dos dois após o pull, até o próximo pull.
Forma de saída (guest → host). Um documento MutatorOutput contendo:
patches— um array de documentos JSONPatch opacos (RFC 6902) que o host aplica somente aos rótulos dos nós; os valores que a entrada carregava são somente leitura.
Cada patch endereça os rótulos de um nó específico por meio de JSON Pointer (RFC 6901); o host aplica os patches na ordem do array e reincorpora o conjunto de rótulos modificado ao grafo IR. A função do papel label-transform é a rotulagem automática corporativa — adicionar rótulos de conformidade / observabilidade / atribuição de custos declarados pela política corporativa sem modificar o conteúdo do catálogo. A superfície de rótulos é o único alvo autorizado deste papel: um patch que toca um campo do nó diferente dos seus rótulos, adiciona ou remove um nó, ou define um valor de rótulo que não é uma string interrompe o build em vez de ser absorvido silenciosamente. A RFC 6901 é a referência de base da gramática de caminhos para toda superfície de caminho de documento em Aggrega — o contrato de plugins Wasm aqui, mais os exports *_path de .locals, mais os campos de schema *Path em outras partes do corpus. Veja 02-naming-conventions.md “Disciplina de sufixos de nomenclatura de caminhos de documento” para a declaração canônica dessa referência de base e a disciplina de sufixos *Path / *_path que distingue os dois lados da escrita.
Codificação de transmissão. O payload e o resultado deste papel trafegam como CBOR canônico (RFC 8949 §4.2.1), nas duas direções. Canônico significa que uma entrada idêntica produz bytes idênticos em cada lado, o que permite comparar um payload entre os três kits de plugin em vez de apenas codificá-lo e decodificá-lo de volta, e é por isso que a saída de um build permanece idêntica byte a byte. Um guest os lê e os escreve por meio dos pontos de entrada que o tipo de payload do seu kit já carrega — DecodeCBOR e EncodeCBOR em Go, decode_cbor e encode_cbor em Rust, decodeCBORMutatorInput e encodeCBORMutatorOutput em TypeScript — de modo que nenhuma biblioteca CBOR é necessária e nada analisa bytes à mão. Em Rust, o export recebe e retorna Vec<u8>; em TypeScript, ele lê Host.inputBytes() e escreve Host.outputBytes(...). Os nodes do grafo, os labels de cada nó e os values de cada nó são mapas que o schema marca como mapas que preservam a ordem, então eles trafegam como listas ordenadas de entradas — os nós na ordem em que o build os guarda, que é a ordem do autor, os rótulos de cada nó na ordem em que o nó os carrega, e os valores de cada nó na ordem em que o Aggregate os escreve — e um guest lê os três por meio do contêiner do seu kit que mantém a ordem. Cada valor trafega como os bytes do seu documento JSON: os kits de Go e Rust o entregam ao guest como esse JSON, para ser analisado tanto quanto uma regra precisar, e o kit de TypeScript como o valor já analisado.
Duas coisas que isso não muda. O array patches continua sendo JSON: o socket carrega cada documento de patch sem alteração como conteúdo opaco e nenhum dos lados lê seu interior, de modo que a forma própria de um documento de patch é independente da codificação que seu socket carrega. E settings e sources continuam sendo repassados sem alteração — settings chega como os bytes que a vinculação escreveu, que um guest analisa como JSON se precisar examinar o conteúdo.
Todos os outros papéis de governança carregam a mesma codificação — o papel annotation-transform e os dois papéis de veredito dizem isso cada um em sua própria seção — de modo que um guest que atende a mais de um papel fala CBOR canônico em cada papel que atende, lendo cada payload por meio do ponto de entrada de decodificação do seu próprio tipo.
Definições de tipos. Os tipos de transmissão do mutador — MutatorInput, MutatorOutput, CompilationContext, MutatorGraph, MutatorNode — são publicados nos três pacotes ABI (github.com/aggrega-ai/aggrega-abi/go, o crate aggrega-abi e @aggrega-ai/aggrega-abi), gerados a partir de um único codec para que os três permaneçam sincronizados. O host monta a entrada e aplica os patches que o guest retorna.
Os papéis de veredito — saída de array de vereditos
Um guest de política inspeciona um build e retorna uma lista de vereditos; o host age conforme a severidade de cada veredito e nunca interpreta a política em si. O tratamento completo — os quatro papéis, as severidades, o canal de entrada fornecido pelo operador, a escrita de uma política para qualquer um dos dois mecanismos que acompanham o compilador, o encapsulamento de um mecanismo de políticas externo, os guests de referência e como um operador vincula uma política — está na página do socket de governança. Esta seção registra o posicionamento no pipeline e as formas tipadas de transmissão.
Posicionamento no pipeline. Uma política é vinculada a exatamente um papel de veredito, que determina onde ela é avaliada:
ir-verdict— avaliado na análise estática, antes da renderização base. O analisador monta o payload em todo build.render-verdict— avaliado após a renderização, sobre os artefatos emitidos.
Quando um espaço de trabalho vincula um plugin de um papel de veredito, o pipeline serializa o payload desse papel para o plugin e lê de volta seus vereditos.
Forma de entrada (host → guest). O papel seleciona o payload:
- O
PolicyInputdeir-verdictcarregagraph— o grafo IR completo, agnóstico em relação às capacidades (a mesma forma que o construtor de topologia emite), com cada detalhe de nós, arestas e vinculações que o compilador mantém, exceto que um valor que um autor declarou sensível chega retido (veja Valores que uma entrada marca como sensíveis) — eprecalculated_paths, os caminhos de roteamento que o analisador enumera junto, de modo que uma política pode raciocinar sobre a alcançabilidade sem percorrer o grafo de novo. O grafo é o grafo IR versionado, com fonte única no schemair-v1beta1; a forma do IR não é secreta (é o mesmo grafo queaggrega inspectemite) e os segredos nele são ponteiros, nunca texto puro. - O
RenderPolicyInputderender-verdictcarregaartifacts— os arquivos de saída renderizados ordenados por caminho, de modo que os dados transmitidos são idênticos byte a byte entre execuções com entrada idêntica. Cada entrada carrega opathde saída do artefato e seucontentrenderizado; ela também carrega oformatem que foi renderizado, quando o provedor que o produziu declarou um, e umtree, a visão canônica analisada de um formato que o guest não lê nativamente, que o host analisa por meio do analisador resolvido e repassa de forma opaca. Ambos ficam ausentes quando não se aplicam — um formato que o guest lê nativamente (JSON, YAML) fica sem análise para que o guest o leia a partir decontent.
Os dois papéis carregam ainda as sources da vinculação (arquivos de definição de políticas que o host lê em tempo de build e entrega ao guest sem alteração, com os caminhos como nomes base e o conteúdo opaco) e as settings (um objeto de forma livre repassado sem alteração). Ambos ficam ausentes quando a vinculação não declara nenhum.
Forma de saída (guest → host). Um documento PolicyOutput contendo:
results— um array de entradasDiagnostic, cada uma com umaseverity(halt,warnouinfo) e uma stringmessage. Um veredito também pode definircode,rule_id,classification,source_ref,locationesuggestna mesma entrada; o host acrescenta ao veredito exibido aqueles que o veredito carregava, em toda rota de severidade.
Só aparecem os vereditos disparados; uma avaliação que permite retorna um array vazio. O host percorre os vereditos e mapeia cada severidade para uma ação: halt interrompe o build (exibindo cada mensagem halt), warn sinaliza o veredito e deixa o build prosseguir, info o registra sem afetar o resultado. Um halt interrompe o build por meio do mesmo ponto de controle que uma violação de seletor ou de appliesTo usa.
Codificação de transmissão. Os payloads dos dois papéis, e o PolicyOutput que um guest retorna em qualquer um deles, trafegam como CBOR canônico (RFC 8949 §4.2.1). Um guest os lê e os escreve por meio dos pontos de entrada que os tipos de payload carregam — DecodeCBOR e EncodeCBOR em Go, decode_cbor e encode_cbor em Rust, decodeCBORPolicyInput, decodeCBORRenderPolicyInput e encodeCBORPolicyOutput em TypeScript — de modo que nenhuma biblioteca CBOR é necessária e nada analisa bytes à mão. Em Rust, cada export recebe e retorna Vec<u8>; em TypeScript, ele lê Host.inputBytes() e escreve Host.outputBytes(...). Os mapas do grafo que preservam a ordem, entre eles seus nodes e os labels de cada nó, trafegam como listas ordenadas de entradas na ordem em que o build os guarda, e um guest os lê por meio do contêiner do seu kit que mantém a ordem; em que ordem uma política os encontra sob cada mecanismo de políticas está na página do socket de governança. settings, e o tree analisado de um artefato, trafegam como os bytes dos seus documentos JSON, que um guest analisa como JSON para examinar o conteúdo. Uma resposta que não é um PolicyOutput nesta codificação — uma escrita como JSON, ou uma que carrega um campo de nível superior que a forma não declara — interrompe o build, nomeando o plugin e o seu export, em vez de ser lida como uma lista vazia de vereditos. Chamado diretamente com aggrega plugin run-local --export verdict_ir ou --export verdict_render, um guest recebe o payload JSON escrito pelo autor convertido para esta codificação, e sua resposta é lida como a forma de saída do export e impressa como JSON — uma resposta que não tem essa forma é recusada, nomeando o export, assim como um build a recusa.
Definições de tipos. Os tipos de transmissão das políticas são publicados nos mesmos três pacotes ABI: PolicyInput (papel ir-verdict), RenderPolicyInput (papel render-verdict), o PolicySource compartilhado e PolicyOutput, cujas entradas results são valores Diagnostic. A severidade de um diagnóstico é um de três valores que todo socket compartilha — halt, warn ou info — e os três são publicados como constantes ao lado dos tipos de transmissão em cada um dos três pacotes, de modo que um guest reporta a partir do mesmo conjunto fechado sobre o qual o host roteia. Um guest que retorna qualquer outro valor interrompe o build, com a mensagem nomeando o plugin e o valor que retornou: uma severidade não roteável é um defeito do plugin que o host reporta, em vez de um diagnóstico que ele descarta.
Contrato de forma de saída — o pipeline de FeatureRecipe e os sockets de provedor
Os sockets abaixo oferecem superfícies de contrato tipadas que o compilador aciona em tempo de build. As etapas de pipeline: da FeatureRecipe e da Recipe são executadas no pipeline de plugins sobre o conjunto de documentos renderizados; o socket de renderização de provedores é executado na renderização base; o linter de publicação é executado fora de banda.
Patches RFC 6902 (o pipeline de plugins)
As etapas de pipeline: da FeatureRecipe e da Recipe executadas no pipeline de plugins emitem operações JSON Patch RFC 6902 sobre o conjunto de documentos renderizados. O host entrega a cada etapa o conjunto de documentos indexado por chave inteiro; a etapa seleciona pelo conteúdo os documentos que tem como alvo e retorna patches endereçados por chave, que o mecanismo de aplicação aplica aos documentos endereçados — tipicamente adicionando um contêiner sidecar, montando um volume de secret ou reescrevendo uma variável de ambiente. Uma etapa também retorna side_effects (abaixo), diagnostics — cada entrada na mesma forma compartilhada Diagnostic em que todo socket relata problemas — e outputs (abaixo). Descrito em examples/04-secrets.md.
Status atual: disponível. Cada etapa declarada é executada durante aggrega build.
Codificação de transmissão. A entrada de uma etapa (FRPStepInput) e sua resposta (FRPStepOutput) trafegam como CBOR canônico (RFC 8949 §4.2.1), nas duas direções. Um guest decodifica sua entrada e codifica sua resposta por meio dos pontos de entrada que os tipos de payload carregam — DecodeCBOR e EncodeCBOR em Go, decode_cbor e encode_cbor em Rust (nos tipos que o crate aggrega-abi publica), decodeCBORFRPStepInput e encodeCBORFRPStepOutput em TypeScript — lendo e escrevendo bytes (Vec<u8> em Rust, Host.inputBytes() e Host.outputBytes(...) em TypeScript). Nenhuma biblioteca CBOR é necessária e nada analisa bytes à mão. A entrada with da etapa (step_input), os outputs que ela retorna e os conjuntos de documentos own e host são mapas que o schema marca como mapas que preservam a ordem, então eles trafegam como listas ordenadas de entradas na ordem em que o pipeline os guarda, e um guest os lê e os escreve por meio do contêiner do seu kit que mantém a ordem — que é o que permite que as saídas de uma etapa cheguem a .steps.<id>.outputs na ordem em que a etapa as retornou. O tree de cada unidade, cada valor de step_input e outputs, o value de um patch, o crd de um efeito colateral e o context de renderização trafegam como os bytes dos seus documentos JSON, que um guest analisa como JSON para examinar o conteúdo; os bytes de uma unidade trafegam como uma sequência de bytes brutos que o decodificador gerado preenche no tipo de campo próprio do kit — um slice de bytes em Go, uma string base64 em Rust e TypeScript. Cada diagnóstico trafega na forma compartilhada Diagnostic. Uma resposta que não é um FRPStepOutput nesta codificação — uma escrita como JSON, ou uma que carrega um campo de nível superior que a forma não declara — faz a etapa falhar, nomeando a função que ela executa, o que interrompe o build a menos que a etapa seja optional. Chamada diretamente com aggrega plugin run-local --export step, uma etapa recebe o payload JSON escrito pelo autor convertido para esta codificação, e sua resposta é lida como a forma de saída do export e impressa como JSON — uma resposta que não tem essa forma é recusada, nomeando o export, assim como um build a recusa.
Efeitos colaterais — emissão de recursos (plugins de credenciais no pipeline de plugins)
Os pipelines de FeatureRecipe de credenciais (princípio do Plugin em duas partes: Fetcher + Injector) emitem recursos completos junto com um patch por meio dos side_effects de uma etapa, cada um declarando um dos dois tipos que o contrato define: emit_crd, um documento de recurso personalizado como um CRD ExternalSecret ou VaultSecret que o cluster busca em tempo de execução, ou emit_file, um arquivo escrito. Uma etapa que retorna qualquer outro tipo interrompe o build, nomeando o nó, o índice do efeito colateral e o tipo que declarou. A etapa do Fetcher emite o recurso completo; a etapa do Injector retorna um patch que monta o Secret do Kubernetes resultante. Descrito em examples/04-secrets.md.
Status atual: disponível.
Saída de etapa (mapa outputs de uma etapa de pipeline:)
Uma etapa do pipeline de plugins publica saídas nomeadas que as etapas seguintes consomem por meio de {{ .steps.<id>.outputs.<key> }}. A forma da saída é definida pelo provedor para cada plugin; as saídas das etapas têm como escopo o mesmo pipeline e são visíveis apenas para as etapas seguintes, na ordem de declaração. Documentado em templates/expansion-matrix.md, linha 10.
Status atual: disponível.
Renderização de Provider — o socket conduzido pelo guest
Um provedor é um guest Wasm. A renderização é somente Wasm: o nome de capability: de uma Recipe se resolve no Plugin de renderização de provedores (pluginType: provider) que lista esse nome em suas spec.provider.capabilities e anuncia um export render_node, e o guest desse plugin renderiza o nó. Não há renderizador dentro do host ao qual recorrer; um nome de provedor que não se resolve em nenhum Plugin que o atenda interrompe o build no momento do roteamento. Adicionar um provedor padrão é distribuir um guest .wasm e uma entidade Plugin do catálogo — o host não carrega código específico de provedor.
Uma capacidade que um provedor atende não contém dois-pontos, e o mesmo vale para uma com a qual uma etapa de pipeline se declara compatível. O capability: de uma Recipe é lido como a capacidade até seus últimos dois-pontos, seguida de uma fixação de versão — helm:1.0.0 pede helm na versão 1.0.0 — então um nome que contém dois-pontos é um que nenhuma Recipe pode pedir. O host recusa tal nome nas capabilities de describe() para um guest provider ou pipeline-step quando o guest é carregado e quando sua entidade é gerada para publicação, nomeando o guest e o nome. O parse:<format> de um analisador e o import:<format> de um importador mantêm seus dois-pontos: eles são procurados por formato, nunca por meio do capability: de uma Recipe.
O host é um roteador genérico. Ele lê o autorrelato describe() do guest — incluindo seu contrato de comportamento de renderização — e despacha os exports do guest sem entender nenhum formato de provedor. Esse contrato conduz o despacho como dados:
input_kinds(sourced,synthesized,artifacts_standalone) — quais tipos de entrada de Recipe o guest renderiza; o host verifica o tipo de entrada de um nó em relação a este conjunto.boundary_assembly(none|merge|nest) — como o guest combina a saída de um grupo de despacho:mergeclassifica a saída de cada nó como fragmentos que o montador mescla em um único artefato,nestaninha os arquivos de cada nó sob um invólucro montado,nonegrava diretamente a saída de cada nó.nest_segment(opcional) — para uma montagemnest, o diretório sob o qual o subdiretório próprio de cada contribuidor é colocado, escrito como um único nome de diretório; se ausente, o subdiretório de cada contribuidor fica diretamente na posição de despacho.assembly_name_annotation(opcional) — uma anotação de fronteira cujo valor resolvido nomeia o artefato que o guest monta a partir de um grupo de despacho; se ausente, o guest nomeia sua montagem apenas a partir do caminho de despacho.cross_boundary_linking(opcional) — se o guest conecta uma arestausesentre fronteiras por meio dos seus exportslink_publishelink_resolve; um guest o declara verdadeiro exatamente quando exporta ambos, e o carregamento recusa um guest cuja flag e cujos exports não coincidem.artifact_delimiters(opcional) — o par de delimitadores de template Go que o guest aplica aos corpos dos artefatos.reusable_instance(opcional) — se uma única instância carregada pode atender cada travessia do build (veja Determinismo e reutilização de instâncias abaixo).omits(opcional) — se o guest respeita as entradas de omissão que uma renderização de fonte carrega (veja Deixar de fora unidades renderizadas abaixo).boundary_artifacts(opcional) — se o destino do guest aceita os arquivos com que uma Recipe contribui para a saída compartilhada da sua fronteira (veja Aceitar os arquivos com que uma Recipe contribui para a fronteira abaixo).source_ignore(opcional) — os arquivos que o ecossistema do guest nunca distribui junto a uma fonte que ele renderiza (veja Declarar o que o ecossistema de uma fonte nunca distribui abaixo).
O socket é um conjunto fixo de exports — um obrigatório, os demais opcionais e anunciados em describe():
render_node(obrigatório) — renderiza um nó IR em arquivos nativos do provedor.assemble_boundary(opcional) — mescla a saída por nó de um grupo de despacho em um único artefato por caminho (presente quandoboundary_assemblyémergeounest).validate_node_input(opcional) — validação estrutural da entrada de um nó antes da renderização; um diagnósticohaltinterrompe o build, umwarnaparece no resultado do build.carve/reassemble(opcionais, em par) — o codec de patches próprio do guest, fiel byte a byte, para etapas de pipeline pós-renderização, usado apenas quando ambos são anunciados.name_bound(opcional) — o guest avalia se um nome que o host propõe como identidade de um componente gera nomes que o seu destino aceita, respondendo com uma restrição em vez de um nome próprio.rendered_name(opcional) — o guest informa o nome que o seu destino dá aos recursos que ele renderiza para um nó.link_publish/link_resolve(opcionais, em par) — o guest conecta uma arestausesentre fronteiras: a extremidade consumida publica um identificador, e a extremidade consumidora o resolve na sua própria saída montada.
Os artifacts: de uma Recipe se integram a render_node por meio de uma projeção de artefatos na entrada: o host faz a leitura de $import, a avaliação dos templates Go e o cálculo das chaves/valores de proveniência, e entrega ao guest cada entrada já lida e avaliada; o guest é responsável pelo posicionamento e pela emissão no formato que só ele conhece. Documentado em architecture/13-catalog-and-registry.md.
A entrada de uma renderização de fonte carrega os valores do nó em node.values, e node.values_mapped diz de onde eles vieram: é true quando são a saída do valuesMapping da Recipe — ou, para a renderização própria de uma vinculação, do da sua FeatureRecipe — e fica ausente quando são os valores próprios do componente repassados como foram escritos. Se um guest o lê ou não faz parte do contrato próprio desse guest. O provedor cloudformation associa os Parameters de um template proveniente de uma fonte apenas a valores que um mapeamento produziu, porque os valores próprios de um componente podem ter sido escritos para as outras entradas da Recipe; o provedor terraform escreve os argumentos de um módulo proveniente de uma fonte a partir dos valores que sua montagem recebe, e não lê a flag. Esses valores trafegam em cada nó renderizado de uma entrada de assemble_boundary para um nó renderizado a partir de uma fonte — os de um componente, quer um mapeamento os tenha produzido ou não, os de uma Feature vinculada somente onde o valuesMapping da sua FeatureRecipe os produziu — e a mesma flag trafega junto a eles e somente onde eles trafegam, de modo que um montador lê a mesma resposta que a renderização própria do nó leu; o provedor cloudformation a lê ali para saber quais parâmetros a associação de um nó preencheu, e recusa uma referência a um deles a partir de qualquer outro lugar da stack, incluindo o componente hospedeiro de uma Feature vinculada. A flag registra como os valores foram produzidos e nunca é derivada de uma chave ou de um valor.
Codificação de transmissão. Cada export deste socket recebe sua entrada e retorna sua saída como CBOR canônico (RFC 8949 §4.2.1), nas duas direções. Um guest decodifica sua entrada e codifica sua saída por meio dos pontos de entrada que os tipos de payload já carregam — DecodeCBOR e EncodeCBOR em Go, decode_cbor e encode_cbor em Rust, e em TypeScript as funções decodeCBOR e encodeCBOR de cada tipo, como decodeCBORRenderNodeInput e encodeCBORRenderNodeOutput — lendo e escrevendo bytes (Vec<u8> em Rust, Host.inputBytes() e Host.outputBytes(...) em TypeScript). Nenhuma biblioteca CBOR é necessária e nada analisa bytes à mão. O content de um arquivo renderizado, e todo outro campo de bytes, trafega como uma sequência de bytes brutos que o decodificador gerado preenche no tipo de campo próprio do kit: um slice de bytes em Go, uma string base64 em Rust e TypeScript. Os mapas que o schema marca como mapas que preservam a ordem — entre eles os values, features e uses de um nó, as derived_keys de uma resposta e os values de um contribuidor de uma montagem — trafegam como listas ordenadas de entradas na ordem em que o build os guarda, e um guest os lê por meio do contêiner do seu kit que mantém a ordem. Cada valor dos values de um nó trafega como os bytes do seu próprio documento JSON, de modo que as chaves dentro de um valor mantêm a ordem em que foram escritas; o mesmo vale para cada entrada de vinculação de features, o contexto de renderização, a carga de trabalho analisada, cada aresta enriquecida, cada unidade recortada e cada operação de patch, e um guest os analisa como JSON para examinar o conteúdo. Cada diagnóstico trafega na forma compartilhada Diagnostic. Uma resposta que não tem a forma de saída do seu export nesta codificação — uma escrita como JSON, ou uma que carrega um campo de nível superior que a forma não declara — interrompe o build, nomeando o export que ele chamou. Os exemplos de payloads nesta página estão escritos como JSON para facilitar a leitura. Chamado diretamente com aggrega plugin run-local --export render_node, ou com qualquer outro export do socket, um guest recebe o payload JSON escrito pelo autor convertido para esta codificação, e sua resposta é lida como a forma de saída do export e impressa como JSON — uma resposta que não tem essa forma é recusada, nomeando o export, assim como um build a recusa.
Status atual: disponível para os cinco provedores. O guest helm renderiza charts provenientes de uma fonte (resolvendo a raiz do chart), cargas de trabalho sintetizadas e artefatos independentes como manifestos planos do Kubernetes. O guest helm-chart monta um umbrella chart, aninhando o chart proveniente de uma fonte de cada nó como subchart, e carrega um codec de patches fiel byte a byte e delimitadores de artefato entre colchetes ([[ ]]). O guest compose renderiza arquivos compose provenientes de uma fonte e cargas de trabalho sintetizadas e mescla um grupo de despacho em um único docker-compose.yaml, ligando um serviço às redes dos componentes que o seu x-aggrega-networks-of nomeia. O guest terraform emite configuração Terraform sem alterações (HCL ou JSON) ou incorpora um módulo proveniente de uma fonte e fornece suas entradas como argumentos do bloco module desse componente, valida estruturalmente o HCL de um módulo proveniente de uma fonte antes da renderização, e compõe uma fronteira em uma única configuração raiz que declara cada componente como um bloco module cuja origem é o subdiretório próprio desse componente. O guest cloudformation renderiza templates provenientes de uma fonte e fragmentos de stack independentes, mescla um grupo de despacho em um único template de stack, e conecta uma aresta uses entre fronteiras por meio de link_publish e link_resolve. Cada um renderiza offline e de forma determinística.
Declarar os nomes que um guest deriva
Um guest de provedor geralmente deriva nomes de que sua saída precisa mas que ninguém escreveu — o identificador pelo qual um destino endereça um recurso, o nome sob o qual uma saída é publicada para que outra a referencie — a partir da identidade do nó e do recurso que está emitindo. Dois nós podem chegar a um mesmo nome sempre que as partes das quais são derivados coincidem, e como o nome vive dentro dos bytes do arquivo que o host escreve literalmente, o host não consegue ver o conflito: ele teria de analisar o formato do provedor para encontrá-lo, que é exatamente o conhecimento que permanece no guest.
Por isso render_node retorna em sua saída derived_keys opcionais, e a direção é invertida — em vez de o host inspecionar a saída, o guest declara e o host verifica:
{ "files": [ { "path": "stack.yaml", "content": "..." } ], "derived_keys": { "logical-ids": ["paymentsapiQueue", "paymentsapiTopic"], "export-names": ["aggrega--prod--api--orders-db--host"] }}Cada chave de derived_keys é um espaço de chaves que o guest nomeia, e cada espaço carrega os nomes que o guest derivou nele, em ordem de derivação. Tanto os nomes dos espaços quanto os nomes dentro deles são seu vocabulário: o host os lê apenas como strings a comparar quanto à igualdade dentro de um mesmo espaço. Ele não analisa um nome, não aprende o que um espaço ou um nome significa e nunca deriva um por conta própria — assim, uma única verificação cobre todo tipo de nome que qualquer provedor deriva, e um novo provedor não precisa de novo código no host. Nos tipos publicados, derived_keys é um mapa que mantém a ordem, de modo que os espaços trafegam na ordem em que seu guest os define.
O que o host faz com eles se resume a uma única pergunta: dentro de um espaço, cada nome declarado é distinto entre os contribuidores cuja saída se funde em uma única montagem? Dois contribuidores que declaram um mesmo nome em um mesmo espaço interrompem o build, e a interrupção nomeia o espaço, o nome e ambos os contribuidores, de modo que um autor pode agir sem ler o provedor. Nomes distintos, e nomes que por acaso coincidem entre dois espaços diferentes, passam.
Vale a pena conhecer três propriedades ao decidir o que declarar:
- O escopo é uma saída montada — o conjunto de contribuidores cujos arquivos se fundem. Um guest que quer unicidade em um escopo mais estreito ou mais amplo que esse expressa o escopo no nome do espaço que declara, o que deixa a escolha com você, e não com o host.
- Um contribuidor pode repetir um nome livremente. Um nó pode ser renderizado em várias travessias — uma renderização de fonte, uma síntese de carga de trabalho, um posicionamento de artefatos — e as declarações se fundem. O mesmo nome declarado duas vezes por um contribuidor é esse contribuidor descrevendo um mesmo recurso duas vezes, não um conflito.
- Declarar não altera nenhum byte. O campo é uma afirmação sobre o que o guest derivou, nunca uma alteração no que ele emitiu, de modo que a saída renderizada de um guest é idêntica quer ele declare, quer não. Omitir
derived_keysé válido e deixa a verificação inativa para esse guest.
Relatar fatos sobre o que um guest emitiu
Algumas coisas sobre a renderização de um nó são visíveis apenas para o provedor que a produziu — o que os documentos que ele escreveu contêm, quais nomes definem, quantos itens de algo ele emitiu — porque extraí-las dos bytes do arquivo significa entender o formato do provedor. render_node pode relatar essas coisas por conta própria, em uma lista opcional render_facts ao lado de seus arquivos:
{ "files": [ { "path": "stack.yaml", "content": "..." } ], "render_facts": [ { "name": "exported_outputs", "value": ["QueueUrl", "TopicArn"] }, { "name": "stacks", "value": [ { "name": "payments-api", "resources": 2 } ] } ]}Cada fato é um name e um value, e ambos pertencem ao seu provedor: quais fatos ele relata, o que cada nome significa e o que cada entrada contém fazem parte do contrato documentado próprio do seu provedor, então documente-os para os autores que vão lê-los.
Relate o valor de cada fato como uma lista — um array JSON — mesmo quando ela contém uma única entrada. Um mesmo nome pode ser relatado por mais de uma renderização de um componente: sua própria renderização pode envolver várias chamadas — uma renderização de chart e um posicionamento de artefatos, por exemplo — e cada Feature vinculada ao componente é renderizada por meio de uma chamada ao provedor própria. Nenhum provedor pode saber, ao renderizar, se seu relato será o único sob um nome, então todo relato é uma lista, e o compilador junta em uma única lista as listas que um nome recebe. Um fato cujo valor seja qualquer outra coisa — um objeto, uma string, um número, um booleano, null — é recusado quando seu guest o retorna: o build é interrompido com o código curto E0325, nomeando o fato, o nó e seu guest, e dizendo qual era o valor. As entradas dentro de uma lista são quaisquer valores JSON na forma que você documentar.
Que um valor seja uma lista é a única coisa que o compilador aprende sobre ele. Ele indexa os fatos por nome e entrega cada lista aos templates que a leem — os fatos do componente hospedeiro a cada Feature vinculada a ele, os fatos de cada chamador a uma Feature que declara ler os fatos de renderização de seus chamadores, e os fatos de cada destino a uma Feature que declara ler os fatos de renderização dos componentes aos quais seu componente hospedeiro está conectado, como descreve o contexto de template — decodificando cada lista em um valor que um template pode percorrer. Ele nunca aprende o que um nome ou uma entrada significa e nunca deriva um fato por conta própria, de modo que um novo provedor pode relatar novos fatos sem nenhuma alteração do lado do compilador. Os fatos que uma Feature vinculada ao nó relata a partir de sua própria renderização são mantidos separados dos que a renderização própria do nó relatou.
Vale a pena conhecer quatro propriedades ao decidir o que relatar:
- A ordem é sua. Os fatos mantêm a ordem em que seu guest os lista, e cada valor mantém seus próprios bytes — a ordem das entradas de uma lista e das chaves de cada objeto é a ordem que seu guest escreveu. Liste os fatos em uma ordem fixa e escreva cada entrada com uma ordem de chaves fixa, para que dados de entrada idênticos produzam bytes idênticos; uma lista de fatos em vez de um mapa existe justamente para que essa ordem sobreviva no tipo de sequência próprio de cada kit sem nada a marcar, enquanto um mapa mantém a ordem que um guest escreveu somente quando seu schema o marca como mapa que preserva a ordem e o guest preenche o contêiner que mantém a ordem do seu kit.
- Relatar não altera nenhum byte. Os arquivos que o compilador escreve são os arquivos que seu guest retornou, quer fatos os acompanhem, quer não.
- Um nó pode relatar em várias travessias. Um nó pode ser renderizado como renderização de fonte, síntese de carga de trabalho e posicionamento de artefatos; os fatos que cada uma relata são mantidos na ordem em que as travessias foram executadas, e um nome relatado por mais de uma delas é lido como uma única lista que as junta nessa ordem.
- Não relatar nada é completo. Omitir
render_factsé válido, e um provedor que não relata nada renderiza exatamente como faria sem o campo.
O tipo RenderFact é publicado nos três pacotes ABI e reexportado pelo kit de desenvolvimento de plugins de cada linguagem, e os exemplos de renderização dos kits relatam dois fatos ao lado de seus arquivos. Em Go, um valor é o JSON que seu guest escreve; serializar um slice de structs em vez de mapas é o que mantém as chaves de cada entrada na ordem em que você as declarou:
type stackFact struct { Name string `json:"name"` Resources int `json:"resources"`}
stacks, err := json.Marshal([]stackFact{{Name: "payments-api", Resources: 2}})if err != nil { pdk.SetError(err) return 1}out := aggrega.RenderNodeOutput{ Files: files, RenderFacts: []aggrega.RenderFact{{Name: "stacks", Value: stacks}},}Deixar de fora unidades renderizadas
Uma renderização de fonte pode nomear unidades que o provedor deve deixar de fora do que renderiza — um Secret que um chart obtido gera de novo a cada renderização, por exemplo. Qual unidade renderizada uma entrada nomeia é um conhecimento que só o seu provedor tem, então as entradas trafegam até o seu guest e é o seu guest que as deixa de fora. Elas chegam na entrada de render_node como uma lista opcional omits ao lado do source_listing:
{ "node": { "id": "payments-api" }, "context": { }, "source_listing": { "root": "/acquired/payments-chart", "root_is_dir": true, "entries": [] }, "omits": [ { "kind": "Secret", "name": "payments-api-token", "namespace": "payments" }, { "kind": "ConfigMap", "name": "payments-api-dashboards" } ]}Cada entrada é um kind, um name e um namespace opcional, já resolvidos em strings simples e listados na ordem em que o autor os declarou; uma entrada que não se aplica ao build não é transmitida. O que os três campos selecionam é o contrato próprio do seu provedor — o tipo, o nome e o namespace de um recurso no formato do seu destino — então documente-o para os autores que escrevem as entradas.
Um autor pode construir os campos de uma entrada a partir de um valor que declarou sensível — um recurso com o nome de uma configuração sensível, por exemplo. Uma entrada assim chega com "sensitive": true, e seu guest a trata como trata qualquer outro valor marcado que a entrada de renderização carrega (veja Valores que uma entrada marca como sensíveis): ele continua fazendo a correspondência e a contagem da entrada pelos seus campos, que é para o que a entrada serve, e mantém cada um de seus campos fora de uma recusa, de um aviso ou de uma linha de log. A marcação cobre a entrada inteira, porque o compilador não diz qual campo o valor produziu. Ela fica ausente quando nenhum campo foi construído a partir de um valor assim.
Um guest que respeita as entradas faz três coisas:
- Faz a correspondência de cada entrada com o que renderizou, nos termos do seu formato.
- Deixa cada unidade correspondente de fora de tudo o que retorna — seus
files, os nomes que declara emderived_keyse os fatos que relata emrender_facts— de modo que nada do que o compilador recebe ainda a descreve. - Relata uma contagem por entrada em uma lista opcional
omittedem sua saída, na ordem em que as entradas chegaram, cada uma o número de unidades com que aquela entrada correspondeu, contadas quer outra entrada também tenha correspondido a elas, quer não:
{ "files": [ { "path": "templates/deployment.yaml", "content": "..." } ], "omitted": [1, 0]}Um zero é uma resposta completa: aquela entrada não correspondeu a nada do que seu guest renderizou. As contagens são tudo o que volta sobre o que foi deixado de fora; as próprias unidades simplesmente estão ausentes do que seu guest retornou.
Um provedor que faz as três coisas declara isso com omits: true em seu contrato. A entidade Plugin registra a mesma declaração como spec.provider.contract.omits; onde a entidade carrega um contrato de comportamento de renderização, o carregamento recusa um guest cujo describe() relata um valor diferente. As entradas acompanham uma listagem da fonte e nada mais: uma renderização de uma carga de trabalho sintetizada ou de um conjunto de artefatos nunca as carrega.
Uma renderização que não carrega entradas não é alterada pelos campos. Ambos os campos são opcionais e ficam ausentes quando vazios, de modo que uma renderização que não carrega entradas atravessa o socket byte a byte como faria se os campos não existissem, e um guest que nunca os lê não é afetado por eles. O tipo OmitEntry é publicado nos três pacotes ABI e reexportado pelo kit de desenvolvimento de plugins de cada linguagem.
O que o compilador faz com sua resposta. As entradas vêm da chave omits: que um autor escreve em uma Recipe ou em uma FeatureRecipe (Recipe → O campo omits:); o compilador avalia os templates de cada entrada e entrega ao seu guest as que se aplicam. Em seguida, lê suas contagens, e somente suas contagens — nunca olha dentro de um arquivo retornado para verificá-las:
- Uma lista de contagens que não tem uma contagem não negativa por entrada entregue interrompe o build — ausente, curta demais, longa demais ou com uma contagem abaixo de zero — nomeando o nó, seu provedor, quantas entradas foram enviadas e quantas contagens voltaram. Um relato que não confere não deixa nenhuma forma de saber qual entrada deixou o quê de fora. Veja A provider’s omitted counts do not match the omits entries it was handed (As contagens de omissões de um provedor não correspondem às entradas omits que ele recebeu).
- Um zero interrompe o build, nomeando a primeira entrada, na ordem do autor, cuja contagem é zero: o nó, seu provedor, a posição da entrada na lista que seu documento declara, e o tipo, o nome e o namespace em que ela foi resolvida. Seu guest relata o zero; a interrupção é do compilador. Veja An omits entry left out nothing the source rendered (Uma entrada omits não deixou de fora nada do que a fonte renderizou).
- Um documento que declara
omits:cujo provedor não declaraomits: trueé recusado antes que qualquer coisa seja renderizada, de modo que um autor fica sabendo imediatamente que a chave não teria efeito, em vez de encontrar o documento na saída. O compilador lê sua declaração do seudescribe()assim que cada Recipe e FeatureRecipe do build está associada, e recusa antes que o primeiro componente seja renderizado — assim, um guest que não declara a chave nunca recebe uma entrada. A recusa nomeia o provedor e o componente para o qual o documento renderiza, ou, para uma FeatureRecipe que gera uma única vez para uma fronteira, a fronteira e a vinculação. Veja The provider does not support omits (O provedor não oferece suporte a omits).
Status atual: disponível. Os guests helm, compose e cloudformation distribuídos com o compilador fazem a declaração e respeitam as entradas. O guest helm não escreve nenhum campo de nenhuma entrada em um texto que retorna. Os guests compose e cloudformation nomeiam o tipo, o nome e o namespace de uma entrada quando recusam a entrada, e as unidades que uma entrada deixou de fora quando recusam um arquivo ou um template que ainda as nomeia, e mostram ali cada campo de uma entrada marcada como <redacted>. Os guests helm-chart e terraform não fazem a declaração, então um documento que declara omits: e que um deles renderiza é recusado.
Aceitar os arquivos com que uma Recipe contribui para a fronteira
Alguns arquivos pertencem a uma fronteira como um todo, e não a um de seus componentes — uma configuração de provedor que um destino lê uma única vez para tudo o que a fronteira implanta, por exemplo. Uma Recipe os escreve sob spec.boundary.artifacts, e é o compilador, não o seu guest, que faz o trabalho: ele avalia cada arquivo no contexto em que uma entrada artifacts: é avaliada, funde por nome os arquivos que cada contribuidor do grupo de despacho declarou, e escreve cada um uma única vez no diretório que contém a saída montada do grupo, ao lado do que o seu assemble_boundary retorna. Seu guest não recebe nenhum desses arquivos em nenhum export e nunca é consultado sobre nenhum deles, então não há nada a implementar — apenas uma afirmação a fazer sobre o seu destino:
"contract": { "input_kinds": { "sourced": true, "artifacts_standalone": true }, "boundary_assembly": "nest", "boundary_artifacts": true}Declare boundary_artifacts: true somente quando o seu destino lê um arquivo colocado nesse diretório como parte da saída da fronteira. A entidade Plugin registra a mesma declaração como spec.provider.contract.boundaryArtifacts; onde a entidade carrega um contrato de comportamento de renderização, o carregamento recusa um guest cujo describe() relata um valor diferente. Uma Recipe que declara o bloco cujo provedor não o declara é recusada antes que qualquer coisa seja renderizada, nomeando o provedor e o componente; veja The provider does not support boundary artifacts (O provedor não oferece suporte a artefatos de fronteira). Um arquivo que uma dessas fusões coloca sob um nome que sua montagem também escreve interrompe o build como dois contribuidores escrevendo um mesmo caminho de saída, de modo que os nomes que sua montagem escreve fazem parte do que você documenta para os autores.
Status atual: disponível. O guest terraform distribuído com o compilador faz a declaração, e o Terraform lê cada arquivo ao lado da configuração raiz da fronteira; os guests helm, compose, helm-chart e cloudformation não a fazem.
Declarar o que o ecossistema de uma fonte nunca distribui
O diretório de fonte local de uma Recipe — um chart colocado junto a ela, um módulo — é publicado com a Recipe, e nem todo arquivo nele pertence a ela. Um guest de provedor declara o que o seu próprio ecossistema nunca distribui por meio de source_ignore no seu contrato, como regras de exclusão na sintaxe que .gitignore usa:
"contract": { "input_kinds": { "sourced": true, "synthesized": false, "artifacts_standalone": false }, "boundary_assembly": "none", "source_ignore": { "patterns": [".git/", ".hg/", ".svn/", ".bzr/", "templates/.?*"], "files": [".helmignore"] }}patternssão regras lidas a partir da raiz do diretório da fonte, aplicadas em ordem, com uma correspondência posterior prevalecendo sobre uma anterior.filesnomeia os arquivos de exclusão que o seu ecossistema respeita dentro de uma fonte. Onde quer que a varredura de uma fonte encontre um deles, suas linhas são lidas como regras adicionais para o diretório que o contém, depois dos seus padrões.
A declaração é lida quando uma entidade é fixada, não quando é renderizada. A etapa de fixação do autor resolve, no espaço de trabalho dele, o plugin que atende a capacidade da entidade, compõe as suas regras com o .aggregaignore dele — cujas linhas vêm por último e, por isso, prevalecem em qualquer caminho que nomeiem — e registra o nome do seu plugin, sem versão, junto com as regras compostas exatas, no entity.lock da entidade. Cada publicação, comparação e renderização posteriores dessa entidade aplicam as regras registradas; o host faz a correspondência e não tem nenhuma opinião própria sobre nenhum ecossistema. Assim, os arquivos que o seu guest recebe na renderização — a listagem e cada arquivo que ele pede ao host para empacotar ou ler — são exatamente os arquivos que uma publicação da entidade carrega, e um arquivo que as regras deixam de fora é respondido como inexistente, com seu nome. Um link simbólico dentro de uma fonte é recusado antes que o seu guest seja invocado.
A compatibilidade decorre do que foi registrado. Um guest pode renderizar uma Recipe publicada para a sua capacidade quando fala a mesma versão da ABI, o seu contrato corresponde à declaração da sua entidade e ele não precisa de nenhum arquivo fora do conjunto publicado. Um guest que precisa de um arquivo que o conjunto deixou de fora deve fazer o seu build falhar de forma visível e nomear o arquivo — a recusa do host a um empacotamento ou a uma leitura o nomeia, e um guest leva isso para a sua própria falha. Onde o plugin que o espaço de trabalho de um consumidor associa a uma capacidade declara regras diferentes das que o arquivo de bloqueio de uma entidade registra, o pull do consumidor imprime um aviso que nomeia ambos os plugins e a diferença; ele nunca é interrompido por isso.
Omitir source_ignore não declara nenhuma regra, e uma fonte que você renderiza mantém então todo arquivo que as regras próprias do autor mantêm. O campo é opcional e não precisa de uma versão de ABI própria: um guest que o omite é carregado como um que não declara nada. A entidade Plugin registra a mesma declaração como spec.provider.contract.sourceIgnore; quando o faz, o carregamento recusa um guest cujo describe() informa algo diferente.
Determinismo e reutilização de instâncias
O host consome os bytes de saída de um guest literalmente, então um guest deve produzir saída idêntica a partir de entrada idêntica. Por padrão, um guest é carregado do zero para cada nó — nenhum estado é transportado entre nós, por construção. Um guest que autodeclara reusable_instance é, em vez disso, carregado uma vez por build e a sua única instância atende cada travessia, o que recupera o custo dominante de instanciação por nó. Como a reutilização só é segura para um guest sem estado, aggrega build --verify-determinism renderiza cada nó duas vezes pela mesma instância e interrompe o build se as duas renderizações de qualquer nó diferirem; o build padrão renderiza uma vez e confia na declaração. O cache de compilação do Wasm fica em disco e é compartilhado por todo o processo, então um guest é compilado uma vez e builds a quente pulam a recompilação.
O socket de linter — o linter de publicação
O socket de linter é distribuído como o publishing-linter padrão, um ponto de controle fora de banda executado por meio de aggrega lint em vez de em tempo de compilação. Ele consome uma entidade do catálogo (e, no modo --pre-publish, a versão atualmente publicada da entidade) e retorna uma lista de achados, cada um com uma severidade e uma mensagem; no modo --pre-publish, também retorna uma classificação do incremento de versão. O host o despacha por meio do runtime Wasm embutido, atrás do mesmo firewall de pureza AOT de todos os outros sockets. O conjunto completo de regras, as severidades e as exclusões por regra estão documentados em cli/aggrega-lint.md.
O linter é uma disciplina de catálogo de adesão opcional: o compilador não o executa durante aggrega build (com a única exceção do aviso que desaconselha x-aggrega-*, que aparece com severidade warn durante o build e com severidade halt sob aggrega lint --pre-publish). Como as regras ficam em um plugin, uma empresa pode apontar aggrega lint para um plugin de linter diferente para impor a sua própria disciplina.
Nenhum valor de parâmetro chega a um plugin de linter, em qualquer escopo em que aggrega lint seja executado. Antes de qualquer documento ser entregue, o host retém os valores padrão dos parâmetros de um Aggregate, os valores que ele passa a cada módulo que importa e os parâmetros de uma Release, mantendo o contrato de cada declaração de parâmetro — apenas as chaves com que uma declaração é escrita, em cada nível de aninhamento — e qualquer texto de template que leia um parâmetro: o valor de um parâmetro pode ser ele próprio uma credencial, e o plugin vinculado aqui pode ser código que o espaço de trabalho não escreveu. O que cada documento carrega está descrito em O que um plugin de linter recebe.
Codificação de transmissão. A entrada e a saída trafegam ambas como CBOR canônico (RFC 8949 §4.2.1). Um guest decodifica sua entrada e codifica sua saída por meio dos pontos de entrada que LinterInput e LinterOutput do seu kit já carregam — DecodeCBOR e EncodeCBOR em Go, decode_cbor e encode_cbor em Rust, decodeCBORLinterInput e encodeCBORLinterOutput em TypeScript — lendo e escrevendo bytes (Vec<u8> em Rust, Host.inputBytes() e Host.outputBytes(...) em TypeScript). Nenhuma biblioteca CBOR é necessária e nada analisa bytes à mão. Os documentos de entidade — proposed, previous, implemented_component e release — e cada valor de components trafegam como os bytes dos seus documentos JSON, então um guest os analisa como JSON para examinar o conteúdo. components é um mapa que o schema marca como mapa que preserva a ordem, então, na entrada de uma regra que lê uma Release inteira, ele trafega como uma lista ordenada de entradas na ordem em que o Aggregate declara suas instâncias de componente, e um guest o lê por meio do contêiner do seu kit que mantém a ordem. policies trafega como um mapa que contém apenas as flags definidas, então uma flag que ele não contém é lida como falsa, e cada achado trafega na forma compartilhada Diagnostic. Uma resposta que não é um LinterOutput nesta codificação — uma escrita como JSON, ou uma que carrega um campo de nível superior que a forma não declara — faz o lint falhar, nomeando o export chamado, em vez de ser lida como uma execução que não encontrou nada. Chamado diretamente com aggrega plugin run-local --export lint_rules, um linter recebe o payload JSON escrito pelo autor convertido para esta codificação, e sua resposta é lida como a forma de saída do export e impressa como JSON — uma resposta que não tem essa forma é recusada, nomeando o export, assim como um build a recusa.
Status atual: disponível. O publishing-linter é distribuído e executado por meio do host via aggrega lint.
O socket de analisador — saída de árvore canônica
Um analisador transforma uma fonte escrita em um formato que o compilador não lê nativamente em uma árvore estruturada canônica, de modo que um consumidor lê a árvore em vez de carregar um analisador próprio. O host resolve o analisador que anuncia o formato solicitado como parse:<format> e chama o seu export parse em três pontos: quando uma política do papel render-verdict recebe um artefato renderizado em um formato que ela não lê nativamente, quando um importador pede ao host uma árvore por meio de aggrega_parse_source, e quando uma importação que não nomeia nenhum formato é reconhecida (veja o socket importador abaixo). Um guest nunca chama um analisador diretamente.
Forma de entrada (host → guest). Um documento ParseInput contendo:
format— o formato solicitado, uma das capacidadesparse:<format>do analisador sem o seu prefixo.bytes— os bytes da fonte.options— um documento de opções que o consumidor fornece para um comportamento específico do analisador, repassado literalmente. Ausente quando o consumidor não fornece nenhum.
Forma de saída (guest → host). Um documento ParseOutput contendo o tree — a fonte analisada como um documento JSON, cujo nível superior pode ser um objeto, um array ou um escalar — eventuais diagnósticos na forma compartilhada Diagnostic, intervalos de fonte opcionais que localizam nós da árvore nos bytes originais, e uma falha em error quando a análise não pôde ser concluída. Cada campo e suas restrições estão na referência do schema do socket de analisador gerada.
Codificação de transmissão. A entrada e a saída trafegam ambas como CBOR canônico (RFC 8949 §4.2.1), a codificação em que o mesmo ParseInput trafega quando um guest o entrega a aggrega_parse_source. Um guest decodifica sua entrada e codifica sua saída por meio dos pontos de entrada que ParseInput e ParseOutput do seu kit já carregam — DecodeCBOR e EncodeCBOR em Go, decode_cbor e encode_cbor em Rust, decodeCBORParseInput e encodeCBORParseOutput em TypeScript — lendo e escrevendo bytes (Vec<u8> em Rust, Host.inputBytes() e Host.outputBytes(...) em TypeScript). Nenhuma biblioteca CBOR é necessária e nada analisa bytes à mão. Os bytes da fonte trafegam como uma sequência de bytes brutos, e o decodificador gerado os preenche no tipo de campo próprio do kit: um slice de bytes em Go, uma string base64 em Rust e TypeScript. options e tree trafegam como os bytes dos seus documentos JSON, de modo que a árvore que um analisador escreve chega ao seu consumidor literalmente. Um analisador que não consegue concluir diz por quê no error da saída, e a análise falha nomeando o analisador e essa mensagem; uma resposta que não é um ParseOutput nesta codificação — uma escrita como JSON, ou uma que carrega um campo de nível superior que a forma não declara — também faz a análise falhar, nomeando o analisador e o seu export parse. Uma análise com falha interrompe um build no papel render-verdict e chega a um importador como a falha com que aggrega_parse_source responde. O mesmo vale para uma fonte que o analisador recusa — uma à qual ele responde com um diagnóstico halt junto à sua árvore: a chamada do importador falha com a mensagem de cada um desses diagnósticos, na ordem do analisador, e nunca recebe a árvore. Chamado diretamente com aggrega plugin run-local --export parse, um analisador recebe o payload JSON escrito pelo autor convertido para esta codificação — a fonte escrita nesse payload como base64, assim como JSON escreve qualquer campo de bytes — e sua resposta é lida como a forma de saída do export e impressa como JSON — uma resposta que não tem essa forma é recusada, nomeando o export, assim como um build a recusa.
Definições de tipos. Os tipos de transmissão do analisador — ParseInput, ParseOutput, NodeSpan e SourceSpan — são publicados nos três pacotes ABI e reexportados pelo kit de desenvolvimento de plugins de cada linguagem, gerados a partir de um único codec para que os três permaneçam sincronizados. O exemplo parse de cada kit lê sua entrada e escreve sua saída dessa forma, e o mesmo fazem os analisadores para HCL, TOML, YAML, JSON e JSON com comentários que são distribuídos dentro do binário.
Status atual: disponível — despachado no papel render-verdict para um artefato em um formato que a política não lê nativamente, por meio de aggrega_parse_source para um importador, e para reconhecer o formato de uma importação que não nomeia nenhum.
O socket de importador — saída de rascunhos de autoria
Um importador transforma uma fonte escrita para outra ferramenta — um fluxo exportado de um construtor de agentes, por exemplo — em arquivos de autoria do Aggrega em rascunho. Ele é executado fora de banda: aggrega import, o método aggrega/import da sessão do editor e a ferramenta import voltada ao assistente resolvem o importador que anuncia o formato solicitado como import:<format> e chamam o seu export import uma vez por importação. Um build nunca o despacha. Qual importador é executado, e o que um operador lhe entrega, está descrito em Qual importador transforma uma fonte em rascunhos. Os importadores próprios do compilador, um para cada formato que ele lê, estão descritos em Importadores core: quais são esses formatos, o que cada um lê, o que gera como rascunho, as configurações que aceita, sua publicação a cada versão do compilador e como uma importação baixa e verifica um que a máquina ainda não contém.
Forma de entrada (host → guest). Um documento ImportInput contendo:
format— o formato que a importação solicitou, uma das capacidadesimport:<format>do importador sem o seu prefixo.bytes— os bytes da fonte: o arquivo inteiro para uma importação de um arquivo, e vazio para uma importação de um diretório, cujos arquivos chegam emsources.name— o nome da fonte, sem diretório antes dele, para que o importador possa nomear a fonte naquilo que relata e naquilo que gera como rascunho: para uma importação de um arquivo, o nome base do arquivo do qualbytesfoi lido; para uma importação de um diretório, o nome base do próprio diretório, lido do seu caminho completo, de modo queaggrega import .entrega o nome do diretório em que é executado, enquanto os arquivos do diretório continuam chegando cada um com seu próprio nome. Ausente onde a fonte não tem nome a dar.sources— as fontes nomeadas, cada uma com seu nome e seus bytes, em uma única lista ordenada por nome: para uma importação de um diretório, cada arquivo dele que os padrões de arquivo declarados do importador selecionam, excluída a pasta de saída de build do workspace, nomeado pelo seu caminho separado por barras dentro do diretório; e os arquivos que a entradaplugins.importerque vincula este importador declara emwith.sources, cada um com seu nome base. Um arquivo do diretório e um arquivo dewith.sourcescom o mesmo nome fazem a importação ser recusada, em vez de um esconder o outro. Ausente onde não há nenhuma.settings— o objeto de configurações que essa entrada declara emwith.settings, como um documento JSON com suas chaves ordenadas, repassado literalmente. Ausente quando nenhuma entrada vincula o importador ou a entrada não declara nenhuma.catalog— uma visão dos Components que o catálogo próprio do espaço de trabalho contém: o catálogo do qual o próprio importador foi selecionado — as pastas de catálogo do espaço de trabalho ou, onde ele não nomeia nenhuma, o snapshot do catálogo que seu registro padrão publica, mantido nesta máquina —, sem que nada seja baixado para a própria visão. Sua listacomponentscontém uma entrada por nome de Component, ordenada por nome; onde o catálogo contém várias versões de um Component, a entrada descreve a versão para a qual se resolve uma referência que o nomeia sem versão. Cada entrada carrega onamee aversiondo Component, seuslabels, os nomes das chaves de nível superior que seus values e provides declaram (valueseprovides, cada um ordenado), e seussockets— cada um com onamedo socket e oselectorde rótulos que uma dependência conectada por meio dele deve satisfazer — na ordem em que o Component os declara. Um Component que estende outro carrega o que herda além do que declara, e os sockets que herda vêm primeiro. A visão contém apenas nomes, versões, rótulos e seletores — nunca um valor, um valor padrão ou um segredo — e sua ordem é fixa, de modo que um catálogo produz uma única sequência de bytes. Ausente quando o catálogo não contém nenhum Component.
Forma de saída (guest → host). Um documento ImportOutput contendo as entidades que a importação produziu — cada uma uma referência a uma entidade de catálogo existente ou um corpo gerado como rascunho — as decisões de mapeamento por trás delas, eventuais diagnósticos na forma compartilhada Diagnostic, os arquivos de scaffold a escrever, e uma falha em error quando a importação não pôde ser concluída. Cada campo e suas restrições estão na referência do schema do socket de importador gerada.
Codificação de transmissão. A entrada e a saída trafegam ambas como CBOR canônico (RFC 8949 §4.2.1). Um guest decodifica sua entrada e codifica sua saída por meio dos pontos de entrada que ImportInput e ImportOutput do seu kit já carregam — DecodeCBOR e EncodeCBOR em Go, decode_cbor e encode_cbor em Rust, decodeCBORImportInput e encodeCBORImportOutput em TypeScript — lendo e escrevendo bytes (Vec<u8> em Rust, Host.inputBytes() e Host.outputBytes(...) em TypeScript). Nenhuma biblioteca CBOR é necessária e nada analisa bytes à mão. settings trafega dentro do documento binário como os bytes do seu documento JSON, de modo que um guest o analisa como JSON para examinar o conteúdo, como em qualquer outro socket. Um importador que não consegue concluir diz por quê no error da saída, e a importação é interrompida nomeando o importador e essa mensagem; uma resposta que não é um ImportOutput nesta codificação — uma escrita como JSON, ou uma que carrega um campo de nível superior que a forma não declara — também interrompe a importação, nomeando o importador e o seu export import. Chamado diretamente com aggrega plugin run-local --export import, um importador recebe o payload JSON escrito pelo autor convertido para esta codificação, e sua resposta é lida como a forma de saída do export e impressa como JSON — uma resposta que não tem essa forma é recusada, nomeando o export, assim como um build a recusa.
Como uma fonte do seu formato é reconhecida. Uma importação pode não nomear nenhum formato, e o host então reconhece um a partir do que os importadores declaram, sem conhecer por si só nenhum formato. Um importador declara no seu autorrelato describe(), em importer (um ImporterContract), uma lista detect das assinaturas pelas quais uma fonte dos seus formatos é reconhecida. Cada DetectSignature nomeia:
syntax— o formato sintático em que a fonte é analisada, um formato que um plugin de analisador anuncia comoparse:<syntax>, comojsonouyaml;files— padrões opcionais de nome de arquivo comparados com o final do nome da fonte: um segmento com o próprio nome do arquivo, vários segmentos separados por barras com o mesmo número de segmentos finais do seu caminho, com*,?e[...]correspondendo dentro de um segmento. Uma assinatura que não declara nenhum se aplica a uma fonte que é um único arquivo, qualquer que seja seu nome, e a nenhum arquivo de um diretório;match— os predicados que a árvore analisada deve satisfazer todos, cada um umPathMatchcom umpathde chaves unidas por pontos a partir do topo da árvore (um segmento de número inteiro seleciona uma posição de array), umisentrepresent,absent,object,array,string,numberouboolean, e opcionalmente uma stringequalsou uma stringprefix— no máximo uma das duas.
Quando uma importação não nomeia nenhum formato, o host compara as assinaturas de cada importador entre os quais a importação escolhe — os do catálogo do espaço de trabalho e os importadores core do compilador — na ordem de sua identidade e versão: ele analisa a fonte por meio do analisador que o catálogo serve para uma sintaxe — ou, para uma sintaxe para a qual o catálogo não serve nenhum analisador, aquele que o próprio compilador carrega — no máximo uma vez por sintaxe, avalia os predicados sobre a árvore e lê a fonte como o formato do único importador cuja assinatura corresponde. Esse é também o analisador por meio do qual a chamada aggrega_parse_source de um importador é respondida, de modo que um importador lê sua fonte por meio do analisador pelo qual ela foi reconhecida. Uma fonte que não é analisada em uma sintaxe não corresponde a nenhuma assinatura que a nomeia; uma sintaxe para a qual nem o catálogo nem o compilador servem um analisador interrompe o reconhecimento, nomeando a ausência do analisador. Uma fonte à qual nenhuma assinatura corresponde é recusada pedindo o formato, e uma reconhecida como mais de um formato é recusada nomeando-os. Uma assinatura reconhece uma fonte como cada formato que seu importador anuncia, de modo que um importador cujas fontes devem ser reconhecidas serve um único formato, e um que não declara nenhuma assinatura só é alcançado nomeando seu formato.
A entidade Plugin do importador registra a mesma lista como spec.importer.detect, derivada de describe() quando a entidade é gerada a partir do guest; o reconhecimento lê esse registro, de modo que o guest não é carregado até que seu formato esteja definido. Carregar e publicar o guest recusam um cujo autorrelato difere do registro da sua entidade, nomeando importer.detect, e uma entidade que não registra nenhuma não declara nada. O descritor é recusado no carregamento quando o contrato é declarado em um plugin que não é um importador, quando uma assinatura não nomeia nenhuma sintaxe ou nomeia um padrão de arquivo malformado, e quando um predicado não nomeia nenhum caminho, nomeia um is fora dos sete, ou nomeia tanto equals quanto prefix.
Os importadores core do compilador e o exemplo import do kit Go declaram as suas dessa forma. O importador Langflow lê uma fonte como JSON e pede um array em data.nodes; o importador Flowise pede arrays em nodes e edges e nada em data.nodes; o importador n8n pede um array em nodes, um objeto em connections e nada em edges nem em data.nodes; o importador MCP declara uma assinatura por configuração de cliente, nomeando seu arquivo — .mcp.json, claude_desktop_config.json e .cursor/mcp.json, lidos como JSON com um objeto em mcpServers, e .vscode/mcp.json, lido como JSON com comentários, como o Visual Studio Code o lê, com um objeto em servers — e uma que não nomeia nenhum arquivo e pede uma string $schema que comece com https://static.modelcontextprotocol.io/schemas/; o importador Compose lê uma fonte como YAML, nomeia os arquivos que o Compose lê por padrão — compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml e seus quatro arquivos de sobrescrita — e pede um objeto em services; o importador Dify lê uma fonte como YAML, não nomeia nenhum arquivo e pede a string app em kind e algo em app.mode e em version; o importador CrewAI nomeia config/agents.yaml e config/tasks.yaml, lidos como YAML sem nada pedido à árvore, crew.jsonc e crew.json, lidos como JSON com comentários com uma lista em agents, e agents/*.jsonc e agents/*.json, lidos como JSON com comentários com algo em role, de modo que nenhum par deles corresponde a uma mesma fonte, e um arquivo importado sozinho sem nenhum formato nomeado é lido como YAML além de como JSON; o importador LangGraph nomeia langgraph.json, lido como JSON com um objeto em graphs, declara uma assinatura que não nomeia nenhum arquivo e pede um objeto em graphs e a string https://langgra.ph/schema.json em $schema, e não nomeia nenhum arquivo de ambiente, já que o reconhecimento lê todo arquivo que os padrões de qualquer importador selecionam, de modo que um padrão que nomeasse um abriria os arquivos de ambiente de cada diretório importado sem nomear nenhum formato; o importador Google ADK nomeia root_agent.yaml, lido como YAML com algo em name e em instruction, ou uma string em agent_class e algo em name, e não nomeia nenhum outro arquivo, já que a configuração de um subagente pode ter qualquer nome e um padrão que nomeasse todo arquivo YAML abriria cada um deles em cada diretório importado sem nomear nenhum formato; o importador Agent Framework lê uma fonte como YAML, não nomeia nenhum arquivo e pede a string Prompt em kind e um objeto em model; o exemplo import do kit Go lê uma fonte como YAML e pede a string DemoSource em kind. Em Go:
Importer: &aggrega.ImporterContract{Detect: []aggrega.DetectSignature{{ Syntax: "json", Match: []aggrega.PathMatch{{Path: "data.nodes", Is: "array"}},}}},O que uma importação de um diretório lê. Uma fonte pode ser um diretório, e os padrões de arquivo declarados do importador decidem o que ele lê: o host lê exatamente os arquivos do diretório, em qualquer profundidade, que um dos padrões files das assinaturas do importador seleciona — cada um comparado com o final do caminho separado por barras do arquivo dentro do diretório — e os entrega como sources em ordem de nome, com bytes vazio e o nome do próprio diretório como name. Nenhum outro arquivo do diretório é aberto. A pasta em que um build do workspace grava seus arquivos renderizados — dist/ abaixo da raiz do workspace — não é lida como parte de um diretório que a contém: nenhum de seus arquivos é entregue ou reconhecido, e um link que leva a ela é ignorado, de modo que um diretório que passou por build é lido como o projeto que contém, enquanto um diretório que é essa pasta, ou está dentro dela, é lido conforme nomeado. Uma assinatura que não declara nenhum padrão files não seleciona nenhum arquivo de um diretório, de modo que um importador que não declara nenhum lê um único arquivo e recusa um diretório, e um diretório que não contém nenhum arquivo que seus padrões selecionem também é recusado. O diretório fica restrito a si mesmo: um link entre os arquivos que o host leria, ou para um diretório, que leva para fora do diretório é recusado antes que qualquer coisa seja lida, um link para um diretório nunca é percorrido, e um link para um arquivo que nenhum padrão seleciona é ignorado sem ser lido. Reconhecer o formato de um diretório segue a mesma regra — cada assinatura é testada contra os arquivos que seus padrões selecionam, em ordem de nome, cada arquivo lido e analisado no máximo uma vez por sintaxe, e uma assinatura que não declara nenhum padrão não se aplica a nenhum deles. O host não limita nada: um diretório grande demais para o importador é recusado pelos limites de runtime próprios do importador. Nenhum dos importadores Langflow, Flowise, n8n, Dify e Agent Framework do compilador declara padrões files, de modo que cada um lê um único arquivo; seu importador MCP declara os nomes das quatro configurações de cliente, de modo que lê cada uma delas que um diretório contém; seu importador Compose declara os oito nomes de arquivo do Compose, de modo que recebe cada arquivo Compose que um diretório contém e mescla aqueles que o Compose leria; e seu importador CrewAI declara os seis nomes sob os quais as declarações de um projeto CrewAI são escritas, de modo que recebe as declarações de um projeto e nada do seu programa; e seu importador LangGraph declara langgraph.json, de modo que recebe a configuração de uma aplicação e nada do seu código ou dos seus arquivos de ambiente, e um arquivo de ambiente só chega a ele no with.sources da sua vinculação; e seu importador Google ADK declara root_agent.yaml, de modo que recebe a configuração do agente raiz de uma aplicação e nada do seu código ou do seu arquivo de ambiente, e as configurações que seus subagentes nomeiam só chegam a ele no with.sources da sua vinculação.
Definições de tipos. Os tipos de transmissão do importador — ImportInput, ImportSource, CatalogProjection, CatalogComponent, CatalogSocket, ImportOutput e as formas de entidade, decisão e scaffold que ele carrega — são publicados nos três pacotes ABI e reexportados pelo kit de desenvolvimento de plugins de cada linguagem, gerados a partir de um único codec para que os três permaneçam sincronizados, assim como os tipos de reconhecimento ImporterContract, DetectSignature e PathMatch que o autorrelato describe carrega. O pacote importer do kit Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer, carrega tudo o que um importador faz, qualquer que seja seu formato, e os importadores core do compilador, todos construídos sobre ele, leem sua entrada e escrevem sua saída dessa forma.
Em relação a que pontua um importador construído sobre o kit Go. O pontuador do kit pondera cada nó da fonte em relação aos Components da visão catalog e a nada mais: os candidatos são o catálogo próprio do espaço de trabalho — os Components de um catálogo corporativo exatamente como os da biblioteca padrão — e o kit não carrega nenhum candidato próprio. De cada Component ele lê o nome, a categoria que seu rótulo component.aggrega.ai/category carrega, seus rótulos e os nomes das chaves que seus values declaram; suas chaves provides e seus sockets não são ponderados. Um Component adicionado ao catálogo é um candidato na próxima importação, sem que nenhum importador seja recompilado. Onde a visão está ausente, porque o catálogo não contém nenhum Component, nenhum nó tem candidato: nenhum é referenciado nem sugerido, e cada nó ao qual o rascunho dá um Component próprio é gerado como rascunho. Todo importador que pontua por meio do kit pontua dessa forma — entre eles os importadores Langflow, Flowise, n8n e Compose do compilador, enquanto seu importador MCP não pondera nenhum candidato; um importador que não usa o kit lê a visão como quiser.
Para que um importador construído sobre o kit Go lê os sockets de uma plataforma. Sockets não pesam nada em uma pontuação, mas o kit os lê para organizar um rascunho. Um formato cujos fluxos uma plataforma executa tal como estão escritos — como fazem os do Langflow, do Flowise e do n8n — é gerado como rascunho por padrão como uma instância do Component dessa plataforma que carrega o fluxo, e cada parte do fluxo é conectada ao primeiro socket, na ordem em que a entrada catalog da plataforma lista seus sockets, cujo selector os rótulos do Component da parte satisfazem, tal como a visão carrega esses rótulos. Apenas o seletor e os rótulos são lidos, e o seletor é comparado por uma função que o importador fornece, já que o kit não carrega nenhuma gramática de seletores própria; onde a visão não contém nenhum Component com o nome da plataforma, nenhuma parte é conectada. Importadores core descreve o rascunho que os importadores Langflow, Flowise e n8n do compilador fazem dessa forma, e a configuração layout que, em vez disso, gera cada nó como rascunho como um Component próprio.
Status atual: disponível — despachado por aggrega import e pela mesma operação na sessão do editor e na ferramenta voltada ao assistente.
Critério de posicionamento: o socket de linter versus os papéis de veredito de governança
Dois dos sockets documentados compartilham uma superfície semelhante — ambos emitem resultados por regra — mas diferem no posicionamento no pipeline e na semântica de bloqueio. O critério para decidir qual socket carrega uma determinada verificação:
- Os papéis de veredito de governança (em banda, que interrompem o build). Reservados para políticas que interrompem o build: um veredito
haltpara o pipeline de compilação e o build não produz artefatos. Os casos de uso são políticas cuja violação torna a saída insegura de aplicar: pontos de controle de conformidade (posicionamento das fronteiras PCI / SOC2), invariantes de topologia (ingress zero-trust, autenticação entre fronteiras), forma do fluxo de credenciais (nenhum segredo em texto simples na IR) etc. Uma política raciocina sobre o grafo de IR (ir-verdict, antes da renderização) ou sobre os artefatos renderizados (render-verdict, depois da renderização). - O socket de linter (fora de banda, CI / IDE, consultivo). Reservado para verificações de boas práticas e de facilidade de descoberta: regras cuja violação é suspeita, mas não insegura — segredos órfãos, parâmetros não usados, vocabulário de rótulos obsoleto, completude das tags para atribuição de custos, desvio das convenções de nomenclatura. Uma falha produz saída consultiva; o build ainda produz artefatos.
O critério de posicionamento formulado como uma única regra: se a verificação deve interromper o build, ela pertence a um papel de veredito de governança; se a verificação deve avisar um autor ou um revisor sem bloquear o pipeline, ela pertence ao socket de linter.
Ambos podem ser usados hoje. O socket de linter executa o publishing-linter via aggrega lint; os papéis de veredito de governança são acionados em banda durante aggrega build quando um espaço de trabalho vincula um plugin com papel de veredito. Observe que um papel de veredito tem suas próprias severidades — uma política pode ela mesma emitir vereditos warn e info que avisam sem interromper —, de modo que a linha entre interromper e avisar traçada acima é a orientação de posicionamento para verificações inteiras, e não uma afirmação de que uma política só pode interromper. Veja a página do socket de governança para o modelo de severidade.
Referências cruzadas
policy-socket.md— o tratamento completo do socket de governança: os quatro papéis, as severidades dos vereditos, o canal de entrada do operador, como escrever uma política para qualquer um dos dois mecanismos que vêm dentro do compilador, como encapsular um mecanismo de políticas externo e os guests de referência.core-importers.md— os importadores próprios do compilador, um para cada formato que ele lê: o que cada um lê, suas configurações e sua publicação a cada versão do compilador.10-status.md#compilation-pipeline-phases— classificação do pipeline de plugins na página de status (prontidão de execução do pipeline de plugins Wasm).architecture/04-entity-taxonomy.md§“Domain 3: Infrastructure Base (Domínio 3: base de infraestrutura)” — princípio do Plugin em duas partes para FeatureRecipes de credenciais (padrão Fetcher + Injector).architecture/13-catalog-and-registry.md— a taxonomia OCI que começa pelo segmento do provedor.entities/featurerecipe.md— a superfície de criaçãopipeline:da FeatureRecipe.when-to-use-a-pipeline-step.md— guia de decisão: uma etapa de pipeline versus uma FeatureRecipe com templates.templates/expansion-matrix.md— as regras de avaliação de templates do blocopipeline:with:do pipeline de plugins e a semântica de acesso a.steps.examples/04-secrets.md— o formato de pipeline Fetcher + Injector que uma FeatureRecipe de credenciais pode assumir.errors/error-translation.md— a disciplina de tradução de erros da qual participam os guests de plugins.