Connect レシピ規約

Connect レシピ規約

Connect クックブックのすべてのレシピは、同じ契約に従います。このページではその契約を文書化し、読者が期待できる内容と、執筆者が満たすべき要件を明確にします。このページは解説的なものであり、規約を記録するためのものです。強制はここではなく、nextpdf/server リポジトリのツールとドキュメントスタイルのオーバーライドシートで行われます。

Connect レシピは nextpdf/server リポジトリの docs/public/ 配下で執筆され、aggregator がそれらを本サイトに取り込みます。以下の規約は、Connect レシピの配置場所にかかわらず適用されます。

1. ツール呼び出しはトランスポート非依存

Connect レシピのツール呼び出しは、すべてのトランスポートで同じように動作します。

• レシピでは、ツール呼び出しを一度だけ示します。同じ呼び出しが、Model Context Protocol（tools/call）、REST ツールエンドポイント、gRPC サービスのいずれでもツールを駆動します。これは、3 つすべてが 1 つのツールエグゼキューターを共有しているためです。
• ツールの正式な引数スキーマは、稼働中のデプロイメントが tools/list（MCP）またはサービス記述子（gRPC）から返すものです。レシピのサンプル引数は呼び出しの形を示すためのものであり、レシピが再定義する固定スキーマではありません。
• レシピでは、ツールの総数を固定値として主張しません。正式なカタログはサーバー自身のツールカタログであり、レシピはそこにリンクします。

2. ティア条件付きツールは明示し、暗黙にしない

サーバーのツールレジストリは、コアツールを無条件に登録します。その後、class_exists() で Pro および Enterprise プロバイダーを確認し、nextpdf/premium がサーバーと併せてインストールされている場合にのみ、それらのツールを登録します。

• Pro または Enterprise のツールに依存するレシピでは、そのティア依存を明示し、ツールが自身のデプロイメントに存在することを確認する方法（tools/list 呼び出し）を読者に伝えます。
• ツールを解決できないデプロイメントでは、呼び出しは unknown-tool エラーを返します。レシピでは、それを劣化ではなく意図されたティア境界として提示し、ティアでゲートされたツールが常に利用可能であるかのようには示しません。

3. リスクモデルと確認ゲート

すべてのツールは、4 つのリスクレベルのいずれかを宣言します。最も高い approval_required は、初回の呼び出しでは実行されません。

• （設計上またはオペレーターのオーバーライドにより）ツールが approval_required になり得るレシピでは、ConfirmationGate を文書化します。このゲートは、ツール名、nonce、および 300 秒の TTL にバインドされた使い捨ての challenge トークンを返します。引数にはバインドされません。呼び出し側は、arguments._confirmation_token を付けて同じツールを一度だけ再呼び出しします。
• レシピでは、構成のオーバーライドでツールのリスクレベルを引き上げることだけが可能であり、設計上 approval_required であるツールを引き下げることは決してできないと述べます。このゲートは、すべてのトランスポートで同一に動作します。

4. エラー処理はトランスポートとステータスを分離する

HTTP 経由でリモートサービスに到達するレシピでは、トランスポートの失敗と成功以外の HTTP ステータスは、別々のケースとして扱います。PSR-18 クライアントは、リクエストをまったく送信できない場合にのみ、型付きのクライアント例外を発生させます（PSR-18 §4）。4xx または 5xx のレスポンスは、レシピがキャッチする例外ではなく、レシピが検査する通常の戻り値です。本番運用に対応した Connect レシピでは、空の catch ブロックを使わず、両方のケースを明確に区別して処理する例を示します。

5. conformance および certification の境界

Connect レシピでは、標準への対応を support として扱い、決して conformance や certification としては扱いません。

• エンジンは、標準（PDF/UA-2、PDF/A-4、PAdES レベル）に準拠することを意図した出力を生成します。conformance は、生成元のソフトウェアが主張するものではなく、独立したバリデーターが標準の要件に照らして判定するものです（PDF/A-4 §6.7.3）。
• readiness アセスメントは準備状況を示すシグナルであり、certification ではありません。attestation は法的な保証ではありません。ドキュメントに含まれる long-term-validation 用のデータは、そのドキュメントが備える機能であり、署名が無期限に有効であることの保証ではありません。これは、下位の PAdES レベルとは異なる、Enterprise 専用の機能です。
• 絶対的な conformance を表す語は、エンジンに関する主張として使用しません。レシピが照合される語彙ブロックリストは、文字どおりトークン “certified”、次に “guaranteed”、次に 2 語からなる句 “fully” + “compliant”、次に “tamper-proof”、次に “legally valid” です。これらはいずれも NextPDF 出力の主張された属性として用いてはなりません。conformance は、生成元のソフトウェアではなく、独立したバリデーターが標準の要件に照らして判定するものだからです（PDF/A-4 §6.7.3）。上流の主張を緩和するレシピは、その緩和を、同じ場所に配置された downgraded-claims サイドカーに記録します。

6. 公開ゲート

すべての Connect レシピは、Writing Gate を通過するまで publish: false を保持します。デフォルトは拒否です。ページをマージしても公開されません。公開は、front-matter に記録された明示的なゲート判断によってのみ行われます。compliance-engine の実際の障害により規範的な引用を固定できなかったレシピは、さらに unresolved-citation マーカーを保持し、引用が再固定されるまで publish: false のままになります。そのマーカーは、リポジトリの RAG インフラ障害フォールバックプロトコルによって管理されます。執筆者は、引用をでっち上げたり主張を取り下げたりするのではなく、そのプロトコルに従います。

7. provenance（来歴情報）フィールドは aggregator が書き込む

Connect レシピの執筆者は、aggregator が所有する 4 つの source-provenance フィールド、すなわち source_repo、source_ref、source_hash、manifest_hash を手書きしません。aggregator は、nextpdf/server からレシピを取り込む際にそれらを埋め込むため、公開されたページには、どのリビジョンが生成したのかが正確に記録されます。このインデックスとこの規約ページは docs-native であるため、それらの provenance フィールドは設計上ゼロで埋められており、aggregator はそれらを上書きしません。

まとめ

Connect レシピとは、トランスポート非依存のツール呼び出し、明示されたティア依存、文書化されたリスクモデルと確認ゲート、トランスポートとステータスを分離するエラー処理、誠実な conformance 境界、そして Writing Gate を通過するまでの publish: false デフォルトを備えたものです。6 つすべてを満たすページがレシピであり、満たす数がそれより少ないページはドラフトです。

関連項目

• Connect クックブック — レシピのスラッグマップと tier/transport 境界。
• Integration クックブックレシピ規約 — このページで Connect 向けに特殊化した、エコシステム全体のレシピ契約。