LandNutzen.Anmelden

ADR-0064: Apple-PDFKit-/Quartz-Regression für den PDF/UA-Shadow

  • Status: angenommen; implementiert, Preview-verifiziert und ausgeliefert
  • Datum: 28. August 2026
  • Issue: #333 bleibt offen
  • Vorgänger: ADR-0063

Kontext

Slice E bindet den vollständigen synthetischen Vier-Tier-Vertrag an den tatsächlichen PostgreSQL-Store-Roundtrip. veraPDF prüft die PDF/UA-1-Struktur, und Poppler prüft Text, Links sowie die gerasterte Ausgabe. Damit fehlt noch ein reproduzierbarer Lauf durch einen zweiten, auf macOS tatsächlich verwendeten PDF-Stack.

Ein bloßes Öffnen der Apple-Vorschau-App wäre nicht automatisierbar genug, um Seitenzahl, Textschicht, Linkannotationen und Rastergrenzen bei jeder Releaseprüfung fail-closed zu binden. Die manuelle Bedienung von Apple Vorschau und VoiceOver bleibt dennoch ein eigenständiges Produktgate.

Entscheidung

  1. npm run qa:pdf:ua-shadow führt auf macOS zusätzlich einen nativen Apple-PDFKit-/Quartz-Lauf aus. Auf Nicht-macOS-Systemen meldet das Gate ausdrücklich, dass dieser lokale macOS-Releasecheck nicht verfügbar ist; die bestehenden Linux-CI-Prüfungen mit veraPDF und Poppler bleiben unverändert verpflichtend.
  2. Der Swift-Prüfer lädt die bereits im selben Lauf erzeugten Dateien für free, standard, premium und planer mit PDFDocument. Pro Tier sind exakt acht Seiten, zwei Linkannotationen und acht seitenspezifische Textmarker erforderlich. Jede Seite muss eine nicht triviale Textschicht mit mindestens 100 Zeichen besitzen.
  3. Jede der 32 Seiten wird über PDFPage.draw(with:to:) in einen 1.190 × 1.684 Pixel großen 8-Bit-Graustufen-Kontext von Quartz gerendert. Die bestehenden Rastergrenzen prüfen weiße Ränder, mittlere Helligkeit, Schwarzflächen und sichtbaren Body-Ink. Fehlende, leere, abgeschnittene oder dunkel gefüllte Seiten schließen den Lauf fail-closed.
  4. Der Swift-Code erhält ausschließlich Pfade zu den kurzlebigen, repository-fixierten PDF/UA-Kanaris. Er liest keine Datenbank, Session, Produktionsdatei, Adresse, Koordinate oder Providerantwort und führt keinen Netzwerkzugriff aus. Das temporäre Verzeichnis wird im vorhandenen finally-Pfad entfernt.
  5. Slice F ändert weder Renderer noch Route, Header oder öffentlichen Produktpfad. Der Shadow bleibt slice-e-1, Preview-only und synthetisch; der öffentliche Report bleibt bei React-PDF und ist nicht als PDF/UA getaggt.
  6. Der automatisierte PDFKit-/Quartz-Lauf schließt nur den Apple-Rendererteil der Viewerregression. Die manuelle Apple-Vorschau, Chrome/PDFium- und VoiceOver-Abnahme, echte Karteninhalte, kontrollierter Produktrollout und PDF/UA-Live-Readback bleiben offen. Issue #333 bleibt deshalb offen.

Nachgelagerte manuelle Abnahme

Die im Entscheidungszeitpunkt offene Apple-Vorschau- und VoiceOver-Stichprobe wurde am 4. September 2026 mit der commitgebundenen synthetischen Premium-Preview-Datei abgeschlossen. Apple Vorschau 11.0 zeigte acht von acht Seiten vollständig; mit aktivem VoiceOver waren die acht Seiten per Tastatur erreichbar. Der native Accessibility-Baum exponierte 19 Überschriften, sieben Tabellen, sechs Listen, drei beschriebene Abbildungen und zwei benannte Links. VoiceOver wurde danach wieder ausgeschaltet. Der Slice-F-Nachweis bindet Datei-Hash, Systemstand und die beobachtete Semantik.

Chrome/PDFium, echte Karteninhalte, kontrollierter Produktrollout und PDF/UA-Live-Readback eines echten Nutzerreports bleiben eigene offene Gates; Issue #333 bleibt deshalb offen.

Konsequenzen

  • Der Vier-Tier-Shadow wird bei der lokalen macOS-Releaseprüfung durch einen zweiten PDF-Stack geladen, semantisch ausgelesen und vollständig gerastert.
  • Linux-CI bleibt reproduzierbar und benötigt weder Apple-Frameworks noch einen macOS-Runner; ein Release darf den ausdrücklich gemeldeten lokalen macOS-Check aber nicht als in CI bewiesen darstellen.
  • Ein grüner automatisierter Quartz-Lauf ersetzt keine assistive manuelle Bedienprüfung und öffnet keinen Produktionspfad.

Referenzen