registry: refresh seven stale doc claims in the core engine (#565)

[t0k0sh1]

Summary

doc/comment のみの修正。#532 の監査が起票した #565(registry コアエンジンのコメント/doc陳腐化 12件)を現行 HEAD で再検証し、現存する7件を修正した。既に #561〜#564 のフォローアップ(特に #562 の PR #572/#573)で解消済みだった5件は再検証結果を issue コメントに記録済み。加えて、再検証中に issue 本文に無い同種の陳腐化を1件発見し(enforce_budget の doc)、同じ性質の修正なので合わせて含めた。

コード変更なし。挙動は一切変わらない。

修正した7件+1件

• concurrency.rs: dispatch_chunks_concurrently の呼び出し元所在(src/extract.rs → Run::extract_chunks_concurrently in src/extract/run.rs; "below" → src/registry/embeddings.rs)
• registry.rs: PutSchemaError::ReservedAlias の EMPTY_SOURCE 参照先(export.rs:315 → export::render の予約 source id 拒否)
• registry.rs: Entry::lock_unless_deleted の不変条件を「全post-lookupロックが通る」から、実際の4パターン(inline Slot match / tombstone を立てる当事者 / 呼び出し元が排他所有 / boot 時)へ書き直し。兄弟の read_unless_deleted の存在にも言及
• lifecycle.rs: AppState::create の "up to eight unlinks" を、固定本数+件数無制限のマーカー unlink という実態に合わせて数を持たない表現に
• concurrency.rs: SemaphorePermit/Semaphore の doc — permit はサーキットブレーカの拒否チェックより前に取得され、ブレーカ open の拒否も slot を短時間消費することを明記
• registry.rs: CueCache::CAP の "~12 MB" が3072次元前提であることを明記し、次元は provider レスポンス依存であることを追記
• concurrency.rs: ディスパッチャ doc に、f 内 panic が捕捉されないこと(thread::scope が join 後に unwind を再送)、および Err(String) チャネルが deadline失効/slotタイムアウト/プロバイダエラーを区別できないことを追記
• engine.rs: enforce_budget の doc に、except 単独で予算超過し evict 不能な飽和状態では resident estimate が budget に収まらないことを追記(issue 本文には無いが、再検証中に発見した同種の陳腐化)

再検証の結果、今回は対象外にした5件(#565 コメント参照)

• Add a dedicated citation endpoint returning located passage excerpts #5, Expose the citation endpoint as an MCP tool #6: 「on-disk family」からの schema サイドカー漏れ — registry: キャッシュ予算/クォータ/ディスク会計のずれ 11 件 #562 PR registry: fix disk-usage accounting gaps and add missing flush/search signals (#562 items 3,4,5,7,9) #573(51d5da6)で解消済み
• Spike: determine whether ingested documents carry detectable section markers #7: truncate_wal の既定値依存 — registry: キャッシュ予算/クォータ/ディスク会計のずれ 11 件 #562(c1ecb1c)で解消済み
• Stop discarding chunk/paragraph provenance in extract::merge() #8: 「64操作で drift を抑える」— registry: fix budget-sweep/quota/WAL accounting drift (#562 items 1,2,6,8,10,11) #572 のレビュー対応(036eaf2)で解消済み
• Add an optional locator field to Attribution (graph format migration) #10: api/contexts.rs の mid-rename — 誤指摘(コメント自身が既に明示的に除外している)

Test plan

• cargo fmt
• cargo clippy --all-targets --all-features — 警告ゼロ
• RUSTDOCFLAGS="-D rustdoc::broken_intra_doc_links" cargo doc --no-deps --document-private-items — 新規に追加した intra-doc リンク(Entry::read_unless_deleted, crate::export::render)は解決を確認。本 diff と無関係な既存の壊れたリンク(context/write.rs, deadline.rs 等)が main にも存在することは git stash で確認済み
• cargo test — フルスイート通過(500 passed、doc-only なので挙動不変の確認)
• Pre-PR mutation gate(cargo mutants --in-diff)— doc-only 差分のため対象ミュータント 0件("No mutants to filter")

Closes #565

Summary by CodeRabbit

• ドキュメント
  • 削除競合時のロック動作と、予約ソースID拒否に関する説明を更新しました。
  • 並列処理におけるパニック、失敗、タイムアウト、同時実行制限の扱いを明確化しました。
  • 予算超過時の退避処理と飽和状態の記録について補足しました。
  • アプリケーション作成時のファイル処理対象数に関する説明を更新しました。
  • キャッシュ容量の見積もり基準をベクトル次元数に基づく表現へ変更しました。

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: e9c3c4ae-dff2-4e96-843f-025daa2d4f10

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

registry コアエンジンのドキュメントコメントを、ロック、並行処理、予算処理、キャッシュ容量、ディスク処理の現在の実装に合わせて更新しました。実装コードと公開宣言は変更していません。

Changes

registry コアドキュメント更新

Layer / File(s)	Summary
ロック・エラー・キャッシュの説明更新 src/registry.rs	lock_unless_deleted の例外的なロック経路、PutSchemaError::ReservedAlias の予約ソースID拒否、CueCache の次元依存の容量見積もりを記載しました。
並行処理の動作説明更新 src/registry/concurrency.rs	パニックの再送出、部分結果を返さない動作、失敗結果の区別、入力順、セマフォ許可の保持範囲を記載しました。
予算処理とディスク処理の説明更新 src/registry/engine.rs, src/registry/lifecycle.rs	予算超過時の飽和記録と後続の退避条件を追加しました。create の可変回数のディスク処理を記載しました。

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• t0k0sh1/taguru#572: enforce_budget の同じ動作に関するドキュメント更新です。
• t0k0sh1/taguru#574: CueCache の容量とベクトル幅に関する変更で、同じ説明を更新しています。
• t0k0sh1/taguru#576: src/registry/lifecycle.rs の動作に関するテストを追加しています。

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	タイトルはregistryコアエンジンの陳腐化したdocを更新する主要変更を具体的に示し、簡潔です。
Linked Issues check	✅ Passed	変更は#565の対象である参照、ロック、unlink、セマフォ、キャッシュ、dispatcher、予算処理のdoc更新をカバーしています。
Out of Scope Changes check	✅ Passed	変更は#565に関連するドキュメント更新に限定され、コード動作を変更する無関係な変更はありません。
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 565-registry-doc-staleness

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/registry/engine.rs`:
- Around line 594-599: Update the documentation comment for enforce_budget to
remove the claim that except itself may fail to save; describe instead that
targeted dirty candidates can remain resident when their saves fail, while
preserving the existing saturation and later-call behavior.

In `@src/registry/lifecycle.rs`:
- Around line 36-41: Update the lifecycle documentation around
sweep_stale_stem_files to describe unlink counts only for paths that function
actually removes, excluding meta_path because save_files overwrites it. Keep the
references to stale rename/import marker cleanup and save_files fsyncs accurate.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 1b4237b2-4ee4-4c79-aa3a-7f65026595e5

📥 Commits

Reviewing files that changed from the base of the PR and between 61c420a and 1b472ae.

📒 Files selected for processing (4)

• src/registry.rs
• src/registry/concurrency.rs
• src/registry/engine.rs
• src/registry/lifecycle.rs