Guia do desenvolvedor de plugins Wasm
Este é o guia canônico para criar um plugin WebAssembly (Wasm) do Aggrega e publicá-lo como uma entidade do catálogo. Ele ensina o contrato do autor de plugins de ponta a ponta: o que é um plugin, como um plugin se descreve para o host, como criar seus exports e suas declarações de capacidades, os limites de execução e as funções de host que o host aplica, a entidade Plugin que leva um plugin ao catálogo, como uma Recipe ou uma FeatureRecipe referencia um plugin, e o ciclo de vida publish→pull→build que leva um plugin de um arquivo .wasm em disco a um artefato verificado e fixado por digest que um build consome.
A página complementar plugin-contract.md documenta os sockets — os pontos do pipeline em que os plugins são vinculados e as formas de entrada/saída que cada socket consome e produz. Este guia documenta o plugin — a entidade, a superfície de capacidades e o ciclo de vida. Leia a página do contrato para saber qual socket seu plugin tem como alvo; leia esta página para saber como criá-lo e distribuí-lo.
Para um percurso prático por toda a tarefa em vez de uma referência sobre ela, criar um provedor constrói de ponta a ponta um pequeno guest de provedor — descritor, build, entidade, vinculação e uma renderização cuja saída você pode ler —, incluindo a recusa que um primeiro rascunho costuma encontrar e como lê-la.
1. O que é um plugin Wasm
Um plugin Wasm é um módulo WebAssembly que estende o compilador em um socket designado. O binário host em Go não contém nenhuma lógica específica de nuvem ou de infraestrutura; toda a inteligência específica do domínio — renderização de templates, tradução de formatos, avaliação de políticas, linting — fica dentro dos plugins. O host orquestra o pipeline e passa o payload de cada socket ao guest através da fronteira da ABI; o guest faz o trabalho de domínio e retorna a forma de resultado desse socket. O payload e o resultado de cada socket trafegam como CBOR canônico, com duas exceções: um plugin CLI recebe seu vetor de argumentos como texto JSON e responde com um código de saída e o texto que transmite, e o autorrelato describe é texto JSON. A seção de cada socket no contrato de plugins informa sua codificação, e um guest a lê e a escreve por meio dos pontos de entrada que o tipo de payload de seu kit já traz, de modo que nenhum guest analisa bytes à mão.
Um plugin é executado por trás de um firewall de pureza ahead-of-time. O host carrega e executa o módulo por meio de um runtime Wasm embutido em uma configuração com capacidades negadas: sem sockets de rede, sem sistema de arquivos, sem ambiente, stdio descartado e um relógio de parede observável congelado em um instante invariante entre builds. Qualquer chamada de E/S que um guest tente falha na fronteira da chamada, de modo que um plugin não pode recorrer ao estado de tempo de execução. Crie plugins tendo esse firewall em mente: um plugin transforma o payload que recebe e retorna um resultado que o host consome literalmente, e o determinismo é responsabilidade sua — uma entrada idêntica deve produzir bytes de saída idênticos. O único canal sancionado para conteúdo remoto é a busca de entradas externas mediada pelo host (Seção 4), que serve bytes sob uma disciplina de fixação por digest em vez de dar ao guest acesso direto à rede.
Os sockets que um plugin pode ter como alvo — entre eles o ponto de controle de mutação na construção da topologia, o ponto de controle de validação na análise estática, o pipeline de FeatureRecipe, o linter fora de banda e o socket de renderização de provedores — e suas formas de entrada/saída por socket estão documentados em plugin-contract.md. O socket que um plugin atende é o único valor que ele declara em metadata.pluginType, e o conjunto completo de valores que esse campo aceita é a entrada de referência dele em entities/plugin.md §“metadata.pluginType”. Os exemplos deste guia usam provider (renderiza nós de IR em artefatos nativos do provedor), linter (inspeciona o conteúdo criado pelo autor e emite diagnósticos) e pipeline-step (uma etapa no pipeline: de uma FeatureRecipe ou de uma Recipe que aplica patches ao conjunto de documentos renderizados).
Você cria o guest para o host por meio do kit de desenvolvimento de plugins (PDK) em três linguagens — Go, Rust ou TypeScript. O PDK encapsula a toolchain Wasm subjacente com builders tipados do Aggrega para as formas de entrada e saída que cada socket transporta.
2. O autorrelato describe()
Todo plugin exporta uma função describe() que retorna o autorrelato do plugin: o tipo ou os tipos de socket que ele implementa, a versão da ABI que tem como alvo, as capacidades que declara — lidas de acordo com o tipo de socket, ou seja, nomes de capacidades para um provedor ou uma etapa de pipeline e formatos de fonte com prefixo para um analisador ou um importador —, as funções de host que importa e a capacidade por export de cada ponto de entrada que oferece. describe() é o relato que o próprio plugin faz do que ele é e do que faz.
O autorrelato é a âncora do modelo de confiança. A entidade Plugin que leva o plugin ao catálogo (Seção 5) reafirma os mesmos fatos como declarações criadas pelo autor, e o host confronta as declarações da entidade com a saída de describe() do plugin em dois momentos — na publicação, antes que qualquer byte chegue ao registro, e no carregamento, antes que o plugin seja executado. Uma divergência causa uma interrupção explícita. A entidade é a superfície legível por pessoas e visível no catálogo; describe() é a referência de máquina contra a qual o host a verifica. Crie ambas para que concordem; a verificação cruzada existe justamente para detectar o caso em que elas divergem. Ela verifica o que a entidade declara, e não o que ela deixa de fora: uma entidade que declara menos do que o binário informa — por exemplo, uma que ficou para trás após uma recompilação que adicionou um export — ainda é carregada, embora não descreva mais tudo o que o binário faz.
3. Criar os exports e suas declarações de capacidades
Um plugin oferece um ou mais exports — pontos de entrada nomeados para os quais o host despacha chamadas (por exemplo render_node, lint_naming, step). Cada export carrega um bloco de capacidade: a declaração do autor sobre o que esse export faz. A capacidade de um export tem quatro campos:
name— o nome ABI do export, o nome para o qual o host despacha chamadas. Obrigatório.operates— a operação de pipeline que o export executa:patch(modificar um documento renderizado existente) ouemit(adicionar um novo documento). Esta é uma declaração de capacidade explícita. O host a confronta com o autorrelatodescribe()do plugin na publicação e no carregamento, de modo que a declaração criada na entidade e o relato próprio do plugin devem concordar. É uma declaração validada sobre o export, e não um seletor de despacho: no momento da renderização, a operação que uma etapa realmente executa é carregada pelo resultado retornado pelo guest, e não selecionada a partir deste campo. Se ausente, não carrega nenhuma declaração de operação.scope— a raiz de documentos sobre a qual o export opera:own(os documentos renderizados próprios do nó) ouhost(os documentos do componente ao qual uma FeatureRecipe com escopo de componente está vinculada). Antes que o plugin de uma etapa de pipeline seja executado, o host lê o escopo de export declarado da etapa e exige que o provedor que renderiza os documentos desse escopo apareça nasspec.pipelineStep.capabilitiesdo plugin (Seção 5) — um export com escopoowné verificado contra o provedor que renderiza os documentos próprios do nó, um export com escopohostcontra o provedor do componente hospedeiro, e um escopo vazio equivale aownpara essa verificação. Este é o ponto de controle de compatibilidade de provedores, executado antes da etapa; o documento que uma operação do guest realmente toca é nomeado por operação no resultado retornado pelo guest, e não selecionado a partir deste campo declarado. Se ausente, o padrão éown.selector— uma descrição livre e legível por pessoas daquilo sobre o que o export atua (por exemploworkloads carrying a pod template). Documentação para leitores do catálogo e para a superfícieaggrega inspect; o compilador não a interpreta.
Crie os exports na ordem em que você quer que sejam lidos; as entradas preservam a ordem do autor na entidade e em inspect. Um plugin sem exports criados não declara nenhuma superfície de export — o que é válido para um plugin cujo socket não precisa de uma declaração de capacidade por export.
4. Limites de execução e funções de host
Uma entidade de plugin pode ter um bloco runtime opcional que restringe como o host carrega e executa o plugin.
Limites de memória e de tempo. maxMemoryPages limita a memória linear do plugin em páginas Wasm (64 KiB por página); timeoutMs limita por quanto tempo o código próprio do plugin pode ser executado durante uma chamada, em milissegundos. O tempo gasto dentro das funções de host que o plugin chama não é contado. No Linux, a medida é o tempo de processador da thread que executa o guest, de modo que o tempo que o guest passa esperando por um processador em uma máquina ocupada também não é contado; em outros sistemas, é o tempo decorrido. A primeira chamada a um plugin recém-carregado também conta a inicialização única do runtime da linguagem guest, que é executada dentro dessa chamada. Ambos os limites são opcionais com valores padrão: zero ou ausente aplica o limite padrão da plataforma. O carregador limita todo plugin ao padrão da plataforma quando a entidade não declara nenhum, de modo que um carregamento nunca é ilimitado e uma chamada nunca é impossível de cancelar. Aumente um limite na entidade quando uma vinculação realmente precisar de mais memória ou de mais tempo do que o padrão permite.
Funções de host. hostFunctions registra os nomes das funções de host que o plugin importa. É um campo derivado por máquina — não o escreva. aggrega plugin sync lê as funções de host diretamente da seção de importações do .wasm e registra o campo no arquivo da entidade para você, e a publicação as deriva novamente do binário e recusa uma entidade cujo registro difere; assim, um plugin obtém exatamente as funções de host que seu binário realmente importa, validadas contra uma lista de permissões selecionada (uma importação fora da lista de permissões é rejeitada de forma explícita). O registro é um instantâneo do binário publicado, da mesma forma que a referência plugin: endereçada por conteúdo é um instantâneo dos bytes publicados: ele reflete o binário no momento da publicação e é derivado novamente e verificado quando o plugin é obtido por pull. Para ver as funções de host que um .wasm local importa antes da publicação — o valor que aggrega plugin sync registra —, execute aggrega inspect --plugin <file.wasm>.
A superfície de host selecionada. Três das funções de host são de uso geral: aggrega_log (um nível e uma mensagem, emitidos como uma linha de log no destino de log do host), aggrega_emit_warning (um código, uma mensagem e um caminho, acumulados como um aviso estruturado que o host exibe após a chamada) e aggrega_fetch_external_input (uma URL, respondida com os bytes da entrada sob a disciplina de fixação abaixo). O PDK encapsula as três em cada linguagem — Go: aggrega.Log, aggrega.EmitWarning, aggrega.FetchExternalInput; Rust: log, emit_warning, fetch_external_input; TypeScript: log, emitWarning, fetchExternalInput —, de modo que um guest chama uma função tipada em vez da ABI bruta. Os callbacks de fonte e de análise — para um guest que lê fatias de uma fonte adquirida ou obtém uma árvore analisada por meio do host — e a codificação que os slots de cada callback carregam estão listados em plugin-contract.md.
O conteúdo da fonte local vem pelo host — nunca do sistema de arquivos. Um plugin de renderização de provedor nunca lê sua fonte do disco; uma chamada ao sistema de arquivos falha na fronteira da chamada. O host entrega ao guest uma listagem da fonte dentro do payload de renderização — o caminho de cada entrada relativo à raiz da fonte e se ela é um diretório, em ordem classificada, sem conteúdo de arquivos —, e o guest aplica a ela sua própria lógica de layout e depois lê de volta exatamente os arquivos que seleciona por meio dos callbacks de fonte, que retornam os bytes que o host lê sob a raiz da fonte. As formas de payload por socket e os callbacks estão documentados em plugin-contract.md.
O conteúdo remoto vem pela busca de entradas externas. Um plugin que precisa de conteúdo remoto — um arquivo de chart, um documento de schema remoto — chama o wrapper de busca do PDK. Na transmissão, o guest passa a URL para aggrega_fetch_external_input como texto UTF-8 e recebe uma única resposta em CBOR canônico, carregando ou os bytes buscados, brutos, ou uma mensagem de erro ao lado de seu código comparável por máquina; o wrapper decodifica a resposta em bytes ou erro. Os bytes chegam exatamente como foram buscados, incluindo um payload que não é UTF-8 válido, e um payload de comprimento zero volta como bytes vazios em vez de um erro. O host serve a URL sob a disciplina de fixação de entradas externas:
- Uma URL já fixada no arquivo de bloqueio da Release é servida a partir do armazenamento local endereçado por conteúdo e verificada contra seu digest registrado a cada leitura. Um blob ausente no armazenamento é recarregado da rede pelo digest registrado — um recarregamento verificado por digest não pode alterar a saída.
- Uma URL não fixada é recusada, com um erro que nomeia a URL e a solução. Um build renderiza o fecho que seu arquivo de bloqueio registra, de modo que nenhum build busca uma referência não fixada e não existe nenhuma configuração que faça isso.
- A fixação acontece quando as dependências da Release são resolvidas:
aggrega pullrenderiza a Release para descobrir quais entradas externas sua renderização solicita, busca cada uma delas e a registra no arquivo de bloqueio ao lado das fixações de dependências. Então o ciclo de trabalho do autor de um plugin é: resolver uma vez e depois fazer o build offline quantas vezes você quiser.
Os esquemas permitidos são https, http apenas para hosts de loopback, e oci (fixado pelo digest do manifesto). O arquivo de bloqueio registra cada entrada fixada — sua URL, seu digest sha256, seu tamanho e os plugins que a exigiram —, de modo que um novo build serve os mesmos bytes a partir do armazenamento local: reproduzível e offline depois de fixado.
Com o PDK Go:
import "github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega"
chart, err := aggrega.FetchExternalInput("https://charts.example.com/postgresql-16.3.2.tgz")if err != nil { // The error names the URL and the remedy — an unpinned URL reports exactly // what to pin and how. Surface it as a render failure; do not mask it. return fmt.Errorf("fetching chart archive: %w", err)}O que falha, e por quê.
- Uma chamada ao sistema de arquivos ou à rede falha na fronteira da chamada: o guest não tem diretórios pré-abertos nem sockets. Isso se aplica a todo caminho de código, incluindo uma dependência de biblioteca que tente ler um arquivo — em vez disso, leia a fonte por meio dos callbacks de fonte.
- Uma importação sob um módulo fora de
wasi_snapshot_preview1,extism:host/enveextism:host/userfalha no carregamento, com um diagnóstico que nomeia o módulo e a importação. Nomes individuais de funções WASI dentro de um módulo permitido nunca são censurados — as importações não usadas de sistema de arquivos e de sockets do runtime de uma linguagem ligado estaticamente não são um problema, porque nomear uma importação não concede nada. - A busca de uma URL que o arquivo de bloqueio não fixa falha com um erro que nomeia a URL; a solução é executar
aggrega pull --release <release>, que fixa cada entrada externa que a renderização da Release consome, e depois fazer o build.
Não existe nenhum campo de lista de hosts permitidos para acesso de saída à rede. Um plugin nunca chega à rede em tempo de build — essa é a fronteira ahead-of-time —, então não existe nenhum campo desse tipo para criar. O conteúdo remoto chega pelo canal de entradas externas mediado pelo host e fixado por digest descrito acima, nunca por acesso ambiente à rede.
Configuração. configKV é um mapa de string para string que o runtime entrega ao plugin na inicialização. As entradas preservam a ordem do autor, de modo que o registro emitido é idêntico byte a byte entre execuções. Se ausente, a configuração vazia padrão do runtime permanece em vigor.
5. A entidade Plugin
Um plugin entra no catálogo como uma entidade Plugin — a superfície de criação e de metadados do plugin. A entidade declara o que o plugin é e aponta para o artefato .wasm; o compilador não interpreta o comportamento do plugin e encaminha a referência fixada, enquanto o runtime Wasm executa os bytes.
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: aws-secrets-manager version: 1.2.0 pluginType: pipeline-stepspec: abiVersion: v1beta1 pipelineStep: capabilities: - helm - compose signature: type: sigstore-cosign runtime: maxMemoryPages: 256 timeoutMs: 5000 # hostFunctions is recorded by `aggrega plugin sync` from the .wasm — do not author it. exports: - name: fetch operates: emit scope: own selector: external-secret resources for the bound credentialOs campos:
- Nenhum campo de localização do artefato, deliberadamente. A entidade não carrega nenhum ponteiro para o
.wasme o schema não aceita nenhum. A localização do artefato de um plugin é derivada de sua identidade — a coordenadametadata.pluginType/metadata.name, que forma o caminho do repositórioplugin/<pluginType>/<name>— mais o registro para o qual o espaço de trabalho está configurado, de modo que não há nenhuma localização a criar nem a errar. O digest de conteúdo resolvido é registrado por Release no arquivo de bloqueio dessa Release, e o build verifica os bytes buscados contra ele: a identidade na entidade, os bytes verificados no arquivo de bloqueio. metadata.version— a release que a entidade publica, que precisa ser igual à versão de proveniência do build do próprio guest, conforme informada emdescribe(). O autor de um plugin versiona o.wasmno momento do build — o build grava a versão no guest, e um build que a obtém de uma tag de release grava a versão da release apenas no commit que essa tag nomeia — e ometadata.versionda entidade nomeia essa mesma release. O controle de publicação confronta as duas e interrompe em caso de divergência, de modo que a entidade sempre nomeia a versão exata do binário que distribui.aggrega plugin gen-catalog --plugin(abaixo) copia a versão que o guest informa para a entidade que gera, que é a versão da release quando o guest foi compilado a partir do commit com a tag. Obrigatório.metadata.pluginType— o tipo de socket que este plugin implementa, escolhido entreprovider,linter,pipeline-step,governance,cli,parsereimporter. Um plugin implementa exatamente um. Ele fica no bloco de endereçamento ao lado denameeversione fornece o segmento<pluginType>da coordenada derivada. Obrigatório.spec.abiVersion— a versão da ABI host/guest que o plugin tem como alvo.v1beta1é o valor aceito; uma futura revisão da ABI adiciona um valor aceito. Obrigatório.- O bloco do seu tipo de socket, carregando
capabilities— um plugin declara o que atende dentro do bloco que pertence ao seumetadata.pluginType, e é o bloco que fixa o que uma entrada significa.spec.provider.capabilitiesnomeia as capacidades que um provedor atende (nomes de capacidades comohelmoucompose).spec.pipelineStep.capabilitiesnomeia os provedores com cuja saída renderizada sua etapa é compatível.spec.parser.capabilitiesnomeia os formatos de fonte que um analisador lê, cada um escritoparse:<format>.spec.importer.capabilitiesnomeia os formatos externos a partir dos quais um importador redige rascunhos de entidades, cada um escritoimport:<format>. Um importador escrito em Go pode obter tudo o que não depende de seu formato — a pontuação, a decisão entre referenciar ou redigir um rascunho, os rascunhos e sua renderização, e suas configurações — do pacote importer do kit Go,github.com/aggrega-ai/aggrega-pdk/go/pkg/importer. Um pluginlinter,governanceouclinão atende nenhuma capacidade e não carrega nenhum dos quatro blocos. As entradas preservam a ordem do autor, e cada lista é uma declaração explícita e testada: declare aquilo contra o que você realmente compilou e testou o plugin, porque um consumidor resolve exatamente contra o que está listado. Para uma etapa de pipeline, essa declaração é imposta na renderização — quando uma etapa toca um escopo, o build é interrompido, a menos que o provedor que renderiza os documentos desse escopo esteja entre os que seu plugin declara —, de modo que uma lista vazia não corresponde a nenhum provedor e não admite a etapa em lugar nenhum. spec.signature— um ponteiro descritivo opcional para a assinatura anexada do plugin (Seção 8). Este bloco é apenas documentação: registra onde a assinatura está e como foi produzida, para os leitores do catálogo; ele não admite o plugin por si só. A verificação que se impõe é a política de confiança por registro aplicada no pull.spec.runtime— o bloco opcional de restrições de execução da Seção 4. O autor escrevemaxMemoryPages,timeoutMseconfigKV;hostFunctionsé derivado por máquina e registrado poraggrega plugin sync, o que a publicação verifica, e não é escrito pelo autor.spec.exports— as declarações de capacidade por export da Seção 3 (name,operates,scope,selector).
Gerar a entidade a partir do seu .wasm. Você não precisa escrever à mão as partes da entidade gerenciadas pela máquina. aggrega plugin gen-catalog --plugin <file.wasm> lê o autorrelato describe() do guest e produz a partir dele uma entidade Plugin pronta para publicação, mais uma pequena sobreposição criada por você (a identidade, os limites de execução e qualquer bloco de provedor). O gerador grava os campos dos quais o binário é a fonte da verdade — as declarações de export, o contrato de capacidades, o espelho de comandos e o registro das funções de host — e copia metadata.version da versão de proveniência do build em describe() do guest, enquanto a sobreposição fornece apenas o que o binário não informa. Este é o caminho suportado para o autor de um plugin de terceiros: compile e versione o seu .wasm e depois gere novamente a entidade para que seus campos gerenciados pela máquina permaneçam sincronizados com o binário. A versão é o único campo copiado que nomeia uma release em vez de um fato sobre os bytes, então gere a partir de um build do commit que a tag da release nomeia — ou, partindo de um build de desenvolvimento, defina metadata.version como a release na entidade gerada antes de aplicar a tag ao commit que a contém. Um guest que não carrega nenhuma versão de proveniência do build não pode ser gerado como uma entidade versionada — versione primeiro o guest no momento do build.
O .wasm ao lado de sua entidade. Enquanto você cria um plugin, nada está publicado para um build buscar, então um build lê o .wasm do plugin que fica ao lado de sua entidade Plugin em um diretório de catálogo, com um nome derivado do tipo de plugin e do nome da entidade: para pipeline-step/patch, é pipeline-step--patch.wasm. Letras minúsculas, dígitos e a maioria dos hífens são escritos nesse nome como são; qualquer outro caractere é escrito em forma escapada, assim como um hífen em algumas posições — por isso, onde isso importa, a recusa de um .wasm ausente, A plugin’s .wasm is not on this machine (o arquivo de um plugin não está nesta máquina), dá o nome completo. aggrega lint <plugin.yaml> lê o .wasm do mesmo lugar — ao lado do arquivo de entidade que recebe, em qualquer diretório em que esse arquivo esteja — a menos que o próprio binário carregue o plugin, e imprime um aviso para cada export, capacidade ou contrato que o .wasm informa e que a entidade omite. Onde não houver nenhum .wasm ali, o lint diz que ignorou esse relatório, nomeando o arquivo que procurou e o diretório, e seu resultado não muda.
Para a referência campo a campo, veja a página da entidade ../entities/plugin.md.
6. Referenciar um plugin
Uma etapa de pipeline ou um socket de plugin referencia um plugin por seu URI de entidade Plugin — a identidade da entidade, não o artefato .wasm diretamente. A entidade é a camada que carrega a fixação por digest, as declarações de capacidade, os limites de execução e a assinatura; referenciar a entidade é como um consumidor obtém tudo isso.
Um caminho .wasm simples ou uma referência bruta de artefato deixada em um campo plugin é rejeitada no carregamento: nenhuma entidade Plugin corresponde a ela, de modo que a resolução do plugin falha de forma explícita. O URI da entidade é obrigatório — a indireção por meio da entidade é o contrato, não uma conveniência opcional. Uma etapa de pipeline de uma FeatureRecipe nomeia a entidade em pipeline[].plugin; veja ../entities/featurerecipe.md para a superfície de criação do pipeline.
Quando dois ou mais plugins estão acoplados — precisam concordar sobre um contrato de transferência compartilhado, como em um par Fetcher e Injector em que a saída de um plugin é a entrada do outro (o princípio do Plugin em duas partes descrito em plugin-contract.md) —, crie esse contrato uma única vez e faça cada plugin depender da definição única, em vez de reafirmar a forma JSON da transferência de modo independente em cada plugin. A forma compartilhada é a estrutura JSON que os plugins trocam, que pode ficar em uma única entrada de SchemaLibrary referenciada pelos dois plugins. Uma fonte única para o contrato mantém os plugins acoplados sincronizados à medida que ele evolui; reafirmações independentes divergem, e a divergência só aparece quando os dois deixam de concordar em tempo de execução. A recomendação é compartilhar o contrato, não o código Wasm — cada plugin continua sendo seu próprio artefato.
7. O ciclo de vida publish → pull → build
Um plugin passa de um arquivo .wasm em disco a um artefato verificado e consumível por um build em três estágios.
Publish. aggrega push publica uma entidade Plugin e seu .wasm juntos como um único manifesto OCI, com a tag metadata.version: o YAML da entidade é o blob de configuração do manifesto e o .wasm vai como uma camada do mesmo manifesto. Publicar o par como um único manifesto com tag é o que torna o push atômico — não existe nenhuma janela em que uma metade esteja publicada e a outra não — e é por isso que uma única assinatura sobre esse manifesto cobre as duas metades. As duas metades são nomeadas no manifesto, de modo que um cliente OCI genérico que busca a tag de versão grava a entidade em entity.yaml e o executável em entity.wasm.
Antes que qualquer byte chegue, a publicação executa suas verificações. A entidade é lida primeiro contra o schema Plugin, da mesma forma que um carregamento do catálogo a lê, de modo que um metadata.version que não seja uma versão semântica — ou qualquer outro desvio do schema — é recusado antes de o .wasm ser lido. Em seguida, o .wasm é carregado e seu autorrelato describe() é confrontado com as declarações de capacidade criadas na entidade — uma divergência causa uma interrupção explícita, de modo que uma entidade publicada nunca declara o que o plugin que ela distribui não informa. Um guest cuja versão de proveniência do build em describe() carrega a marca -dirty, aplicada a um build feito a partir de uma árvore de trabalho com alterações não commitadas, é recusado: essa versão nomeia um commit que não contém o que foi compilado. Uma versão de desenvolvimento compilada a partir de um commit (1.0.0-3-g1a2b3c4) e uma pré-release (1.0.0-rc.1) são publicadas. O metadata.version registrado é confrontado com a versão de proveniência do build em describe() do guest, e uma divergência interrompe a publicação, de modo que as duas precisam concordar. As duas recusas são resolvidas da mesma forma: compile o plugin a partir de um checkout limpo do commit que a tag da release nomeia, para que ele próprio informe a versão da release — para uma nova release, faça o commit da entidade com a fonte que ela publica e aplique primeiro a tag a esse commit. Copiar para a entidade a versão que um build de desenvolvimento informa não é uma correção: isso publica esse build sob uma versão que nenhuma tag de release nomeia. As funções de host que o .wasm importa são derivadas do binário e comparadas com o registro commitado em spec.runtime.hostFunctions; uma divergência interrompe a publicação e nomeia aggrega plugin sync, que registra o campo novamente, porque o campo é gerenciado pela máquina e uma publicação nunca reescreve o arquivo da entidade commitado. A entidade publicada carrega o registro gravado das funções de host; o digest de conteúdo do .wasm é uma propriedade do manifesto com o qual o par é publicado, e é registrado para um consumidor no arquivo de bloqueio da Release em vez de ser gravado na entidade.
Pull. aggrega pull resolve todas as dependências de uma Release e grava um arquivo de bloqueio por Release que fixa cada entidade do catálogo e cada artefato remoto a uma versão e a um digest de conteúdo. Um Plugin publicado é resolvido por essa resolução de dependências; seu .wasm é buscado com o manifesto que o carrega e os bytes são verificados contra o digest de conteúdo que o arquivo de bloqueio registra. O pull também deriva novamente as funções de host a partir do .wasm verificado e as confronta com o registro hostFunctions gravado, interrompendo se os dois divergirem — uma verificação de defesa em profundidade sobre a fixação por digest, que detecta um binário cujo registro gravado não foi produzido a partir de suas próprias importações. Se a política de confiança do registro exigir assinaturas, a assinatura da entidade é buscada e verificada neste estágio e registrada como um fato verificado no arquivo de bloqueio (Seção 8). A verificação acontece no pull, nunca no build — o build permanece puro ahead-of-time.
Build. aggrega build consome o plugin fixado e verificado a partir das dependências resolvidas. O compilador encaminha a referência fixada por digest e o runtime Wasm executa os bytes; o controle de carregamento executa novamente a verificação cruzada com describe() e a imposição das funções de host e dos limites de execução antes de o plugin ser executado.
8. Assinatura e confiança
Uma entidade Plugin é assinada exatamente como qualquer outra entidade do catálogo: o digest do manifesto é assinado e anexado como um referrer OCI. O artefato .wasm não é assinado separadamente, e não precisa de uma assinatura separada — ele é uma camada do próprio manifesto cujo digest é assinado, de modo que a assinatura o cobre diretamente: adulterar o .wasm altera o digest do manifesto e invalida a assinatura.
A assinatura é de adesão opcional na publicação; a verificação é imposta pela política de confiança por registro no pull. Um registro configurado para exigir assinaturas interrompe o pull quando uma assinatura exigida está ausente, não é confiável ou é inválida. O bloco spec.signature na entidade é um ponteiro de documentação para onde a assinatura está e como foi produzida; ele registra fatos para os leitores do catálogo e não controla a admissão por si só. O ponto de controle é a política no momento do pull.
Os comandos e suas flags estão documentados com as superfícies de publicação e de consumo — veja ../cli/aggrega-sign.md, ../cli/aggrega-push.md e ../cli/aggrega-pull.md. Este guia não reproduz as tabelas de flags; essas páginas são o lugar único da superfície de comandos.
9. Versionar a entidade
Uma entidade Plugin carrega uma Semantic Version estrita em metadata.version. Uma versão publicada é imutável: publicar novamente uma versão que já existe no registro com um conteúdo diferente é rejeitado no controle de publicação.
Quando você altera uma entidade de plugin e a publica novamente, a disciplina de publicação classifica a alteração em relação à versão publicada anteriormente e exige que o incremento de versão corresponda. A classificação segue a rubrica de incremento de versão: uma alteração apenas de documentação ou de comentários é PATCH; uma alteração estritamente aditiva (um novo campo opcional, uma nova entrada) é MINOR; uma remoção, um estreitamento de tipo ou um campo antes opcional que se torna obrigatório é MAJOR. Um incremento excessivo é sempre permitido; um incremento insuficiente é interrompido com um diagnóstico que nomeia o incremento exigido. A primeira publicação de uma entidade pula a verificação do incremento e exibe um aviso de que nenhuma verificação foi realizada. Execute a verificação antes de publicar com aggrega lint --pre-publish; veja ../cli/aggrega-lint.md para a rubrica completa e as configurações por regra.
Um Plugin não tem superfície extends, de modo que as regras de herança que regem os Components e as Features do catálogo não o alcançam. A rubrica de incremento de versão e a imutabilidade são a disciplina de versionamento que rege uma entidade de plugin.
10. Referências cruzadas
authoring-a-provider-walkthrough.md— um guest de provedor construído de ponta a ponta, de um diretório vazio até a saída renderizada.plugin-contract.md— os pontos de socket que um plugin tem como alvo e as formas de entrada/saída por socket.policy-socket.md— o socket de governança em profundidade: seus quatro papéis, as severidades dos vereditos, o canal de entrada do operador, como escrever uma política para qualquer um dos dois mecanismos que vêm dentro do compilador e os guests de políticas de referência.core-importers.md— os importadores próprios do compilador, um para cada formato que ele lê, construídos sobre o pacote importer do kit Go: o que cada um lê, suas configurações e sua publicação a cada versão do compilador.../compatibility.md— como os kits de plugin são versionados e o que faz um plugin compilado para uma versão continuar carregando na seguinte.../entities/plugin.md— a referência campo a campo da entidadePlugin.../entities/featurerecipe.md— a superfície de criaçãopipeline:da FeatureRecipe que referencia um plugin por URI de entidade.../cli/aggrega-lint.md— o publishing-linter, a rubrica de incremento de versão e a imposição da imutabilidade.../cli/aggrega-inspect.md— a inspeção das capacidades, dos limites de execução e da assinatura de uma entidadePlugin.../cli/aggrega-push.md,../cli/aggrega-pull.md,../cli/aggrega-sign.md— as superfícies de comandos de publicação, de consumo e de assinatura.