Conventies voor Connect-recipes

Elk recipe in het Connect-cookbook volgt hetzelfde contract. Deze pagina legt dat contract vast, zodat lezers weten wat ze mogen verwachten en auteurs weten waaraan een recipe moet voldoen. De pagina is beschrijvend: ze documenteert de conventie. De handhaving gebeurt in de tooling van de nextpdf/server-repository en in het stijl-overrideblad van de documentatie, niet hier.

Auteurs schrijven Connect-recipes in de nextpdf/server-repository onder docs/public/; de aggregator haalt ze op voor deze site. De onderstaande conventies gelden ongeacht waar een Connect-recipe zich bevindt.

1. Tool-aanroepen zijn transportonafhankelijk

Een Connect-recipe gebruikt dezelfde tool-aanroep, ongeacht het transport.

Het recipe toont de tool-aanroep eenmaal. Dezelfde aanroep stuurt de tool aan via het Model Context Protocol (tools/call), het Representational State Transfer (REST)-tool-endpoint en de gRPC-service, omdat alle drie dezelfde tool-executor delen.
Het gezaghebbende argumentschema van een tool is het schema dat de actieve deployment teruggeeft via tools/list (MCP) of de service-descriptor (gRPC). De voorbeeldargumenten in een recipe tonen de vorm van de aanroep; ze vormen geen vastgelegd schema dat het recipe opnieuw definieert.
Een recipe noemt nooit een vast totaalaantal tools. De bron van waarheid is de eigen tool-catalogus van de server, waarnaar het recipe linkt.

2. Tier-afhankelijke tools worden vermeld, niet verondersteld

Het toolregister van de server registreert altijd de core-tools. Daarna controleert het met class_exists() of de Pro- en Enterprise-providers aanwezig zijn, en registreert het hun tools alleen wanneer nextpdf/premium naast de server is geïnstalleerd.

Een recipe dat afhankelijk is van een Pro- of Enterprise-tool vermeldt die niveau-afhankelijkheid expliciet en legt uit hoe een tools/list-aanroep bevestigt dat de tool op de deployment aanwezig is.
Op een deployment waarop de tool niet wordt gevonden, geeft de aanroep een unknown-tool-fout terug. Een recipe presenteert dat resultaat als de bedoelde niveaugrens, niet als een degradatie, en suggereert nooit dat een niveau-afgeschermde tool altijd beschikbaar is.

3. Het risicomodel en de bevestigingspoort

Elke tool declareert een van vier risiconiveaus. Het hoogste niveau, approval_required, wordt niet uitgevoerd bij de eerste aanroep.

Een recipe waarvan de tool approval_required kan zijn (door het ontwerp of door een operator-overrule) documenteert de ConfirmationGate: de poort geeft een eenmalig challenge-token terug dat gebonden is aan de toolnaam, een nonce en een time to live (TTL) van 300 seconden, niet aan de argumenten. De aanroeper roept dezelfde tool eenmaal opnieuw aan met arguments._confirmation_token.
Een recipe vermeldt dat een configuratie-overrule het risiconiveau van een tool alleen mag verhogen; de overrule kan een tool die door het ontwerp approval_required is, nooit verlagen. Voor alle transporten gedraagt de poort zich identiek.

4. Foutafhandeling scheidt transport van status

Voor een recipe dat via Hypertext Transfer Protocol (HTTP) een externe service benadert, zijn een transportfout en een HTTP-status die geen succes aangeeft verschillende gevallen. Een PSR-18-client werpt alleen een getypeerde client-exception op wanneer het verzoek helemaal niet kan worden verzonden — PSR-18 §4; een 4xx- of 5xx-respons is een normale retourwaarde die het recipe inspecteert, geen exception die het opvangt. Een productieklaar Connect-recipe handelt beide gevallen afzonderlijk af, zonder een leeg catch-blok.

5. De conformiteits- en certificeringsgrens

Een Connect-recipe behandelt ondersteuning voor een standaard als ondersteuning, nooit als conformiteit of certificering.

De engine produceert uitvoer die bedoeld is om aan een standaard te voldoen (PDF/UA-2, PDF/A-4, een PAdES-niveau); conformiteit wordt door een onafhankelijke validator bepaald aan de hand van de eisen van de standaard, en niet geclaimd door de producerende software — PDF/A-4 §6.7.3.
Een gereedheidsbeoordeling is een gereedheidssignaal, geen certificering. Een attestatie is geen juridische garantie. Long-term-validation-materiaal dat in een document aanwezig is, is een mogelijkheid die het document meedraagt, geen garantie dat de handtekening onbeperkt geldig blijft. Deze mogelijkheid is uitsluitend beschikbaar voor Enterprise en staat los van de lagere PAdES-niveaus.
Absolute conformiteitswoorden worden niet gebruikt als claims over de engine. De lexicale blokkeerlijst waaraan een recipe wordt getoetst, bestaat letterlijk uit de tokens “certified”, vervolgens “guaranteed”, vervolgens de tweewoordige uitdrukking “fully” + “compliant”, vervolgens “tamper-proof”, vervolgens “legally valid”: geen daarvan mag gelden als een geclaimde eigenschap van NextPDF-uitvoer, omdat conformiteit wordt bepaald door een onafhankelijke validator aan de hand van de eisen van de standaard, niet door de producerende software — PDF/A-4 §6.7.3. Een recipe dat een upstream-claim afzwakt, legt die afzwakking vast in de bijbehorende downgraded-claims-sidecar.

6. De publicatiepoort

Elk Connect-recipe houdt publish: false totdat het de Writing Gate passeert. De standaard is weigeren: een gemergde pagina wordt daardoor niet gepubliceerd; dat gebeurt alleen door een expliciete poortbeslissing die in de front-matter is vastgelegd. Een recipe waarvan de normatieve citaten niet konden worden vastgepind vanwege een werkelijke storing van de compliance-engine, draagt ook een unresolved-citation-markering en blijft publish: false totdat het citaat opnieuw wordt vastgepind. Het Retrieval-Augmented Generation (RAG) infra-outage-fallbackprotocol van de repository beheert die markering; een auteur volgt dat protocol in plaats van een citaat te verzinnen of de claim te laten vallen.

7. De aggregator schrijft de herkomstvelden

Een auteur van een Connect-recipe schrijft de vier source-provenance-velden die de aggregator beheert niet handmatig: source_repo, source_ref, source_hash en manifest_hash. De aggregator vult ze in wanneer deze het recipe ophaalt uit nextpdf/server, zodat de gepubliceerde pagina exact de revisie vastlegt waaruit die is geproduceerd. Deze index en deze conventiepagina zijn docs-native, dus hun herkomstvelden zijn door het ontwerp met nullen gevuld en de aggregator overschrijft ze niet.

Samenvatting

Een Connect-recipe heeft transportonafhankelijke tool-aanroepen, een expliciet vermelde niveau-afhankelijkheid, het gedocumenteerde risicomodel en de bevestigingspoort, foutafhandeling die transport van status scheidt, een eerlijke conformiteitsgrens en een standaardwaarde publish: false tot aan de Writing Gate. Een pagina die aan alle zes voldoet, is een recipe; een pagina die aan minder voldoet, is een concept.

Zie ook

Connect-cookbook — de recipe-slugkaart en de niveau- en transportgrens.
Conventies voor recipes in het integratiecookbook — het ecosysteembrede recipe-contract dat deze pagina voor Connect specialiseert.