Convenções das receitas do Connect
Convenções de receitas do Connect
Seção intitulada “Convenções de receitas do Connect”Toda receita do cookbook do Connect segue o mesmo contrato. Esta página registra esse contrato para que você saiba o que esperar como leitor e o que uma receita deve cumprir como autor. Ela é descritiva: documenta a convenção. A aplicação das regras fica a cargo do ferramental do repositório nextpdf/server e da planilha de override de estilo da documentação, não desta página.
Os autores escrevem as receitas do Connect no repositório nextpdf/server, em docs/public/, e o agregador as traz para este site. As convenções abaixo se aplicam onde quer que exista uma receita do Connect.
1. As chamadas de ferramenta são independentes do transporte
Seção intitulada “1. As chamadas de ferramenta são independentes do transporte”Uma receita do Connect usa a mesma invocação de ferramenta em todos os transportes.
- A receita mostra a chamada de ferramenta uma única vez. A mesma chamada aciona a ferramenta pelo Model Context Protocol (
tools/call), pelo endpoint de ferramenta Representational State Transfer (REST) e pelo serviço gRPC, porque os três compartilham o mesmo executor de ferramentas. - O schema de argumentos autoritativo para uma ferramenta é o que a implantação em execução retorna de
tools/list(MCP) ou do descritor de serviço (gRPC). Os argumentos de exemplo de uma receita mostram o formato da chamada; eles não são um schema congelado redefinido pela receita. - Uma receita nunca afirma um total fixo de ferramentas. O catálogo oficial é o próprio catálogo de ferramentas do servidor, ao qual a receita remete por link.
2. As ferramentas condicionadas ao tier são declaradas, não presumidas
Seção intitulada “2. As ferramentas condicionadas ao tier são declaradas, não presumidas”O registry de ferramentas do servidor sempre registra as ferramentas core. Em seguida, ele verifica os provedores Pro e Enterprise com class_exists() e registra as ferramentas deles somente quando nextpdf/premium está instalado junto com o servidor.
- Uma receita que depende de uma ferramenta Pro ou Enterprise declara explicitamente essa dependência de tier e diz como confirmar que a ferramenta está presente na sua implantação com uma chamada
tools/list. - Em uma implantação na qual a ferramenta não é resolvida, a chamada retorna um erro de ferramenta desconhecida. A receita apresenta esse resultado como o limite de tier pretendido, não como uma degradação, e nunca dá a entender que uma ferramenta restrita por tier está sempre disponível.
3. O modelo de risco e o portão de confirmação
Seção intitulada “3. O modelo de risco e o portão de confirmação”Toda ferramenta declara um dos quatro níveis de risco. O nível mais alto, approval_required, não é executado na primeira chamada.
- Uma receita cuja ferramenta pode ser
approval_required(por design ou por um override do operador) documenta o ConfirmationGate: o portão retorna um token de desafio de uso único vinculado ao nome da ferramenta, a um nonce e a um time to live (TTL) de 300 segundos, não aos argumentos. O chamador invoca novamente a mesma ferramenta uma vez comarguments._confirmation_token. - Uma receita declara que um override de configuração pode apenas elevar o nível de risco de uma ferramenta; nunca pode rebaixar uma ferramenta que é
approval_requiredpor design. O portão se comporta de forma idêntica em todos os transportes.
4. O tratamento de erros separa o transporte do status
Seção intitulada “4. O tratamento de erros separa o transporte do status”Para uma receita que acessa um serviço remoto pelo Hypertext Transfer Protocol (HTTP), uma falha de transporte e um status HTTP sem sucesso são casos distintos. Um cliente PSR-18 lança uma exceção de cliente tipada somente quando não consegue enviar a requisição de forma alguma — PSR-18 §4; uma resposta 4xx ou 5xx é um valor de retorno normal que a receita inspeciona, não uma exceção que ela captura. Uma receita do Connect pronta para produção trata os dois casos de forma distinta, sem nenhum bloco catch vazio.
5. O limite de conformidade e certificação
Seção intitulada “5. O limite de conformidade e certificação”Uma receita do Connect trata o suporte a um padrão como suporte, nunca como conformidade ou certificação.
- O motor produz uma saída destinada a estar em conformidade com um padrão (PDF/UA-2, PDF/A-4, um nível PAdES); a conformidade é determinada em relação aos requisitos do padrão por um validador independente, não afirmada pelo software produtor — PDF/A-4 §6.7.3.
- Uma avaliação de prontidão é um sinal de prontidão, não uma certificação. Uma atestação não é uma garantia legal. O material de validação de longo prazo presente em um documento é um recurso que o documento carrega, não uma garantia de validade indefinida da assinatura. Esse recurso é exclusivo do Enterprise, distinto dos níveis PAdES inferiores.
- Palavras de conformidade absoluta não são usadas como afirmações sobre o motor. A blocklist léxica usada para verificar uma receita é, literalmente, os tokens “certified”, depois “guaranteed”, depois a expressão de duas palavras “fully” + “compliant”, depois “tamper-proof”, depois “legally valid”: nenhum deles pode figurar como propriedade afirmada da saída do NextPDF, porque a conformidade é decidida por um validador independente em relação aos requisitos do padrão, não pelo software produtor — PDF/A-4 §6.7.3. Uma receita que suaviza uma afirmação upstream registra a suavização no seu arquivo sidecar colocalizado de afirmações rebaixadas.
6. O portão de publicação
Seção intitulada “6. O portão de publicação”Toda receita do Connect carrega publish: false até passar pelo Writing Gate. O padrão é negar: fazer merge de uma página não a publica; somente uma decisão explícita do portão registrada no front-matter faz isso. Uma receita cujas citações normativas não puderam ser fixadas por causa de uma indisponibilidade genuína do compliance-engine também carrega um marcador de citação não resolvida e permanece publish: false até que a citação seja fixada novamente. O protocolo de fallback do repositório para indisponibilidade da infraestrutura de Retrieval-Augmented Generation (RAG) rege esse marcador; um autor o segue em vez de inventar uma citação ou descartar a afirmação.
7. O agregador escreve os campos de proveniência
Seção intitulada “7. O agregador escreve os campos de proveniência”Um autor de receita do Connect não escreve manualmente os quatro campos de proveniência da origem que pertencem ao agregador: source_repo, source_ref, source_hash e manifest_hash. O agregador os preenche quando traz a receita de nextpdf/server, de modo que a página publicada registre a revisão exata que a produziu. Este índice e esta página de convenções são nativos da documentação; por isso, seus campos de proveniência são preenchidos com zeros por design, e o agregador não os sobrescreve.
Uma receita do Connect tem chamadas de ferramenta independentes do transporte, uma dependência de tier declarada explicitamente, modelo de risco e portão de confirmação documentados, tratamento de erros que separa transporte de status, um limite de conformidade honesto e o padrão publish: false até o Writing Gate. Uma página que atende aos seis é uma receita; uma página que atende a menos é um rascunho.
Veja também
Seção intitulada “Veja também”- Cookbook do Connect — o mapa de slugs das receitas e o limite de tier e transporte.
- Convenções de receitas do cookbook de integração — o contrato de receitas válido para todo o ecossistema, que esta página especializa para o Connect.