Mini Data Engine Runtime Copilot

インタラクティブデータシステムラボ

MCP ネイティブのランタイムコパイロットレイヤーを備えた、実行可能な Python および Rust のデータシステム内部実装です。

このリポジトリは、次の 2 つを組み合わせています。

• PostgreSQL に似た内部実装と Databricks に似た内部実装を学べる、ローカルファーストのエンジニアリングラボ
• 診断、説明可能性、リグレッションチェック、運用メモリを提供する Runtime Copilot MCP サーフェス

主な機能

• ストレージとプランナーの内部実装：ヒープテーブル、B ツリーインデックス、選択性、プランの選択。
• 永続化とリプレイ：WAL／チェックポイント形式のフローと、決定論的な状態遷移。
• ワークフローと書き込みパスのモデリング：イベントファーストアーキテクチャ、冪等性、リトライのセマンティクス。
• 説明可能なランタイム運用：トレース付き実行、失敗の要約、リグレッション判定、ベースライン比較。
• MCP アクセス：場当たり的なシェルスクリプトに代わる、マシンから利用できる運用インターフェイス。

対象ユーザー

• データウェアハウスやクエリエンジンの内部実装を学ぶデータエンジニア。
• ストレージと実行の基礎を教えるプラットフォームエンジニアやインフラエンジニア。
• オンボーディングラボ、ワークショップ、デモ環境を構築するチーム。

クイックスタート

要件：

• Python 3.10 以降（Python 3.14 でテスト済み）

セットアップ：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "psycopg[binary]"

エンドツーエンドのフローを実行：

cargo run --bin e2e_flow

コアデモを実行：

.venv/bin/python mini_pg_like.py
.venv/bin/python mini_databricks_clone.py
cargo run --bin mini_pg_like
cargo run --bin mini_databricks_clone

このリポジトリの内容

• mini_pg_like.py：ヒープテーブル、B ツリーインデックス、プランナーの出力を備えた、PostgreSQL に似たトイエンジン。
• mini_databricks_clone.py：バージョン管理、パーティション、DAG、イベントを備えた、Databricks に似たトイプラットフォーム。
• src/bin/mini_pg_like.rs：Rust による PostgreSQL に似たデモ。
• src/bin/mini_databricks_clone.rs：Rust による Databricks に似たデモ。
• src/lib.rs、src/common.rs、src/pg.rs：共有 Rust コアモジュール。
• mcp_engine_server.py：診断およびリグレッションワークフロー用の MCP ランタイムアダプター。

このプロジェクトの目的

内部実装に関するコンテンツの多くは、図の説明で終わります。このプロジェクトは実行と確認が可能です。

• 同じシステムの概念を実装した Python 版と Rust 版を比較できます。
• 具体的なイベントと状態遷移を使って、書き込みパスの動作をトレースできます。
• MCP を通じて、説明可能なリグレッションチェックを実行できます。
• ランタイム運用を、AI クライアントが検出可能なコントロールサーフェスに変換できます。

MCP アダプターレイヤー

このリポジトリには、ラボの操作をラップする最小限の MCP サーバーも含まれています。

• mcp_engine_server.py
• Cursor の設定：.cursor/mcp.json

このリリースで利用できる MCP ツールの一覧（合計 47 個）：

エンジンの状態とランタイム：

• init_engine
• insert_row
• upsert_row
• create_index
• explain_customer
• reindex_project
• run_e2e_flow

説明可能性とデモ：

• explain_run
• demo_explain_run
• demo_explain_run_failure
• demo_explain_semantic_failure
• demo_explain_idempotency_conflict
• demo_explain_concurrency_failure_storm
• explain_regression_suite

トレースと検索：

• record_tool_trace
• similar_incidents
• refresh_trace_path
• refresh_docs_path
• memory_upsert
• memory_search

SLO と ROI：

• health_check
• benchmark_calls
• scenario_load_test
• capture_roi_baseline
• report_drift_bug
• decision_gate

スキーマ評価（MCP 経由で判定とレポートを提供。外部の Postgres は不要）：

• schema_load_tool
• schema_explain_tool
• schema_evaluate_tool
• schema_evaluate_full_tool

プロジェクトの契約と回帰テスト：

• project_manifest
• project_capabilities
• project_tool_catalog
• project_get_defaults
• project_run_regression
• project_capture_baseline
• project_compare_baseline

汎用プロジェクトの状態：

• project_list_entities
• project_get_entity
• project_upsert_entity
• project_delete_entity
• project_append_event
• project_ingest_trace
• project_explain_run
• project_export_state

汎用ヒューリスティクス：

• project_list_heuristics
• project_run_heuristic

機械可読な情報の取得には、次のツールを優先してください：

• project_tool_catalog
• project_get_defaults

project_run_heuristic で利用できるヒューリスティックプロファイル：

