Konvensi recipe Connect

Setiap recipe dalam cookbook Connect mengikuti kontrak yang sama. Halaman ini mencatat kontrak tersebut agar, sebagai pembaca, Anda tahu apa yang dapat diharapkan, dan sebagai penulis, apa yang harus dipenuhi oleh sebuah recipe. Halaman ini bersifat deskriptif: isinya mencatat konvensi. Penegakannya berada pada perkakas repositori nextpdf/server dan lembar penggantian gaya dokumentasi, bukan di sini.

Penulis membuat recipe Connect di repositori nextpdf/server di bawah docs/public/, dan agregator menariknya ke situs ini. Konvensi berikut berlaku di mana pun sebuah recipe Connect berada.

1. Panggilan tool tidak bergantung pada transport

Sebuah recipe Connect menggunakan panggilan tool yang sama di setiap transport.

Sebuah recipe menampilkan panggilan tool satu kali. Panggilan yang sama menjalankan tool melalui Model Context Protocol (tools/call), endpoint tool Representational State Transfer (REST), dan layanan gRPC, karena ketiganya berbagi satu eksekutor tool.
Skema argumen otoritatif untuk sebuah tool adalah skema yang dikembalikan oleh tools/list (MCP) atau deskriptor layanan (gRPC) pada deployment yang sedang berjalan. Contoh argumen dalam sebuah recipe menunjukkan bentuk panggilannya; argumen tersebut bukan skema beku yang didefinisikan ulang oleh recipe.
Sebuah recipe tidak pernah menyatakan jumlah total tool yang tetap. Katalog acuan resminya adalah katalog tool milik server itu sendiri, yang ditautkan oleh recipe.

2. Tool yang bergantung pada tier dinyatakan, bukan diasumsikan

Registri tool server selalu mendaftarkan tool inti. Setelah itu, registri memeriksa keberadaan penyedia Pro dan Enterprise dengan class_exists() dan mendaftarkan tool-nya hanya ketika nextpdf/premium terpasang bersama server.

Sebuah recipe yang bergantung pada tool Pro atau Enterprise menyatakan ketergantungan tier tersebut secara eksplisit dan memberi tahu Anda cara memastikan tool itu ada pada deployment Anda dengan panggilan tools/list.
Pada deployment yang tidak dapat me-resolve tool tersebut, panggilan mengembalikan galat tool-tidak-dikenal. Sebuah recipe menyajikan hasil tersebut sebagai batas tier yang disengaja, bukan sebagai penurunan kualitas, dan tidak pernah menyiratkan bahwa tool yang dibatasi oleh tier selalu tersedia.

3. Model risiko dan gerbang konfirmasi

Setiap tool mendeklarasikan salah satu dari empat tingkat risiko. Tingkat tertinggi, approval_required, tidak dijalankan pada panggilan pertama.

Sebuah recipe yang tool-nya dapat menjadi approval_required (secara desain atau melalui penggantian oleh operator) mendokumentasikan ConfirmationGate: gerbang ini mengembalikan token tantangan sekali pakai yang terikat pada nama tool, nonce, dan time to live (TTL) selama 300 detik, bukan pada argumen. Pemanggil memanggil ulang tool yang sama satu kali dengan arguments._confirmation_token.
Sebuah recipe menyatakan bahwa penggantian konfigurasi hanya boleh menaikkan tingkat risiko sebuah tool; penggantian itu tidak pernah dapat menurunkan tool yang approval_required secara desain. Gerbang ini berperilaku identik di seluruh transport.

4. Penanganan galat memisahkan transport dari status

Untuk recipe yang mengakses layanan jarak jauh melalui Hypertext Transfer Protocol (HTTP), kegagalan transport dan status HTTP yang tidak sukses merupakan dua kasus berbeda. Klien PSR-18 hanya memunculkan eksepsi klien bertipe ketika klien sama sekali tidak dapat mengirim permintaan — PSR-18 §4; respons 4xx atau 5xx adalah nilai kembalian normal yang diperiksa oleh recipe, bukan eksepsi yang ditangkapnya. Sebuah recipe Connect yang siap produksi menangani kedua kasus tersebut secara terpisah, tanpa blok catch kosong.

