diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/architecture.md | 363 | ||||
| -rw-r--r-- | docs/implementation-status.md | 227 |
2 files changed, 582 insertions, 8 deletions
diff --git a/docs/architecture.md b/docs/architecture.md index f23f06a..edf2dfa 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,9 +1,14 @@ # Architecture -`tiny-convmem-mcp` currently proves only the MCP integration boundary. The -executable composes an mcpc stdio server and registers a single `health` tool. +設計項目ごとの実装・テスト状況は +[設計・実装・テスト状況一覧](implementation-status.md)を参照してください。 -Future conversation-memory work is split into these dependencies: +`tiny-convmem-mcp` is a single-process Windows C17 MCP server backed by a +durable append-only conversation log. The executable owns the stdio dispatch +boundary and uses mcpc's bundled mjson parser through a local compatibility +layer. + +Conversation-memory work is split into these dependencies: ```text MCP transport and tools -> domain contracts <- storage adapters @@ -11,11 +16,353 @@ MCP transport and tools -> domain contracts <- storage adapters - `src/mcp` translates MCP requests and responses. It may depend on mcpc and domain contracts, but it must not contain persistence logic. -- `src/domain` will own conversation and message concepts without depending on +- `src/domain` owns conversation and message concepts without depending on mcpc or a database. -- `src/storage` will implement domain persistence contracts using a storage - engine selected in the next design phase. +- `src/storage` implements the versioned binary log, recovery, snapshot, and + compaction using Win32 file APIs. + +## Implemented prototype contract (v1) + +The six public tools are `write_message`, `read_messages`, `search_messages`, +`delete_message`, `rebuild_index`, and `get_system_health`. The detailed +"ProtoType Architecture v0.0.1" below is retained as the original proposal; +where it conflicts with this section, the implemented contract is authoritative. + +- `write_message` creates the ULID and UTC millisecond timestamp. A PUT or DEL + succeeds only after `FlushFileBuffers` succeeds. +- Deletion is immediately invisible but remains a tombstone until synchronous + compaction. `metadata.deleted` is not part of immutable Message data. +- Metadata is limited to optional `tool_call_id`, `tags`, and `memory_tier`. + Tiers are labels only; no automatic lifecycle operation is performed. +- Search uses ASCII-case-folded Unicode codepoint 2/3-grams, verifies hash + matches against the original codepoints, and ranks exact substrings first. +- A log record contains magic, format version, type, payload length, sequence, + and payload CRC32. PUT, DEL, and generation marker records are supported. +- A valid snapshot contains immutable messages and a log generation/offset. + Startup loads it only when the active log generation matches, then replays the + tail. Otherwise startup performs a full log replay. +- An incomplete final record is truncated. Unknown versions/types, invalid + lengths, non-monotonic sequences, or CRC errors within a complete record stop + startup without silently skipping data. +- `--data-dir <path>` is mandatory and guarded by a process-exclusive lock. + +The prototype remains Windows x64/MSVC and single-process. Retention, +encryption, pagination, multiple writers, automated summarization, and secure +physical erasure are outside v1. + +# ProtoType Architecture v0.0.1 +Tiny-ConvMem-MCP: FINAL TOOL INTERFACE SPECIFICATION (v1.0) + +この定義は、システムと外部（LLMプロセス）との間の「契約書」となります。これで実装に着手できますね！ +No. Tool Name カテゴリ 機能概要 入力引数 (Arguments) 出力値 (Response) +1 write_message SET/WRITE 新しいメッセージイベントをログファイルへ追記し、インデックスを更新する。 session_id, role, content, timestamp status: Enum(OK, ERROR) +2 read_messages GET/READ 特定セッションIDの全メッセージを時系列順に読み出す。（フル履歴取得） session_id: 文字列 history: 配列（メッセージオブジェクト） +3 search_messages GET/READ クエリに基づいてログファイルから関連するメッセージを特定し、返す。（インデックス利用が前提） query, session_id (任意), limit: 整数 results: 配列（メッセージオブジェクト） +4 delete_message SET/MANAGE 特定のメッセージIDを指定してログから完全に削除し、インデックスをクリーンアップする。 message_id: 唯一ID, session_id (任意) status: Enum(OK, NOT_FOUND) +5 rebuild_index SET/MANAGE インデックスファイルを再生成し、データ整合性を回復させる。（メンテナンス） なし status: Enum(OK, ERROR) +6 get_system_health GET/READ システムの稼働状況とログファイルの健全性レポートを提供する。 なし report: JSON (ヘルスステータス) + + +データ構造設計：メッセージオブジェクト (Message Object Definition) +🎯 基本方針 + +全てのデータは**「不変（Immutable）」**であることを原則とします。一度記録されたイベントは変更せず、削除が必要な場合は新しいエントリで処理するか、専用の delete_message コマンドで対応します。 +📝 メッセージオブジェクト (Message) の構造定義案 + +メッセージを構成する要素を分解し、データ型を明確に定義します。（C++でのStructやJSONスキーマとして使用できます） + +{ + "message_id": "UUID/ULID文字列", // ★最重要。削除・参照のユニークキー + "session_id": "ユーザー固有のセッション識別子", + "timestamp": 1720843200000, // UTCミリ秒タイムスタンプ (UTC厳守) + "role": "ENUM (user | assistant | system)", // メッセージの発信元 + "content": "メッセージの本文（テキストデータ）", // 記録したい主要な情報 + "metadata": { // 追加情報格納用。拡張性を持たせるための辞書型 + "tool_call_id": "もしこのメッセージがツール呼び出しの結果ならIDを保持", + "is_system_message": true/false, // システム操作やプロンプト定義など + "checksum": "（オプション）データの完全性を保証するためのハッシュ値" + } +} + +⚙️ 補足的なデータ構造の定義 + +ログシステムをより堅牢にするために、メッセージとは別に必要な型も定義しておくと完璧です。 + + LogEntry (永続化層の最小単位): + 実際にディスクに書き込まれる最も小さいデータ単位。（上記 Message のバイナリ/JSON表現） + SearchIndexEntry (インデックス構造体): + 検索効率を最大化するための、非常に軽量なメタデータ。 + message_id: どのメッセージかを示すキー + session_id: 属するセッションID + keywords_hash: メッセージ内容から抽出されたキーワードのハッシュ値（またはリスト） + file_offset: ログファイル内での物理的な開始位置 + data_size: そのメッセージが占めるバイトサイズ + +📐 Tiny-ConMem-MCP: ストレージ制御 統合設計仕様 +1. アーキテクチャ概観 + +┌─────────────────────────────────────────────────────────────┐ +│ 外部プロセス (LLM Host) │ +└──────────────────────────┬──────────────────────────────────┘ + │ stdio (JSON-RPC) +┌──────────────────────────▼──────────────────────────────────┐ +│ L1: Protocol Layer (mcpc) │ +│ MCPメッセージの受信・ツールディスパッチ │ +└──────────────────────────┬──────────────────────────────────┘ + │ +┌──────────────────────────▼──────────────────────────────────┐ +│ L2: Memory Core (ビジネスロジック) │ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ Write Queue │ │ In-Memory │ │ Search │ │ +│ │ (保留中キュー) │ │ Index │ │ Engine │ │ +│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ +│ │ │ │ │ +└─────────┼────────────────┼────────────────┼──────────────────┘ + │ │ │ +┌─────────▼────────────────▼────────────────▼──────────────────┐ +│ L3: Persistence Layer (永続化層) │ +│ │ +│ ┌──────────┐ ┌────────────┐ ┌───────────────────┐ │ +│ │ active.log│ │snapshot.bin│ │ compaction worker │ │ +│ │(append- │ │(状態保存) │ │(ログ整理・容量削減) │ │ +│ │ only) │ └────────────┘ └───────────────────┘ │ +│ └──────────┘ │ +└─────────────────────────────────────────────────────────────┘ + +2. データ構造定義 +2.1 Message Object（永続化対象の基本単位） + +全ツールの入力・出力の中心となるデータです。一度書き込まれたら不変（Immutable）で、変更は新エントリの追記で表現します。 + +// Message (ログ1レコードの論理構造) +{ + "message_id": "ULID文字列", // 削除・参照のユニークキー + "session_id": "セッション識別子", // セッション単位のグルーピング + "timestamp": 1720843200000, // UTC ミリ秒 + "role": "user | assistant | system", + "content": "メッセージ本文", + "metadata": { + "tool_call_id": "（任意）ツール呼び出しID", + "tags": ["カレー", "設計"], //（任意）検索用タグ + "memory_tier": "short | mid | long", // 後述のメモリ階層フラグ + "deleted": false // 論理削除フラグ + } +} + +2.2 LogRecord（ディスク上の物理フォーマット） + +active.log に追記される物理レコードです。Message Object をシリアライズしたものに、検証用のメタ情報を付加します。 + +┌──────────┬──────────┬─────────────────────┬──────────┐ +│ record │ payload │ payload (serialized │ checksum │ +│ length │ type │ Message Object) │ (CRC32) │ +│ (4 byte) │ (1 byte) │ (可変長) │ (4 byte) │ +└──────────┴──────────┴─────────────────────┴──────────┘ + +payload_type: + 0x01 = PUT (メッセージの書き込み) + 0x02 = DEL (メッセージの論理削除) + 0x03 = SNAPSHOT_MARKER (snapshot境界マーカー) + +2.3 In-Memory Index（メモリ上のインデックス） + +メモリ上に保持する高速検索用の目次です。これが SearchIndexEntry の実体で、search_messages / read_messages の高速化を担います。 + +struct IndexEntry { + uint64_t file_id; // ログファイル識別子 (1 = active.log 等) + uint64_t offset; // レコードの開始バイト位置 + uint32_t length; // レコード長 + int64_t timestamp; // メッセージのタイムスタンプ + uint8_t type; // PUT / DEL + // セッションID・メッセージID は + // ハッシュテーブルの Key として使用 +}; + +// メモリ上のデータ構造（ハッシュテーブル + リスト） +HashTable<message_id, IndexEntry*> // message_id → 位置情報 +HashTable<session_id, List<message_id>> // session_id → 所属メッセージ一覧 +HashTable<keyword_hash, List<message_id>> // 検索用キーワード逆引き + +3. 書き込みパイプライン（write_message / delete_message） + +┌─────────────┐ +│ MCP Tool 呼出 │ write_message / delete_message +└──────┬──────┘ + │ + ▼ +┌─────────────────────┐ +│ Step 1: メモリ更新 │ In-Memory Index に即座に反映 +│ │ (PUT → 追加, DEL → フラグ更新) +└──────┬──────────────┘ + │ + ▼ +┌─────────────────────┐ +│ Step 2: キュー追加 │ Write Queue に LogRecord を積む +└──────┬──────────────┘ + │ + ▼ +┌─────────────────────┐ +│ Step 3: バッチ書き込み │ flush_interval_ms (1000ms) または +│ │ max_pending_records (128件) に +│ │ 達したら write() で一括追記 +└──────┬──────────────┘ + │ + ▼ +┌─────────────────────┐ +│ Step 4: 定期 fsync │ fsync_interval_ms (5000ms) ごとに +│ │ fsync() でディスクに確実に落とす +└─────────────────────┘ + +設計パラメータ: + +#define FLUSH_INTERVAL_MS 1000 // キュー→ファイルの書き出し間隔 +#define FSYNC_INTERVAL_MS 5000 // fsync() の実行間隔 +#define MAX_PENDING_RECORDS 128 // キューの最大保留件数 + +4. 読み込みパイプライン（read_messages / search_messages） + +┌─────────────┐ +│ MCP Tool 呼出 │ read_messages / search_messages +└──────┬──────┘ + │ + ▼ +┌─────────────────────┐ +│ Step 1: インデックス │ In-Memory Index から該当レコードの +│ 検索 │ (file_id, offset, length) を取得 +└──────┬──────────────┘ + │ + ▼ +┌─────────────────────┐ +│ Step 2: pread() │ ログファイルの該当オフセットのみ +│ 部分読み出し │ pread(fd, buf, length, offset) +│ │ ※ログ全体は読み込まない +└──────┬──────────────┘ + │ + ▼ +┌─────────────────────┐ +│ Step 3: デシリアライズ│ LogRecord → Message Object に復元 +│ │ deleted フラグを確認し、 +│ │ 削除済みなら除外 +└──────┬──────────────┘ + │ + ▼ +┌─────────────────────┐ +│ Step 4: レスポンス │ JSON配列として MCP 経由で返却 +│ 返却 │ +└─────────────────────┘ + +5. 起動時復旧シーケンス + +プロセス起動 + │ + ▼ +┌──────────────────┐ +│ Step 1: │ +│ snapshot.bin 読込 │ 最後のスナップショットから +│ │ In-Memory Index を復元 +└──────┬───────────┘ + │ + ▼ +┌──────────────────┐ +│ Step 2: │ snapshot 作成時点以降の +│ ログ再生 │ active.log を先頭から順に読み、 +│ │ PUT / DEL レコードを適用 +│ │ (index を更新していく) +└──────┬───────────┘ + │ + ▼ +┌──────────────────┐ +│ Step 3: │ インデックスが完全に再構築された状態で +│ サービス開始 │ stdio 受付を開始 +└──────────────────┘ + +6. Snapshot 処理（rebuild_index の一部としても動作） + +現在有効なデータ (deleted=false) を列挙 + │ + ▼ +snapshot.tmp にシリアライズして書き出し + │ + ▼ +fsync(snapshot.tmp) + │ + ▼ +rename(snapshot.tmp → snapshot.bin) + │ ← アトミック操作。クラッシュしても古い snapshot.bin が残る + ▼ +完了 + +役割: 起動時のログ再生量を減らし、起動時間を短縮する。 +7. Compaction 処理 + +トリガー: ログファイルサイズが閾値を超えた または rebuild_index 呼出 + │ + ▼ +現在有効なデータ (deleted=false) のみを列挙 + │ + ▼ +new_active.log に有効レコードのみを書き出し + │ + ▼ +fsync(new_active.log) + │ + ▼ +rename(new_active.log → active.log) + │ ← アトミック操作 + ▼ +古いログファイルを削除 + │ + ▼ +新しい snapshot.bin も生成 (compaction 後の状態を保存) + │ + ▼ +In-Memory Index の file_id / offset を更新 + +役割: ログ肥大化を防ぎ、ディスク使用量を削減する。 +8. メモリ階層とデータライフサイクル + +Message Object の metadata.memory_tier を用いて、LLM会話の寿命を管理します。 + +┌─────────────┬──────────────────────────┬──────────────────┐ +│ 階層 │ 内容 │ 保存場所 │ +├─────────────┼──────────────────────────┼──────────────────┤ +│ short (短期) │ 直近の会話メッセージ │ メモリ + active.log│ +│ │ │ (即座に参照可能) │ +├─────────────┼──────────────────────────┼──────────────────┤ +│ mid (中期) │ セッションの要約・抽象化 │ active.log + │ +│ │ │ snapshot │ +├─────────────┼──────────────────────────┼──────────────────┤ +│ long (長期) │ 重要なユーザー設定・ │ snapshot 優先で │ +│ │ 継続的記憶 (key-value) │ 永続化 │ +├─────────────┼──────────────────────────┼──────────────────┤ +│ discard │ 一時的な雑談・重複情報・ │ compaction 時に │ +│ (破棄対象) │ 古い全文ログ │ 削除対象 │ +└─────────────┴──────────────────────────┴──────────────────┘ + +ライフサイクル: -No conversation schema, retention policy, search behavior, or storage engine is -implied by the current scaffold. +write_message (memory_tier=short) + │ + │ セッション終了・要約トリガー + ▼ +要約生成 → write_message (memory_tier=mid) + │ 元の short メッセージを delete_message で論理削除 + ▼ +compaction 時に short の deleted レコードが物理削除される + │ + │ 長期的に重要と判断されたもの + ▼ +write_message (memory_tier=long) + │ snapshot 優先で永続化 + ▼ +discard レコードは compaction 時に消える +9. MCP Tool とストレージ層の対応表（最終版） +Tool L2処理 L3処理 関連コンポーネント +write_message Index更新 + Queue追加 flush時に active.log へ追記 Write Queue, In-Memory Index +read_messages session_id で Index 検索 pread() で該当レコード読み出し In-Memory Index, active.log +search_messages キーワードハッシュで Index 検索 pread() で該当レコード読み出し In-Memory Index, active.log +delete_message Index の type を DEL に更新 DEL レコードを active.log へ追記 Write Queue, In-Memory Index +rebuild_index 全有効データを再列挙 snapshot 作成 + compaction 実行 Snapshot, Compaction Worker +get_system_health 各種カウンタ収集 ログファイルサイズ・整合性チェック 全コンポーネント diff --git a/docs/implementation-status.md b/docs/implementation-status.md new file mode 100644 index 0000000..9812ac9 --- /dev/null +++ b/docs/implementation-status.md @@ -0,0 +1,227 @@ +# 設計・実装・テスト状況一覧 + +最終更新日: 2026-06-29 + +この文書は、[architecture.md](architecture.md) の初期案、確定したプロトタイプ実装計画、 +現在のソースコード、CTestを突き合わせた追跡表です。設計案に存在しても確定したv1の +対象外となった項目は、単純な未実装と区別しています。 + +## ステータスの読み方 + +| 表記 | 実装状況 | テスト作成状況 | テスト実施状況 | +|---|---|---|---| +| ✅ | 実装済 | 作成済 | 実施済・成功 | +| 🟡 | 部分実装、または設計との差異あり | 一部のみ作成済 | 一部条件のみ実施済 | +| ⬜ | 未実装 | 未作成 | 未実施 | +| ➖ | v1対象外、または採用しない設計 | 該当なし | 該当なし | + +「テスト作成済」はテストコードが存在すること、「実施済」は記載した構成で実際に成功した +ことを意味します。テスト済みでも、電源断などテスト環境で再現していない保証までは含みません。 + +## 現在の検証結果 + +| 構成 | ビルド | CTest | 実施日 | 結果 | +|---|---|---|---|---| +| Windows x64 / MSVC / Debug | ✅ 実施済 | ✅ 実施済 | 2026-06-29 | 5/5成功 | +| Windows x64 / MSVC / Release | ✅ 実施済 | ✅ 実施済 | 2026-06-29 | 5/5成功 | +| Windows以外 | ⬜ 未実施 | ⬜ 未実施 | ― | v1対象外 | + +実行コマンド: + +```powershell +cmake --build --preset windows-vs2026-debug +ctest --preset windows-vs2026-debug +cmake --build --preset windows-vs2026-release +ctest --preset windows-vs2026-release +``` + +## アーキテクチャとプロセス + +| 設計項目 | 実装 | 実装根拠・現在の挙動 | テスト作成 | テスト実施 | 補足・残作業 | +|---|---|---|---|---|---| +| C17単一プロセスMCPサーバ | ✅ 実装済 | `src/app/main.c` と `src/mcp/server.c` | ✅ 作成済 | ✅ Debug/Release | 単一stdioクライアント前提 | +| MCP、ドメイン、ストレージの分離 | 🟡 部分実装 | ディレクトリと型は分離済み | ⬜ 未作成 | ⬜ 未実施 | MCP層がStore APIを直接呼ぶ。専用Memory Core/Application Serviceは未実装 | +| Domainのmcpc/Win32非依存 | ✅ 実装済 | `message.*`, `search.*` は標準Cのみ | ✅ 作成済 | ✅ Debug/Release | 依存方向の自動検査は未作成 | +| Repository function table | ⬜ 未実装 | MCP層へ `tiny_store_t` を直接渡す | ⬜ 未作成 | ⬜ 未実施 | ストレージ差替え契約は未抽象化 | +| `--data-dir <path>` 必須化 | ✅ 実装済 | 相対パスを絶対化し、不足時は終了コード2 | ✅ 作成済 | ✅ Debug/Release | `--help` の自動テストは未作成 | +| data directory自動作成 | ✅ 実装済 | `CreateDirectoryW` | 🟡 間接テスト | ✅ Debug/Release | 深い親ディレクトリの再帰作成は未実装 | +| data directory排他ロック | ✅ 実装済 | `store.lock` を共有なしで保持 | ✅ 作成済 | ✅ Debug/Release | 複数writerはv1対象外 | +| stdoutをJSON-RPC専用、stderrを診断専用 | ✅ 実装済 | プロトコル応答と起動エラーを分離 | 🟡 間接テスト | ✅ Debug/Release | stderr汚染の専用テストは未作成 | +| Windows x64/MSVC対応 | ✅ 実装済 | Win32 file API、BCrypt、CMake preset | ✅ 作成済 | ✅ Debug/Release | Windows SDK差異のCIマトリクスは未作成 | + +## MCP互換境界と外部契約 + +| 設計項目 | 実装 | 実装根拠・現在の挙動 | テスト作成 | テスト実施 | 補足・残作業 | +|---|---|---|---|---|---| +| `initialize` / `tools/list` / `tools/call` | ✅ 実装済 | MCP 2024-11-05の必要フローをローカルdispatcherで処理 | ✅ 作成済 | ✅ Debug/Release | MCP全メソッド対応ではない | +| `notifications/initialized` | ✅ 実装済 | notificationとして応答せず継続 | 🟡 smokeに入力あり | ✅ Debug/Release | 単独の応答なし検証は未作成 | +| raw JSON arguments | ✅ 実装済 | mcpc同梱mjsonでobjectを直接解析 | ✅ 作成済 | ✅ Debug/Release | malformed JSON/JSON-RPCの網羅試験は未作成 | +| required/optional、object、array schema | ✅ 実装済 | `tools/list` に正しいschemaを返す | ✅ 作成済 | ✅ Debug/Release | schema全文のgolden testではなく主要断片を検証 | +| 64-bit timestamp/counter | ✅ 実装済 | JSON builderとバイナリ形式で64-bitを使用 | 🟡 間接テスト | ✅ Debug/Release | 最大/最小境界値は未作成 | +| callbackへのアプリ状態受渡し | ✅ 実装済 | server/handlerへStoreとSearch Indexを明示的に渡す | 🟡 間接テスト | ✅ Debug/Release | 汎用callback APIではない | +| upstream `server.c`/serializerのoverlay | ➖ 設計変更 | submoduleを変更せず、プロジェクト側dispatcherを実装 | ✅ 統合テスト | ✅ Debug/Release | 固定版mcpcのmjsonのみ利用する方針へ変更 | +| TextContent内JSON成功応答 | ✅ 実装済 | 全ツール結果をescape済みJSON文字列で返す | ✅ 作成済 | ✅ Debug/Release | `structuredContent` は未対応 | +| MCP application error (`isError=true`) | ✅ 実装済 | 検証/I/O/内部エラーで設定 | ✅ 検証エラー作成済 | ✅ Debug/Release | 全エラーコードのMCP経由試験は未作成 | +| 安定エラーコード | 🟡 部分実装 | `VALIDATION_ERROR`, `IO_ERROR`, `CORRUPT_STORE`, `BUSY`, `INTERNAL_ERROR` を定義・使用 | 🟡 一部作成済 | 🟡 一部実施済 | `BUSY`/`CORRUPT_STORE` は起動前に発生し、MCP応答にはならない | +| 不正JSON-RPCへの標準error object | ⬜ 未実装 | 一部の不正requestは応答せず無視する | ⬜ 未作成 | ⬜ 未実施 | parse error、invalid request、method not foundの標準応答が必要 | + +## MCPツール別状況 + +| Tool / 要件 | 実装 | テスト作成 | テスト実施 | 現在の確認範囲・不足 | +|---|---|---|---|---| +| `write_message` 基本書込み | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | MCPから書込み、応答Message、再起動後読込みを確認 | +| サーバ生成ULID | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | Crockford形式と同一プロセス内の単調順を確認 | +| サーバ生成UTCミリ秒 | ✅ 実装済 | 🟡 間接テスト | ✅ Debug/Release | 実時刻との許容差・時計巻戻り専用テストは未作成 | +| role検証 | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | 有効/無効値をDomainで確認 | +| metadata `tool_call_id` | ✅ 実装済 | ⬜ 未作成 | ⬜ 未実施 | round-tripと上限境界が未確認 | +| metadata `tags` | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | 日本語tag検索をDomainで確認。32件/128 byte境界は未確認 | +| metadata `memory_tier` | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | enumとMCP入力を確認。自動ライフサイクルは対象外 | +| `read_messages` 全履歴取得 | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | 1件/0件を確認 | +| timestamp、message_id安定順序 | ✅ 実装済 | ⬜ 未作成 | ⬜ 未実施 | 複数件・同一timestampの順序試験が必要 | +| `search_messages` content検索 | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | ASCII大小文字とMCP検索を確認 | +| 日本語・tag検索 | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | Domainで確認 | +| `session_id` 絞込み | ✅ 実装済 | ⬜ 未作成 | ⬜ 未実施 | 複数sessionを使う統合試験が必要 | +| `limit` 既定20・最大100 | ✅ 実装済 | 🟡 一部作成済 | ✅ Debug/Release | limit=10は使用。既定値、0、100、101、非整数境界は未確認 | +| 検索順位とtie-break | ✅ 実装済 | 🟡 基本scoreのみ | 🟡 一部実施済 | 複数候補で exact match、timestamp、ID順を検証していない | +| `delete_message` 即時不可視化 | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | lifecycle testでdelete後のreadから消えることを確認 | +| `delete_message` session照合 | ✅ 実装済 | 🟡 正しいsessionのみ | 🟡 一部実施済 | session不一致時のNOT_FOUND未確認 | +| `delete_message` NOT_FOUND | ✅ 実装済 | ⬜ 未作成 | ⬜ 未実施 | 存在しないID、二重削除の統合試験が必要 | +| `rebuild_index` 同期compaction | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | MCP呼出しと削除本文の物理除去を確認 | +| rebuild結果カウンタ | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | `records_removed=1` を確認 | +| `get_system_health` 基本カウンタ | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | log/snapshot size、件数、sequenceを出力 | +| health `OK` | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | smokeで確認 | +| health `DEGRADED` | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | 不正snapshot/末尾復旧後に確認 | +| health `ERROR` | ⬜ 未実装 | ⬜ 未作成 | ⬜ 未実施 | 致命的Store破損ではサーバが起動しないためtoolを呼べない | +| 復旧履歴 | 🟡 部分実装 | 🟡 一部作成済 | ✅ Debug/Release | `recovered_tail` と直近 `last_error` のみ。履歴配列は未実装 | + +## Messageと入力制約 + +| 設計項目 | 実装 | テスト作成 | テスト実施 | 補足・残作業 | +|---|---|---|---|---| +| immutable Messageモデル | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | 更新APIを持たず、deep copyで所有権を分離 | +| `message_id` 26文字ULID | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | 不正alphabet/先頭値を確認 | +| `session_id` 最大256 bytes | ✅ 実装済 | ⬜ 未作成 | ⬜ 未実施 | 0、256、257 bytes境界が未確認 | +| `content` 最大1 MiB | ✅ 実装済 | ⬜ 未作成 | ⬜ 未実施 | 1 MiB前後、長大JSON lineの統合試験が未作成 | +| `tool_call_id` 最大256 bytes | ✅ 実装済 | ⬜ 未作成 | ⬜ 未実施 | 境界試験なし | +| tags最大32件、各128 bytes | ✅ 実装済 | ⬜ 未作成 | ⬜ 未実施 | 境界試験なし | +| query最大4096 bytes | ✅ 実装済 | ⬜ 未作成 | ⬜ 未実施 | 境界試験なし | +| UTF-8妥当性 | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | 基本的なvalid/overlong invalidを確認。全不正系列は未網羅 | +| `metadata.deleted` の排除 | ✅ 実装済 | 🟡 schemaで間接確認 | ✅ Debug/Release | 削除状態はStore entry/DELのみ | +| checksumを論理metadataから排除 | ✅ 実装済 | ➖ 該当なし | ➖ 該当なし | CRC32を物理recordで保持 | + +## 検索索引 + +| 設計項目 | 実装 | テスト作成 | テスト実施 | 補足・残作業 | +|---|---|---|---|---| +| Unicode codepoint 2/3-gram逆引き索引 | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | contentとtagsを索引化 | +| ASCII case folding | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | `CURRY`/`curry` を確認 | +| 日本語検索 | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | `設計` tagを確認 | +| hash衝突時の実codepoint照合 | ✅ 実装済 | 🟡 実装経路のみ | 🟡 間接実施 | 意図的なhash collision fixtureは未作成 | +| 1 codepoint query fallback | ✅ 実装済 | ⬜ 未作成 | ⬜ 未実施 | 全候補からscore計算する経路が未確認 | +| 起動時索引構築 | ✅ 実装済 | 🟡 再起動で間接確認 | ✅ Debug/Release | 大量データ時の時間/メモリ試験なし | +| write時索引更新 | ✅ 実装済 | ✅ MCP検索で確認 | ✅ Debug/Release | index allocation失敗のfault injectionなし | +| compaction後索引再構築 | ✅ 実装済 | 🟡 rebuild後health/readのみ | 🟡 一部実施済 | rebuild直後のsearch専用試験が必要 | +| `message_id -> entry` hash map | ⬜ 未実装 | ⬜ 未作成 | ⬜ 未実施 | 現在は配列の線形探索 | +| `session_id -> message list` index | ⬜ 未実装 | ⬜ 未作成 | ⬜ 未実施 | 現在は全entry走査 | +| Unicode normalization/full case folding | ➖ v1対象外 | ➖ 該当なし | ➖ 該当なし | NFKC、非ASCII大文字小文字変換は未対応 | + +## バイナリログと耐久性 + +| 設計項目 | 実装 | テスト作成 | テスト実施 | 補足・残作業 | +|---|---|---|---|---| +| `active.log` append-only | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | compaction時のみ置換 | +| little-endian versioned header | ✅ 実装済 | 🟡 round-tripのみ | ✅ Debug/Release | byte単位golden fixtureは未作成 | +| magic/version/type/length/sequence/CRC32 | ✅ 実装済 | 🟡 CRC破損あり | ✅ Debug/Release | 各header fieldの単独異常試験は未作成 | +| PUT payload round-trip | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | write→close→reopenで確認 | +| DEL payload round-trip | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | delete→再起動→compactionで確認 | +| generation marker | ✅ 実装済 | 🟡 lifecycleで間接確認 | ✅ Debug/Release | marker単独のbinary testは未作成 | +| 64-bit file offset API | ✅ 実装済 | ⬜ 未作成 | ⬜ 未実施 | 4 GiB超のsparse file試験は未作成 | +| record長上限とoverflow防止 | ✅ 実装済 | ⬜ 未作成 | ⬜ 未実施 | 巨大length/整数overflow fixtureが必要 | +| PUT/DEL後の `FlushFileBuffers` | ✅ 実装済 | 🟡 API成功経路のみ | ✅ Debug/Release | flush失敗fault injection、実電源断は未実施 | +| 成功前のメモリ確保 | ✅ 実装済 | ⬜ 未作成 | ⬜ 未実施 | allocation failure注入は未作成 | +| OS書込み後・flush前クラッシュ | 🟡 コード上復旧可能 | ⬜ 未作成 | ⬜ 未実施 | プロセス強制終了/電源断試験が必要 | +| record offset/lengthだけを保持するIndexEntry | ⬜ 未実装 | ⬜ 未作成 | ⬜ 未実施 | 現在はMessage全体をメモリ保持 | +| offset指定部分読出し | ⬜ 未実装 | ⬜ 未作成 | ⬜ 未実施 | 現在のread/searchはメモリ上Messageを使用 | + +## 起動時復旧とsnapshot + +| 設計項目 | 実装 | テスト作成 | テスト実施 | 補足・残作業 | +|---|---|---|---|---| +| 空Store起動 | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | smokeで確認 | +| ログ全再生 | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | storage/lifecycleで再起動確認 | +| snapshot生成 | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | compaction時にlive Messageを保存 | +| generation/CRC/log offset検証 | ✅ 実装済 | ✅ 不正snapshot作成済 | ✅ Debug/Release | generation不一致そのものの専用fixtureは未作成 | +| 有効snapshotから状態復元 | ✅ 実装済 | 🟡 snapshot生成のみ | 🟡 一部実施済 | 有効snapshotを使った再起動を明示判定するテストは未作成 | +| snapshot offset以降のtail再生 | ✅ 実装済 | ⬜ 未作成 | ⬜ 未実施 | snapshot後にPUT/DELして再起動するテストが必要 | +| 不正snapshotを無視して全ログ再生 | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | lifecycleで不正内容へ置換して確認 | +| EOF末尾の不完全record切詰め | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | `TC` を追記して確認 | +| 完全recordのCRC不一致で起動失敗 | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | 最終complete recordを破損して確認 | +| ログ途中recordの破損 | ✅ 実装済 | ⬜ 未作成 | ⬜ 未実施 | 複数recordの中間を破損する専用試験が必要 | +| 未知version/type拒否 | ✅ 実装済 | ⬜ 未作成 | ⬜ 未実施 | binary fixture未作成 | +| 非単調sequence拒否 | ✅ 実装済 | ⬜ 未作成 | ⬜ 未実施 | binary fixture未作成 | +| snapshot作成中クラッシュ | 🟡 原子的置換で設計 | ⬜ 未作成 | ⬜ 未実施 | `snapshot.tmp` 各段階の強制終了試験が必要 | + +## Compactionと削除保証 + +| 設計項目 | 実装 | テスト作成 | テスト実施 | 補足・残作業 | +|---|---|---|---|---| +| DEL後の即時不可視化 | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | readから除外されることを確認 | +| live PUTだけの新ログ生成 | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | 削除本文のbyte列が消えることを確認 | +| 一時ログのflush | ✅ 実装済 | 🟡 成功経路のみ | ✅ Debug/Release | Flush失敗注入は未作成 | +| `MoveFileExW` によるログ置換 | ✅ 実装済 | 🟡 成功経路のみ | ✅ Debug/Release | 置換失敗/直前クラッシュ試験は未作成 | +| ログ置換後のsnapshot置換 | ✅ 実装済 | 🟡 成功経路のみ | ✅ Debug/Release | 2ファイル間クラッシュ窓の強制終了試験は未作成 | +| compaction失敗時の旧Store維持 | 🟡 部分確認 | ✅ temp作成失敗を作成 | ✅ Debug/Release | replacement段階の失敗は未確認 | +| `rebuild_index` 手動トリガー | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | 同期実行中はstdio処理をブロック | +| ログサイズ閾値による自動compaction | ⬜ 未実装 | ⬜ 未作成 | ⬜ 未実施 | v1実装では手動rebuildのみ | +| background compaction worker | ➖ 採用しない | ➖ 該当なし | ➖ 該当なし | 単一スレッド同期方式へ確定変更 | +| SSD/バックアップからの安全消去 | ➖ v1対象外 | ➖ 該当なし | ➖ 該当なし | APIの物理削除保証には含めない | + +## メモリ階層とライフサイクル + +| 設計項目 | 実装 | テスト作成 | テスト実施 | 補足・残作業 | +|---|---|---|---|---| +| `short/mid/long/discard` 属性保存 | ✅ 実装済 | ✅ 作成済 | ✅ Debug/Release | tierは検索/削除ポリシーに影響しない | +| session終了トリガー | ➖ v1対象外 | ➖ 該当なし | ➖ 該当なし | 未実装 | +| LLM要約生成 | ➖ v1対象外 | ➖ 該当なし | ➖ 該当なし | 外部LLM連携なし | +| short→mid→long自動昇格 | ➖ v1対象外 | ➖ 該当なし | ➖ 該当なし | 未実装 | +| discard自動破棄 | ➖ v1対象外 | ➖ 該当なし | ➖ 該当なし | discardも明示deleteまで保持 | +| retention/TTL | ➖ v1対象外 | ➖ 該当なし | ➖ 該当なし | 未実装 | + +## テスト資産一覧 + +| CTest名 | 種別 | テスト作成 | Debug | Release | 主な対象 | +|---|---|---|---|---|---| +| `tiny-convmem-mcp.smoke` | MCP E2E | ✅ 作成済 | ✅ 成功 | ✅ 成功 | initialize、6 tool schema、write/read/search/rebuild/health、検証エラー | +| `tiny-convmem-mcp.domain` | Unit | ✅ 作成済 | ✅ 成功 | ✅ 成功 | role/tier、UTF-8、ULID、deep copy、ASCII/日本語n-gram | +| `tiny-convmem-mcp.storage` | Unit/Integration | ✅ 作成済 | ✅ 成功 | ✅ 成功 | lock、write/reopen、ULID順、temp失敗、CRC破損拒否 | +| `tiny-convmem-mcp.lifecycle` | MCP/Storage E2E | ✅ 作成済 | ✅ 成功 | ✅ 成功 | delete、不可視化、compaction、本文除去、不正snapshot、末尾復旧 | +| `tiny-convmem-mcp.requires-data-dir` | Process | ✅ 作成済 | ✅ 成功 | ✅ 成功 | data-dir必須、非0終了 | + +## 未実装・テスト不足の優先バックログ + +| 優先度 | 項目 | 現在の状態 | 完了条件 | +|---|---|---|---| +| P1 | 専用Memory Core/Application Service | ⬜ 未実装 | MCPがStoreへ直接依存せず、domain repository contract経由になる | +| P1 | message/session索引 | ⬜ 未実装 | ID削除とsession読込みが線形走査でなくなる | +| P1 | 有効snapshot＋tail replay試験 | ⬜ 未作成・未実施 | snapshot後のPUT/DELだけがtailから適用されることを確認 | +| P1 | binary corruption matrix | 🟡 一部のみ | unknown version/type、巨大length、非単調sequence、中間CRC破損を自動試験 | +| P1 | 入力サイズ境界 | ⬜ 未作成・未実施 | 全上限の境界内成功/境界外拒否をMCP経由で確認 | +| P2 | read/searchの安定順序 | 🟡 実装済・試験不足 | 複数session/同時刻/同score/limitを網羅 | +| P2 | compaction crash/failure matrix | 🟡 一部のみ | flush、rename前後、log/snapshot間の各停止点から復旧 | +| P2 | 4 GiB超offset | ⬜ 未作成・未実施 | sparse logで64-bit seek/replayを確認 | +| P2 | JSON-RPC標準エラー | ⬜ 未実装 | malformed/invalid/method-not-foundへ規格準拠errorを返す | +| P3 | ログサイズ閾値compaction | ⬜ 未実装 | 設定閾値超過時に安全に同期compactionする | +| P3 | 性能・メモリ・長時間試験 | ⬜ 未作成・未実施 | 大量message、巨大session、繰返しrebuildの基準値を定義・測定 | + +## 明示的なv1対象外 + +| 項目 | 状態 | 理由 | +|---|---|---| +| 非同期write queue、定期flush/fsync | ➖ 非採用 | `OK` 後の消失を避ける同期耐久性を優先 | +| background worker | ➖ 非採用 | 単一stdio・単一スレッドの初期実装に限定 | +| 自動要約、tier昇格、discard削除 | ➖ 対象外 | LLMライフサイクルは6 tool完成後の別機能 | +| encryption at rest | ➖ 対象外 | 鍵管理を含む別設計が必要 | +| pagination | ➖ 対象外 | `read_messages` は現状フル履歴契約 | +| 複数writer/network server | ➖ 対象外 | data directoryを単一プロセスが排他所有 | +| SSD/バックアップの安全消去 | ➖ 対象外 | filesystem compactionだけでは保証不能 | +| Linux/macOS | ➖ 対象外 | Win32 durability/atomic replacementを採用 | |