Tesserae v0.25.1 — la compilation n'est plus bloquée, et les docs dégradés sont récupérables

<!-- translations:start -->

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

<!-- translations:end -->

Publié 2026-07-25 · PyPI · GitHub release · pip install --upgrade tesserae==0.25.1

Un correctif. Aucun changement API — compatible avec v0.25.0, avec un seul défaut de comportement inversé (voir Mise à niveau).

Chaque correctif ici s'est dégagé d'une seule enquête. Une compilation sur un projet réel s'est retrouvée à 0% CPU pendant 5 heures 43 minutes, bloquée par un enfant \codex exec\ resté inactif pendant 4 heures 6 minutes. Il avait déjà créé 32 nœuds \COMMUNITY_SUMMARY\ en mémoire et n'a jamais vécu assez longtemps pour les persister, donc \graph.json\ s'est terminé avec zéro. Tirer sur ce fil a fait surface trois défauts supplémentaires.

Correctifs

• Le garde de blocage de l'extraction est armé par défaut. v0.25.0 a livré un délai d'expiration par fichier lors de l'extraction, mais opt-in — donc il est resté désactivé et l'échec qu'il prévient a continué de se produire. Le \killpg\ du groupe de processus de \_run_cli\ était correctement câblé tout du long ; il n'a simplement jamais déclenché, parce que \communicate(timeout=None)\ ne lève jamais. La limite est maintenant 1800 s par tentative par défaut. Tuer le groupe de processus de l'enfant bloqué a laissé la compilation parente reprendre en quelques secondes — elle était stationnée dans \communicate()\ pendant quatre heures.

Une faute de frappe ne doit pas désarmer silencieusement une soupape de sécurité, donc une valeur inutilisable (\10m\, \600s\, négatif, \inf\) avertit maintenant et garde la défaut au lieu de se replier sur « pas de cutoff ». \TESSERAE_EXTRACT_TIMEOUT=0\ est l'échappatoire explicite.

• \compile --retry-fallbacks\ récupère les docs qui se sont dégradés à déterministe. Quand une extraction échoue, le doc est servi par la baseline déterministe — mais son entrée manifest était byte-identique à une extraction propre, donc \--changed-only\ l'a sauté à chaque compilation ultérieure et la dégradation était permanente jusqu'à ce que le contenu du fichier lui-même change. Récupérer une poignée de docs signifiait éditer manuellement \manifest.json\, avec le risque actuel d'au contraire remplir déterministiquement l'ensemble du corpus et détruire des heures de travail typé. De telles entrées sont maintenant marquées et re-tentées à la demande, mirroir de \distill --retry-fallbacks\.
• \live_member_count\ sur les cartes \graph_map\. \size\ et \leaf_member_count\ viennent tous deux du sidecar \hierarchy.json\, qui est écrit mid-compilation. Quand \graph.json\ est réécrit après, les deux divergent, et une carte peut faire la publicité de centaines de membres qui résolvent en rien — sans aucun moyen pour un client de le distinguer d'une carte saine sans re-lire \graph.json\ lui-même. Les cartes dérivées du graphe (\kind=community|node\) rapportent maintenant aussi combien de membres le graphe courant porte. \0\ signifie que le scope est mort : passez-le au lieu de descendre.

Sur un vrai graphe de 7 133 nœuds, ceci a immédiatement fait surface 2 cartes racine mortes et 42 partiellement résolues que personne n'avait remarquées.

• Le seam de test \_CLIENT_FACTORY\ honore le délai d'expiration de l'appelant. \build_default_json_client\ l'a abandonné, remettant au faux injecté un défaut 30 s peu importe — donc un test pinant un délai d'expiration a silencieusement prouvé rien. Seam-only ; la composition de production était déjà correcte.

Mise à niveau depuis v0.25.0

Compatible, avec une chose à savoir : l'extraction est maintenant bornée par défaut (1800 s par tentative). Si vous voulez délibérément des exécutions non bornées, définissez \TESSERAE_EXTRACT_TIMEOUT=0\.

La limite est par tentative, pas par document — lors du délai d'expiration le client bascule vers le profil \CODEX_HOME\ / répertoire de configuration claude suivant, donc le pire cas d'un document est \timeout × profils configurés\.

Si une compilation passée a laissé des documents bloqués sur l'extraction déterministe, récupérez-les avec :

\\\sh tesserae compile --changed-only --retry-fallbacks \\\

Seuls les documents dont l'extraction typée a réellement échoué sont re-tentés ; les propres restent ignorés.