ADR-0059: PDF/UA-1-Machbarkeit vor einem Rendererwechsel belegen

Status: angenommen; Slice A lokal und in Linux-CI commitgebunden belegt
Datum: 26. August 2026
Issue: #333

Kontext

Der produktive Report wird serverseitig mit @react-pdf/renderer erzeugt und anschließend mit pdf-lib finalisiert. Er besitzt eine selektierbare Textschicht, Dokumentensprache, Metadaten, Outline, Links und einen über mehrere Viewer abgesicherten weißen Seitenhintergrund. Diese Eigenschaften belegen weder einen semantischen Strukturbaum noch PDF/UA-Konformität. Im aktuellen Produktionsoutput sind insbesondere Überschriften, Absätze, Listen, Tabellen und Abbildungen nicht als belastbare Lesestruktur nachgewiesen; wiederkehrender Seiten-Chrome ist nicht verifiziert als Artefakt markiert.

Ein unmittelbarer Austausch des Renderers würde dagegen Layout, Seitenumbrüche, Schriften, Links, Karten, Kaltstart, Speicherverbrauch und die bereits abgenommene Mehrseitenkompatibilität gleichzeitig verändern. Vor einer solchen Produktentscheidung muss deshalb isoliert belegt werden, dass ein für die Vercel-Runtime grundsätzlich geeigneter Browserpfad die erforderliche Dokumentsemantik überhaupt erzeugen und ein unabhängiger Validator sie reproduzierbar erkennen kann.

Entscheidung

Der Zielstandard für neu erzeugte Report-PDFs ist PDF/UA-1 nach ISO 14289-1 auf Basis von PDF 1.7. Slice A ist ausschließlich ein synthetisches Machbarkeits- und Vertragsprüfgate für diesen Zielstandard. Es schaltet keinen neuen Produktionsrenderer frei.
Eine feste, netzwerkfreie HTML-Fixture mit ausschließlich erfundenen Daten bildet die relevanten Semantikklassen ab: Dokumenttitel, Überschriften, Absätze, Liste, Tabelle mit Kopfzellen, Link, informative Abbildung mit Alternativtext sowie dekorative und wiederkehrende Seitenelemente. Die logische DOM-Reihenfolge ist zugleich die erwartete Lesereihenfolge. Der Runner bindet die rohen Fixture-Bytes an einen festen SHA-256, verbietet Skripte und Inline-Eventhandler, deaktiviert JavaScript und blockiert HTTP-, Datei- sowie WebSocket-Verbindungen.
Ein Chromium-basierter Kandidatenpfad erzeugt aus dieser Fixture ein getaggtes PDF. Er muss mindestens einen semantischen Strukturbaum, MarkInfo/Marked, die Dokumentensprache, ein PDF/UA-1-Kennzeichen im XMP-Metadatenstrom, Dokumenttitel und -metadaten, eine erhaltene Outline, erhaltenen Text, einen echten Link, Alternativtext für informative Abbildungen und Artefaktgrenzen für rein dekorative Elemente bereitstellen. Die Strukturrollen müssen in der definierten DOM-/Fixture-Reihenfolge erscheinen; bloß vorhandene, aber vertauschte Tags genügen nicht. Eine separate Poppler-Prüfung bindet die physische Textschicht seitenweise an feste Textmarker und deren Reihenfolge sowie den sichtbaren Linktext. Sie behauptet keine zusätzliche Zuordnung jedes Textmarkers zu einem konkreten MCID. Die technische Finalisierung darf die Tags nicht entfernen oder eine nur behauptete Konformität nachträglich in einen ungetaggten Output schreiben.
Ein gepinnter veraPDF-Validator prüft den Kandidaten gegen das PDF/UA-1-Profil. Das Prüfgate ist nur positiv, wenn der Validator ohne fehlgeschlagene Regeln endet. Parser- oder Prozessfehler gelten als Fehler, nicht als übersprungene Prüfung.
Derselbe Lauf erzeugt aus semantisch entsprechenden, erfundenen Daten ein PDF über den heutigen React-PDF-Produktionsrenderer. Diese Gegenprobe muss am PDF/UA-1-Validator oder an den vorgelagerten Strukturgates fail-closed scheitern. Damit belegt Slice A nicht nur, dass die positive Fixture grün wird, sondern auch, dass ein ungetaggter Bestandsoutput nicht versehentlich als konform durchläuft.
Lokaler Lauf und ein eigener, paralleler CI-Job verwenden dieselbe Fixture, denselben Runner und dieselbe gepinnte Validatorversion. CI veröffentlicht die PDFs nicht als Artefakt. Das eindeutig erzeugte PDF-Arbeitsverzeichnis wird im finally entfernt; Browser und Context werden dort ebenfalls geschlossen. Browserprofil, Downloads und Validatorinstallation liegen im kurzlebigen Dateisystem des GitHub-Hosted-Runners und werden spätestens mit diesem Runner verworfen. Ein harter Prozess- oder Jobabbruch kann kein JavaScript-finally garantieren, veröffentlicht die Dateien aber ebenfalls nicht und hinterlässt keinen wiederverwendeten Runner.
Slice A ist erst belegt, wenn Commit, Runtime-, Chromium-, Java- und veraPDF-Version, Fixture-Hash, positives Ergebnis, negative Gegenprobe und CI-Lauf im Machbarkeitsnachweis protokolliert sind. Ein grüner Unit-Test ohne tatsächlichen Validatorlauf genügt nicht.
Der produktive Pfad bleibt bis zu einer eigenen Folgeentscheidung bei React-PDF. Issue #333 bleibt nach Slice A offen. Vor einem Rendererwechsel fehlen mindestens die Übertragung der vollständigen Free- und Premium-Reportstruktur, echte Karten-Alternativtexte, sichere Artefaktmarkierung des Seiten-Chrome, korrekte Lesereihenfolge bei realen Umbrüchen, Serverless-Kaltstart-/Speicherbenchmarks, Regression gegen den Mehrseiten-Viewervertrag und die manuelle Abnahme mit mindestens einem Screenreader.

