Konventionen für Connect-Recipes

Jedes Recipe im Connect-Cookbook folgt demselben Vertrag. Diese Seite dokumentiert ihn, damit klar ist, was Leser erwartet und was Autoren in einem Recipe erfüllen müssen. Diese Seite ist deskriptiv: Sie hält die Konvention fest. Durchgesetzt wird dieser Vertrag vom Tooling des nextpdf/server-Repositorys und vom Style-Override-Sheet der Dokumentation, nicht hier.

Connect-Recipes werden im nextpdf/server-Repository unter docs/public/ erstellt, und der Aggregator zieht sie in diese Site. Die folgenden Konventionen gelten überall, wo ein Connect-Recipe abgelegt ist.

1. Tool-Aufrufe sind transportunabhängig

Die Tool-Aufrufe eines Connect-Recipes verhalten sich über jeden Transport hinweg gleich.

Das Recipe zeigt den Tool-Aufruf einmal. Derselbe Aufruf steuert das Tool über das Model Context Protocol (tools/call), den REST-Tool-Endpunkt und den gRPC-Service, weil alle drei einen einzigen Tool-Executor teilen.
Das maßgebliche Argument-Schema für ein Tool ist das Schema, das das laufende Deployment aus tools/list (MCP) oder dem Service-Deskriptor (gRPC) zurückgibt. Die Beispielargumente eines Recipes veranschaulichen die Form des Aufrufs; sie sind kein eingefrorenes Schema, das das Recipe neu definiert.
Ein Recipe behauptet nie eine feste Gesamtzahl an Tools. Der maßgebliche Katalog ist der eigene Tool-Katalog des Servers, auf den das Recipe verlinkt.

2. Stufenabhängige Tools werden benannt, nicht vorausgesetzt

Die Tool-Registry des Servers registriert Core-Tools bedingungslos, prüft anschließend mit class_exists(), ob die Pro- und Enterprise-Provider vorhanden sind, und registriert deren Tools nur dann, wenn nextpdf/premium neben dem Server installiert ist.

Ein Recipe, das von einem Pro- oder Enterprise-Tool abhängt, benennt diese Stufenabhängigkeit ausdrücklich und erklärt dem Leser, wie er prüft, ob das Tool in seinem Deployment vorhanden ist (ein tools/list-Aufruf).
In einem Deployment, in dem das Tool nicht aufgelöst wurde, gibt der Aufruf einen Unknown-Tool-Fehler zurück. Ein Recipe stellt das als die beabsichtigte Stufengrenze dar, nicht als Verschlechterung, und legt nie nahe, dass ein stufengesteuertes Tool immer verfügbar ist.

3. Das Risikomodell und das Confirmation-Gate

Jedes Tool deklariert eine von vier Risikostufen; die höchste, approval_required, wird beim ersten Aufruf nicht ausgeführt.

Ein Recipe, dessen Tool approval_required sein kann (per Design oder durch ein Operator-Override), dokumentiert das ConfirmationGate: Das Gate gibt ein einmalig verwendbares Challenge-Token zurück, das an den Tool-Namen, eine Nonce und eine TTL von 300 Sekunden gebunden ist – nicht an die Argumente. Der Aufrufer ruft dasselbe Tool ein zweites Mal mit arguments._confirmation_token auf.
Ein Recipe stellt klar, dass ein Konfigurations-Override die Risikostufe eines Tools nur anheben darf; ein Tool, das per Design approval_required ist, kann er niemals herabstufen. Das Gate verhält sich über alle Transporte hinweg identisch.

4. Die Fehlerbehandlung trennt Transport von Status

Bei einem Recipe, das einen entfernten Service über HTTP erreicht, sind ein Transportfehler und ein nicht erfolgreicher HTTP-Status zwei verschiedene Fälle. Ein PSR-18-Client wirft nur dann eine typisierte Client-Exception, wenn er die Anfrage überhaupt nicht senden kann – PSR-18 §4; eine 4xx- oder 5xx-Antwort ist ein normaler Rückgabewert, den das Recipe prüft, und keine Exception, die es abfängt. Ein produktionsreifes Connect-Recipe zeigt beide Fälle getrennt, ohne leeren Catch-Block.

