5.3 KB · updated 2026-07-31 · md

v0.25.1.ja.md

docs/i18n/release-notes/v0.25.1.ja.md

Tesserae v0.25.1 — コンパイルがもうハングしなくなり、劣化したドキュメントが復旧可能に

<!-- translations:start -->

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

<!-- translations:end -->

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

バグ修正リリースです。API 変更なし — v0.25.0 の上に直接導入可能ですが、 1 つの動作デフォルトが反転しています（*アップグレード*を参照）。

ここのすべての修正は 1 つの調査から出てきました。実際のプロジェクトでコンパイルが 0% CPU で 5 時間 43 分間スタックし、その背後に4 時間 6 分間 アイドル状態だった codex exec 子プロセスがありました。すでにメモリ内に 32 個の COMMUNITY_SUMMARY ノードを作成していたのに永続化されず、 だから graph.json はゼロで終わりました。この糸を引くと、さらに 3 つの欠陥が浮かびました。

修正

  • 抽出ウェッジガードがデフォルトで有効になりました。 v0.25.0 はファイル毎の 抽出タイムアウトを提供していましたが、オプトインでした — つまり無効のままで、 それが防ぐはずだった故障は起きつづけました。_run_cli のプロセスグループ killpg はずっと正しく配線されていました；ただ communicate(timeout=None) が例外を投げないため、発動しませんでした。デフォルトの限界は今や 試行ごと 1800 秒です。ウェッジした子のプロセスグループを kill することで 親のコンパイルが*数秒以内に*再開しました — それは 4 時間 communicate() で停滞していました。

タイプミスが安全弁を静かに無効化してはいけないので、使用不可能な値 （10m、600s、負の数、inf）は今や警告を出してデフォルトを保ちます。 TESSERAE_EXTRACT_TIMEOUT=0 が明示的なエスケープハッチです。

  • compile --retry-fallbacks は確定的に劣化したドキュメントを復旧します。 抽出が失敗すると、ドキュメントは確定的ベースラインで提供されます — ただしそのマニフェストエントリがクリーン抽出とバイト同一だったため、 --changed-only は後続のすべてのコンパイルで skip し、 そのファイル自身のコンテンツが変わるまで劣化は永続的でした。 少数ドキュメントを復旧するなら manifest.json を手編集し、 かつ全語料を確定的に埋めて数時間の手作業を破壊するリスクを負いました。 こういった項目は今やマークされ、必要に応じて再試行され、 distill --retry-fallbacks をミラーします。
  • graph_map カード上の live_member_count。 size と leaf_member_count の両方はコンパイル中盤に書かれた hierarchy.json サイドカーから来ます。 後で graph.json が書き直されると両者が乖離し、カードが数百のメンバーを宣伝できても 何も解決されません — クライアントが graph.json 自身を再読みしないかぎり ヘルシーなカードと区別できません。グラフ由来カード（kind=community|node）は 今や*現在*グラフが持つメンバー数も報告します。0 はスコープが dead： descend するな skip せよ。

ある実際の 7,133 ノードグラフでこれは即座に 2 つのデッド root カードと 42 の部分解決済みカードを浮かび上がらせ、誰も気づいていませんでした。

  • _CLIENT_FACTORY テストシームが呼び出し元のタイムアウトを尊重します。 build_default_json_client はそれを落とし、注入されたフェイク対象に 30 秒デフォルトを渡しました — つまりタイムアウトをピンした test は silent で何も証明しませんでした。シームのみ； 本番構成はすでに正しかったのです。

v0.25.0 からのアップグレード

直接適用可能、ただし 1 つ知っておくこと：抽出はデフォルトで境界付き （試行ごと 1800 秒）。意図的に無限実行を望むなら、 TESSERAE_EXTRACT_TIMEOUT=0 を設定してください。

限界は*試行*ごと、ドキュメント毎ではない — タイムアウト時、クライアントが 次の CODEX_HOME / claude 設定 dir に rotate するため、ドキュメントの 最悪ケースは timeout × 設定済みプロファイル数 です。

過去のコンパイルがドキュメントを確定的抽出に stuck したままなら、以下で復旧：

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

入力抽出が実際に失敗したドキュメントのみ再試行；clean なものは skip のまま。