Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

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 governação, 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 os passos de FeatureRecipe e Recipe; um socket de renderização de fornecedores; 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: que sockets existem, o que cada socket consome e produz, onde cada socket se situa no pipeline de compilação e a sandbox dentro da qual cada plugin é executado.

Esta página trata dos sockets — os pontos do pipeline e as 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 — ver o guia do programador de plugins Wasm.

O Aggrega incorpora um runtime anfitrião Wasm — Extism sobre o motor Wazero — que carrega e executa plugins por detrás de uma firewall de pureza AOT: o anfitrião não concede a um guest nenhuma capacidade ambiente — sem rede, sem sistema de ficheiros, sem ambiente, stdio descartado, um relógio de parede observável congelado num instante invariante entre compilações — pelo que um plugin não consegue quebrar as garantias ahead-of-time do compilador. A superfície completa de capacidades — a regra dos módulos de importação no carregamento, as recusas no momento da instanciação e as funções do anfitrião selecionadas — é o contrato da sandbox mais abaixo. Os autores de Plugin visam o anfitrião através do PDK em três linguagens (Go, Rust, TypeScript). aggrega lint aciona o socket do linter — o linter de publicação standard — através do anfitrião. aggrega build aciona os papéis do socket de governação ativos em tempo de compilação 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 veredicto de IR na análise estática e do veredicto de renderização sobre os artefactos renderizados. Cada um é uma operação nula quando nenhum plugin está anexado a esse papel, pelo que uma compilação sem configuração de governação fica inalterada. aggrega build aciona também o pipeline: da FeatureRecipe e da Recipe no pipeline de plugins que encerra a renderização — cada passo declarado é executado através do anfitrião sobre o conjunto de documentos renderizados, aplicando os patches RFC 6902 do passo e emitindo os seus efeitos secundários. Ver Estado da linguagem → Fases do pipeline de compilação.

O contrato da sandbox

Cada socket aciona o seu plugin através da mesma sandbox do anfitrião. A sandbox tem duas camadas independentes — uma verificação estrutural no carregamento e a recusa de capacidades na instanciação — e, em conjunto, definem o que um plugin pode alcançar, o que não pode alcançar e aquilo por que é responsável.

A regra dos módulos de importação (no carregamento). O carregador percorre a secçã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 do anfitrião 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 anfitrião 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 ficheiros e de sockets que os seus caminhos de código ativos nunca chamam — trazidas transitivamente por dependências — e nomear uma importação não concede nada. É a recusa 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 anfitrião instancia o guest com um comportamento WASI real e nenhuma autoridade ambiente:

  • sem sistema de ficheiros — sem diretórios pré-abertos, pelo que uma chamada ao sistema de ficheiros 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 anfitrião;
  • um relógio de parede observável congelado, fixado num instante invariante entre compilações, pelo que um guest que lê a hora não pode deixar escapar a hora da compilação para a sua saída;
  • um relógio monotónico real e que avança — o runtime de uma linguagem guest precisa de um para arrancar, e o tempo monotónico mede uma duração decorrida, não um instante do relógio de parede;
  • entropia real do anfitrião — 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 o deixar surgir como saídas diferentes;
  • um único nome de programa sintético como argv.

Uma chamada de E/S que um guest efetivamente faz — abrir um ficheiro, ligar-se a um socket — falha na fronteira da chamada. É o próprio modelo de segurança baseado em capacidades do WASI: a sandbox recusa a capacidade em vez de policiar o código.

As entradas chegam apenas através do payload e das funções do anfitrião selecionadas. Um plugin recebe tudo o que renderiza ou avalia no payload que o 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 secção própria desse socket mais abaixo; cada tipo de payload publicado inclui um ponto de entrada de codificação e um de descodificação para a codificação do seu socket, pelo que um guest chama uma função em vez de escolher um analisador. Para uma renderização de fornecedor 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 qualquer interpretação da estrutura do fornecedor por parte do anfitrião. O guest aplica a sua própria lógica de estrutura — selecionar o único ficheiro compose, descer até à raiz de um chart, exigir um Chart.yaml, fazer o vendoring de um módulo recursivamente — e volta a ler exatamente a fatia que seleciona através de um callback do anfitrião. Para além do payload, o anfitrião disponibiliza um conjunto selecionado de funções do anfitrião de privilégio mínimo, e concede a um plugin exatamente aquelas que o seu binário importa:

  • aggrega_log — uma linha de log no destino de logs do anfitrião.
  • aggrega_emit_warning — um aviso estruturado que o anfitrião apresenta após a chamada.
  • aggrega_fetch_external_input — o canal de obtenção 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 anfitrião lê e empacota exatamente isso sob uma sandbox que resolve caminhos sob a raiz e rejeita ...
  • aggrega_read_source_file — uma leitura do conteúdo de um único ficheiro sob a mesma 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 anfitrião resolve um analisador para esse formato, executa-o e devolve a árvore canónica que este produziu. É assim que um consumidor obtém a saída de um produtor através do anfitrião em vez de invocar ele próprio um guest produtor, e o anfitrião limita-o a um único nível — um produtor alcançado desta forma que o chame de novo é recusado — pelo que um consumidor o chama uma vez por fonte e pode consumir muitas fontes em sequência.

O anfitrião deriva o conjunto que um plugin importa a partir do seu binário .wasm, valida-o face à lista de permissões selecionada e confronta-o com as funções do anfitrião que o describe() do guest declara. aggrega plugin sync regista o conjunto no spec.runtime.hostFunctions da entidade, e uma publicação recusa uma entidade cujo registo difere do binário, pelo que a superfície do anfitrião de cada plugin é visível no catálogo e não pode divergir do binário.

As falhas de callback transportam um código comparável por máquina, sob hostfunc_error_code. Os callbacks do anfitrião que devolvem 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 transporta uma mensagem legível por pessoas e, ao lado dela, um código opcional comparável por máquina sob hostfunc_error_code, retirado 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 êxito, o código está ausente; em caso de falha, o anfitrião 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 — pelo que 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 do anfitrião.

🔴 Dois vocabulários diferentes nomeiam uma falha nesta fronteira, e a chave que se lê indica qual deles se tem em mãos. Confundi-los é o único erro que vale a pena assinalar aqui, porque um valor de qualquer um dos dois é uma string simples e nem o anfitrião nem o guest verificam de que conjunto veio.

  • hostfunc_error_code, numa resposta que o anfitrião envia a um guest. O seu valor é um membro do catálogo fechado referido acima — uma lista fixa, que muda lentamente, das formas como um callback do anfitrião pode falhar. Como o conjunto é fechado, um guest pode comparar um valor com uma constante nomeada que o seu kit reexporta e ramificar com base no resultado.
  • condition_code ao lado de condition_short_code, numa saída de socket que um guest devolve ao anfitrião. São os dois identificadores de uma condição de interrupção que o próprio guest levantou, e provêm do conjunto aberto e crescente de condições que o compilador regista, e não do catálogo. condition_code é o código descritivo sob o qual a condição está registada; condition_short_code é a forma compacta — a letra E e quatro dígitos — que um leitor cita, pesquisa e cola num relatório. O anfitrião imprime o código curto no cabeçalho entre parênteses retos do diagnóstico que renderiza, pelo que uma condição levantada por um guest pode ser citada exatamente como uma levantada pelo compilador. Não deriva nenhum dos dois valores, mas verifica-os: um código curto que não se resolve em nenhuma condição que este compilador declare, ou que se resolve numa cujo número foi retirado, interrompe a compilação 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 comunicados em conjunto: um guest que define um e não o outro nomeou uma condição que o anfitrião não consegue resolver, e o anfitrião comunica então, em vez disso, a sua própria condição genérica de falha de plugin, com a mensagem a transportar ainda a falha inteira. E um condition_code nunca é membro do catálogo de funções do anfitrião, pelo que compará-lo com uma constante reexportada nunca encontra correspondência — e é por isso que cada chave nomeia o seu próprio vocabulário em vez da falha em geral.

As ranhuras de cada callback transportam uma codificação declarada, e toda a ranhura que contém um documento de payload contém-no em binário. Todo o argumento que um callback do anfitrião recebe é um ponteiro para a memória do guest, à exceção do nível numérico de aggrega_log; um callback que devolve uma resposta também responde com um ponteiro. O que cada uma dessas ranhuras contém é fixado por callback:

CallbackRanhuras de argumentoRanhura de resposta
aggrega_log, aggrega_emit_warningTexto UTF-8 — nenhum documento de payloadsem resposta
aggrega_fetch_external_inputum URL UTF-8 simples — nenhum documento de payloadCBOR canónico
aggrega_pack_source, aggrega_read_source_file, aggrega_parse_sourceCBOR canónico (RFC 8949 §4.2.1)CBOR canónico

A tabela divide-se pelo que cada ranhura contém, e não pela identidade do callback: uma ranhura que contém um documento de payload transporta CBOR canónico, e uma ranhura que contém uma string simples — uma linha de log, um campo de diagnóstico, um URL — transporta texto UTF-8. aggrega_fetch_external_input é o único cujas duas ranhuras diferem: o seu argumento é um URL simples, lido como texto UTF-8, e a sua resposta é um documento de payload em CBOR canónico.

O que um guest faz numa ranhura que transporta payload, e o que não deve fazer. 🔴 Uma ranhura que contém um documento de payload contém uma sequência de bytes opaca, não texto UTF-8 — pelo que esta é a forma que um guest declara, não apenas os bytes que lá coloca. Um guest que aloca um tal pedido como string, ou lê uma tal resposta como string, não interopera: uma conversão de texto em qualquer dos sentidos corrompe os bytes binários. A falha é explícita em vez de parcial — um pedido que o anfitrião não consegue descodificar volta como um envelope de resposta que transporta o código request_undecodable, na mesma forma em banda de qualquer outra falha de callback, pelo que o guest a comunica em vez de prosseguir com um payload lido a meio. 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, cujo URL é alocado como texto. Em concreto, por kit:

  • Go — constrói-se o pedido com EncodeCBOR() do tipo de pedido, aloca-se com pdk.AllocateBytes (não pdk.AllocateString) e lê-se a resposta com ReadBytes() na memória para a qual o ponteiro da resposta se resolve, para DecodeCBOR do tipo de resposta. O URL de obtenção é a exceção do lado do pedido, alocado com pdk.AllocateString; a sua resposta lê-se como qualquer outra. A declaração //go:wasmimport é um ponteiro em qualquer dos casos, pelo que nada na assinatura mostra a forma — esta reside na alocação e na leitura.
  • Rust — a declaração #[host_fn] indica a forma diretamente: cada um dos três callbacks de payload é fn <callback>(request: Vec<u8>) -> Vec<u8>;, e o callback de obtenção é fn aggrega_fetch_external_input(url: String) -> Vec<u8>;. Constrói-se o pedido com encode_cbor() do tipo de pedido e lê-se a resposta com decode_cbor(&raw) do tipo de resposta.
  • TypeScript — constrói-se o pedido com a função encodeCBOR… do tipo de pedido, aloca-se com Memory.fromBuffer (não Memory.fromString) e lê-se a resposta com readBytes() para a função decodeCBOR… do tipo de resposta. O URL de obtenção é alocado com Memory.fromString; a sua resposta lê-se com readBytes() como as restantes. Tal como em Go, a entrada declare module é um ponteiro em qualquer dos casos.

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 das suas assinaturas nomeia um tipo de transmissão, pelo que um guest que chega a estes callbacks através do seu kit não aloca nem descodifica nada por si; um guest que declara e chama por si as funções do anfitrião aloca e lê a sua memória como descrito acima. Um pedido alocado como texto é recusado em vez de servido a meio, e uma resposta lida como texto não pode ser descodificada, pelo que uma discrepância entre os dois lados é explícita em vez de silenciosa.

