Raphael Friedmann
← Das Log

Das Oracle, das du dir selbst baust

Dependabot hat fünf PRs gegen diese Site geöffnet, drei davon major. Keine Testsuite, also habe ich den Check selbst gebaut: die Site mit beiden Versionen rendern und das Ergebnis diffen.

Dependabot hat fünf Pull Requests gegen diese Site geöffnet. Drei waren Major-Bumps: node 22 → 26 in der Build-Stage, nginx 1.27 → 1.31 in der Serve-Stage und Astro 6.4.7 → 7, der Renderer, der das Markdown, das du gerade liest, in HTML verwandelt.

Dieses Repository hat keine Tests. Es hat keine CI. Und ein Merge nach main ist ein Deploy: Der Workflow verbindet sich per SSH mit der Kiste, setzt auf origin/main zurück und baut den Container neu, der rfriedmann.de ausliefert. Die Frage war also dieselbe wie beim Bump einer Abhängigkeit, die ich nicht lesen konnte, nur dass diesmal nichts von der Maschinerie existierte, die sie beantwortet hatte. Das äußerste Ende dieser Frage ist eine Wiese ganz ohne prüfbare Zahl.

5 → 1
PRs, als ein Commit gemerged (die beiden npm-PRs kollidieren am Lockfile)
3
davon Major-Versionssprünge
1483
Textblöcke zwischen altem und neuem Render verglichen
2
echte Unterschiede, einer davon ein Fix

Der Fehlerfall ist kein Absturz#

Ein Renderer, der laut kaputtgeht, ist der einfache Fall. Der Build endet mit einem Exit-Code ungleich null, das Image wird nie gebaut, der alte Container liefert weiter aus, und du erfährst es in neunzig Sekunden.

Wovor ich wirklich Angst hatte, ist die leise Variante. Eine Major-Version eines Renderers ändert, wie aus Markdown HTML wird und wie dieses HTML minifiziert wird. Der Build bleibt grün, am anderen Ende kommen fünfundvierzig Seiten heraus, und manche davon sind leicht anders: eine Überschrift, die ihre Anchor-ID verloren hat, ein Absatz, in dem zwei Wörter zusammengelaufen sind, eine doppelt escapte Entity, sodass mitten im Satz < steht. Nichts wirft einen Fehler. Es geht einfach still live.

Ein Upgrade-Guide klärt das nicht. Er sagt dir, was die Autoren für erwähnenswert hielten, und er ist für jede Site geschrieben, nicht für meine. Er kann mir nicht sagen, ob dieses Markdown mit diesen fünfundvierzig Seiten noch genauso herauskommt. Das ist kein Dokumentationsproblem, es ist ein Scope-Problem: Eine Frage zu meinem Content kann nur mein Content beantworten.

Eine statische Site ist eine reine Funktion#

Das ist es, was die Sache handhabbar macht, und es ist der ganze Trick. Ein Static Site Generator ist eine reine Funktion. Gib ihm einen Git-Tree, und du bekommst ein Verzeichnis voller Dateien. Gleiche Eingabe, gleiche Ausgabe, jedes Mal.

Ich brauche also keine Testsuite. Ich brauche dieselbe Eingabe durch beide Compiler:

# the new build, from the working tree with all five bumps applied
docker build -t rfriedmann-new .

# the old build, from an untouched checkout of main
git worktree add "$SCRATCH/old" main
docker build -t rfriedmann-old "$SCRATCH/old"

# pull dist out of both images
for v in old new; do
  cid=$(docker create "rfriedmann-$v")
  docker cp "$cid":/usr/share/nginx/html "$SCRATCH/dist-$v"
  docker rm "$cid"
done

Der erste Vergleich ist gratis und fast wertlos. Die Dateilisten sind identisch, bis auf einen Content-Hash im Namen eines Stylesheets. Gut. Dann habe ich die Dateien selbst verglichen, und alle fünfundvierzig HTML-Seiten unterschieden sich. Das ist kein Signal, das ist Rauschen mit einer Zahl dran.

Das Oracle lag falsch, bevor der Code es tat#

Also habe ich etwas Schärferes geschrieben: Tags entfernen, sichtbaren Text vergleichen. Immer noch unterschied sich jede Seite, und jede Seite unterschied sich an derselben Stelle: ganz oben, beim Favicon.

alt: "...Raphael FriedmannRF\"> Skip to content Raphael Friedmann The log..."
neu: "...Raphael FriedmannSkip to contentRaphael FriedmannThe log..."

