Convenzioni delle ricette Connect

Convenzioni delle ricette Connect

Ogni ricetta del cookbook Connect segue lo stesso contratto. Questa pagina lo documenta, così che chi legge sappia cosa aspettarsi e chi scrive sappia quali requisiti deve soddisfare una ricetta. È una pagina descrittiva: registra la convenzione. L’applicazione della convenzione risiede negli strumenti del repository nextpdf/server e nel foglio di override dello stile della documentazione, non qui.

Le ricette Connect vengono create nel repository nextpdf/server sotto docs/public/ e l’aggregatore le importa in questo sito. Le convenzioni seguenti si applicano indipendentemente da dove risieda una ricetta Connect.

1. Le chiamate agli strumenti sono indipendenti dal trasporto

Le invocazioni degli strumenti di una ricetta Connect funzionano allo stesso modo per ogni trasporto.

• Una ricetta mostra la chiamata allo strumento una sola volta. La stessa chiamata invoca lo strumento tramite il Model Context Protocol (tools/call), l’endpoint REST dello strumento e il servizio gRPC, perché tutti e tre condividono un unico tool executor.
• Lo schema autorevole degli argomenti di uno strumento è quello restituito dal deployment in esecuzione tramite tools/list (MCP) o dal descrittore del servizio (gRPC). Gli argomenti di esempio di una ricetta illustrano la forma della chiamata, ma non costituiscono uno schema fisso ridefinito dalla ricetta.
• Una ricetta non afferma mai un numero totale fisso di strumenti. Il catalogo di riferimento è il catalogo degli strumenti del server stesso, a cui la ricetta rimanda.

2. Gli strumenti vincolati al tier vengono dichiarati, non presunti

Il registro degli strumenti del server registra in modo incondizionato gli strumenti core, quindi rileva i provider Pro ed Enterprise con class_exists() e registra i loro strumenti solo quando nextpdf/premium è installato insieme al server.

• Una ricetta che dipende da uno strumento Pro o Enterprise dichiara esplicitamente la dipendenza dal tier e indica a chi legge come verificare la presenza dello strumento sul proprio deployment (una chiamata tools/list).
• In un deployment in cui lo strumento non viene risolto, la chiamata restituisce un errore di strumento sconosciuto. Una ricetta presenta questo comportamento come il confine del tier previsto, non come una degradazione, e non lascia mai intendere che uno strumento vincolato al tier sia sempre disponibile.

3. Il modello di rischio e il gate di conferma

Ogni strumento dichiara uno dei quattro livelli di rischio; il più alto, approval_required, non viene eseguito alla prima chiamata.

• Una ricetta il cui strumento può essere approval_required (per progettazione o tramite un override dell’operatore) documenta il ConfirmationGate: il gate restituisce un token di challenge monouso vincolato al nome dello strumento, a un nonce e a un TTL di 300 secondi, non agli argomenti. Il chiamante reinvoca lo stesso strumento una volta con arguments._confirmation_token.
• Una ricetta dichiara che un override di configurazione può solo aumentare il livello di rischio di uno strumento; non può mai abbassare uno strumento che è approval_required per progettazione. Il gate si comporta in modo identico su tutti i trasporti.

4. La gestione degli errori separa il trasporto dallo stato

Per una ricetta che raggiunge un servizio remoto tramite HTTP, un fallimento del trasporto e uno stato HTTP di non successo sono due casi distinti. Un client PSR-18 solleva un’eccezione client tipizzata solo quando non riesce affatto a inviare la richiesta — PSR-18 §4; una risposta 4xx o 5xx è un normale valore di ritorno da ispezionare, non un’eccezione da intercettare. Una ricetta Connect pronta per la produzione mostra i due casi gestiti separatamente, senza alcun blocco catch vuoto.

5. Il confine di conformità e certificazione

Una ricetta Connect considera il supporto a uno standard come supporto, mai come conformità o certificazione.

• Il motore produce output destinato a essere conforme a uno standard (PDF/UA-2, PDF/A-4, un livello PAdES); la conformità viene determinata rispetto ai requisiti dello standard da un validatore indipendente, non asserita dal software che lo produce — PDF/A-4 §6.7.3.
• Una valutazione di idoneità è un segnale di idoneità, non una certificazione. Un’attestazione non è una garanzia legale. Il materiale di validazione a lungo termine presente in un documento è una capacità del documento, non una garanzia di validità indefinita della firma. È una capacità esclusiva di Enterprise, distinta dai livelli PAdES inferiori.
• I termini di conformità assoluta non vengono utilizzati come affermazioni sul motore. La blocklist lessicale rispetto alla quale una ricetta viene verificata è, alla lettera, costituita dai token «certified», poi «guaranteed», poi la locuzione di due parole «fully» + «compliant», poi «tamper-proof», poi «legally valid»: nessuno di essi può comparire come proprietà asserita dell’output di NextPDF, perché la conformità è decisa da un validatore indipendente rispetto ai requisiti dello standard, non dal software che lo produce — PDF/A-4 §6.7.3. Una ricetta che attenua un’affermazione a monte registra l’attenuazione nel proprio file sidecar delle affermazioni declassate collocato accanto.

6. Il gate di pubblicazione

Ogni ricetta Connect riporta publish: false finché non supera il Writing Gate. Il valore predefinito è il rifiuto: il merge di una pagina non la pubblica; serve una decisione esplicita del gate registrata nel front-matter. Una ricetta le cui citazioni normative non hanno potuto essere fissate a causa di una reale interruzione del compliance-engine riporta inoltre un marcatore di citazione non risolta e resta publish: false finché la citazione non viene fissata di nuovo. Il protocollo di fallback del repository per le interruzioni dell’infrastruttura RAG governa tale marcatore; un autore lo segue anziché inventare una citazione o eliminare l’affermazione.

7. L’aggregatore scrive i campi di provenienza

Un autore di ricette Connect non scrive a mano i quattro campi di provenienza dell’origine gestiti dall’aggregatore: source_repo, source_ref, source_hash e manifest_hash. L’aggregatore li compila quando importa la ricetta da nextpdf/server, in modo che la pagina pubblicata registri esattamente quale revisione l’ha prodotta. Questo indice e questa pagina delle convenzioni sono nativi della documentazione, quindi i loro campi di provenienza sono riempiti con zeri per progettazione e l’aggregatore non li sovrascrive.

Riepilogo

Una ricetta Connect presenta: chiamate agli strumenti indipendenti dal trasporto, una dipendenza dal tier dichiarata esplicitamente, il modello di rischio e il gate di conferma documentati, una gestione degli errori che separa il trasporto dallo stato, un confine di conformità onesto e un valore predefinito publish: false fino al Writing Gate. Una pagina che soddisfa tutti e sei i requisiti è una ricetta; una pagina che non li soddisfa tutti è una bozza.

Vedere anche

• Cookbook Connect — la mappa degli slug delle ricette e il confine tier/transport.
• Convenzioni delle ricette del cookbook Integration — il contratto delle ricette valido per l’intero ecosistema, specializzato qui per Connect.