Tesserae v0.25.1 — la compilación ya no se atasca, y los docs degradados son recuperables

<!-- translations:start -->

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

<!-- translations:end -->

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

Un lanzamiento de correcciones de errores. Sin cambios en la API — funciona directamente sobre v0.25.0, con un comportamiento por defecto invertido (ver Actualización).

Todas las correcciones aquí provinieron de una sola investigación. Una compilación en un proyecto real se quedó a 0% de CPU durante 5 horas 43 minutos, atrapada detrás de un hijo \codex exec\ que había estado inactivo durante 4 horas 6 minutos. Ya había creado 32 nodos \COMMUNITY_SUMMARY\ en memoria y nunca llegó a persistirlos, así que \graph.json\ terminó con cero. Tirar de ese hilo sacó a la luz tres defectos más.

Correcciones

• El protector de cuña de extracción está armado por defecto. v0.25.0 envió un timeout de extracción por archivo, pero opcional — así que quedó desactivado y el fallo que evitaba seguía ocurriendo. El \killpg\ del grupo de procesos en \_run_cli\ estaba correctamente cableado todo el tiempo; simplemente nunca se disparó, porque \communicate(timeout=None)\ nunca lanza. El límite ahora es 1800 s por intento por defecto. Matar el grupo de procesos del hijo atascado dejó que la compilación padre reanudara en segundos — había estado estacionada en \communicate()\ durante cuatro horas.

Un error tipográfico no debe desactivar silenciosamente una válvula de seguridad, así que un valor inutilizable (\10m\, \600s\, negativo, \inf\) ahora advierte y mantiene el predeterminado en lugar de caer a "sin corte". \TESSERAE_EXTRACT_TIMEOUT=0\ es la escotilla de escape explícita.

• \compile --retry-fallbacks\ recupera docs que se degradaron a deterministas. Cuando una extracción falla, el doc se sirve por la línea de base determinista — pero su entrada manifest era byte-idéntica a una extracción limpia, así que \--changed-only\ la saltó en cada compilación posterior y la degradación fue permanente hasta que el contenido del archivo cambió. Recuperar un puñado de docs significaba editar a mano \manifest.json\, con el riesgo de en cambio llenar determinísticamente todo el corpus y destruir horas de trabajo tipado. Tales entradas ahora se marcan y se reintentan bajo demanda, reflejando \distill --retry-fallbacks\.
• \live_member_count\ en tarjetas \graph_map\. \size\ y \leaf_member_count\ ambos vienen del sidecar \hierarchy.json\, que se escribe a mitad de compilación. Cuando \graph.json\ se reescribe después los dos divergen, y una tarjeta puede anunciar cientos de miembros que se resuelven a nada — sin manera para un cliente de distinguirlo de una tarjeta sana sin releer \graph.json\ mismo. Las tarjetas derivadas del grafo (\kind=community|node\) ahora también reportan cuántos miembros el grafo actual lleva. \0\ significa que el ámbito está muerto: sáltalo en lugar de descender.

En un grafo real de 7,133 nodos esto inmediatamente expuso 2 tarjetas raíz muertas y 42 parcialmente resueltas que nadie había notado.

• El seam de prueba \_CLIENT_FACTORY\ honra el timeout del llamador. \build_default_json_client\ lo soltó, entregando al falso inyectado un predeterminado de 30 s sin importar — así que una prueba fijando un timeout silenciosamente no probó nada. Solo seam; la composición de producción ya era correcta.

Actualización desde v0.25.0

Funciona directamente, con una cosa a tener en cuenta: la extracción ahora está acotada por defecto (1800 s por intento). Si deliberadamente quieres ejecuciones sin acote, establece \TESSERAE_EXTRACT_TIMEOUT=0\.

El acote es por intento, no por documento — en timeout el cliente rota al siguiente \CODEX_HOME\ / directorio de configuración de claude, así que el peor caso de un documento es \timeout × perfiles configurados\.

Si una compilación pasada dejó documentos atrapados en extracción determinista, recupéralos con:

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

Solo los documentos cuya extracción tipada realmente falló se reintentan; los limpios se mantienen saltados.