Duas propriedades em que vale a pena confiar. A resposta transporta a mesma codificação quer tenha êxito, quer falhe: um guest lê uma única ranhura e não pode saber antes de descodificar qual dos dois casos contém, pelo que um único ponto de entrada de descodificação lê ambos, e o código de erro e a mensagem descritos acima chegam através dele. E um guest preenche um campo de valor em bytes no tipo de campo próprio do 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 em bruto que a codificação binária transporta é tarefa do codificador gerado, feita à saída e revertida à entrada. Isso abrange os bytes da fonte de ParseInput, o conteúdo do ficheiro que aggrega_read_source_file devolve, o conteúdo que aggrega_fetch_external_input obteve e o conteúdo de cada ficheiro empacotado numa 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 descodificar de base64. O campo content das respostas read-source-file e fetch é omitido quando está vazio, pelo que a resposta para um ficheiro vazio ou um payload obtido de comprimento zero não transporta qualquer conteúdo; uma tal resposta continua a ser um êxito, porque uma falha transporta sempre a sua mensagem e o seu código, e o wrapper de cada kit devolve bytes vazios para ela. A árvore que aggrega_parse_source devolve viaja como uma sequência de bytes que contém o seu próprio documento JSON literalmente; o anfitrião não a lê nem a remodela. Um analisador lê o mesmo ParseInput, na mesma codificação, no seu próprio export parse — ver 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 o fazer passar por uma ida e volta, e é por isso que a saída de uma compilação se mantém idêntica byte a byte. Não é necessária nenhuma biblioteca CBOR num guest e nada analisa bytes à mão: cada tipo de payload publicado inclui os pontos de entrada de codificação e descodificação de que a codificação da sua ranhura precisa.

O determinismo é responsabilidade do autor do plugin. O anfitrião consome os bytes de saída de um guest literalmente e não executa qualquer serializador sobre eles, pelo que o contrato que todo o plugin tem de cumprir é: uma entrada idêntica produz bytes de saída idênticos. A sandbox remove as fontes ambiente de não determinismo — hora do relógio de parede, ambiente, estado do sistema de ficheiros — mas deliberadamente não mascara o resto: um guest que codifica entropia ou tempo monotónico decorrido na sua saída produz bytes visivelmente diferentes entre execuções em vez de um defeito escondido de forma estável.

O canal de obtenção de entradas externas. aggrega_fetch_external_input é o único canal sancionado para conteúdo remoto, e é mediado pelo anfitrião, não um acesso do guest à rede: o guest nomeia um URL, e o anfitrião serve os bytes segundo a disciplina de fixação de entradas externas. Um URL fixado no ficheiro de bloqueio da Release é servido a partir do armazenamento local endereçado por conteúdo e verificado face ao seu digest registado; um URL não fixado é recusado com um diagnóstico que nomeia o URL e o passo que o fixa, porque uma renderização consome o fecho que o seu ficheiro de bloqueio regista e nunca o alarga. 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 programador contém as instruções de criação e a disciplina de fixação na íntegra.

Mapas que mantêm a sua ordem

Alguns mapas que um payload transporta estão marcados como mapas que preservam a ordem no schema do seu socket, porque a ordem das suas entradas faz parte do que transportam: os nós de uma compilação, as etiquetas de um nó, os anexos de um nó, as entradas e saídas de um passo do pipeline, os espaços de chaves que um fornecedor declara. Os tipos de payload publicados guardam cada um desses mapas num contentor que mantém as suas entradas pela ordem em que foram definidas:

KitContentor
Goaggrega.OrderedMap[V] — o nome que o kit dá a abi.OrderedMap[V] do pacote ABI
RustOrderedMap<V> do crate aggrega-abi, reexportado pelo kit
TypeScripto Map<string, V> próprio da linguagem

Os contentores de Go e Rust oferecem as operações de um mapa — procurar uma chave, defini-la, eliminá-la, ler as chaves, percorrer as entradas por ordem, contá-las. Definir uma chave que o contentor já contém substitui o seu valor e mantém a sua posição; uma chave nova fica 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 — pela ordem do contentor, 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 pela ordem do contentor. Um descodificador, em qualquer das duas codificações, recusa um mapa que repete uma chave, indicando 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 pela ordem em que foi preenchido, um guest que preenche um a partir de uma fonte sem ordem fixa — ao iterar um mapa nativo de Go, por exemplo — escreve bytes que diferem entre execuções com entrada idêntica. Deve preenchê-lo numa ordem fixa.
  • A ordem só se mantém enquanto o mapa permanece no seu contentor. Um guest que converte um payload num tipo de valor genérico da sua própria linguagem obtém, em vez disso, a ordem desse tipo: um map[string]any de Go não tem nenhuma, e o serde_json::Value de Rust mantém as chaves dos objetos ordenadas, a não ser que o crate seja compilado com a sua funcionalidade preserve_order.
  • Em TypeScript, ler e escrever através das funções geradas. Um tipo que contém um mapa marcado descodifica o seu JSON membro a membro, pelo que uma chave que se lê como um índice de array, como "8080", mantém a sua posição onde JSON.parse a moveria para o início do objeto; e o seu codificador escreve cada Map como um objeto, onde JSON.stringify escreve um Map como {}. Object.keys de um Map também está vazio: as chaves de um Map leem-se com o seu próprio keys().

Valores que uma entrada marca como sensíveis

Um plugin nunca cita, numa recusa ou num aviso que devolve, um valor que a sua entrada marca como sensível — pela sua chave, ou como parte de um payload marcado no seu todo. Uma recusa é o error que uma saída transporta; um aviso é um Diagnostic que a saída transporta, qualquer que seja a sua severidade, ou um emitido através de aggrega_emit_warning. O anfitrião reproduz esse texto sem alterações onde quer que o comunique — a linha de comandos, o servidor de linguagem e a lista de problemas do editor, as ferramentas do assistente — e não lê nenhum valor a partir dele, pelo que o plugin é a única parte capaz de manter o valor de fora. Em vez disso, deve indicar-se a chave, a definição ou a posição: a partir daí, um leitor encontra o valor.

A regra abrange o texto que uma biblioteca escreve para o plugin tanto quanto o texto que o próprio plugin escreve. Um motor de templates comunica os dados que estava a avaliar, 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 dessas ocorreu sobre um valor que a entrada marca, deve comunicá-la sem o valor — por exemplo, executar de novo o mesmo passo com cada valor marcado substituído por um marcador de posição, comunicar a falha dessa execução quando falhar no mesmo sítio e, caso contrário, indicar que o texto da falha é retido. Sob um payload marcado no seu todo, cada valor nesse payload é um valor marcado, enquanto as suas chaves — a forma do documento — continuam legíveis.

Onde uma entrada marca uma chave ou um payload como sensível, escrito tal como os dados transmitidos o nomeiam:

Socket e exportOnde a marcação é lida
fornecedor 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, pelo que nenhuma delas é marcada aqui — ou uma entrada do mapa attachments do contentor de uma carga de trabalho que lê uma ranhura declarada sensível. node.sensitive_values marca node.values no seu todo: é true quando um valuesMapping — o da Recipe, ou o da FeatureRecipe de um anexo — 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 transporta sensitive_content para o seu próprio conteúdo, incluindo a mensagem de um analisador sobre esse conteúdo. Cada entrada de omits transporta 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 transporta a marcação do seu próprio anexo: sensitive_payload_leaves (as folhas values.<path> e infra.<path> que a sua Feature declara sensíveis), sensitive_inject (as chaves de entrega inject que leem uma chave provides que a sua Feature declara sensível) e sensitive (se o anexo lida ou não com material declarado sensível).
governação ir-verdict (PolicyInput)graph: as sensitive_payload_leaves de cada nó, e as sensitive_payload_leaves, sensitive_inject e sensitive de cada anexo. Cada valor que essas marcações nomeiam já chega como o marcador de retenção {"aggrega_withheld": "declared"}, pelo que o próprio valor nunca chega ao plugin.

Nenhuma outra entrada de socket, e nenhuma entrada de outro export de fornecedor, transporta uma marcação. Uma marcação de chave nomeia apenas o que liga exatamente a uma declaração, pelo que 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 transmite a totalidade dos seus dados, ou um template que não pode ser analisado — e nunca a partir de um valor, pelo que a sua ausência significa que esse template não leu nenhum valor declarado, tanto quanto as suas referências mostram, ou que nenhum template produziu o payload; não é uma afirmação de que o payload não transporta nada sensível.

Posicionamento dos sockets Wasm no pipeline

O pipeline de compilação reserva os seguintes pontos de socket. As etiquetas de forma seguem a taxonomia de quatro etiquetas da página de estado.

SocketPosicionamento no pipelineEstado atual
Socket de governação, papel annotation-transformResolução (antes da expansão de anotações)disponível — acionado quando um espaço de trabalho anexa um plugin annotation-transform; injeta anotações que a expansão transforma em anexos de Feature
Socket de governação, papel label-transformConstrução da topologia (o construtor de topologia)disponível — acionado quando um espaço de trabalho anexa um plugin label-transform; adiciona automaticamente etiquetas aos nós através de JSON Patch
Socket de governação, papel ir-verdictAnálise estática (o analisador estático, sobre o grafo IR)disponível — acionado quando um espaço de trabalho anexa um plugin ir-verdict; um veredicto halt interrompe a compilação
Socket de governação, papel render-verdictRenderização (sobre os artefactos renderizados)disponível — acionado quando um espaço de trabalho anexa um plugin render-verdict; um veredicto halt interrompe a compilação
Plugins de pipeline: da FeatureRecipe e da RecipeO pipeline de plugins (mutação pós-renderização)disponível — cada passo declarado é executado sobre o conjunto de documentos renderizados, aplicando patches RFC 6902 e emitindo efeitos secundários
Plugins de renderização de Provider (helm, helm-chart, compose, terraform, cloudformation)Renderização base (os fornecedores)disponível — cada fornecedor renderiza através do seu guest Wasm; a renderização é exclusivamente Wasm, sem renderizador alternativo dentro do anfitrião
Plugins de analisador (parse:<format>)Renderização, para uma política render-verdict; e fora de banda, para uma importaçãodisponível — chamado para um artefacto num formato que uma política render-verdict não lê nativamente, para um importador através 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 destinada ao assistente
Plugins de linter (linter/publishing)Fora de banda (aggrega lint)disponível — o linter de publicação é distribuído e executado através do anfitrião 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. Valida os valores de anotação em relação ao spec.schema da Feature de destino e injeta anexos de Feature sintéticos no momento da compilação do IR. Ver vocabulary/labels-and-annotations.md para as seis superfícies que transportam anotações e etiquetas e providers/well-known-annotations.md para a forma das associações e as orientações para as escrever.