• pain_structure
• naive_bias
• price_distribution
• liquidity_signals
• price_liquidity_matrix
• cross_category
• sale_format
• speed_signals
• trust_signals

Cursor MCP の自動検出が有効になっている場合は、Cursor を再起動して mini-data-engine に接続してください。 デフォルトの MCP ランタイムデータパスは tests/artifacts/mcp/* 配下です。

Cursor の承認設定（繰り返し表示されるプロンプトを減らす）

Cursor が MCP やコマンドの実行ごとに承認を求め続ける場合は、次の設定を一度行ってください。

1. Cursor のユーザー設定でワークスペースの信頼を有効にします。

"security.workspace.trust.enabled": true

2. Cursor で Settings -> Agents -> Auto-Run を開き、次のように設定します。

   • Auto-run mode：Run in Sandbox
   • MCP Allowlist：よく使う mini-data-engine のツールを追加します
   • Command Allowlist：よく使う安全なコマンドを追加します

3. このリポジトリを同じ信頼済みワークスペースとして開いたままにし、ウィンドウを一度再読み込みします。

注：

• MCP サーバーの承認とツールごとの許可リストの動作は、Cursor のセキュリティ設定によって制御されます。
• 一部の Cursor バージョンでは、許可リストの動作がベストエフォートとなり、例外的なケースで確認が求められることがあります。

MCP 経由で新しい説明可能性のユースケースを最も手早く確認する方法：

demo_explain_run

このツールを一度呼び出すだけで、トレース付きの実行が作成され、1 つの run_id の下に各ステップのイベントが記録されます。また、次の内容を含む説明が返されます。

• 順序付きタイムライン
• ツールの実行経路
• 合計経過時間
• 問題が発生した場合の失敗の概要

その後、次のコマンドで同じ説明を直接再生できます。

explain_run(run_id="...")

回帰テストスイートの説明

回帰チェックを MCP 経由で実行し、個別のテスト出力ではなく、説明可能な実行サマリーとして受け取りたい場合は、explain_regression_suite を使用します。

このスイートは、現在の検証対象を MCP レイヤー経由で実行し、run_id のトレースを付加します。また、各チェックの説明出力を返すため、実行時のインシデントで使われるのと同じ仕組みで回帰を調査できます。

現在、次の項目を実行します。

• python -m unittest discover による Python のユニットテスト
• cargo test による Rust のテスト（現在の engine_cli の統合テストを含む）
• health_check
• benchmark_calls
• scenario_load_test
• 説明可能性の制御デモ

説明可能性のデモには、意図的に成功と失敗の両方の制御を含めています。

• demo_explain_run は expected_success
• demo_explain_run_failure は expected_failure
• demo_explain_semantic_failure は expected_failure
• demo_explain_idempotency_conflict は expected_failure
• demo_explain_concurrency_failure_storm は expected_failure

つまり、このスイートは正常系が引き続き成功するかどうかを確認するだけではありません。説明レイヤーが既知の失敗クラスを正しく分類し、要約できることも確認します。

現在の回帰対象は、次の項目をカバーしています。

• トレース付きの正常系実行
• 実行時およびパスの失敗
• セマンティックデータの検証失敗
• 冪等性の競合による失敗
• 同時実行および失敗集中の制御シナリオ
• サンプリングされたベンチマークとシナリオの SLO 回帰

回帰テスト一式を実行する、最速の MCP 呼び出し：

explain_regression_suite

次の情報をまとめて確認したい場合は、最上位の MCP 回帰エントリーポイントとして使用してください。

• 合格したチェック
• 制御として想定されていた失敗
• トレースされた各実行の説明サマリー
• レイテンシーや動作に回帰が発生したことを示す早期シグナル

MCP レイヤーはアクセスインターフェースであり、プロダクトの中核となる考え方ではありません。リポジトリの中核は、実行可能なラボそのものです。

プロダクトに関するメモ：

• PRODUCT_NOTE_RUNTIME_EXPLAINABILITY.md ランタイムの説明可能性に関するユースケース、必要なシグナル、explain_run の MVP を説明する短いメモです。
• PRODUCT_NOTE_RUNTIME_COPILOT.md MCP ネイティブな運用ブレインとしての Runtime Copilot のプロダクトコンセプトです。
• EXPLAIN_REGRESSION_SUITE_FEASIBILITY.md 説明優先の回帰テストスイートについて、このリポジトリで検証した内容と、現在も対象範囲が限定されている点を説明する短い記事です。

Codex での使用：

• スキルパッケージ：codex/skills/runtime-copilot/SKILL.md
• 自動化の例：codex/automations
• ガイド：docs/use-in-codex.md

永続エンジン CLI を実行する（プロダクト化の手順）：

# Initialize storage
cargo run --bin engine_cli -- init ./tests/artifacts/engine/data orders

# Insert and upsert (WAL append)
cargo run --bin engine_cli -- insert ./tests/artifacts/engine/data orders 1 4242 50
cargo run --bin engine_cli -- upsert ./tests/artifacts/engine/data orders 1 4242 55

# Build index and explain
cargo run --bin engine_cli -- index ./tests/artifacts/engine/data orders
cargo run --bin engine_cli -- explain ./tests/artifacts/engine/data orders 4242

# Write snapshot and truncate WAL
cargo run --bin engine_cli -- checkpoint ./tests/artifacts/engine/data orders

# Transaction simulation: begin/commit/rollback semantics,
# per-table write lock, snapshot read, and conflict detection
cargo run --bin engine_cli -- tx-demo ./tests/artifacts/engine/data orders

# Crash/restart recovery for transaction journals
cargo run --bin engine_cli -- tx-recovery-list ./tests/artifacts/engine/data orders
cargo run --bin engine_cli -- tx-recovery-commit ./tests/artifacts/engine/data orders <tx_id>
cargo run --bin engine_cli -- tx-recovery-rollback ./tests/artifacts/engine/data orders <tx_id>

表示される内容

• mini_pg_like.py：選択性の高い述語では Index Scan に切り替わり、選択性の低い述語では Seq Scan のままです。
• mini_databricks_clone.py：レイヤーごとのデモ出力、ワークフローの DAG 順序とメトリクス、単一の書き込みパスからの正規イベント数が表示されます。
• mini_pg_like（Rust）：共通のコアモジュールを使用し、同じプランナー動作をします。
• mini_databricks_clone（Rust）：共通の Rust ライブラリーコードを使用し、同じレイヤー構成のデモを実行します。
• engine_cli（Rust）：永続スナップショットと WAL のリプレイフローを、シンプルな運用コマンドで実行します。
• engine_cli tx-demo：明示的なトランザクションスコープ、スナップショット読み取り、テーブル単位の書き込みロック、同時アップサートの競合検出を確認できます。
• engine_cli tx-recovery-*：トランザクションごとのジャーナルファイルにより、ステージングされたトランザクション操作がプロセス再起動後も保持され、明示的にコミットまたはロールバックできます。
• e2e_flow：1 つのコマンドで、書き込みパス、チェックポイント、bronze->silver 変換、プランナーの実行計画表示、永続化データに対する DuckDB SQL 検証を実行します。

技術設計の基盤

TECHNICAL_DESIGN_GENERIC.md には、コードを支えるアーキテクチャ上の原則がまとめられています。

• レイヤーを横断する推論（Idea -> API -> Runtime -> Storage -> Perf）
• 決定論的な状態遷移
• イベントファースト設計
• アダプターの契約
• DAG によるオーケストレーション
• 測定可能な go/no-go 基準

これは独立した製品の主張ではありません。ラボ全体で使用されているレビューと実装の指針です。

Docker パッケージ

ローカルビルドを使用する（開発に推奨）

このリポジトリからイメージをビルドすると、GitHub のイメージではなくローカルのコード（スキーマツールを含む）を MCP で使用できます。

./scripts/docker-build-local.sh

これにより mini-data-engine:local がビルドされます。この MCP で別のプロジェクト（例：threads）を操作するには、Cursor MCP がローカルイメージを使用するように設定し、そのプロジェクトをワークスペースとしてマウントします。

• .cursor/mcp.docker.local.json をプロジェクトの .cursor/mcp.json にコピーします（または、mcpServers エントリーを Cursor のユーザー設定にマージします）。
• 操作するプロジェクト（例：threads）を開きます。${workspaceFolder} はそのプロジェクトを指します。コンテナーには WORKSPACE_ROOT=/workspace が設定され、プロジェクトが /workspace にマウントされるため、たとえば schema_path="schema.sql" はそのプロジェクト内のファイルを参照します。

ローカル設定の例（mini-data-engine:local を使用し、現在のワークスペースを /workspace にマウントします）：

{
  "mcpServers": {
    "mini-data-engine": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "WORKSPACE_ROOT=/workspace",
        "-v", "${workspaceFolder}:/workspace",
        "-v", "${workspaceFolder}/tests/artifacts:/app/tests/artifacts",
        "mini-data-engine:local"
      ]
    }
  }
}

公開イメージを使用する（GHCR）

イメージは GHCR に公開されています。

• ghcr.io/kroq86/data-engineering-runtime-lab:latest

プルするには：

docker pull ghcr.io/kroq86/data-engineering-runtime-lab:latest

Cursor MCP 設定での使用例：

{
  "mcpServers": {
    "mini-data-engine": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "${workspaceFolder}/tests/artifacts:/app/tests/artifacts",
        "ghcr.io/kroq86/data-engineering-runtime-lab:latest"
      ]
    }
  }
}

Loom スタック

loom-ops および運用ランブック向けの MCP インターフェースです。エコシステム：ECOSYSTEM.md

pip install ops-runtime-mcp
ops-runtime-mcp   # stdio MCP; see docs/use-in-codex.md