From 28611182ddf57e85554231c19636e3b013bffe79 Mon Sep 17 00:00:00 2001 From: tanaka takashi Date: Sat, 4 Jul 2026 18:10:51 +0900 Subject: 不要なテストコード削除 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/review-and-next-plan.md | 149 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 docs/review-and-next-plan.md (limited to 'docs/review-and-next-plan.md') diff --git a/docs/review-and-next-plan.md b/docs/review-and-next-plan.md new file mode 100644 index 0000000..94523cd --- /dev/null +++ b/docs/review-and-next-plan.md @@ -0,0 +1,149 @@ +# Critical Review of Committed Implementation + Next-Task Plan + +## 1. 現在の実装状況（コミット済: `0634f20` まで） + +| Phase | ID | 状態 | 設計通りか | +|---|---|---|---| +| P0 | 001-003 | 完了 | ✅ 計測、budget、gate が揃っており、`docs/storage-io-budget.md` と整合 | +| P1 | 001 | 完了 | ✅ JSONL export (`view=export`) は read-only、8MiB 予算内 | +| P1 | 002 | 完了 | ⚠️ **実装経路が変更された**。当初は MCP `import_messages` tool → 最終的に独立 CLI へ移行。I/O 予算は一時ファイル 1 flush を守っているが、tool 数は 7 に戻した | +| P2 | 001-002 | 完了 | ✅ delta レコード、optimistic revision、no-op 0/0 を確認 | +| P3 | 001-002 | 完了 | ✅ 6 kind/importance/summary/relations 永続化と BFS context | +| P4 | 001 | 完了 | ✅ score breakdown、filters、context preview | +| P5 | 001 | 完了 | ✅ 前後文脈、incoming/outgoing、8MiB 予算 | +| P6 | 001 | 完了 | ✅ sessions view は O(n²) 集計を索引列挙へ置換済み | +| P7 | 001 | 未着手 | — | + +## 2. 批判的レビュー：コミット済実装の設計乖離とリスク + +### 2.1 P1-002 offline import — 実装経路の変更 + +- **当初計画**: `import_messages` MCP tool 経由で JSONL を取り込む。 +- **実際**: MCP tool を削除し、独立した CLI (`--import ` / `--export `) に移行。 +- **メリット**: tool 数を 7 に維持でき、ホスト連携前のオフライン運用に適する。MCP レイヤーがファイル I/O を持たない。 +- **リスク**: + - ホストが import をトリガーしたい場合、プロセス起動が必要（専用 tool なし）。 + - `import` 実行中に同一 data-dir への MCP サーバー接続はロックで失敗する。これは設計通りだが、運用ドキュメントに明記が必要。 + - `tiny_store_import()` で所有権を deep copy に修正したが、同様の shallow-copy バグが他にないか grep で再確認が必要。 + +### 2.2 プロトコルテストの restart resume — 未解決 + +- `tests/mcp_protocol_test.py` 540-545 行目がコメントアウトされている。 +- コメントには「restart exit code 1 pending root-cause」とあるが、復元すべきコードは `restarted.send(...)` の stub のみ。 +- **実験**: 最小 restart probe (`tests/restart_probe.py`) では、write→close→restart→initialize が成功。 +- **未検証**: + - `rebuild_index` 後の snapshot 読み込み経路で restart する場合。 + - delete 後、compaction 後、大規模 search 後の restart。 + - `server.close()` 直後の lock 解放タイミング（Windows handle 継承の問題）。 +- **推定リスク**: 実際には特定の操作後（特に `rebuild_index`）にのみ restart が失敗する可能性がある。stub では再現しない。 + +### 2.3 性能・スケール — 大規模 P1 往復 benchmark 未実施 + +- `search_index_benchmark.c` があるが、P1-CP に必要な「context view / sessions view の O(n²) 退行確認」「応答 8 MiB 以下」「latency regression 10% 以内」は未測定。 +- 1万/5万件の import/export round-trip も未実施。 +- 現状の sessions view は索引列挙に置換したが、大規模データでのメモリ・レイテンシを計測していない。 + +### 2.4 P7 host consolidation — 未着手 + +- write/read/search 契約の文書化が未着手。 +- summary memory kind の利用ガイドも未作成。 +- これはリリース直前のドキュメント整備タスク。 + +--- + +## 3. 次タスクのプラン + +ユーザー提示の優先順位案を受け、以下のように立案する。 + +### P1: P1-CP 達成のための 10,000/50,000 件 P1 往復 benchmark + +**目的**: P1 checkpoint を完了させ、import/export + context/sessions view のスケールを検証する。 + +**実装**: + +1. `tests/import_export_benchmark.c` を新設（または `tests/search_index_benchmark.c` を拡張）。 +2. 以下のシナリオを測定: + - 1 万件 import → export round-trip（時間、I/O カウンタ、ファイルサイズ）。 + - 5 万件 import → export round-trip。 + - import 後の context view (`view=context`, depth 1/2) latency と応答サイズ。 + - import 後の sessions view latency と応答サイズ。 +3. assert 条件: + - 全 read view で `write_bytes == 0 && flush_calls == 0`。 + - 応答サイズ <= 8 MiB。 + - 各 view の latency が既存 baseline（1 万件 history 100 件 p50 34.2ms 程度）に対して <= 10% regression。 + +**テスト方法**: + +```powershell +cmake --build --preset windows-vs2026-release +.\build\windows-vs2026\tests\Release\tiny-convmem-import-benchmark.exe +``` + +**成果物**: +- 新規 benchmark ソース + CTest 統合。 +- `docs/implementation-status.md` の P1 benchmark 結果更新。 +- P1-CP を「完了」にするための PR。 + +### P2: protocol test restart resume 退行調査 + +**目的**: `tests/mcp_protocol_test.py` のコメントアウトを復活させ、再起動後の initialize 失敗原因を特定・修正する。 + +**手順**: + +1. `Server.close()` の実装を見直し、`stdin` close 後の `stderr` drain と `wait()` の順序を確認。 +2. `rebuild_index` 後の restart を含む最小再現スクリプトを作成（既存 `tests/restart_probe.py` を拡張）。 +3. 失敗が再現したら、stderr / exit code / `active.log` / `snapshot.bin` を収集して原因を特定: + - snapshot generation mismatch + - lock 未解放 + - `replay_log` での CRC / sequence 拒否 +4. 修正後、protocol test のコメントアウト部分を実装し、以下を検証: + - restart 後に `tools/list` が成功。 + - restart 後に直前の write/search/read が継続して動作。 + - 1000 回 search loop の前後で restart しても成功。 + +**成果物**: +- `tests/mcp_protocol_test.py` の restart resume 部分を有効化。 +- 修正が必要な場合は該当 C コード + テスト更新。 +- `docs/implementation-status.md` に restart coverage を追記。 + +### P3: P7 host consolidation（最終段階） + +**目的**: リリース可能な状態にするための契約文書化。 + +**内容**: + +1. `docs/host-consolidation.md` を新設し、以下を定義: + - `write_message` 契約: 必須/オプション、ULID 生成、エラー時の耐久性保証範囲。 + - `read_messages` 契約: history/context/sessions/export 各 view の入力スキーマ、cursor 形式、応答予算。 + - `search_messages` 契約: query、filter、limit、score breakdown、context_size。 + - `update_message` 契約: revision 楽観ロック、部分更新。 + - `delete_message` 契約: session guard、即時不可視化。 + - `rebuild_index` / `get_system_health` 契約: 同期実行、診断情報。 +2. `summary` memory kind の利用ガイド: + - summary kind の意味、relation/source との関係、ホストが summary を生成・更新する流れ。 + - importance、memory_tier、memory_kind の組み合わせ例。 +3. `README.md` の更新: + - 7 tool 概要、CLI import/export、MCP 接続方法、I/O budget 方針。 + +**成果物**: +- `docs/host-consolidation.md`。 +- `README.md` 更新。 +- P7-001 / P7-CP を完了にできる状態。 + +--- + +## 4. 推奨する実行順序 + +| 順序 | タスク | 理由 | +|---|---|---| +| 1 | **P2: restart resume 調査** | 現在のテストにコメントアウトがあり、信頼性に関わる。直近の P1 benchmark や P7 文書化より先に解消すべき。 | +| 2 | **P1: P1-CP benchmark** | P1 checkpoint を完了させ、以降の P2/P3/P4 checkpoint との整合を取る。 | +| 3 | **P3: P7 host consolidation** | すべての機能が揃った後の文書化作業。リリース直前。 | + +--- + +## 5. 即座に確認すべき懸念事項 + +1. `tiny_store_import()` の deep-copy 修正後、他に shallow-copy して caller と共有している箇所がないか grep 確認。 +2. `server.close()` 直後に同じ data-dir へ再接続できることを、`rebuild_index` 後も含めて CTest に追加。 +3. CLI import/export のロック衝突時のエラーメッセージと終了コードを整理（現在 `TINY_STORE_BUSY` は終了コード 3）。 \ No newline at end of file -- cgit v1.2.3