Arquitetura de plugin: Arquitetura de referência

Define como extensões de terceiros ou internas registram capacidades, declaram permissões, isolam falhas e fazem upgrade sem quebrar o núcleo da aplicação host.

Status do pacote: Pacote de referência assistido por IA. A validação estática do pacote foi aprovada; cenários de implementação ainda não foram executados e revisão humana do domínio é necessária antes da adoção estável.

Decisão

Estender o host por meio de plugins dirigidos por manifesto que declaram capacidades e permissões antes do carregamento. O host aplica isolamento para que falhas na extensão desativem a extensão, não o produto principal. Upgrades são controlados por semver com rollback automático quando verificações de saúde falham após a implantação.

Escopo

• Esquema do manifesto da extensão, tipos de capacidade e declarações de permissão.
• Validação em tempo de carregamento, consentimento do usuário e limites de isolamento em tempo de execução.
• Probes de saúde, limites de falha e comportamento de desativação versus crash.
• Garantias de upgrade, rollback e compatibilidade da API do host.

Fora deste bloco

• Cobrança do marketplace e divisão de receita.
• Design completo de hipervisor sandbox para código nativo não confiável.
• Infraestrutura de feature flags (veja o bloco relacionado feature-flags).

Contrato

• Chamadas em tempo de execução requerem permissões declaradas; tentativas de acesso não declaradas falham fechadas em tempo de execução e são auditadas.
• Validação do esquema do manifesto em tempo de carregamento rejeita pacotes com campos obrigatórios ausentes antes da execução do código.
• api_surface_version do host v1 mapeia para intervalo semver >=1.0.0 <2.0.0 para verificações de compatibilidade.
• Permissões que requerem consentimento do usuário bloqueiam a ativação até que um administrador autorizado aprove o escopo listado.
• Falhas consecutivas de saúde além do limite do perfil desativam a extensão enquanto o host permanece disponível.
• Intervalos de compatibilidade da API no manifesto devem corresponder às regras da versão da superfície da API publicada pelo host.
• Pacotes assinados são obrigatórios quando verification_required é true. O host verifica o digest declarado do pacote e o id da chave do publicador contra seu repositório de confiança configurado, incluindo expiração e status de revogação da chave; assinaturas desconhecidas, expiradas, revogadas, incompatíveis ou inválidas bloqueiam a instalação antes do carregamento do código.

Orientações de implementação

• Validar manifestos em CI para extensões internas e no momento da instalação para pacotes de terceiros.
• Manter âncoras de confiança do publicador fora do conteúdo controlado pelo plugin. Versionar o repositório de confiança do host, atualizar informações de revogação sob uma política de frescor fail-closed e vincular a assinatura ao digest canônico do pacote mais identidade e versão do manifesto.
• Executar extensões em workers isolados com limites de memória e CPU definidos no manifesto.
• Expor APIs do host por meio de uma superfície versionada estável; documentar mudanças quebradoras dentro da janela de aviso do perfil.
• Registrar invocações de capacidade com id da extensão, permissão usada e id do workspace que chamou para auditoria.
• Publicar uma matriz de compatibilidade junto com lançamentos da API do host para que publicadores possam testar proativamente.

Tratamento de falhas e salvaguardas

• Em timeout da extensão, abortar a invocação e contar para o limite de falhas sem bloquear hooks não relacionados.
• Fazer rollback automático para a última versão saudável quando probes pós-upgrade falharem.
• Quarentenar extensões com violações repetidas de permissão até revisão do publicador e aprovação de segurança do host.
• Se o status de revogação ou a versão requerida do repositório de confiança não puder ser estabelecida, rejeitar nova instalação ou upgrade; não aceitar uma chave apenas porque seu identificador aparece no manifesto do plugin.

Verificação e operações

• Monitorar taxa de crash da extensão, eventos de desativação e contagens de negação de permissão.
• Testar matriz de compatibilidade entre versões da API do host em staging antes da publicação no marketplace.
• Auditar extensões instaladas trimestralmente para permissões obsoletas.
• Reavaliar pacotes instalados quando uma chave do publicador for revogada e desativar pacotes afetados conforme o perfil do incidente.

Os exemplos com aparência executável neste pacote são fixtures e contratos de aceitação. Valide a estrutura do pacote antes da adoção; então implemente e execute os cenários no repositório alvo.

Premissas para adoção

• Limites de recursos, limites de falha e id de extensão de exemplo em example.yaml e plugin-manifest.yaml são escolhas de perfil, não padrões universais.
• Times devem prover âncoras de confiança para assinatura, rotação de chaves e feeds de revogação, e UX de consentimento em suas políticas de plataforma; os identificadores de exemplo são apenas fixtures.

Referências

• Nenhuma fonte normativa externa é requerida; este pacote define um contrato de host de extensão.