Contrato de forma de saída — o que existe hoje

O socket de governação 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 anfitrião lê-as em tempo de compilação, uma vez por plugin configurado, quando um espaço de trabalho anexa um plugin a esse papel. As subsecções abaixo seguem a ordem pela qual o pipeline os aciona.

O papel annotation-transform — saída de injeção de anotações

Posicionamento no pipeline. Resolução, depois de os componentes serem resolvidos e antes de a expansão de Feature orientada por anotações ser executada.

Forma de entrada (anfitrião → guest). Um documento AnnotationTransformInput que contém:

  • 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 encaminhamento sob os aggregates: de uma fronteira faz entrar, quer a entrada o nomeie quer não — cada um com o seu boundary_path, o seu component_name (para um componente encaminhado, o seu id com pontos no grafo de compilação, como metrics.query) e as annotations que a Release escreve nele, para que um guest possa decidir o que acrescentar sem deslocar um valor escrito pelo autor. Cada valor de anotação chega tal como foi escrito — uma string, um objeto de subchaves, ou null onde o componente prescinde de uma anotação que herdaria — e cada chave que o componente transporta está presente, qualquer que seja o seu valor. Ordenados de forma determinística pelo anfitrião.
  • binding_keys — as chaves de anotação para as quais o Manifest regista uma associação, pela ordem do autor. Uma injeção sob uma chave registada passa a expandir-se num anexo de Feature, pelo que um guest lê esta lista para injetar chaves que terão efeito. O anfitrião não exige que uma injeção nomeie uma chave registada: uma anotação injetada não registada comporta-se exatamente como uma anotação escrita pelo autor sem associação.
  • sources — os ficheiros de definição que o anexo declarou sob with.sources, cada um com o seu caminho de nome base e o seu conteúdo, ordenados por caminho.
  • settings — o objeto de definições de forma livre que o anexo declarou sob with.settings, entregue ao guest sem alterações.

settings e sources são o mesmo canal with, agnóstico em relação ao motor, que todos os outros papéis leem, e ambos estão ausentes quando o anexo não declara nenhum. Como a saída deste papel molda a compilação, as definições e o conteúdo das fontes do anexo são fixados no ficheiro de bloqueio da release no pull e reconstruídos a partir dele na compilação.

Forma de saída (guest → anfitrião). Um documento AnnotationTransformOutput que contém:

  • injections — as anotações a acrescentar, por ordem. Cada uma nomeia uma coordenada de destino existente (boundary_path e component_name) mais a annotation_key e o seu annotation_value: uma string, ou um objeto de subchaves, que alimenta uma associação que encaminha várias subchaves de uma vez.

O anfitrião aplica apenas adições de anotações, a coordenadas que ele próprio forneceu, cada uma com um valor que um autor poderia escrever nessa anotação. Lê um valor injetado exatamente como lê o mesmo valor escrito na Release — as subchaves de um objeto pela ordem em que o guest as escreveu — pelo 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 transporta, ou que transporta null, uma lista, um número, um booleano ou um objeto sem subchaves, interrompe a compilação 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 de qualquer parte dela ser aplicada. Esse confinamento é o que delimita o papel: um operador que anexa aqui um plugin declarou injeção de anotações e nada mais. Onde a compilação recusa mais tarde uma anotação injetada pela forma como encaminha, 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, a sua mensagem nomeia o plugin que a injetou e o papel ao qual está anexado.

Codificação de transmissão. O payload e o resultado deste papel circulam como CBOR canónico (RFC 8949 §4.2.1), nos dois sentidos. Um guest lê-os e escreve-os através dos pontos de entrada que os tipos de payload transportam — DecodeCBOR e EncodeCBOR em Go, decode_cbor e encode_cbor em Rust, decodeCBORAnnotationTransformInput e encodeCBORAnnotationTransformOutput em TypeScript — pelo que nenhuma biblioteca CBOR é necessária e nada analisa bytes à mão. Em Rust, o export recebe e devolve Vec<u8>; em TypeScript, 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, pelo que circulam como uma lista ordenada de entradas pela ordem em que o destino as guarda, e um guest lê-as através do contentor do seu kit que mantém a ordem; cada valor circula como os bytes do seu JSON, tal como o annotation_value de uma injeção no sentido inverso. settings circula como os bytes do seu documento JSON, que um guest analisa como JSON para examinar o conteúdo. Uma resposta que não seja um AnnotationTransformOutput nesta codificação — uma escrita como JSON, ou uma que transporte um campo de nível superior que a forma não declara — interrompe a compilação, 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 a sua resposta é lida como a forma de saída do export e impressa como JSON — uma resposta que não tenha essa forma é recusada, nomeando o export, tal como uma compilação 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 se mantenham sincronizados.

O papel label-transform — saída JSONPatch

Posicionamento no pipeline. Construção da topologia, depois de o grafo ser achatado e antes de o grafo IR ser construído, pelo que os seletores de socket e de Feature que o analisador avalia leem as etiquetas que o papel deixa.

Forma de entrada (anfitrião → guest). Um documento MutatorInput que contém:

  • compilation_context — a identidade da release (release_name, environment).
  • graph — uma projeção MutatorGraph dos nós da topologia: de cada nó, o seu Component, a versão resolvida, as etiquetas e os values que a sua instância declara.
  • settings — o objeto de definições de forma livre que o anexo declarou sob with.settings, entregue ao guest sem alterações.
  • sources — os ficheiros de definição que o anexo declarou sob with.sources, cada um com o seu caminho de nome base e o seu conteúdo, para que um mutador possa ser guiado por um ficheiro de regras ou de mapeamento versionado em vez de definições inline.

O grafo é uma projeção, e não o grafo IR: cada nó transporta o seu conjunto de etiquetas resolvido e os valores que a 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 os seus templates já avaliados em relação aos seus parâmetros, pelo que um valor elevado a um parâmetro chega como o valor que a Release forneceu; um valor predefinido que o schema do Component declara, e tudo o que uma Recipe ou uma Feature contribua, não estão entre eles, e um nó que não declara valores não transporta nenhuma chave values. Um valor que o Component do nó declara sensível é retido exatamente como o veredicto sobre o grafo o retém — lê-se como {"aggrega_withheld": "declared"} — enquanto cada valor irmão que nenhuma declaração alcança chega tal como foi escrito. É isso que permite que uma configuração declarada pelo programador decida uma etiqueta — uma base de dados cujos valores ativam uma extensão vetorial promovida a datastore.aggrega.ai/engine: vector, por exemplo. settings e sources são o mesmo canal with, agnóstico em relação ao motor, que os papéis de veredicto leem; o anfitrião transmite-os e nunca interpreta o seu conteúdo. Como a saída de um mutador molda a compilação, as definições e o conteúdo das fontes do anexo são fixados no ficheiro de bloqueio da release no pull e reconstruídos a partir dele na compilação, pelo que a entrada do mutador é invariante a uma alteração de qualquer um dos dois após o pull, até ao pull seguinte.

Forma de saída (guest → anfitrião). Um documento MutatorOutput que contém:

  • patches — um array de documentos JSONPatch opacos (RFC 6902) que o anfitrião aplica apenas às etiquetas dos nós; os valores que a entrada transportava são só de leitura.

Cada patch endereça as etiquetas de um nó específico através de JSON Pointer (RFC 6901); o anfitrião aplica os patches pela ordem do array e reincorpora o conjunto de etiquetas modificado no grafo IR. A função do papel label-transform é a etiquetagem automática empresarial — acrescentar etiquetas de conformidade / observabilidade / atribuição de custos declaradas pela política da empresa sem modificar o conteúdo do catálogo. A superfície das etiquetas é o único alvo autorizado deste papel: um patch que toque num campo do nó que não as suas etiquetas, acrescente ou remova um nó, ou defina um valor de etiqueta que não seja uma string interrompe a compilação em vez de ser absorvido silenciosamente. A RFC 6901 é a referência de base da gramática de caminhos para todas as superfícies de caminho de documento em Aggrega — o contrato de plugins Wasm aqui, mais os exports *_path de .locals, mais os campos de schema *Path noutras partes do corpus. Ver 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 circulam como CBOR canónico (RFC 8949 §4.2.1), nos dois sentidos. 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 o codificar e voltar a descodificar, e é por isso que a saída de uma compilação se mantém idêntica byte a byte. Um guest lê-os e escreve-os através dos pontos de entrada que o tipo de payload do seu kit já transporta — DecodeCBOR e EncodeCBOR em Go, decode_cbor e encode_cbor em Rust, decodeCBORMutatorInput e encodeCBORMutatorOutput em TypeScript — pelo que nenhuma biblioteca CBOR é necessária e nada analisa bytes à mão. Em Rust, o export recebe e devolve Vec<u8>; em TypeScript, lê Host.inputBytes() e escreve Host.outputBytes(...). Os nodes do grafo, as labels de cada nó e os values de cada nó são mapas que o schema marca como mapas que preservam a ordem, pelo que circulam como listas ordenadas de entradas — os nós pela ordem em que a compilação os guarda, que é a ordem do autor, as etiquetas de cada nó pela ordem em que o nó as transporta, e os valores de cada nó pela ordem em que o Aggregate os escreve — e um guest lê os três através do contentor do seu kit que mantém a ordem. Cada valor circula como os bytes do seu documento JSON: os kits de Go e Rust entregam-no ao guest como esse JSON, para ser analisado tanto quanto uma regra precise, e o kit de TypeScript como o valor já analisado.

Duas coisas que isto não altera. O array patches continua a ser JSON: o socket transporta cada documento de patch sem alterações como conteúdo opaco e nenhum dos lados lê o seu interior, pelo que a forma própria de um documento de patch é independente da codificação que o seu socket transporta. E settings e sources continuam a ser entregues sem alterações — settings chega como os bytes que o anexo escreveu, que um guest analisa como JSON se precisar de examinar o conteúdo.

