Connect recipe 규약

Connect cookbook의 모든 레시피는 동일한 계약을 따릅니다. 이 페이지는 그 계약을 문서화해 독자가 무엇을 기대할 수 있는지, 작성자가 레시피에서 무엇을 충족해야 하는지 알 수 있게 합니다. 이 페이지는 설명형입니다. 즉, 규약을 기록합니다. 시행은 이 페이지가 아니라 nextpdf/server 저장소 도구와 문서 스타일 재정의 시트에 존재합니다.

Connect 레시피는 nextpdf/server 저장소의 docs/public/ 아래에서 작성되며, aggregator가 이를 이 사이트로 가져옵니다. 아래 규약은 Connect 레시피의 위치와 관계없이 적용됩니다.

1. 도구 호출은 전송 방식에 독립적입니다

Connect 레시피의 도구 호출은 모든 전송 방식에서 동일하게 동작합니다.

레시피는 도구 호출을 한 번만 보여 줍니다. 동일한 호출이 Model Context Protocol(tools/call), REST 도구 엔드포인트, gRPC 서비스에서 도구를 구동합니다. 세 가지 모두 하나의 도구 실행기를 공유하기 때문입니다.
도구 인수 스키마의 권위 있는 원본은 실행 중인 배포가 tools/list(MCP) 또는 서비스 디스크립터(gRPC)를 통해 반환하는 것입니다. 레시피의 예시 인수는 호출 형태를 보여 주기 위한 것이며, 레시피가 다시 정의하는 고정된 스키마가 아닙니다.
레시피는 고정된 도구 총 개수를 단정하지 않습니다. 기준 카탈로그는 서버 자체의 도구 카탈로그이며, 레시피가 이를 링크합니다.

2. 등급별 조건부 도구는 명시되며, 가정되지 않습니다

서버의 도구 레지스트리는 핵심 도구를 항상 등록한 다음, class_exists()로 Pro 및 Enterprise 공급자를 탐지하고, nextpdf/premium이 서버와 함께 설치된 경우에만 해당 도구를 등록합니다.

Pro 또는 Enterprise 도구에 의존하는 레시피는 그 등급 의존성을 명시적으로 기술하고, 독자에게 해당 도구가 자신의 배포에 존재하는지 확인하는 방법(tools/list 호출)을 알려 줍니다.
도구를 확인할 수 없는 배포에서는 호출이 알 수 없는 도구 오류를 반환합니다. 레시피는 이를 성능 저하가 아니라 의도된 등급 경계로 제시하며, 등급으로 게이트된 도구가 항상 사용 가능하다고 암시하지 않습니다.

3. 위험 모델과 확인 gate

모든 도구는 네 가지 위험 수준 중 하나를 선언하며, 가장 높은 approval_required는 첫 호출에서 실행되지 않습니다.

도구가 (설계상 또는 운영자 재정의에 의해) approval_required가 될 수 있는 레시피는 ConfirmationGate를 문서화합니다. 이 gate는 도구 이름, nonce, 300 초 TTL에 바인딩된 일회용 챌린지 토큰을 반환하며, 인수에는 바인딩하지 않습니다. 호출자는 arguments._confirmation_token을 사용하여 동일한 도구를 다시 한 번 호출합니다.
레시피는 구성 재정의가 도구의 위험 수준을 높이는 것만 가능하며, 설계상 approval_required인 도구는 결코 낮출 수 없다고 기술합니다. 이 gate는 모든 전송 방식에서 동일하게 동작합니다.

4. 오류 처리는 전송과 상태를 분리합니다

HTTP를 통해 원격 서비스에 접근하는 레시피에서는 전송 실패와 성공이 아닌 HTTP 상태가 서로 별개의 경우입니다. PSR-18 클라이언트는 요청을 전혀 전송할 수 없을 때에만 형식화된 클라이언트 예외를 발생시킵니다 — PSR-18 §4. 4xx 또는 5xx 응답은 레시피가 검사하는 정상적인 반환 값이며, 레시피가 잡는 예외가 아닙니다. 프로덕션에 적합한 Connect 레시피는 빈 catch 블록 없이 두 경우를 명확히 구분해 처리하는 예를 보여 줍니다.