5. Batas conformance dan sertifikasi

Sebuah recipe Connect memperlakukan dukungan terhadap suatu standar sebagai dukungan, tidak pernah sebagai conformance atau sertifikasi.

Engine menghasilkan keluaran yang dimaksudkan untuk memenuhi suatu standar (PDF/UA-2, PDF/A-4, sebuah level PAdES); conformance ditentukan terhadap persyaratan standar oleh validator independen, bukan dinyatakan oleh perangkat lunak yang menghasilkannya — PDF/A-4 §6.7.3.
Penilaian kesiapan adalah sinyal kesiapan, bukan sertifikasi. Sebuah atestasi bukan jaminan hukum. Materi long-term-validation yang terdapat dalam sebuah dokumen adalah kapabilitas yang dibawa dokumen tersebut, bukan jaminan keabsahan tanda tangan tanpa batas. Ini adalah kapabilitas khusus Enterprise yang berbeda dari level PAdES yang lebih rendah.
Kata-kata conformance yang absolut tidak digunakan sebagai klaim engine. Daftar blokir leksikal yang menjadi acuan pemeriksaan sebuah recipe secara verbatim terdiri atas token “certified”, lalu “guaranteed”, lalu frasa dua kata “fully” + “compliant”, lalu “tamper-proof”, lalu “legally valid”: tidak satu pun boleh menjadi properti yang dinyatakan dari keluaran NextPDF, karena conformance diputuskan oleh validator independen terhadap persyaratan standar, bukan oleh perangkat lunak yang menghasilkannya — PDF/A-4 §6.7.3. Sebuah recipe yang melunakkan klaim dari sumber hulu mencatat pelunakan itu dalam berkas sidecar downgraded-claims yang ditempatkan bersamanya.

6. Gerbang publikasi

Setiap recipe Connect membawa publish: false hingga lolos dari Writing Gate. Default-nya adalah menolak: melakukan merge sebuah halaman tidak memublikasikannya; hanya keputusan gerbang yang eksplisit dan dicatat dalam front-matter yang memublikasikannya. Sebuah recipe yang sitasi normatifnya tidak dapat di-pin karena gangguan compliance-engine yang benar-benar terjadi juga membawa penanda sitasi-belum-terselesaikan dan tetap publish: false hingga sitasi tersebut di-pin ulang. Protokol fallback infra-outage Retrieval-Augmented Generation (RAG) milik repositori mengatur penanda tersebut; penulis mengikutinya alih-alih mengarang sitasi atau menghilangkan klaim.

7. Agregator menulis bidang provenance

Penulis recipe Connect tidak menulis secara manual keempat bidang source-provenance yang dimiliki agregator: source_repo, source_ref, source_hash, dan manifest_hash. Agregator mengisinya saat menarik recipe dari nextpdf/server, sehingga halaman yang dipublikasikan mencatat revisi persis yang menghasilkannya. Indeks ini dan halaman konvensi ini bersifat docs-native, sehingga bidang provenance-nya diisi nol secara desain dan agregator tidak menimpanya.

Ringkasan

Sebuah recipe Connect memiliki panggilan tool yang tidak bergantung pada transport, ketergantungan tier yang dinyatakan secara eksplisit, model risiko dan gerbang konfirmasi yang terdokumentasi, penanganan galat yang memisahkan transport dari status, batas conformance yang jujur, dan default publish: false hingga Writing Gate. Halaman yang memenuhi keenamnya adalah sebuah recipe; halaman yang memenuhi lebih sedikit adalah sebuah draf.

Lihat juga

Cookbook Connect — peta slug recipe serta batas tier dan transport.
Konvensi recipe cookbook integrasi — kontrak recipe untuk seluruh ekosistem; halaman ini mengkhususkannya untuk Connect.