Todos os outros papéis de governação transportam a mesma codificação — o papel annotation-transform e os dois papéis de veredicto dizem-no cada um na sua própria secção — pelo que um guest que serve mais de um papel fala CBOR canónico em cada papel que serve, lendo cada payload através do ponto de entrada de descodificaçã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, a crate aggrega-abi e @aggrega-ai/aggrega-abi), gerados a partir de um único codec para que os três se mantenham sincronizados. O anfitrião monta a entrada e aplica os patches que o guest devolve.

Os papéis de veredicto — saída de array de veredictos

Um guest de política inspeciona uma compilação e devolve uma lista de veredictos; o anfitrião age de acordo com a severidade de cada veredicto e nunca interpreta a própria política. 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 motores incluídos no compilador, o encapsulamento de um motor de políticas externo, os guests de referência e a forma como um operador anexa uma política — está na página do socket de governação. Esta secção regista o posicionamento no pipeline e as formas tipadas de transmissão.

Posicionamento no pipeline. Uma política é anexada a exatamente um papel de veredicto, que determina onde é avaliada:

  • ir-verdict — avaliado na análise estática, antes da renderização base. O analisador monta o payload em cada compilação.
  • render-verdict — avaliado após a renderização, sobre os artefactos emitidos.

Quando um espaço de trabalho anexa um plugin de um papel de veredicto, o pipeline serializa o payload desse papel para o plugin e volta a ler os seus veredictos.

Forma de entrada (anfitrião → guest). O papel seleciona o payload:

  • O PolicyInput de ir-verdict transporta graph — o grafo IR completo, agnóstico em relação às capacidades (a mesma forma que o construtor de topologia emite), com todos os detalhes de nós, arestas e anexos que o compilador detém, exceto que um valor que um autor declarou sensível chega retido (ver Valores que uma entrada marca como sensíveis) — e precalculated_paths, os caminhos de encaminhamento que o analisador enumera a par dele, para que uma política possa raciocinar sobre a alcançabilidade sem voltar a percorrer o grafo. O grafo é o grafo IR versionado, com fonte única no schema ir-v1beta1; a forma do IR não é secreta (é o mesmo grafo que aggrega inspect emite) e os segredos nele são ponteiros, nunca texto simples.
  • O RenderPolicyInput de render-verdict transporta artifacts — os ficheiros de saída renderizados ordenados por caminho, pelo que os dados transmitidos são idênticos byte a byte entre execuções com entrada idêntica. Cada entrada transporta o path de saída do artefacto e o seu content renderizado; transporta também o format em que foi renderizado, quando o fornecedor que o produziu declarou um, e um tree, a vista canónica analisada de um formato que o guest não lê nativamente, que o anfitrião analisa através do analisador resolvido e transmite de forma opaca. Ambos estão ausentes quando não se aplicam — um formato que o guest lê nativamente (JSON, YAML) fica por analisar para que o guest o leia a partir de content.

Ambos os papéis transportam ainda as sources do anexo (ficheiros de definição de políticas que o anfitrião lê em tempo de compilação e entrega ao guest sem alterações, com os caminhos como nomes base e o conteúdo opaco) e as settings (um objeto de forma livre entregue sem alterações). Ambos estão ausentes quando o anexo não declara nenhum.

Forma de saída (guest → anfitrião). Um documento PolicyOutput que contém:

  • results — um array de entradas Diagnostic, cada uma com uma severity (halt, warn ou info) e uma string message. Um veredicto pode também definir code, rule_id, classification, source_ref, location e suggest na mesma entrada; o anfitrião acrescenta ao veredicto apresentado aqueles que o veredicto transportava, em todas as vias de severidade.

Só aparecem os veredictos disparados; uma avaliação que permite devolve um array vazio. O anfitrião percorre os veredictos e faz corresponder cada severidade a uma ação: halt interrompe a compilação (apresentando cada mensagem halt), warn assinala o veredicto e deixa a compilação prosseguir, info regista-o sem afetar o resultado. Um halt interrompe a compilação através do mesmo ponto de controlo que uma violação de um seletor ou de appliesTo usa.

Codificação de transmissão. Os payloads de ambos os papéis, e o PolicyOutput que um guest devolve em qualquer um deles, circulam como CBOR canónico (RFC 8949 §4.2.1). Um guest lê-os e escreve-os através dos pontos de entrada que os tipos de payload transportam — DecodeCBOR e EncodeCBOR em Go, decode_cbor e encode_cbor em Rust, decodeCBORPolicyInput, decodeCBORRenderPolicyInput e encodeCBORPolicyOutput em TypeScript — pelo que nenhuma biblioteca CBOR é necessária e nada analisa bytes à mão. Em Rust, cada export recebe e devolve Vec<u8>; em TypeScript, lê Host.inputBytes() e escreve Host.outputBytes(...). Os mapas do grafo que preservam a ordem, entre eles os seus nodes e as labels de cada nó, circulam como listas ordenadas de entradas pela ordem em que a compilação os guarda, e um guest lê-os através do contentor do seu kit que mantém a ordem; a ordem pela qual uma política os encontra em cada motor de políticas está na página do socket de governação. settings, e o tree analisado de um artefacto, circulam como os bytes dos seus documentos JSON, que um guest analisa como JSON para examinar o conteúdo. Uma resposta que não seja um PolicyOutput nesta codificação — uma escrita como JSON, ou uma que transporte um campo de nível superior que a forma não declara — interrompe a compilação, nomeando o plugin e o seu export, em vez de ser lida como uma lista vazia de veredictos. 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 a sua resposta é lida como a forma de saída do export e impressa como JSON — uma resposta que não tenha essa forma é recusada, nomeando o export, tal como uma compilação 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 partilhado e PolicyOutput, cujas entradas results são valores Diagnostic. A severidade de um diagnóstico é um de três valores que todos os sockets partilham — 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, pelo que um guest reporta a partir do mesmo conjunto fechado sobre o qual o anfitrião encaminha. Um guest que devolva qualquer outro valor interrompe a compilação, com a mensagem a nomear o plugin e o valor que devolveu: uma severidade não encaminhável é um defeito do plugin que o anfitrião reporta, em vez de um diagnóstico que descarta.

Contrato de forma de saída — o pipeline de FeatureRecipe e os sockets de fornecedor

Os sockets abaixo oferecem superfícies de contrato tipadas que o compilador aciona em tempo de compilação. Os passos de pipeline: da FeatureRecipe e da Recipe são executados no pipeline de plugins sobre o conjunto de documentos renderizados; o socket de renderização de fornecedores é executado na renderização base; o linter de publicação é executado fora de banda.

Patches RFC 6902 (o pipeline de plugins)

Os passos de pipeline: da FeatureRecipe e da Recipe executados no pipeline de plugins emitem operações JSON Patch RFC 6902 sobre o conjunto de documentos renderizados. O anfitrião entrega a cada passo o conjunto de documentos indexado por chave na íntegra; o passo seleciona pelo conteúdo os documentos que visa e devolve patches endereçados por chave, que o motor de aplicação aplica aos documentos endereçados — tipicamente acrescentando um contentor sidecar, montando um volume de secret ou reescrevendo uma variável de ambiente. Um passo devolve também side_effects (abaixo), diagnostics — cada entrada na mesma forma partilhada Diagnostic em que todos os sockets reportam problemas — e outputs (abaixo). Descrito em examples/04-secrets.md.

Estado atual: disponível. Cada passo declarado é executado durante aggrega build.

Codificação de transmissão. A entrada de um passo (FRPStepInput) e a sua resposta (FRPStepOutput) circulam como CBOR canónico (RFC 8949 §4.2.1), nos dois sentidos. Um guest descodifica a sua entrada e codifica a sua resposta através dos pontos de entrada que os tipos de payload transportam — 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 do passo (step_input), os outputs que devolve e os conjuntos de documentos own e host são mapas que o schema marca como mapas que preservam a ordem, pelo que circulam como listas ordenadas de entradas pela ordem em que o pipeline os guarda, e um guest lê-os e escreve-os através do contentor do seu kit que mantém a ordem — o que permite que as saídas de um passo cheguem a .steps.<id>.outputs pela ordem em que o passo as devolveu. O tree de cada unidade, cada valor de step_input e outputs, o value de um patch, o crd de um efeito secundário e o context de renderização circulam como os bytes dos seus documentos JSON, que um guest analisa como JSON para examinar o conteúdo; os bytes de uma unidade circulam como uma sequência de bytes em bruto que o descodificador gerado coloca no tipo de campo próprio do kit — um slice de bytes em Go, uma string base64 em Rust e TypeScript. Cada diagnóstico circula na forma partilhada Diagnostic. Uma resposta que não seja um FRPStepOutput nesta codificação — uma escrita como JSON, ou uma que transporte um campo de nível superior que a forma não declara — faz falhar o passo, nomeando a função que executa, o que interrompe a compilação, a menos que o passo seja optional. Chamado diretamente com aggrega plugin run-local --export step, um passo recebe o payload JSON escrito pelo autor convertido para esta codificação, e a sua resposta é lida como a forma de saída do export e impressa como JSON — uma resposta que não tenha essa forma é recusada, nomeando o export, tal como uma compilação a recusa.

Efeitos secundários — 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 juntamente com um patch através dos side_effects de um passo, 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 obtém em tempo de execução, ou emit_file, um ficheiro escrito. Um passo que devolva qualquer outro tipo interrompe a compilação, nomeando o nó, o índice do efeito secundário e o tipo que declarou. O passo do Fetcher emite o recurso completo; o passo do Injector devolve um patch que monta o Secret do Kubernetes resultante. Descrito em examples/04-secrets.md.

Estado atual: disponível.

Saída de um passo (mapa outputs de um passo de pipeline:)

Um passo do pipeline de plugins publica saídas nomeadas que os passos seguintes consomem através de {{ .steps.<id>.outputs.<key> }}. A forma da saída é definida pelo fornecedor para cada plugin; as saídas dos passos têm como âmbito o mesmo pipeline e só são visíveis para os passos seguintes, pela ordem de declaração. Documentado em templates/expansion-matrix.md, linha 10.

Estado atual: disponível.

Renderização de Provider — o socket conduzido pelo guest

Um fornecedor é um guest Wasm. A renderização é exclusivamente Wasm: o nome de capability: de uma Recipe resolve-se no Plugin de renderização de fornecedores (pluginType: provider) que lista esse nome nas suas spec.provider.capabilities e anuncia um export render_node, e o guest desse plugin renderiza o nó. Não existe nenhum renderizador dentro do anfitrião ao qual recorrer; um nome de fornecedor que não se resolva em nenhum Plugin que o sirva interrompe a compilação no momento do encaminhamento. Adicionar um fornecedor padrão é distribuir um guest .wasm e uma entidade Plugin do catálogo — o anfitrião não contém código específico de fornecedor.

