Tesserae v0.25.1 — compile verkeilt sich nicht mehr, und degradierte Dokumente sind wiederherstellbar

<!-- translations:start -->

English · 한국어 · 中文 · 日本語 · Русский · Español · Français

<!-- translations:end -->

Veröffentlicht 2026-07-25 · PyPI · GitHub release · pip install --upgrade tesserae==0.25.1

Ein Bugfix-Release. Keine API-Änderungen — Drop-in über v0.25.0, mit einem veränderten Verhaltensstandardwert (siehe Upgrade).

Jeder Fix kam aus einer einzigen Untersuchung. Eine Kompilierung in einem realen Projekt saß bei 0% CPU für 5 Stunden 43 Minuten, hinter einem codex exec-Child-Prozess, der 4 Stunden 6 Minuten untätig gewesen war. Es hatte bereits 32 COMMUNITY_SUMMARY-Knoten im Speicher erstellt und schaffte es nie, sie zu persistieren, sodass graph.json mit null endete. Diesem Thread nachzugehen deckte drei weitere Defekte auf.

Fehlerkorrektionen

• Der Extraction-Wedge-Guard ist jetzt standardmäßig aktiviert. v0.25.0 versendete einen per-File-Extraction-Timeout, aber Opt-in — daher blieb er ausgeschaltet und der Fehler, den er verhindert, hielt an. _run_cli's Process-Group killpg war die ganze Zeit korrekt verdrahtet; es feuerte einfach nie, weil communicate(timeout=None) niemals wirft. Das Limit beträgt jetzt standardmäßig 1800 s pro Versuch. Das Killen der verkeilt festsitzenden Child's Process Group ließ die übergeordnete Kompilierung in Sekunden fortsetzen — sie war 4 Stunden in communicate() parkiert gewesen.

Ein Tippfehler darf keine Safety-Valve stillschweigend entwaffnen, daher warnt jetzt ein unusable Wert (10m, 600s, negativ, inf) und behält den Standard bei, statt auf „kein Cutoff" zurückzufallen. TESSERAE_EXTRACT_TIMEOUT=0 ist die explizite Fluchtmöglichkeit.

• compile --retry-fallbacks stellt Dokumente wieder her, die zu deterministisch degradiert sind. Wenn eine Extraktion fehlschlägt, wird das Dokument durch die deterministische Baseline bereitgestellt — aber sein Manifest-Eintrag war byte-identisch mit einer sauberen Extraktion, daher --changed-only übersprungen bei jeder späteren Kompilierung und die Degradation war dauerhaft, bis sich der Inhalt der Datei selbst änderte. Die Wiederherstellung einer Handvoll Dokumente bedeutete das manuelle Bearbeiten von manifest.json, mit dem laufenden Risiko, stattdessen das ganze Corpus deterministisch-zu-füllen und Stunden getippter Arbeit zu zerstören. Solche Einträge werden jetzt markiert und auf Anfrage neu versucht, was distill --retry-fallbacks spiegelt.
• live_member_count auf graph_map-Karten. size und leaf_member_count kommen beide von der hierarchy.json-Sidecar, die während der Kompilierung geschrieben wird. Wenn graph.json danach umgeschrieben wird, divergieren die beiden, und eine Karte kann hunderte Mitglieder anpreisen, die sich zu nichts auflösen — ohne Möglichkeit für einen Client zu sagen, ob es sich von einer gesunden Karte unterscheidet, ohne graph.json selbst neu zu lesen. Graph-abgeleitete Karten (kind=community|node) berichten jetzt auch, wie viele Mitglieder der aktuelle Graph trägt. 0 bedeutet der Scope ist tot: Überspringen Sie ihn statt abzusteigen.

In einem realen 7,133-node-Graph deckte dies sofort 2 tote Root-Karten und 42 teilweise aufgelöste auf, die keiner bemerkt hatte.

• Der _CLIENT_FACTORY-Test-Seam respektiert das Timeout des Aufrufers. build_default_json_client ließ es fallen, übergab dem eingespritzte Fake unabhängig ein 30-s-Default — daher bewies ein Test, der ein Timeout pinnte, stillschweigend nichts. Nur-Seam; die Produktionskomposition war bereits korrekt.

Upgrade von v0.25.0

Drop-in, mit einer Sache zu beachten: Extraktion ist jetzt standardmäßig begrenzt (1800 s pro Versuch). Wenn Sie bewusst unbegrenzte Durchläufe möchten, setzen Sie TESSERAE_EXTRACT_TIMEOUT=0.

Das Limit ist pro Versuch, nicht pro Dokument — bei Timeout rotiert der Client zum nächsten CODEX_HOME / claude-Konfigurationsverzeichnis, sodass im schlimmsten Fall eines Dokuments timeout × configured profiles ist.

Wenn eine frühere Kompilierung Dokumente auf deterministischer Extraktion steckenließ, stellen Sie sie wieder her mit:

tesserae compile --changed-only --retry-fallbacks

Nur Dokumente, deren getippte Extraktion tatsächlich fehlgeschlagen ist, werden neu versucht; saubere bleiben übersprungen.