Das RF"> steht nicht auf der Seite. Es ist ein Artefakt meines eigenen Tag-Filters. Das Favicon ist ein Inline-SVG in einer data:-URI, und Astro 6 hat dessen spitze Klammern roh ins Attribut geschrieben, also traf meine Regex <[^>]*> auf ein >, das zum Wert gehörte, und hielt das Tag für beendet. Astro 7 escapt sie als &lt;, also schluckt dieselbe Regex das ganze Tag sauber. Zwei verschiedene Renderings, für einen Browser identisch, weil ein HTML-Parser die Entity direkt zurückdekodiert, und mein Sieb meldete das auf jeder einzelnen Seite als Unterschied.

Das Erste, was ein selbstgebautes Oracle findet, ist meist ein Bug im selbstgebauten Oracle. Das ist kein Grund, es nicht zu bauen; es ist ein Grund, sich anzusehen, was es sagt, statt der Zahl zu trauen. Ein Checker, der „45 von 45 Seiten geändert“ meldet, hat dir nichts gesagt, und in diesem Moment ist die Versuchung groß, es als Whitespace-Rauschen abzutun und zu mergen. Genau dann lohnen sich noch einmal zwanzig Minuten.

Eine Frage stellen, die eine Antwort wert ist#

Die Einsicht, die den Unterschied machte: Whitespace zwischen Block-Elementen ist unsichtbar, diesen Abstand bestimmt das Layout, nicht das Markup. Whitespace innerhalb eines Satzes dagegen ist alles, worauf es ankommt. Also nur den Text in Prosa-Elementen vergleichen und jeden Unterschied klassifizieren:

// same block, both builds. If removing every space makes them equal,
// only whitespace moved. If not, actual characters changed.
const strip = s => s.replace(/\s/g, '');

if (a === b) continue;                       // identical
if (strip(a) === strip(b)) { wsOnly++; }     // whitespace only
else { real++; report(a, b); }               // this is the interesting pile

Vierzig Zeilen JavaScript, die meisten davon laufen Verzeichnisse ab. Und jetzt bedeutet die Antwort etwas:

Was jede Stufe des Siebs überstanden hat
1483 43 2 1 Blöcke verglichen überhaupt anders nicht nur Whitespace eine Verbesserung
Jeder Absatz, jedes Listenelement, jede Überschrift, Tabellenzelle und jedes Blockzitat auf 45 Seiten, gerendert von Astro 6 und Astro 7. Einundvierzig der Unterschiede waren Whitespace. Zwei änderten tatsächliche Zeichen. Einer dieser zwei machte die Site besser.

Die zwei, auf die es ankam#

Der erste echte Unterschied war ein Nicht-Ereignis, und ich will ihn trotzdem nennen, weil „das Oracle hat zweimal angeschlagen“ schlimmer klingt, als es war:

alt: "...divide the accumulator by the normaliser, O &#x3C;- O / l, to get..."
neu: "...divide the accumulator by the normaliser, O &lt;- O / l, to get..."

&#x3C; und &lt; sind zwei Schreibweisen von <. Andere Bytes, dasselbe Zeichen, dieselbe Seite.

Der zweite ist der Grund, warum ich diesen Post schreibe. Eine Überschrift im Roofline-Text steht im Markdown als ## "Compute is free", mit geraden Anführungszeichen, die der Renderer in typografische verwandelt. Das hat jede Version daraus gemacht:

alt: id="compute-is-free">”Compute is free”      U+201D … U+201D
neu: id="compute-is-free">“Compute is free”      U+201C … U+201D

Astro 6 eröffnete diese Überschrift mit einem schließenden Anführungszeichen. Astro 7 eröffnet sie mit einem öffnenden. Das ist ein typografischer Bug, der seit Juni auf dieser Site live war, auf einer Seite, die ich ein Dutzend Mal wieder gelesen habe, und ich habe ihn kein einziges Mal gesehen. Das Upgrade, das ich auf Regressionen abklopfte, hat stattdessen still etwas repariert.

Was ein grüner Build bewiesen hat

  • Astro 7 läuft auf node 26
  • 45 Seiten kamen heraus
  • nginx 1.31 liefert sie aus
  • Nichts darüber, ob es dieselben Seiten sind

Was der Diff bewiesen hat

  • 1481 von 1483 Blöcken identisch, bis auf Whitespace
  • Beide geänderten Blöcke erklärt, einzeln
  • Die Whitespace-Deltas im CSS verortet
  • Einen bestehenden Bug gefunden, nebenbei

Die einundvierzig, auf die es nicht ankam, und warum#

Astro 7 komprimiert HTML nach JSX-Whitespace-Regeln, die aggressiver sind als das, was vorher da war. Meistens trifft das Stellen zwischen Flex-Items, wo es konstruktionsbedingt unsichtbar ist. Ein Fall brauchte einen genauen Blick:

