diff options
Diffstat (limited to 'docs/review-and-next-plan.md')
| -rw-r--r-- | docs/review-and-next-plan.md | 149 |
1 files changed, 0 insertions, 149 deletions
diff --git a/docs/review-and-next-plan.md b/docs/review-and-next-plan.md deleted file mode 100644 index 94523cd..0000000 --- a/docs/review-and-next-plan.md +++ /dev/null @@ -1,149 +0,0 @@ -# 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 <file>` / `--export <file>`) に移行。 -- **メリット**: 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 |