Convenciones para las recipes de Connect

Cada recipe del cookbook de Connect sigue el mismo contrato. Esta página lo documenta para que quien lee sepa qué esperar y quien escribe sepa qué debe cumplir una recipe. Es una referencia descriptiva: registra la convención. Su aplicación efectiva vive en las herramientas del repositorio nextpdf/server y en la hoja de anulaciones de estilo de la documentación, no aquí.

Las recipes de Connect se escriben en el repositorio nextpdf/server bajo docs/public/, y el aggregator las incorpora a este sitio. Las convenciones siguientes se aplican dondequiera que resida una recipe de Connect.

1. Las llamadas a herramientas son independientes del transporte

Las invocaciones de herramientas de una recipe de Connect funcionan igual sobre cualquier transporte.

La recipe muestra la llamada a la herramienta una sola vez. Esa misma llamada ejecuta la herramienta sobre el Model Context Protocol (tools/call), el endpoint REST de herramientas y el servicio gRPC, porque los tres comparten un único ejecutor de herramientas.
El esquema de argumentos autoritativo de una herramienta es el que devuelve el despliegue en ejecución desde tools/list (MCP) o el descriptor de servicio (gRPC). Los argumentos de ejemplo de una recipe ilustran la forma de la llamada; no son un esquema congelado que la recipe vuelva a definir.
Una recipe nunca afirma un número fijo de herramientas. El catálogo de referencia es el propio catálogo de herramientas del servidor, al que la recipe enlaza.

2. Las herramientas condicionadas al nivel se declaran, no se dan por hechas

El registro de herramientas del servidor registra sin condiciones las herramientas del núcleo; luego detecta los proveedores Pro y Enterprise con class_exists() y registra sus herramientas solo cuando nextpdf/premium está instalado junto al servidor.

Una recipe que depende de una herramienta Pro o Enterprise declara explícitamente esa dependencia de nivel e indica a quien lee cómo confirmar que la herramienta está presente en su despliegue (una llamada a tools/list).
En un despliegue donde la herramienta no se resolvió, la llamada devuelve un error de herramienta desconocida. Una recipe lo presenta como el límite de nivel previsto, no como una degradación, y nunca da a entender que una herramienta controlada por nivel esté siempre disponible.

3. El modelo de riesgo y la compuerta de confirmación

Cada herramienta declara uno de cuatro niveles de riesgo; el más alto, approval_required, no se ejecuta en la primera llamada.

Una recipe cuya herramienta puede ser approval_required (por diseño o por una anulación del operador) documenta la ConfirmationGate: la compuerta devuelve un token de desafío de un solo uso vinculado al nombre de la herramienta, a un nonce y a un TTL de 300 segundos, no a los argumentos. Quien llama invoca de nuevo la misma herramienta una sola vez con arguments._confirmation_token.
Una recipe declara que una anulación de configuración solo puede elevar el nivel de riesgo de una herramienta; nunca puede rebajar una herramienta que es approval_required por diseño. La compuerta se comporta de forma idéntica en todos los transportes.

4. El manejo de errores separa el transporte del estado

Para una recipe que accede a un servicio remoto sobre HTTP, un fallo de transporte y un estado HTTP no exitoso son dos casos distintos. Un cliente PSR-18 lanza una excepción de cliente tipada solo cuando no puede enviar la petición en absoluto (PSR-18 §4); una respuesta 4xx o 5xx es un valor de retorno normal que la recipe inspecciona, no una excepción que capture. Una recipe de Connect lista para producción muestra ambos casos manejados de forma diferenciada, sin ningún bloque catch vacío.

5. El límite de conformidad y certificación

Una recipe de Connect interpreta la compatibilidad con un estándar como compatibilidad, nunca como conformidad ni como certificación.

El motor produce una salida destinada a conformar con un estándar (PDF/UA-2, PDF/A-4, un nivel PAdES); la conformidad la determina un validador independiente frente a los requisitos del estándar, no la declara el software productor (PDF/A-4 §6.7.3).
Una evaluación de preparación es una señal de preparación, no una certificación. Una atestación no es una garantía legal. El material de validación a largo plazo presente en un documento es una capacidad que el documento lleva consigo, no una garantía de validez indefinida de la firma. Es una capacidad exclusiva de Enterprise, distinta de los niveles PAdES inferiores.
Las palabras de conformidad absoluta no se usan como afirmaciones del motor. La lista de bloqueo léxica frente a la que se comprueba una recipe es, textualmente, los tokens «certified», luego «guaranteed», luego la frase de dos palabras «fully» + «compliant», luego «tamper-proof», luego «legally valid»: ninguno puede figurar como una propiedad afirmada de la salida de NextPDF, porque la conformidad la decide un validador independiente frente a los requisitos del estándar, no el software productor (PDF/A-4 §6.7.3). Una recipe que suaviza una afirmación de origen registra ese suavizado en su archivo adjunto colocalizado de afirmaciones rebajadas.

6. El publish gate

Cada recipe de Connect lleva publish: false hasta que supera el Writing Gate. El valor predeterminado es denegar: fusionar una página no la publica; solo la publica una decisión explícita de la compuerta registrada en el front-matter. Una recipe cuyas citas normativas no se pudieron fijar a causa de una interrupción genuina del compliance-engine lleva además un marcador de cita sin resolver y permanece con publish: false hasta que la cita se vuelve a fijar. El protocolo de reserva del repositorio para interrupciones de la infraestructura RAG rige ese marcador; quien escribe lo sigue en lugar de inventar una cita o descartar la afirmación.

7. El aggregator escribe los campos de procedencia

Quien escribe una recipe de Connect no rellena a mano los cuatro campos de procedencia de origen que controla el aggregator: source_repo, source_ref, source_hash y manifest_hash. El aggregator los rellena cuando extrae la recipe de nextpdf/server, de modo que la página publicada registra exactamente qué revisión la produjo. Este índice y esta página de convenciones son nativos de la documentación, por lo que sus campos de procedencia se rellenan con ceros por diseño y el aggregator no los sobrescribe.

Resumen

Una recipe de Connect consiste en: llamadas a herramientas independientes del transporte, una dependencia de nivel declarada explícitamente, el modelo de riesgo y la compuerta de confirmación documentados, un manejo de errores que separa el transporte del estado, un límite honesto de conformidad y un valor predeterminado publish: false hasta el Writing Gate. Una página que cumple los seis puntos es una recipe; una página que cumple menos es un borrador.

Véase también

Cookbook de Connect — el mapa de slugs de recipes y el límite de tier/transport.
Convenciones de las recipes del cookbook de integraciones — el contrato de recipes de todo el ecosistema que esta página especializa para Connect.