alt: <p class="post-meta"> 27 March 2026 <span class="level-badge">…
neu: <p class="post-meta">27 March 2026<span class="level-badge">…

Dieses Leerzeichen ist weg, und .post-meta ist ein einfacher Block, kein Flex-Container, also liefert nichts den Abstand automatisch. Ob das eine Regression oder ein Rundungsfehler ist, entscheidet allein das Stylesheet, und das Stylesheet sagt, der Badge ist inline-flex mit margin-left: .6rem. Datum und Badge stehen also etwa vier Pixel enger zusammen als vorher, und nichts kollidiert.

Was ich nicht verifiziert habe#

Den letzten Absatz habe ich aus dem CSS hergeleitet, nicht aus einem Screenshot. Für den visuellen Diff hätte ich ein Browser-Tool benutzt, aber es war kein Chromium installiert, und ich wollte weder einen Browser auf diesem Host installieren noch ein Zwei-Gigabyte-Image ziehen, um vier Pixel zu bestätigen.

Die ehrliche Version lautet also: Das Layout ist konstruktionsbedingt verifiziert, jeder Container, dessen Whitespace sich geändert hat, ist entweder Flex mit gap oder hat einen expliziten Margin, aber nicht nach Augenschein. Das ist eine schwächere Aussage als der Textvergleich, der vollständig und mechanisch ist. Wenn du das bei etwas machst, wo vier Pixel zählen, mach die Screenshots.

Und dann schlug der Deploy trotzdem fehl#

Gemerged, gepusht, und der Deploy wurde innerhalb von zwanzig Sekunden rot. Nicht wegen des Bumps:

ERROR: failed to resolve source metadata for docker.io/library/nginx:1.31-alpine:
unexpected status from HEAD request: 429 Too Many Requests

Docker Hub hat den Server gedrosselt. Zwei neue Base-Images in einem Build, node 26 und nginx 1.31, beide nicht lokal gecacht, und das anonyme Pull-Limit sagte nein. Ein neuer Lauf zehn Minuten später wurde grün.

Der Fehler war auf eine bemerkenswerte Art harmlos: docker compose up --build scheiterte im Build-Schritt, der laufende Container wurde also nie gestoppt. Die Site lieferte die ganze Zeit den alten, funktionierenden Build aus, und der tägliche News-Rebuild hätte es ohnehin von selbst noch einmal versucht. Aber es zeigt sauber, dass das Oracle genau eine Frage beantwortet, hat sich die Ausgabe geändert?, und dass Infrastruktur-Flakiness eine andere Frage ist, die ein anderes Gate braucht. Meins wiederholt den Pull jetzt dreimal.

Das Prinzip#

Das CUTLASS-Oracle war teuer. Es bedeutete, 4-Bit-Decode aus der Formatspezifikation neu herzuleiten und das interne Swizzle einer Vendor-Bibliothek zu invertieren, und es zahlt sich nur aus, weil es bei jedem künftigen Bump wiederverwendet wird.

Dieses hier hat zwanzig Minuten und vierzig Zeilen JavaScript gekostet, weil die Ausgabe Text ist und Text sich selbst difft. Diese Asymmetrie ist der Punkt. Die meisten Projekte, die etwas deterministisch rendern, eine Site, einen Report, ein Config-Bundle, ein Schema, haben dieses Oracle direkt vor der Nase, und fast niemand baut es, weil es keine Testdatei gibt, in die es gehört, und weil es sich anfühlt, als zähle es nicht.

Die Form ist in beiden Fällen identisch: Vergleiche gegen etwas außerhalb der Änderung. Bei CUTLASS war das fp64-Arithmetik, hergeleitet aus einer veröffentlichten Spezifikation. Hier ist es die Ausgabe des vorherigen Builds selbst. Keines von beiden fragt, ob der neue Code gut ist, das ist nicht die Frage, die ein Dependency-Bump aufwirft. Beide fragen, ob er etwas anders macht, und zwingen dich dann, dir jede Stelle anzusehen, an der er es tut.

Der letzte Schritt war, es nicht mehr von Hand zu machen. Das Repo baut jetzt jeden Pull Request zu einem echten Image, startet den Container und prüft, dass die Routen, die es ausliefern soll, mit 200 und Inhalt antworten. Patch- und Minor-Updates mergen sich selbst, sobald das grün ist; Majors warten auf einen Menschen, denn ein Major ist genau der Fall, in dem der Diff es verdient, gelesen zu werden. Der mechanische Teil ist es wert, automatisiert zu werden. Das Urteil nicht.