Uma capacidade que um fornecedor serve não contém dois pontos, e o mesmo acontece com uma com a qual um passo de pipeline se declara compatível. O capability: de uma Recipe é lido como a capacidade até aos seus últimos dois pontos, seguida de uma fixação de versão — helm:1.0.0 pede helm na versão 1.0.0 — pelo que um nome que contenha dois pontos é um que nenhuma Recipe pode pedir. O anfitrião recusa tal nome nas capabilities de describe() para um guest provider ou pipeline-step quando o guest é carregado e quando a 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 os seus dois pontos: são procurados por formato, nunca através do capability: de uma Recipe.

O anfitrião é um encaminhador genérico. Lê a autodescrição describe() do guest — incluindo o seu contrato de comportamento de renderização — e despacha os exports do guest sem compreender nenhum formato de fornecedor. Esse contrato conduz o despacho como dados:

  • input_kinds (sourced, synthesized, artifacts_standalone) — que tipos de entrada de Recipe o guest renderiza; o anfitrião 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: merge classifica a saída de cada nó como fragmentos que o montador funde num único artefacto, nest aninha os ficheiros de cada nó sob um invólucro montado, none escreve diretamente a saída de cada nó.
  • nest_segment (opcional) — para uma montagem nest, o diretório sob o qual é colocado o subdiretório próprio de cada contribuidor, 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 artefacto que o guest monta a partir de um grupo de despacho; se ausente, o guest nomeia a sua montagem apenas a partir do caminho de despacho.
  • cross_boundary_linking (opcional) — se o guest liga uma aresta uses entre fronteiras através dos seus exports link_publish e link_resolve; um guest declara-o verdadeiro exatamente quando exporta ambos, e o carregamento recusa um guest cujo indicador e cujos exports não coincidam.
  • artifact_delimiters (opcional) — o par de delimitadores de template Go que o guest aplica aos corpos dos artefactos.
  • reusable_instance (opcional) — se uma única instância carregada pode servir cada travessia da compilação (ver 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 transporta (ver Deixar de fora unidades renderizadas abaixo).
  • boundary_artifacts (opcional) — se o destino do guest aceita os ficheiros com que uma Recipe contribui para a saída partilhada da sua fronteira (ver Aceitar os ficheiros com que uma Recipe contribui para a fronteira abaixo).
  • source_ignore (opcional) — os ficheiros que o ecossistema do guest nunca distribui junto a uma fonte que renderiza (ver Declarar o que o ecossistema de uma fonte nunca distribui abaixo).

O socket é um conjunto fixo de exports — um obrigatório, os restantes opcionais e anunciados em describe():

  • render_node (obrigatório) — renderiza um nó IR em ficheiros nativos do fornecedor.
  • assemble_boundary (opcional) — funde a saída por nó de um grupo de despacho num único artefacto por caminho (presente quando boundary_assembly é merge ou nest).
  • validate_node_input (opcional) — validação estrutural da entrada de um nó antes da renderização; um diagnóstico halt interrompe a compilação, um warn surge no resultado da compilação.
  • carve / reassemble (opcionais, em par) — o codec de patches próprio do guest, fiel byte a byte, para passos de pipeline pós-renderização, usado apenas quando ambos são anunciados.
  • name_bound (opcional) — o guest avalia se um nome que o anfitrião 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 indica o nome que o seu destino dá aos recursos que renderiza para um nó.
  • link_publish / link_resolve (opcionais, em par) — o guest liga uma aresta uses entre fronteiras: a extremidade consumida publica um identificador, e a extremidade consumidora resolve-o na sua própria saída montada.

Os artifacts: de uma Recipe integram-se em render_node através de uma projeção de artefactos na entrada: o anfitrião 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 transporta os valores do nó em node.values, e node.values_mapped indica de onde vieram: é true quando são a saída do valuesMapping da Recipe — ou, para a renderização própria de um anexo, do da sua FeatureRecipe — e está ausente quando são os valores próprios do componente transmitidos tal como foram escritos. Se um guest o lê ou não faz parte do contrato próprio desse guest. O fornecedor 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 fornecedor terraform escreve os argumentos de um módulo proveniente de uma fonte a partir dos valores que a sua montagem recebe, e não lê o indicador. Esses valores circulam 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 quer não, os de uma Feature anexada apenas onde o valuesMapping da sua FeatureRecipe os produziu — e o mesmo indicador circula junto deles e apenas onde eles circulam, pelo que um montador lê a mesma resposta que a renderização própria do nó leu; o fornecedor cloudformation lê-o aí para saber que parâmetros a associação de um nó preencheu, e recusa uma referência a um deles a partir de qualquer outro ponto da stack, incluindo o componente anfitrião de uma Feature anexada. O indicador regista como os valores foram produzidos e nunca é derivado de uma chave nem de um valor.

Codificação de transmissão. Cada export deste socket recebe a sua entrada e devolve a sua saída como CBOR canónico (RFC 8949 §4.2.1), nos dois sentidos. Um guest descodifica a sua entrada e codifica a sua saída através dos pontos de entrada que os tipos de payload já transportam — 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 ficheiro renderizado, e qualquer outro campo de bytes, circula como uma sequência de bytes em bruto que o descodificador gerado coloca 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 — circulam como listas ordenadas de entradas pela ordem em que a compilação os guarda, e um guest lê-os através do contentor do seu kit que mantém a ordem. Cada valor dos values de um nó circula como os bytes do seu próprio documento JSON, pelo que as chaves dentro de um valor mantêm a ordem em que foram escritas; o mesmo acontece com cada entrada de anexo 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 analisa-os como JSON para examinar o conteúdo. Cada diagnóstico circula na forma partilhada Diagnostic. Uma resposta que não tenha a forma de saída do seu export nesta codificação — uma escrita como JSON, ou uma que transporte um campo de nível superior que a forma não declara — interrompe a compilação, nomeando o export que esta 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 a sua resposta é lida como a forma de saída do export e impressa como JSON — uma resposta que não tenha essa forma é recusada, nomeando o export, tal como uma compilação a recusa.

Estado atual: disponível para os cinco fornecedores. O guest helm renderiza charts provenientes de uma fonte (resolvendo a raiz do chart), cargas de trabalho sintetizadas e artefactos 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 transporta um codec de patches fiel byte a byte e delimitadores de artefacto entre parênteses retos ([[ ]]). O guest compose renderiza ficheiros compose provenientes de uma fonte e cargas de trabalho sintetizadas e funde um grupo de despacho num ú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 as 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 numa ú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, funde um grupo de despacho num único template de stack, e liga uma aresta uses entre fronteiras através 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 fornecedor deriva habitualmente nomes de que a 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á a emitir. Dois nós podem chegar a um mesmo nome sempre que as partes de que são derivados coincidem, e como o nome vive dentro dos bytes do ficheiro que o anfitrião escreve tal como estão, o anfitrião não consegue ver o conflito: teria de analisar o formato do fornecedor para o encontrar, que é exatamente o conhecimento que permanece no guest.

Por isso, render_node devolve na sua saída derived_keys opcionais, e a direção inverte-se — em vez de o anfitrião inspecionar a saída, o guest declara e o anfitrião 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 transporta os nomes que o guest derivou para ele, por ordem de derivação. Tanto os nomes dos espaços como os nomes dentro deles são o seu vocabulário: o anfitrião lê-os apenas como cadeias a comparar quanto à igualdade dentro de um mesmo espaço. Não analisa um nome, não aprende o que um espaço ou um nome significa e nunca deriva um por si — assim, uma única verificação cobre todo o tipo de nome que qualquer fornecedor deriva, e um novo fornecedor não precisa de novo código no anfitrião. Nos tipos publicados, derived_keys é um mapa que mantém a ordem, pelo que os espaços circulam pela ordem em que o seu guest os define.

O que o anfitrião faz com eles resume-se a uma única pergunta: dentro de um espaço, cada nome declarado é distinto entre os contribuidores cuja saída se funde numa única montagem? Dois contribuidores que declaram um mesmo nome num mesmo espaço interrompem a compilação, e a interrupção nomeia o espaço, o nome e ambos os contribuidores, pelo que um autor pode agir sem ler o fornecedor. Nomes distintos, e nomes que por acaso coincidem entre dois espaços diferentes, passam.

Convém conhecer três propriedades ao decidir o que declarar:

  • O âmbito é uma saída montada — o conjunto de contribuidores cujos ficheiros se fundem. Um guest que pretenda unicidade num âmbito mais estreito ou mais amplo do que esse exprime o âmbito no nome do espaço que declara, o que mantém a escolha do lado de quem escreve o guest e não do lado do anfitrião.
  • 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 artefactos — e as declarações fundem-se. O mesmo nome declarado duas vezes por um contribuidor é esse contribuidor a descrever 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 ao que emitiu, pelo que a saída renderizada de um guest é idêntica quer declare quer não. Omitir derived_keys é válido e deixa a verificação inativa para esse guest.

Comunicar factos sobre aquilo que um guest emitiu

Algumas coisas sobre a renderização de um nó só são visíveis para o fornecedor que a produziu — o que contêm os documentos que escreveu, que nomes definem, quantos elementos de algo emitiu — porque extraí-las dos bytes do ficheiro implica compreender o formato do fornecedor. render_node pode comunicar essas coisas por si próprio, numa lista opcional render_facts junto aos seus ficheiros:

{
"files": [ { "path": "stack.yaml", "content": "..." } ],
"render_facts": [
{ "name": "exported_outputs", "value": ["QueueUrl", "TopicArn"] },
{ "name": "stacks", "value": [ { "name": "payments-api", "resources": 2 } ] }
]
}

Cada facto é um name e um value, e ambos pertencem ao seu fornecedor: que factos comunica, o que cada nome significa e o que cada entrada contém fazem parte do contrato documentado próprio do seu fornecedor, pelo que devem ser documentados para os autores que os vão ler.

O valor de cada facto deve ser comunicado como uma lista — um array JSON — mesmo quando contém uma única entrada. Um mesmo nome pode ser comunicado por mais de uma renderização de um componente: a sua própria renderização pode envolver várias chamadas — uma renderização de chart e um posicionamento de artefactos, por exemplo — e cada Feature anexada ao componente é renderizada através de uma chamada ao fornecedor própria. Nenhum fornecedor pode saber, ao renderizar, se a sua comunicação será a única sob um nome, pelo que cada comunicação é uma lista, e o compilador junta numa única lista as listas que um nome recebe. Um facto cujo valor seja qualquer outra coisa — um objeto, uma cadeia, um número, um booleano, null — é recusado quando o seu guest o devolve: a compilação é interrompida com o código curto E0325, nomeando o facto, o nó e o seu guest, e indicando qual era o valor. As entradas dentro de uma lista são quaisquer valores JSON na forma que for documentada.

Que um valor seja uma lista é a única coisa que o compilador aprende sobre ele. Indexa os factos por nome e entrega cada lista aos templates que a leem — os factos do componente anfitrião a cada Feature anexada a ele, os factos de cada chamador a uma Feature que declara ler os factos de renderização dos seus chamadores, e os factos de cada destino a uma Feature que declara ler os factos de renderização dos componentes a que o seu componente anfitrião está ligado, como descreve o contexto de template — descodificando cada lista num valor que um template pode percorrer. Nunca aprende o que um nome ou uma entrada significa e nunca deriva um facto por si, pelo que um novo fornecedor pode comunicar novos factos sem qualquer alteração do lado do compilador. Os factos que uma Feature anexada ao nó comunica a partir da sua própria renderização são mantidos separados dos que a renderização própria do nó comunicou.

Convém conhecer quatro propriedades ao decidir o que comunicar:

  • A ordem é sua. Os factos mantêm a ordem pela qual o seu guest os lista, e cada valor mantém os seus próprios bytes — a ordem das entradas de uma lista e das chaves de cada objeto é a ordem que o seu guest escreveu. Os factos devem ser listados por uma ordem fixa, e cada entrada escrita com uma ordem de chaves fixa, para que dados de entrada idênticos produzam bytes idênticos; uma lista de factos em vez de um mapa existe precisamente para que essa ordem sobreviva no tipo de sequência próprio de cada kit sem nada a marcar, ao passo que um mapa mantém a ordem que um guest escreveu apenas quando o seu esquema o marca como mapa que preserva a ordem e o guest preenche o contentor que mantém a ordem do seu kit.
  • Comunicar não altera nenhum byte. Os ficheiros que o compilador escreve são os ficheiros que o seu guest devolveu, quer haja factos a acompanhá-los quer não.
  • Um nó pode comunicar em várias travessias. Um nó pode ser renderizado como renderização de fonte, síntese de carga de trabalho e posicionamento de artefactos; os factos que cada uma comunica são mantidos pela ordem em que as travessias foram executadas, e um nome comunicado por mais de uma delas lê-se como uma única lista que as junta por essa ordem.
  • Não comunicar nada é completo. Omitir render_facts é válido, e um fornecedor que não comunica nada renderiza exatamente como renderizaria 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 comunicam dois factos junto aos seus ficheiros. Em Go, um valor é o JSON que o seu guest escreve; serializar uma slice de structs em vez de mapas é o que mantém as chaves de cada entrada pela ordem em que foram declaradas:

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 fornecedor tem de deixar de fora do que renderiza — um Secret que um chart obtido gera de novo em cada renderização, por exemplo. Que unidade renderizada uma entrada nomeia é um conhecimento que só o seu fornecedor tem, pelo que as entradas circulam até ao seu guest e é o seu guest que as deixa de fora. Chegam na entrada de render_node como uma lista opcional omits junto ao 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 cadeias simples e listados pela ordem em que o autor os declarou; uma entrada que não se aplica à compilação não é transmitida. O que os três campos selecionam é o contrato próprio do seu fornecedor — o tipo, o nome e o namespace de um recurso no formato do seu destino — pelo que deve ser documentado 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 definição sensível, por exemplo. Uma entrada assim chega com "sensitive": true, e o seu guest trata-a como trata qualquer outro valor marcado que a entrada de renderização transporta (ver Valores que uma entrada marca como sensíveis): continua a fazer corresponder e a contar a entrada pelos seus campos, que é para isso que a entrada serve, e mantém cada um dos seus campos fora de uma recusa, de um aviso ou de uma linha de registo. A marcação abrange a entrada inteira, porque o compilador não diz que campo o valor produziu. Está ausente quando nenhum campo foi construído a partir de um valor assim.

Um guest que respeita as entradas faz três coisas:

  • Faz corresponder cada entrada ao que renderizou, nos termos do seu formato.
  • Deixa cada unidade correspondente de fora de tudo o que devolve — os seus files, os nomes que declara em derived_keys e os factos que comunica em render_facts — pelo que nada do que o compilador recebe ainda a descreve.
  • Comunica uma contagem por entrada numa lista opcional omitted na sua saída, pela ordem em que as entradas chegaram, cada uma o número de unidades a que essa entrada correspondeu, contadas quer outra entrada também lhes tenha correspondido quer não:
{
"files": [ { "path": "templates/deployment.yaml", "content": "..." } ],
"omitted": [1, 0]
}

Um zero é uma resposta completa: essa entrada não correspondeu a nada do que o seu guest renderizou. As contagens são tudo o que volta sobre o que foi deixado de fora; as próprias unidades estão simplesmente ausentes do que o seu guest devolveu.

Um fornecedor que faz as três coisas declara-o com omits: true no seu contrato. A entidade Plugin regista a mesma declaração como spec.provider.contract.omits; onde a entidade transporta um contrato de comportamento de renderização, o carregamento recusa um guest cujo describe() indica 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 artefactos nunca as transporta.

Uma renderização que não transporta entradas não é alterada pelos campos. Ambos os campos são opcionais e ausentes quando vazios, pelo que uma renderização que não transporta entradas atravessa o socket byte a byte tal 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 a sua resposta. As entradas vêm da chave omits: que um autor escreve numa Recipe ou numa FeatureRecipe (Recipe → O campo omits:); o compilador avalia os templates de cada entrada e entrega ao seu guest as que se aplicam. Depois lê as suas contagens, e apenas as suas contagens — nunca olha para dentro de um ficheiro devolvido para as verificar:

Estado 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 num texto que devolve. 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 ficheiro ou um template que ainda as nomeia, e mostram aí cada campo de uma entrada marcada como <redacted>. Os guests helm-chart e terraform não fazem a declaração, pelo que um documento que declara omits: e que um deles renderiza é recusado.

Aceitar os ficheiros com que uma Recipe contribui para a fronteira

Alguns ficheiros pertencem a uma fronteira como um todo, e não a um dos seus componentes — uma configuração de fornecedor que um destino lê uma única vez para tudo o que a fronteira implanta, por exemplo. Uma Recipe escreve-os sob spec.boundary.artifacts, e é o compilador, não o seu guest, que faz o trabalho: avalia cada ficheiro no contexto em que uma entrada artifacts: é avaliada, funde por nome os ficheiros 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, junto ao que o seu assemble_boundary devolve. O seu guest não recebe nenhum destes ficheiros em nenhum export e nunca é consultado sobre nenhum deles, pelo que 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
}

