5.0 KB · updated 2026-07-31 · md

v0.25.1.ko.md

docs/i18n/release-notes/v0.25.1.ko.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 위에 바로 올려도 되지만, 한 가지 동작 기본값이 뒤바뀌었습니다 (업그레이드 참조).

모든 수정이 한 건의 조사에서 나왔습니다. 실제 프로젝트에서 컴파일이 0% CPU로 5시간 43분 동안 멈춰 있었는데, 그 뒤에는 4시간 6분 동안 유휴 상태였던 codex exec 자식 프로세스가 있었습니다. 이미 메모리에 32개의 COMMUNITY_SUMMARY 노드를 만들었지만 영속화되지 못했고, 그래서 graph.json은 0개로 끝났습니다. 이 실을 당기자 세 가지 더 있는 결함이 드러났습니다.

수정 사항

  • 추출 웨지 가드가 기본으로 활성화되었습니다. v0.25.0은 파일별 추출 타임아웃을 선택적으로 제공했지만, 꺼져 있었으므로 그것이 방지하는 실패가 계속 일어났습니다. _run_cli의 프로세스 그룹 killpg는 처음부터 제대로 연결되어 있었으나, communicate(timeout=None)이 예외를 던지지 않았기 때문에 실행되지 않았습니다. 이제 한계가 시도당 1800초 기본값입니다. 웨지된 자식의 프로세스 그룹을 죽이자 부모 컴파일이 몇 초 안에 재개되었습니다 — 4시간 동안 communicate()에서 대기 중이었습니다.

타이핑 실수가 안전 밸브를 조용히 해제해서는 안 되므로, 사용할 수 없는 값(10m, 600s, 음수, inf)은 이제 경고를 하고 기본값을 유지합니다. TESSERAE_EXTRACT_TIMEOUT=0이 명시적 탈출구입니다.

  • compile --retry-fallbacks가 결정론적으로 저하된 문서를 복구합니다. 추출이 실패하면 문서는 결정론적 기준선으로 제공되지만, 매니페스트 항목이 깨끗한 추출과 바이트 동일했으므로 --changed-only가 나중의 모든 컴파일에서 건너뛰었고 파일의 자체 내용이 변할 때까지 저하가 영구적이었습니다. 몇 개의 문서를 복구하려면 manifest.json을 손으로 편집해야 했으며, 대신 결정론적 채우기로 전체 코퍼스를 채우고 수 시간의 입력 작업을 파괴할 위험이 있었습니다. 이러한 항목은 이제 표시되고 필요에 따라 재시도되며, distill --retry-fallbacks를 반영합니다.
  • graph_map 카드의 live_member_count. size와 leaf_member_count는 컴파일 중간에 작성되는 hierarchy.json 사이드카에서 옵니다. graph.json이 나중에 다시 작성되면 둘이 달라지고, 카드가 수백 개의 멤버를 광고할 수 있지만 아무것도 해결되지 않습니다 — 클라이언트가 graph.json 자체를 다시 읽지 않으면 건강한 카드와 구별할 방법이 없습니다. 그래프에서 파생된 카드(kind=community|node)는 이제 현재 그래프가 수용하는 멤버 수도 보고합니다. 0은 스코프가 죽었다는 뜻이며: 내려가지 말고 건너뜁니다.

한 실제 7,133노드 그래프에서는 즉시 2개의 죽은 루트 카드와 42개의 부분 해결 카드를 드러냈으며 아무도 알아채지 못했습니다.

  • _CLIENT_FACTORY 테스트 시임이 호출자의 타임아웃을 존중합니다. build_default_json_client가 이를 떨어뜨렸고, 주입된 가짜에 30초 기본값을 제공했으므로, 타임아웃을 설정한 테스트가 조용히 아무것도 증명하지 못했습니다. 시임만 해당; 프로덕션 구성은 이미 올바렀습니다.

v0.25.0에서 업그레이드

바로 올려도 되지만, 한 가지 알아야 할 점: 추출이 기본값으로 시간이 제한됩니다 (시도당 1800초). 의도적으로 무제한 실행을 원한다면 TESSERAE_EXTRACT_TIMEOUT=0을 설정하세요.

한계는 문서당이 아니라 *시도*당입니다 — 타임아웃 시 클라이언트가 다음 CODEX_HOME / claude 설정 디렉터리로 회전하므로, 문서의 최악의 경우는 timeout × 구성된 프로필입니다.

이전 컴파일이 문서를 결정론적 추출에서 멈춰 두었다면, 다음으로 복구하세요:

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

입력 추출이 실제로 실패한 문서만 재시도되며; 깨끗한 것들은 건너뛴 상태로 유지됩니다.