Conventions des recipes Connect

Chaque recipe du Cookbook Connect suit le même contrat. Cette page le documente, afin qu’un lecteur sache à quoi s’attendre et qu’un auteur sache quelles exigences un recipe doit satisfaire. Elle est descriptive : elle consigne la convention. Son application relève de l’outillage du dépôt nextpdf/server et de la feuille de style de surcharge de la documentation, pas de cette page.

Les recipes Connect sont rédigés dans le dépôt nextpdf/server sous docs/public/, puis l’agrégateur les rapatrie vers ce site. Les conventions ci-dessous s’appliquent partout où se trouve un recipe Connect.

1. Les appels d’outils sont indépendants du transport

Les invocations d’outils d’un recipe Connect fonctionnent de la même manière sur chaque transport.

Le recipe montre l’appel d’outil une seule fois. Ce même appel pilote l’outil via le Model Context Protocol (tools/call), le point de terminaison REST des outils et le service gRPC, car les trois partagent un seul exécuteur d’outils.
Le schéma d’arguments faisant autorité pour un outil est celui que le déploiement en cours renvoie depuis tools/list (MCP) ou via le descripteur de service (gRPC). Les arguments d’exemple d’un recipe illustrent la forme de l’appel ; ils ne constituent pas un schéma figé que le recipe redéfinit.
Un recipe n’affirme jamais un nombre total fixe d’outils. Le catalogue qui fait foi est celui du serveur, vers lequel le recipe pointe.

2. Les outils conditionnés par le niveau sont énoncés, pas supposés

Le registre d’outils du serveur enregistre sans condition les outils du cœur, puis sonde les fournisseurs Pro et Enterprise avec class_exists() et n’enregistre leurs outils que lorsque nextpdf/premium est installé aux côtés du serveur.

Un recipe qui dépend d’un outil Pro ou Enterprise énonce explicitement cette dépendance de niveau et indique au lecteur comment confirmer que l’outil est présent sur son déploiement (un appel tools/list).
Sur un déploiement où l’outil n’a pas été résolu, l’appel renvoie une erreur d’outil inconnu. Un recipe présente ce cas comme la frontière de niveau attendue, pas comme une dégradation, et ne laisse jamais entendre qu’un outil verrouillé par niveau est toujours disponible.

3. Le modèle de risque et la porte de confirmation

Chaque outil déclare l’un des quatre niveaux de risque ; le plus élevé, approval_required, ne s’exécute pas au premier appel.

Un recipe dont l’outil peut être approval_required (par conception ou en raison d’une surcharge d’opérateur) documente la ConfirmationGate : la porte renvoie un jeton de défi à usage unique lié au nom de l’outil, à un nonce et à une TTL de 300 secondes — pas aux arguments. L’appelant réinvoque une fois le même outil avec arguments._confirmation_token.
Un recipe indique qu’une surcharge de configuration ne peut qu’élever le niveau de risque d’un outil ; elle ne peut jamais abaisser celui d’un outil qui est approval_required par conception. La porte se comporte de manière identique sur tous les transports.

4. La gestion des erreurs sépare le transport du statut

Pour un recipe qui appelle un service distant via HTTP, un échec de transport et un statut HTTP d’échec sont deux cas distincts. Un client PSR-18 ne lève une exception client typée que lorsqu’il ne peut pas du tout envoyer la requête — PSR-18 §4 ; une réponse 4xx ou 5xx est une valeur de retour normale que le recipe inspecte, pas une exception à intercepter. Un recipe Connect prêt pour la production montre un traitement distinct des deux cas, sans bloc catch vide.

5. La frontière de conformité et de certification

Un recipe Connect interprète la prise en charge d’une norme comme une prise en charge, jamais comme une conformité ni une certification.

Le moteur produit une sortie destinée à se conformer à une norme (PDF/UA-2, PDF/A-4, un niveau PAdES) ; la conformité est déterminée par un validateur indépendant au regard des exigences de la norme, et non affirmée par le logiciel producteur — PDF/A-4 §6.7.3.
Une évaluation de préparation est un signal de préparation, pas une certification. Une attestation n’est pas une garantie juridique. Le matériel de validation à long terme présent dans un document est une capacité portée par le document, pas une garantie de validité indéfinie de la signature. Cette capacité est réservée à Enterprise et reste distincte des niveaux PAdES inférieurs.
Les termes de conformité absolue ne sont pas employés comme affirmations du moteur. La liste lexicale de blocage au regard de laquelle un recipe est vérifié contient, mot pour mot, les jetons « certified », puis « guaranteed », puis l’expression de deux mots « fully » + « compliant », puis « tamper-proof », puis « legally valid » : aucun ne peut être présenté comme une propriété affirmée de la sortie NextPDF, car la conformité est décidée par un validateur indépendant au regard des exigences de la norme, pas par le logiciel producteur — PDF/A-4 §6.7.3. Un recipe qui atténue une affirmation en amont consigne cette atténuation dans son fichier annexe co-localisé de claims rétrogradées.

6. La porte de publication

Chaque recipe Connect porte publish: false tant qu’il n’a pas franchi la Writing Gate. Par défaut, c’est le refus : fusionner une page ne la publie pas ; seule une décision de porte explicite, consignée dans le front-matter, le fait. Un recipe dont les citations normatives n’ont pas pu être épinglées à cause d’une véritable panne du compliance-engine porte en plus un marqueur de citation non résolue et reste publish: false jusqu’à ce que la citation soit ré-épinglée. Le protocole de repli du dépôt en cas de panne d’infrastructure RAG régit ce marqueur ; un auteur le suit au lieu d’inventer une citation ou de supprimer la claim.

7. L’agrégateur écrit les champs de provenance

Un auteur de recipe Connect n’écrit pas à la main les quatre champs de provenance de la source gérés par l’agrégateur : source_repo, source_ref, source_hash et manifest_hash. L’agrégateur les remplit lorsqu’il rapatrie le recipe depuis nextpdf/server, afin que la page publiée indique exactement quelle révision l’a produite. Cet index et cette page de conventions sont natifs des docs ; leurs champs de provenance sont donc remplis de zéros par conception, et l’agrégateur ne les écrase pas.

Résumé

Un recipe Connect, c’est : des appels d’outils indépendants du transport, une dépendance de niveau énoncée explicitement, le modèle de risque et la porte de confirmation documentés, une gestion des erreurs qui sépare le transport du statut, une frontière de conformité honnête et un défaut publish: false jusqu’à la Writing Gate. Une page qui satisfait ces six critères est un recipe ; une page qui en satisfait moins est un brouillon.

Voir aussi

Cookbook Connect — la cartographie des slugs de recipes et la frontière tier/transport.
Conventions des recipes du Cookbook Intégrations — le contrat de recipe à l’échelle de l’écosystème, que la présente page spécialise pour Connect.