5. Die Grenze zwischen Konformität und Zertifizierung

Ein Connect-Recipe beschreibt die Unterstützung eines Standards als Unterstützung, nie als Konformität oder Zertifizierung.

Die Engine erzeugt Ausgaben, die einem Standard entsprechen sollen (PDF/UA-2, PDF/A-4, eine PAdES-Stufe); Konformität wird anhand der Anforderungen des Standards durch einen unabhängigen Validator bestimmt, nicht von der erzeugenden Software behauptet – PDF/A-4 §6.7.3.
Eine Bereitschaftsbewertung ist ein Bereitschaftssignal, keine Zertifizierung. Eine Attestierung ist keine rechtliche Garantie. Long-Term-Validation-Material, das in einem Dokument vorhanden ist, ist eine Fähigkeit, die das Dokument trägt, keine Garantie für unbegrenzte Signaturgültigkeit. Diese Fähigkeit ist eine reine Enterprise-Fähigkeit, die sich von den niedrigeren PAdES-Stufen unterscheidet.
Absolute Konformitätsbegriffe werden nicht als Aussagen über die Engine verwendet. Die lexikalische Blockliste, gegen die ein Recipe geprüft wird, enthält wortwörtlich die Tokens „certified“, dann „guaranteed“, dann die zweiwortige Phrase „fully“ + „compliant“, dann „tamper-proof“, dann „legally valid“: Keines davon darf als zugesicherte Eigenschaft der Ausgabe von NextPDF stehen, weil Konformität von einem unabhängigen Validator gegen die Anforderungen des Standards entschieden wird, nicht von der erzeugenden Software – PDF/A-4 §6.7.3. Ein Recipe, das eine vorgelagerte Aussage abschwächt, hält die Abschwächung in seiner beiliegenden Sidecar-Datei für herabgestufte Aussagen fest.

6. Das Publish-Gate

Jedes Connect-Recipe trägt publish: false, bis es das Writing Gate passiert. Die Voreinstellung ist „verweigern“: Das Mergen einer Seite veröffentlicht sie nicht; nur eine ausdrückliche, im Front-Matter festgehaltene Gate-Entscheidung tut das. Ein Recipe, dessen normative Zitate wegen eines echten Ausfalls der Compliance-Engine nicht gepinnt werden konnten, trägt zusätzlich einen Marker für ungelöste Zitate und bleibt publish: false, bis das Zitat neu gepinnt wird. Das Fallback-Protokoll des Repositorys für RAG-Infrastrukturausfälle regelt diesen Marker; ein Autor folgt ihm, statt ein Zitat zu erfinden oder die Aussage fallen zu lassen.

7. Der Aggregator schreibt die Provenance-Felder

Ein Autor eines Connect-Recipes schreibt die vier Source-Provenance-Felder, die dem Aggregator gehören, nicht von Hand: source_repo, source_ref, source_hash und manifest_hash. Der Aggregator füllt sie aus, wenn er das Recipe aus nextpdf/server zieht, sodass die veröffentlichte Seite genau festhält, aus welcher Revision sie erzeugt wurde. Dieser Index und diese Konventionsseite sind docs-nativ, sodass ihre Provenance-Felder per Design mit Nullen gefüllt sind und der Aggregator sie nicht überschreibt.

Zusammenfassung

Ein Connect-Recipe umfasst: transportunabhängige Tool-Aufrufe, eine ausdrücklich benannte Stufenabhängigkeit, das dokumentierte Risikomodell und Confirmation-Gate, eine Fehlerbehandlung, die Transport von Status trennt, eine ehrliche Konformitätsgrenze und eine publish: false-Voreinstellung bis zum Writing Gate. Eine Seite, die alle sechs erfüllt, ist ein Recipe; eine Seite, die weniger davon erfüllt, ist ein Entwurf.

Siehe auch

Connect-Cookbook – die Slug-Map der Recipes und die tier/transport-Grenze.
Konventionen für Recipes im Integration-Cookbook – der ökosystemweite Recipe-Vertrag, den diese Seite für Connect spezialisiert.