boundary_artifacts: true só deve ser declarado quando o seu destino lê um ficheiro colocado nesse diretório como parte da saída da fronteira. A entidade Plugin regista a mesma declaração como spec.provider.contract.boundaryArtifacts; onde a entidade transporta um contrato de comportamento de renderização, o carregamento recusa um guest cujo describe() indica um valor diferente. Uma Recipe que declara o bloco cujo fornecedor não o declara é recusada antes de qualquer renderização, nomeando o fornecedor e o componente; ver The provider does not support boundary artifacts (O fornecedor não suporta artefactos de fronteira). Um ficheiro que uma destas fusões coloca sob um nome que a sua montagem também escreve interrompe a compilação como dois contribuidores a escrever um mesmo caminho de saída, pelo que os nomes que a sua montagem escreve fazem parte do que é documentado para os autores.

Estado atual: disponível. O guest terraform distribuído com o compilador faz a declaração, e o Terraform lê cada ficheiro junto à 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 dela, um módulo — é publicado com a Recipe, e nem todos os ficheiros que contém lhe pertencem. Um guest de fornecedor declara o que o seu próprio ecossistema nunca distribui através de source_ignore no seu contrato, sob a forma de 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"]
}
}
  • patterns são regras lidas a partir da raiz do diretório da fonte, aplicadas por ordem, prevalecendo uma correspondência posterior sobre uma anterior.
  • files nomeia os ficheiros de exclusão que o ecossistema do guest respeita dentro de uma fonte. Sempre que o percurso de uma fonte encontra um deles, as suas linhas são lidas como regras adicionais para o diretório que o contém, depois dos padrões declarados.

A declaração é lida quando uma entidade é fixada, não quando é renderizada. O passo de fixação do autor resolve, no espaço de trabalho do autor, o plugin que serve a capacidade da entidade, compõe as regras do plugin com o próprio .aggregaignore do autor — cujas linhas vêm em último lugar e, por isso, prevalecem em qualquer caminho que nomeiem — e regista o nome do plugin, sem versão, juntamente com as regras compostas exatas, no entity.lock da entidade. Cada publicação, comparação e renderização posteriores dessa entidade aplicam as regras registadas; o anfitrião faz a correspondência e não tem qualquer opinião própria sobre nenhum ecossistema. Assim, os ficheiros que o guest recebe na renderização — a listagem e cada ficheiro que pede ao anfitrião para empacotar ou ler — são exatamente os ficheiros que uma publicação da entidade transporta, e a um ficheiro que as regras deixam de fora responde-se que não existe, nomeando-o. Uma ligação simbólica dentro de uma fonte é recusada antes de o guest ser invocado.

A compatibilidade decorre do que foi registado. 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 não precisa de nenhum ficheiro fora do conjunto publicado. Um guest que precise de um ficheiro que o conjunto deixou de fora tem de fazer falhar a sua compilação de forma visível e nomear o ficheiro — a recusa pelo anfitrião de um empacotamento ou de uma leitura nomeia-o, e um guest transporta isso para a sua própria falha. Quando o plugin que o espaço de trabalho de um consumidor associa a uma capacidade declara regras diferentes das que o ficheiro de bloqueio de uma entidade regista, o pull do consumidor imprime um aviso que nomeia ambos os plugins e a diferença; nunca é interrompido por isso.

Omitir source_ignore não declara nenhuma regra, e uma fonte que se renderize mantém então todos os ficheiros 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 omita é carregado como um que não declara nada. A entidade Plugin regista a mesma declaração como spec.provider.contract.sourceIgnore; quando o faz, o carregamento recusa um guest cujo describe() indique algo diferente.

Determinismo e reutilização de instâncias