5. conformance와 certification 경계

Connect 레시피는 표준 지원을 지원으로만 해석하며, conformance나 certification으로 해석하지 않습니다.

엔진은 표준(PDF/UA-2, PDF/A-4, PAdES 레벨)에 준수하도록 의도된 출력을 생성합니다. conformance는 생성 소프트웨어가 단정하는 것이 아니라 독립적인 검증기가 표준의 요구 사항에 따라 결정합니다 — PDF/A-4 §6.7.3.
readiness assessment는 readiness 신호이지, certification이 아닙니다. 증명(attestation)은 법적 보증이 아닙니다. 문서에 포함된 장기 검증(LTV) 자료는 문서의 기능이며, 무기한 서명 유효성에 대한 보증이 아닙니다. 이는 하위 PAdES 레벨과 구별되는 Enterprise 전용 기능입니다.
절대성을 나타내는 conformance 표현은 엔진 주장(claim)으로 쓰지 않습니다. 레시피 검사에 쓰이는 어휘 차단 목록은 토큰 “certified”, 이어서 “guaranteed”, 이어서 두 단어 구 “fully” + “compliant”, 이어서 “tamper-proof”, 이어서 “legally valid”입니다. 그 어느 것도 NextPDF 출력의 단정된 속성으로 내세울 수 없습니다. 이는 conformance가 생성 소프트웨어가 아니라 독립적인 검증기가 표준의 요구 사항에 따라 결정하기 때문입니다 — PDF/A-4 §6.7.3 . 상위(upstream) 주장을 완화하는 레시피는 그 완화 내용을 함께 위치한 강등된 주장 사이드카에 기록합니다.

6. 발행 gate

모든 Connect 레시피는 Writing Gate를 통과할 때까지 publish: false 상태입니다. 기본 동작은 거부입니다. 즉, 페이지를 병합하는 것만으로는 발행되지 않으며, front-matter에 기록된 명시적인 gate 결정이 있어야만 발행됩니다. 실제 compliance-engine 중단으로 인해 규범적 인용을 고정할 수 없었던 레시피는 추가로 미해결 인용 표시를 지니며, 해당 인용이 다시 고정될 때까지 publish: false 상태를 유지합니다. 저장소의 RAG 인프라 중단 폴백 프로토콜이 그 표시를 관장합니다. 작성자는 인용을 지어내거나 주장을 누락하는 대신 이를 따릅니다.

7. aggregator가 provenance 필드를 기록합니다

Connect 레시피 작성자는 aggregator가 소유하는 네 개의 소스 출처(provenance) 필드, 즉 source_repo, source_ref, source_hash, manifest_hash를 손으로 작성하지 않습니다. aggregator는 nextpdf/server에서 레시피를 가져올 때 이 필드들을 채우므로, 발행된 페이지는 정확히 어떤 리비전에서 생성됐는지 기록합니다. 이 색인과 이 규약 페이지는 docs 고유(docs-native)이므로, 출처 필드는 설계상 0으로 채워지며 aggregator는 이를 덮어쓰지 않습니다.

요약

Connect 레시피는 전송 방식에 독립적인 도구 호출, 명시적으로 기술된 등급 의존성, 문서화된 위험 모델과 확인 gate, 전송과 상태를 분리하는 오류 처리, 명확한 conformance 경계, 그리고 Writing Gate 전까지의 publish: false 기본값을 갖춘 페이지입니다. 여섯 가지를 모두 충족하는 페이지는 레시피이고, 그보다 부족한 페이지는 초안입니다.

함께 보기

Connect cookbook — 레시피 슬러그 맵과 tier/transport 경계입니다.
Integration cookbook recipe conventions — 이 페이지가 Connect에 맞게 특화한 생태계 전반의 레시피 계약입니다.