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

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) ou emit (adicionar um novo documento). Esta é uma declaração de capacidade explícita. O host a confronta com o autorrelato describe() 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ó) ou host (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 nas spec.pipelineStep.capabilities do plugin (Seção 5) — um export com escopo own é verificado contra o provedor que renderiza os documentos próprios do nó, um export com escopo host contra o provedor do componente hospedeiro, e um escopo vazio equivale a own para 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 exemplo workloads carrying a pod template). Documentação para leitores do catálogo e para a superfície aggrega 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 pull renderiza 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/env e extism:host/user falha 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/v1beta1
kind: Plugin
metadata:
name: aws-secrets-manager
version: 1.2.0
pluginType: pipeline-step
spec:
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 credential

Os campos:

  • Nenhum campo de localização do artefato, deliberadamente. A entidade não carrega nenhum ponteiro para o .wasm e o schema não aceita nenhum. A localização do artefato de um plugin é derivada de sua identidade — a coordenada metadata.pluginType/metadata.name, que forma o caminho do repositório plugin/<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 em describe(). O autor de um plugin versiona o .wasm no 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 o metadata.version da 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 entre provider, linter, pipeline-step, governance, cli, parser e importer. Um plugin implementa exatamente um. Ele fica no bloco de endereçamento ao lado de name e version e 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 seu metadata.pluginType, e é o bloco que fixa o que uma entrada significa. spec.provider.capabilities nomeia as capacidades que um provedor atende (nomes de capacidades como helm ou compose). spec.pipelineStep.capabilities nomeia os provedores com cuja saída renderizada sua etapa é compatível. spec.parser.capabilities nomeia os formatos de fonte que um analisador lê, cada um escrito parse:<format>. spec.importer.capabilities nomeia os formatos externos a partir dos quais um importador redige rascunhos de entidades, cada um escrito import:<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 plugin linter, governance ou cli nã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 escreve maxMemoryPages, timeoutMs e configKV; hostFunctions é derivado por máquina e registrado por aggrega 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 entidade Plugin.
  • ../entities/featurerecipe.md — a superfície de criação pipeline: 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 entidade Plugin.
  • ../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.