O anfitrião consome os bytes de saída de um guest literalmente, pelo que um guest tem de produzir uma saída idêntica a partir de uma entrada idêntica. Por predefinição, um guest é carregado de novo para cada nó — nenhum estado transita entre nós, por construção. Um guest que autodeclara reusable_instance é, em vez disso, carregado uma vez por compilação e a sua única instância serve 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 através da mesma instância e interrompe a compilação se as duas renderizações de qualquer nó diferirem; a compilação predefinida renderiza uma vez e confia na declaração. A cache de compilação do Wasm fica em disco e é partilhada por todo o processo, pelo que um guest é compilado uma vez e as compilações a quente saltam 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 controlo fora de banda que é executado através de aggrega lint e não em tempo de compilação. Consome uma entidade do catálogo (e, no modo --pre-publish, a versão atualmente publicada da entidade) e devolve uma lista de constatações, cada uma com uma severidade e uma mensagem; no modo --pre-publish, devolve também uma classificação do incremento de versão. O anfitrião despacha-o através do runtime Wasm integrado, por trás da mesma firewall de pureza AOT que qualquer outro socket. 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 voluntária: o compilador não o executa durante aggrega build (com a única exceção do aviso que desaconselha x-aggrega-*, que surge com severidade warn durante a compilação e com severidade halt sob aggrega lint --pre-publish). Como as regras residem num 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 âmbito em que aggrega lint seja executado. Antes de qualquer documento ser entregue, o anfitrião retém os valores predefinidos dos parâmetros de um Aggregate, os valores que este 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 anexado aqui pode ser código que o espaço de trabalho não escreveu. O que cada documento transporta está descrito em O que é entregue a um plugin de linter.

Codificação de transmissão. A entrada e a saída circulam ambas como CBOR canónico (RFC 8949 §4.2.1). Um guest descodifica a sua entrada e codifica a sua saída através dos pontos de entrada que LinterInput e LinterOutput do seu kit já transportam — 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 circulam como os bytes dos seus documentos JSON, pelo que um guest os analisa como JSON para examinar o conteúdo. components é um mapa que o schema marca como mapa que preserva a ordem, pelo que, na entrada de uma regra que lê uma Release inteira, circula como uma lista ordenada de entradas pela ordem em que o Aggregate declara as suas instâncias de componente, e um guest lê-o através do contentor do seu kit que mantém a ordem. policies circula como um mapa que contém apenas os indicadores definidos, pelo que um indicador que não contenha é lido como falso, e cada constatação circula na forma partilhada Diagnostic. Uma resposta que não seja um LinterOutput nesta codificação — uma escrita como JSON, ou uma que transporte um campo de nível superior que a forma não declara — faz falhar o lint, 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 a sua resposta é lida como a forma de saída do export e impressa como JSON — uma resposta que não tenha essa forma é recusada, nomeando o export, tal como uma compilação a recusa.

Estado atual: disponível. O publishing-linter é distribuído e executado através do anfitrião via aggrega lint.

O socket de analisador — saída de árvore canónica

Um analisador transforma uma fonte escrita num formato que o compilador não lê nativamente numa árvore estruturada canónica, pelo que um consumidor lê a árvore em vez de transportar um analisador próprio. O anfitrião resolve o analisador que anuncia o formato pedido como parse:<format> e chama o seu export parse em três pontos: quando uma política do papel render-verdict recebe um artefacto renderizado num formato que não lê nativamente, quando um importador pede ao anfitrião uma árvore através de aggrega_parse_source, e quando é reconhecida uma importação que não nomeia nenhum formato (ver o socket importador abaixo). Um guest nunca chama ele próprio um analisador.

Forma de entrada (anfitrião → guest). Um documento ParseInput que contém:

  • format — o formato pedido, uma das capacidades parse:<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, entregue literalmente. Ausente quando o consumidor não fornece nenhum.

Forma de saída (guest → anfitrião). Um documento ParseOutput que contém 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 partilhada 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 as 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 circulam ambas como CBOR canónico (RFC 8949 §4.2.1), a codificação em que o mesmo ParseInput circula quando um guest o entrega a aggrega_parse_source. Um guest descodifica a sua entrada e codifica a sua saída através dos pontos de entrada que ParseInput e ParseOutput do seu kit já transportam — 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 circulam como uma sequência de bytes em bruto, e o descodificador gerado coloca-os no tipo de campo próprio do kit: um slice de bytes em Go, uma string base64 em Rust e TypeScript. options e tree circulam como os bytes dos seus documentos JSON, pelo que a árvore que um analisador escreve chega ao seu consumidor literalmente. Um analisador que não consiga concluir diz porquê no error da saída, e a análise falha nomeando o analisador e essa mensagem; uma resposta que não seja um ParseOutput nesta codificação — uma escrita como JSON, ou uma que transporte um campo de nível superior que a forma não declara — faz também falhar a análise, nomeando o analisador e o seu export parse. Uma análise falhada interrompe uma compilação no papel render-verdict e chega a um importador como a falha com que aggrega_parse_source responde. O mesmo acontece com uma fonte que o analisador recusa — uma à qual responde com um diagnóstico halt junto da sua árvore: a chamada do importador falha com a mensagem de cada um desses diagnósticos, pela 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, tal como o JSON escreve qualquer campo de bytes — e a sua resposta é lida como a forma de saída do export e impressa como JSON — uma resposta que não tenha essa forma é recusada, nomeando o export, tal como uma compilação 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 se mantenham sincronizados. O exemplo parse de cada kit lê a sua entrada e escreve a sua saída desta 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.

Estado atual: disponível — despachado no papel render-verdict para um artefacto num formato que a política não lê nativamente, através de aggrega_parse_source para um importador, e para reconhecer o formato de uma importação que não nomeie 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 ficheiros de autoria do Aggrega em rascunho. É executado fora de banda: aggrega import, o método aggrega/import da sessão do editor e a ferramenta import destinada ao assistente resolvem o importador que anuncia o formato pedido como import:<format> e chamam o seu export import uma vez por importação. Uma compilação nunca o despacha. Que importador é executado, e o que um operador lhe entrega, está descrito em Que importador transforma uma origem em rascunhos. Os importadores próprios do compilador, um para cada formato que lê, estão descritos em Importadores core: que formatos são esses, o que cada um lê, o que gera como rascunho, as definições que aceita, a sua publicação com cada versão do compilador e a forma como uma importação obtém e verifica um que a máquina ainda não contém.

Forma de entrada (anfitrião → guest). Um documento ImportInput que contém:

  • format — o formato que a importação pediu, uma das capacidades import:<format> do importador sem o seu prefixo.
  • bytes — os bytes da fonte: o ficheiro inteiro numa importação de um ficheiro, e vazio numa importação de um diretório, cujos ficheiros chegam em sources.
  • name — o nome da fonte, sem diretório antes dele, para que o importador possa indicar a fonte naquilo que comunica e naquilo que gera como rascunho: numa importação de um ficheiro, o nome base do ficheiro a partir do qual bytes foi lido; numa importação de um diretório, o nome base do próprio diretório, lido a partir do seu caminho completo, pelo que aggrega import . entrega o nome do diretório em que é executado, enquanto os ficheiros do diretório continuam a chegar cada um com o seu próprio nome. Ausente quando a fonte não tem nome a dar.
  • sources — as fontes nomeadas, cada uma com o seu nome e os seus bytes, numa única lista ordenada por nome: numa importação de um diretório, cada ficheiro deste que os padrões de ficheiro declarados do importador selecionam, excluída a pasta de saída da compilação da área de trabalho, nomeado pelo seu caminho separado por barras dentro do diretório; e os ficheiros que a entrada plugins.importer que anexa este importador declara em with.sources, cada um com o seu nome base. Um ficheiro do diretório e um ficheiro de with.sources com o mesmo nome fazem com que a importação seja recusada, em vez de um esconder o outro. Ausente onde não exista nenhuma.
  • settings — o objeto de definições que essa entrada declara em with.settings, como um documento JSON com as chaves ordenadas, entregue literalmente. Ausente quando nenhuma entrada anexa o importador ou a entrada não declara nenhuma.
  • catalog — uma vista dos Components que o catálogo próprio do espaço de trabalho contém: o catálogo a partir do qual o próprio importador foi selecionado — as pastas de catálogo do espaço de trabalho ou, onde este não indica nenhuma, o snapshot do catálogo que o seu registo predefinido publica, guardado nesta máquina —, sem que nada seja obtido para a própria vista. A sua lista components conté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 indica sem versão. Cada entrada transporta o name e a version do Component, os seus labels, os nomes das chaves de nível superior que os seus values e provides declaram (values e provides, cada um ordenado), e os seus sockets — cada um com o name do socket e o selector de etiquetas que uma dependência ligada através dele tem de satisfazer — pela ordem em que o Component os declara. Um Component que estende outro transporta aquilo que herda além daquilo que declara, e os sockets que herda vêm primeiro. A vista contém apenas nomes, versões, etiquetas e seletores — nunca um valor, um valor predefinido ou um segredo — e a sua ordem é fixa, pelo 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 → anfitrião). Um documento ImportOutput que contém 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 detrás delas, eventuais diagnósticos na forma partilhada Diagnostic, os ficheiros de scaffold a escrever, e uma falha em error quando a importação não pôde ser concluída. Cada campo e as 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 circulam ambas como CBOR canónico (RFC 8949 §4.2.1). Um guest descodifica a sua entrada e codifica a sua saída através dos pontos de entrada que ImportInput e ImportOutput do seu kit já transportam — 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 circula dentro do documento binário como os bytes do seu documento JSON, pelo que um guest o analisa como JSON para examinar o conteúdo, como em qualquer outro socket. Um importador que não consiga concluir diz porquê no error da saída, e a importação é interrompida nomeando o importador e essa mensagem; uma resposta que não seja um ImportOutput nesta codificação — uma escrita como JSON, ou uma que transporte um campo de nível superior que a forma não declara — interrompe também 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 a sua resposta é lida como a forma de saída do export e impressa como JSON — uma resposta que não tenha essa forma é recusada, nomeando o export, tal como uma compilação a recusa.

Como é reconhecida uma fonte do seu formato. Uma importação pode não indicar nenhum formato, e o anfitrião reconhece então um a partir daquilo que os importadores declaram, sem conhecer por si só nenhum formato. Um importador declara na sua autodescrição describe(), em importer (um ImporterContract), uma lista detect das assinaturas pelas quais uma fonte dos seus formatos é reconhecida. Cada DetectSignature indica:

  • syntax — o formato sintático em que a fonte é analisada, um formato que um plugin de analisador anuncia como parse:<syntax>, como json ou yaml;
  • files — padrões opcionais de nome de ficheiro comparados com o final do nome da fonte: um segmento com o próprio nome do ficheiro, vários segmentos separados por barras com igual número de segmentos finais do seu caminho, com *, ? e [...] a corresponder dentro de um segmento. Uma assinatura que não declare nenhum aplica-se a uma fonte que é um único ficheiro, seja qual for o seu nome, e a nenhum ficheiro de um diretório;
  • match — os predicados que a árvore analisada tem de satisfazer todos, cada um um PathMatch com um path de chaves unidas por pontos a partir do topo da árvore (um segmento de número inteiro seleciona uma posição de array), um is entre present, absent, object, array, string, number ou boolean, e opcionalmente uma string equals ou uma string prefix — no máximo uma das duas.