Alternativen, die erwogen wurden

Alternative	Vorteil	Nachteil	Entscheidung
React-PDF ohne Gegenprobe weiterverwenden	Kein neuer Laufzeitbaustein	Die aktuelle API bietet keinen belegten vollständigen PDF/UA-Tag-Pfad; Metadaten allein ersetzen keine Struktur	Nicht als Konformitätsweg angenommen
Browser-PDF ohne unabhängigen Validator akzeptieren	Kurzer Prototyp	Ein vorhandener Tag-Baum kann fachlich unvollständig oder normwidrig sein	Verworfen
Produktionsrenderer sofort auf Chromium umstellen	Direkter Produktpfad	Vermischt Machbarkeit, Layoutmigration, Runtime-Risiko und Barrierefreiheitsabnahme	Verworfen
Synthetisches positives und negatives Vertragsprüfgate	Kleine, reproduzierbare Risikofläche	Belegt noch keine echte Report- oder Screenreader-Tauglichkeit	Für Slice A angenommen

Konsequenzen

Positiv

Der erste Schritt besitzt eine klare, maschinell prüfbare Erfolgs- und Gegenbeweisbedingung.
Es werden weder Produktionsreports noch personenbezogene Daten benötigt.
Ein ungeeigneter Renderer oder Validator kann verworfen werden, bevor der bestehende Reportpfad und seine Viewer-Gates berührt werden.

Negativ / Trade-offs

Chromium, Java und veraPDF erhöhen die Werkzeugs- und CI-Komplexität des Machbarkeitspfads.
Eine synthetische Fixture kann weder reale Seitenumbrüche noch Karten, Tabellenvarianten und vollständige Reportinhalte repräsentieren.
Ein bestandener PDF/UA-Validator ersetzt keine praktische Screenreader-Abnahme.

Folgeentscheidungen

Erst nach belastbarer Slice-A-Evidenz wird entschieden, ob Chromium als produktiver Renderer evaluiert oder ein anderer Tag-fähiger PDF-Pfad gesucht wird.
Ein späterer Produktionswechsel benötigt einen eigenen ADR-/Rolloutnachweis mit Rückfallpfad; er ist nicht Bestandteil dieser Entscheidung.