Quando uma importação não indica nenhum formato, o anfitrião 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 — pela ordem da sua identidade e versão: analisa a fonte através 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 inclui — 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 através do qual é respondida a chamada aggrega_parse_source de um importador, pelo que um importador lê a sua fonte através do analisador através do qual ela foi reconhecida. Uma fonte que não é analisada numa sintaxe não corresponde a nenhuma assinatura que a indique; uma sintaxe para a qual nem o catálogo nem o compilador servem um analisador interrompe o reconhecimento, indicando a ausência do analisador. Uma fonte a que nenhuma assinatura corresponda é recusada pedindo o formato, e uma reconhecida como mais de um formato é recusada indicando-os. Uma assinatura reconhece uma fonte como cada formato que o seu importador anuncia, pelo que um importador cujas fontes devam ser reconhecidas serve um único formato, e um que não declare nenhuma assinatura só é alcançado indicando o seu formato.

A entidade Plugin do importador regista a mesma lista como spec.importer.detect, derivada de describe() quando a entidade é gerada a partir do guest; o reconhecimento lê esse registo, pelo que o guest não é carregado até que o seu formato esteja decidido. O carregamento e a publicação do guest recusam um cuja autodescrição difira do registo da sua entidade, indicando importer.detect, e uma entidade que não registe nenhuma não declara nada. O descritor é recusado no carregamento quando o contrato é declarado num plugin que não é um importador, quando uma assinatura não indica nenhuma sintaxe ou indica um padrão de ficheiro malformado, e quando um predicado não indica nenhum caminho, indica um is fora dos sete, ou indica simultaneamente equals e prefix.

Os importadores core do compilador e o exemplo import do kit Go declaram as suas desta 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, que indica o respetivo ficheiro — .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, tal como o Visual Studio Code o lê, com um objeto em servers — e uma que não indica nenhum ficheiro e pede uma string $schema que comece por https://static.modelcontextprotocol.io/schemas/; o importador Compose lê uma fonte como YAML, indica os ficheiros que o Compose lê por predefinição — compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml e os seus quatro ficheiros de substituição — e pede um objeto em services; o importador Dify lê uma fonte como YAML, não indica nenhum ficheiro e pede a string app em kind e algo em app.mode e em version; o importador CrewAI indica 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, pelo que nenhum par deles corresponde a uma mesma fonte, e um ficheiro importado isoladamente sem nenhum formato indicado é lido como YAML além de como JSON; o importador LangGraph indica langgraph.json, lido como JSON com um objeto em graphs, declara uma assinatura que não indica nenhum ficheiro e pede um objeto em graphs e a string https://langgra.ph/schema.json em $schema, e não indica nenhum ficheiro de ambiente, uma vez que o reconhecimento lê todos os ficheiros que os padrões de qualquer importador selecionam, pelo que um padrão que indicasse um abriria os ficheiros de ambiente de cada diretório importado sem indicar nenhum formato; o importador Google ADK indica 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 indica nenhum outro ficheiro, uma vez que a configuração de um subagente pode ter qualquer nome e um padrão que indicasse todos os ficheiros YAML abriria cada um deles em cada diretório importado sem indicar nenhum formato; o importador Agent Framework lê uma fonte como YAML, não indica nenhum ficheiro 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 lê uma importação de um diretório. Uma fonte pode ser um diretório, e os padrões de ficheiro declarados do importador decidem o que este lê: o anfitrião lê exatamente os ficheiros do diretório, a 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 ficheiro dentro do diretório — e entrega-os como sources por ordem de nome, com bytes vazio e o nome do próprio diretório como name. Nenhum outro ficheiro do diretório é aberto. A pasta para onde uma compilação da área de trabalho escreve os seus ficheiros renderizados — dist/ sob a raiz da área de trabalho — não é lida como parte de um diretório que a contenha: nenhum dos seus ficheiros é entregue ou reconhecido, e uma ligação que conduza a ela é ignorada, pelo que um diretório que foi compilado é lido como o projeto que contém, enquanto um diretório que seja essa pasta, ou esteja dentro dela, é lido tal como indicado. Uma assinatura que não declare nenhum padrão files não seleciona nenhum ficheiro de um diretório, pelo que um importador que não declare nenhum lê um único ficheiro e recusa um diretório, e um diretório que não contenha nenhum ficheiro que os seus padrões selecionem é também recusado. O diretório fica confinado a si próprio: uma ligação entre os ficheiros que o anfitrião leria, ou para um diretório, que conduza para fora do diretório é recusada antes de qualquer coisa ser lida, uma ligação para um diretório nunca é percorrida, e uma ligação para um ficheiro que nenhum padrão seleciona é ignorada sem ser lida. Reconhecer o formato de um diretório segue a mesma regra — cada assinatura é experimentada contra os ficheiros que os seus padrões selecionam, por ordem de nome, cada ficheiro lido e analisado no máximo uma vez por sintaxe, e uma assinatura que não declare nenhum padrão não se aplica a nenhum deles. O anfitrião não limita nada: um diretório demasiado grande 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, pelo que cada um lê um único ficheiro; o seu importador MCP declara os nomes das quatro configurações de cliente, pelo que lê cada uma delas que um diretório contenha; o seu importador Compose declara os oito nomes de ficheiro do Compose, pelo que recebe cada ficheiro Compose que um diretório contenha e junta aqueles que o Compose leria; e o seu importador CrewAI declara os seis nomes sob os quais são escritas as declarações de um projeto CrewAI, pelo que recebe as declarações de um projeto e nada do seu programa; e o seu importador LangGraph declara langgraph.json, pelo que recebe a configuração de uma aplicação e nada do seu código ou dos seus ficheiros de ambiente, chegando-lhe um ficheiro de ambiente apenas no with.sources do seu anexo; e o seu importador Google ADK declara root_agent.yaml, pelo que recebe a configuração do agente raiz de uma aplicação e nada do seu código ou do seu ficheiro de ambiente, chegando-lhe as configurações que os seus subagentes indicam apenas no with.sources do seu anexo.

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 este transporta — 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 se mantenham sincronizados, tal como os tipos de reconhecimento ImporterContract, DetectSignature e PathMatch que a autodescrição describe transporta. O pacote importer do kit Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer, transporta tudo o que um importador faz, seja qual for o seu formato, e os importadores core do compilador, todos construídos sobre ele, leem a sua entrada e escrevem a sua saída desta forma.

Face a que pontua um importador construído sobre o kit Go. O pontuador do kit pondera cada nó da fonte face aos Components da vista 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 empresarial exatamente como os da biblioteca padrão — e o kit não transporta nenhum candidato próprio. De cada Component lê o nome, a categoria que a sua etiqueta component.aggrega.ai/category transporta, as suas etiquetas e os nomes das chaves que os seus values declaram; as suas chaves provides e os seus sockets não são ponderados. Um Component acrescentado ao catálogo é um candidato na importação seguinte, sem que nenhum importador seja recompilado. Onde a vista 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. Todos os importadores que pontuam através do kit pontuam desta forma — entre eles os importadores Langflow, Flowise, n8n e Compose do compilador, enquanto o seu importador MCP não pondera nenhum candidato; um importador que não use o kit lê a vista como entender.

Para que lê os sockets de uma plataforma um importador construído sobre o kit Go. Os sockets não pesam nada numa pontuação, mas o kit lê-os para dispor um rascunho. Um formato cujos fluxos uma plataforma executa tal como estão escritos — como acontece com os do Langflow, do Flowise e do n8n — é gerado como rascunho por predefinição como uma instância do Component dessa plataforma que transporta o fluxo, e cada parte do fluxo é ligada ao primeiro socket, pela ordem em que a entrada catalog da plataforma lista os seus sockets, cujo selector as etiquetas do Component da parte satisfazem, tal como a vista transporta essas etiquetas. Apenas o seletor e as etiquetas são lidos, e o seletor é comparado por uma função que o importador fornece, uma vez que o kit não transporta nenhuma gramática de seletores própria; onde a vista não contém nenhum Component com o nome da plataforma, nenhuma parte é ligada. Importadores core descreve o rascunho que os importadores Langflow, Flowise e n8n do compilador fazem desta forma, e a definição layout que, em vez disso, gera cada nó como rascunho como um Component próprio.

Estado atual: disponível — despachado por aggrega import e pela mesma operação na sessão do editor e na ferramenta destinada ao assistente.

Critério de posicionamento: o socket de linter versus os papéis de veredicto de governação

Dois dos sockets documentados partilham 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 que socket transporta uma determinada verificação:

  • Os papéis de veredicto de governação (em banda, que interrompem a compilação). Reservados para políticas que interrompem a compilação: um veredicto halt para o pipeline de compilação e a compilação não produz artefactos. Os casos de utilização são políticas cuja violação torna a saída insegura de aplicar: pontos de controlo 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 artefactos 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 utilizados, vocabulário de etiquetas obsoleto, completude das tags para atribuição de custos, desvio das convenções de nomenclatura. Uma falha produz saída consultiva; a compilação continua a produzir artefactos.

O critério de posicionamento formulado como uma única regra: se a verificação deve interromper a compilação, pertence a um papel de veredicto de governação; se a verificação deve avisar um autor ou um revisor sem bloquear o pipeline, pertence ao socket de linter.

Ambos podem ser utilizados hoje. O socket de linter executa o publishing-linter através de aggrega lint; os papéis de veredicto de governação são acionados em banda durante aggrega build quando um espaço de trabalho anexa um plugin com papel de veredicto. Note-se que um papel de veredicto tem as suas próprias severidades — uma política pode ela própria emitir veredictos warn e info que avisam sem interromper —, pelo 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. Ver a página do socket de governação para o modelo de severidade.

Referências cruzadas

  • policy-socket.md — o tratamento completo do socket de governação: os quatro papéis, as severidades dos veredictos, o canal de entrada do operador, como escrever uma política para qualquer um dos dois motores incluídos no compilador, como encapsular um motor de políticas externo e os guests de referência.
  • core-importers.md — os importadores próprios do compilador, um para cada formato que lê: o que cada um lê, as suas definições e a sua publicação com cada versão do compilador.
  • 10-status.md#compilation-pipeline-phases — classificação do pipeline de plugins na página de estado (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 fornecedor.
  • entities/featurerecipe.md — a superfície de criação pipeline: da FeatureRecipe.
  • when-to-use-a-pipeline-step.md — guia de decisão: um passo de pipeline versus uma FeatureRecipe com templates.
  • templates/expansion-matrix.md — as regras de avaliação de templates do bloco pipeline: 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 em que participam os guests de plugins.