Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(agent): add evidence-gated strategy discovery facade

shadowinlifebbfd82c87d64
diff --git a/README.md b/README.md
index 1922f2a90..a51455a64 100644
--- a/README.md
+++ b/README.md
@@ -428,9 +428,9 @@ Beyond OHLCV, **22 read-only data tools** reach into fundamentals & flow — fun
Detailed inventories are folded below to keep the main README scannable. Open them when you want to inspect the available building blocks.
<details>
-<summary><b>Finance Skill Library</b> <sub>89 skills across 9 categories</sub></summary>
+<summary><b>Finance Skill Library</b> <sub>90 skills across 9 categories</sub></summary>
-- 📊 89 specialized finance skills organized into 9 categories
+- 📊 90 specialized finance skills organized into 9 categories
- 🌐 Complete coverage from traditional markets to crypto & DeFi
- 🔬 Comprehensive capabilities spanning data sourcing to quantitative research
@@ -443,7 +443,7 @@ Detailed inventories are folded below to keep the main README scannable. Open th
| Crypto | 7 | `perp-funding-basis`, `liquidation-heatmap`, `stablecoin-flow`, `defi-yield`, `onchain-analysis` |
| Flow | 8 | `hk-connect-flow`, `us-etf-flow`, `edgar-sec-filings`, `financial-statement`, `adr-hshare` |
| Tool | 10 | `backtest-diagnose`, `report-generate`, `pine-script`, `doc-reader`, `web-reader`, `vnpy-export`, `trade-journal` |
-| Research | 2 | `alpha-zoo`, `strategy-dev-manager` |
+| Research | 3 | `alpha-zoo`, `strategy-dev-manager`, `strategy-discovery` |
| Risk Analysis | 1 | `ashare-pre-st-filter` |
</details>
@@ -1227,7 +1227,7 @@ Posting `{}` schedules a template on its own suggested cadence with its declared
## 🔌 MCP Plugin
-Vibe-Trading exposes 70 MCP tools for any MCP-compatible client. Runs as a stdio subprocess — no server setup needed. Core research tools work with zero API keys for HK/US/crypto; trading connector tools use the selected connector profile, and `run_swarm` needs an LLM key.
+Vibe-Trading exposes 73 MCP tools for any MCP-compatible client. Runs as a stdio subprocess — no server setup needed. Core research tools work with zero API keys for HK/US/crypto; trading connector tools use the selected connector profile, and `run_swarm` needs an LLM key.
**Environment variables:** the client spawns the server itself, so a shell `export` never reaches it — set them in the client's `env` block. Generated backtest code is sandboxed to the allowed run roots, so writing results into a workspace of your own needs `VIBE_TRADING_ALLOWED_RUN_ROOTS`:
@@ -1296,7 +1296,7 @@ with `--host` / `--port`.
</details>
-**MCP tools exposed (70):** `list_skills`, `load_skill`, `start_research_goal`, `get_research_goal`, `add_goal_evidence`, `update_research_goal_status`, `backtest`, `factor_analysis`, `alpha_zoo`, `alpha_bench`, `analyze_options`, `analyze_options_payoff`, `pattern_recognition`, `read_url`, `read_document`, `web_search`, `write_file`, `read_file`, `trading_connections`, `trading_select_connection`, `trading_check`, `trading_account`, `trading_positions`, `trading_orders`, `trading_quote`, `trading_history`, `list_swarm_presets`, `run_swarm`, `get_market_data`, `get_fund_flow`, `get_dragon_tiger`, `get_northbound_flow`, `get_margin_trading`, `get_block_trades`, `get_shareholder_count`, `get_lockup_expiry`, `get_sector_info`, `get_research_reports`, `get_stock_news`, `get_sec_filings`, `get_financial_statements`, `get_options_chain`, `get_stock_profile`, `screen_market`, `search_symbol`, `get_macro_series`, `iwencai_search`, `qveris_search`, `qveris_inspect`, `qveris_execute`, `get_institutional_holdings`, `etf_holdings`, `prediction_market`, `research_papers`, `get_swarm_status`, `get_run_result`, `list_runs`, `reap_stale_runs`, `retry_run`, `analyze_trade_journal`, `extract_shadow_strategy`, `run_shadow_backtest`, `render_shadow_report`, `scan_shadow_signals`, `quantlib_call`, `cashflow_performance`, `orderbook_depth`, `sentiment`, `technical_indicators`, `get_fundamentals`.
+**MCP tools exposed (73):** `list_skills`, `load_skill`, `start_research_goal`, `get_research_goal`, `add_goal_evidence`, `update_research_goal_status`, `backtest`, `factor_analysis`, `alpha_zoo`, `alpha_bench`, `analyze_options`, `analyze_options_payoff`, `pattern_recognition`, `read_url`, `read_document`, `web_search`, `write_file`, `read_file`, `list_strategies`, `query_strategies`, `get_strategy_evidence`, `trading_connections`, `trading_select_connection`, `trading_check`, `trading_account`, `trading_positions`, `trading_orders`, `trading_quote`, `trading_history`, `list_swarm_presets`, `run_swarm`, `get_market_data`, `get_fund_flow`, `get_dragon_tiger`, `get_northbound_flow`, `get_margin_trading`, `get_block_trades`, `get_shareholder_count`, `get_lockup_expiry`, `get_sector_info`, `get_research_reports`, `get_stock_news`, `get_sec_filings`, `get_financial_statements`, `get_options_chain`, `get_stock_profile`, `screen_market`, `search_symbol`, `get_macro_series`, `iwencai_search`, `qveris_search`, `qveris_inspect`, `qveris_execute`, `get_institutional_holdings`, `etf_holdings`, `prediction_market`, `research_papers`, `get_swarm_status`, `get_run_result`, `list_runs`, `reap_stale_runs`, `retry_run`, `analyze_trade_journal`, `extract_shadow_strategy`, `run_shadow_backtest`, `render_shadow_report`, `scan_shadow_signals`, `quantlib_call`, `cashflow_performance`, `orderbook_depth`, `sentiment`, `technical_indicators`, `get_fundamentals`.
### SWARM external MCP tools
@@ -1320,7 +1320,7 @@ Browse on ClawHub: [clawhub.ai/skills/vibe-trading](https://clawhub.ai/skills/vi
<details>
<summary><b>OpenSpace — self-evolving skills</b></summary>
-All 89 finance skills are published on [open-space.cloud](https://open-space.cloud) and evolve autonomously through OpenSpace's self-evolution engine.
+All 90 finance skills are published on [open-space.cloud](https://open-space.cloud) and evolve autonomously through OpenSpace's self-evolution engine.
To use with OpenSpace, add both MCP servers to your agent config:
@@ -1342,7 +1342,7 @@ To use with OpenSpace, add both MCP servers to your agent config:
}
```
-OpenSpace will auto-discover all 89 skills, enabling auto-fix, auto-improve, and community sharing. Search for Vibe-Trading skills via `search_skills("finance backtest")` in any OpenSpace-connected agent.
+OpenSpace will auto-discover all 90 skills, enabling auto-fix, auto-improve, and community sharing. Search for Vibe-Trading skills via `search_skills("finance backtest")` in any OpenSpace-connected agent.
</details>
@@ -1670,13 +1670,13 @@ Vibe-Trading/
├── agent/ # Backend (Python)
│ ├── cli/ # CLI package — interactive TUI + subcommands
│ ├── api_server.py # FastAPI server — runs, sessions, upload, swarm, SSE
-│ ├── mcp_server.py # MCP server — 70 tools for OpenClaw / Claude Desktop
+│ ├── mcp_server.py # MCP server — 73 tools for OpenClaw / Claude Desktop
│ │
│ ├── src/
│ │ ├── agent/ # ReAct agent core
│ │ │ ├── loop.py # 5-layer compression + read/write tool batching
│ │ │ ├── context.py # system prompt + auto-recall from persistent memory
-│ │ │ ├── skills.py # skill loader (89 bundled + user-created via CRUD)
+│ │ │ ├── skills.py # skill loader (90 bundled + user-created via CRUD)
│ │ │ ├── tools.py # tool base class + registry
│ │ │ ├── memory.py # lightweight workspace state per run
│ │ │ ├── frontmatter.py # shared YAML frontmatter parser
@@ -1685,7 +1685,7 @@ Vibe-Trading/
│ │ ├── memory/ # Cross-session persistent memory
│ │ │ └── persistent.py # file-based memory (~/.vibe-trading/memory/)
│ │ │
-│ │ ├── tools/ # 94 auto-discovered agent tools
+│ │ ├── tools/ # 97 auto-discovered agent tools
│ │ │ ├── backtest_tool.py # run backtests
│ │ │ ├── remember_tool.py # cross-session memory (save/recall/forget)
│ │ │ ├── skill_writer_tool.py # skill CRUD (save/patch/delete/file)
@@ -1703,7 +1703,7 @@ Vibe-Trading/
│ │ ├── api/ # FastAPI route modules
│ │ │ └── alpha_routes.py # /alpha/list, /alpha/{id}, /alpha/bench, SSE stream
│ │ │
-│ │ ├── skills/ # 89 finance skills in 9 categories (SKILL.md each)
+│ │ ├── skills/ # 90 finance skills in 9 categories (SKILL.md each)
│ │ ├── swarm/ # Swarm DAG execution engine
│ │ │ └── presets/ # 30 swarm preset YAML definitions
│ │ ├── session/ # Multi-turn chat + FTS5 session search
diff --git a/README_ar.md b/README_ar.md
index c6a2eced2..42dd86676 100644
--- a/README_ar.md
+++ b/README_ar.md
@@ -428,9 +428,9 @@ LONGBRIDGE_ACCESS_TOKEN=...
القوائم التفصيلية مطوية أدناه حتى يبقى README سهل القراءة. افتحها عندما تريد فحص اللبنات المتاحة.
<details>
-<summary><b>مكتبة المهارات المالية</b> <sub>89 مهارة عبر 9 فئات</sub></summary>
+<summary><b>مكتبة المهارات المالية</b> <sub>90 مهارة عبر 9 فئات</sub></summary>
-- 📊 89 مهارة مالية متخصصة منظمة في 9 فئات
+- 📊 90 مهارة مالية متخصصة منظمة في 9 فئات
- 🌐 تغطية كاملة من الأسواق التقليدية إلى الكريبتو وDeFi
- 🔬 قدرات شاملة من مصادر البيانات إلى البحث الكمي
@@ -443,7 +443,7 @@ LONGBRIDGE_ACCESS_TOKEN=...
| Crypto | 7 | `perp-funding-basis`, `liquidation-heatmap`, `stablecoin-flow`, `defi-yield`, `onchain-analysis` |
| Flow | 8 | `hk-connect-flow`, `us-etf-flow`, `edgar-sec-filings`, `financial-statement`, `adr-hshare` |
| Tool | 10 | `backtest-diagnose`, `report-generate`, `pine-script`, `doc-reader`, `web-reader`, `vnpy-export`, `trade-journal` |
-| Research | 2 | `alpha-zoo`, `strategy-dev-manager` |
+| Research | 3 | `alpha-zoo`, `strategy-dev-manager`, `strategy-discovery` |
| Risk Analysis | 1 | `ashare-pre-st-filter` |
</details>
@@ -1145,7 +1145,7 @@ curl -X POST http://localhost:8899/scheduled-runs/playbooks/premarket-brief \
## 🔌 MCP Plugin
-يعرض Vibe-Trading 70 أداة MCP لأي عميل متوافق مع MCP. يعمل كعملية stdio فرعية، دون إعداد خادم. أدوات البحث الأساسية تعمل دون أي مفاتيح API لأسواق HK/US/crypto؛ وأدوات connector للتداول تستخدم profile الموصل المختار، ويحتاج `run_swarm` وحده إلى مفتاح LLM.
+يعرض Vibe-Trading 73 أداة MCP لأي عميل متوافق مع MCP. يعمل كعملية stdio فرعية، دون إعداد خادم. أدوات البحث الأساسية تعمل دون أي مفاتيح API لأسواق HK/US/crypto؛ وأدوات connector للتداول تستخدم profile الموصل المختار، ويحتاج `run_swarm` وحده إلى مفتاح LLM.
**متغيرات البيئة:** العميل هو من يشغّل الخادم بنفسه، لذا لا يصل إليه `export` من الـ shell أبداً —— اضبطها في كتلة `env` الخاصة بالعميل. كود الاختبار الخلفي المولَّد محصور ضمن جذور التشغيل المسموح بها، لذا تحتاج إلى `VIBE_TRADING_ALLOWED_RUN_ROOTS` لكتابة النتائج في دليل عمل خاص بك:
@@ -1201,7 +1201,7 @@ vibe-trading-mcp --transport sse # legacy SSE (deprecated)
</details>
-**أدوات MCP المعروضة (70):** `list_skills`, `load_skill`, `start_research_goal`, `get_research_goal`, `add_goal_evidence`, `update_research_goal_status`, `backtest`, `factor_analysis`, `alpha_zoo`, `alpha_bench`, `analyze_options`, `analyze_options_payoff`, `pattern_recognition`, `read_url`, `read_document`, `web_search`, `write_file`, `read_file`, `trading_connections`, `trading_select_connection`, `trading_check`, `trading_account`, `trading_positions`, `trading_orders`, `trading_quote`, `trading_history`, `list_swarm_presets`, `run_swarm`, `get_market_data`, `get_fund_flow`, `get_dragon_tiger`, `get_northbound_flow`, `get_margin_trading`, `get_block_trades`, `get_shareholder_count`, `get_lockup_expiry`, `get_sector_info`, `get_research_reports`, `get_stock_news`, `get_sec_filings`, `get_financial_statements`, `get_options_chain`, `get_stock_profile`, `screen_market`, `search_symbol`, `get_macro_series`, `iwencai_search`, `qveris_search`, `qveris_inspect`, `qveris_execute`, `get_institutional_holdings`, `etf_holdings`, `prediction_market`, `research_papers`, `get_swarm_status`, `get_run_result`, `list_runs`, `reap_stale_runs`, `retry_run`, `analyze_trade_journal`, `extract_shadow_strategy`, `run_shadow_backtest`, `render_shadow_report`, `scan_shadow_signals`, `quantlib_call`, `cashflow_performance`, `orderbook_depth`, `sentiment`, `technical_indicators`, `get_fundamentals`.
+**أدوات MCP المعروضة (73):** `list_skills`, `load_skill`, `start_research_goal`, `get_research_goal`, `add_goal_evidence`, `update_research_goal_status`, `backtest`, `factor_analysis`, `alpha_zoo`, `alpha_bench`, `analyze_options`, `analyze_options_payoff`, `pattern_recognition`, `read_url`, `read_document`, `web_search`, `write_file`, `read_file`, `list_strategies`, `query_strategies`, `get_strategy_evidence`, `trading_connections`, `trading_select_connection`, `trading_check`, `trading_account`, `trading_positions`, `trading_orders`, `trading_quote`, `trading_history`, `list_swarm_presets`, `run_swarm`, `get_market_data`, `get_fund_flow`, `get_dragon_tiger`, `get_northbound_flow`, `get_margin_trading`, `get_block_trades`, `get_shareholder_count`, `get_lockup_expiry`, `get_sector_info`, `get_research_reports`, `get_stock_news`, `get_sec_filings`, `get_financial_statements`, `get_options_chain`, `get_stock_profile`, `screen_market`, `search_symbol`, `get_macro_series`, `iwencai_search`, `qveris_search`, `qveris_inspect`, `qveris_execute`, `get_institutional_holdings`, `etf_holdings`, `prediction_market`, `research_papers`, `get_swarm_status`, `get_run_result`, `list_runs`, `reap_stale_runs`, `retry_run`, `analyze_trade_journal`, `extract_shadow_strategy`, `run_shadow_backtest`, `render_shadow_report`, `scan_shadow_signals`, `quantlib_call`, `cashflow_performance`, `orderbook_depth`, `sentiment`, `technical_indicators`, `get_fundamentals`.
### أدوات MCP الخارجية في SWARM
@@ -1225,7 +1225,7 @@ npx clawhub@latest install vibe-trading --force
<details>
<summary><b>OpenSpace — مهارات ذاتية التطور</b></summary>
-كل المهارات المالية الـ 89 منشورة على [open-space.cloud](https://open-space.cloud) وتتطور ذاتياً عبر محرك التطور الذاتي في OpenSpace.
+كل المهارات المالية الـ 90 منشورة على [open-space.cloud](https://open-space.cloud) وتتطور ذاتياً عبر محرك التطور الذاتي في OpenSpace.
للاستخدام مع OpenSpace، أضف خادمي MCP إلى إعداد وكيلك:
@@ -1247,7 +1247,7 @@ npx clawhub@latest install vibe-trading --force
}
```
-سيكتشف OpenSpace كل المهارات الـ 89 تلقائياً، مما يتيح auto-fix وauto-improve والمشاركة المجتمعية. ابحث عن مهارات Vibe-Trading عبر `search_skills("finance backtest")` في أي وكيل متصل بـ OpenSpace.
+سيكتشف OpenSpace كل المهارات الـ 90 تلقائياً، مما يتيح auto-fix وauto-improve والمشاركة المجتمعية. ابحث عن مهارات Vibe-Trading عبر `search_skills("finance backtest")` في أي وكيل متصل بـ OpenSpace.
</details>
@@ -1561,13 +1561,13 @@ Vibe-Trading/
├── agent/ # Backend (Python)
│ ├── cli/ # CLI package — interactive TUI + subcommands
│ ├── api_server.py # FastAPI server — runs, sessions, upload, swarm, SSE
-│ ├── mcp_server.py # MCP server — 70 tools for OpenClaw / Claude Desktop
+│ ├── mcp_server.py # MCP server — 73 tools for OpenClaw / Claude Desktop
│ │
│ ├── src/
│ │ ├── agent/ # ReAct agent core
│ │ │ ├── loop.py # 5-layer compression + read/write tool batching
│ │ │ ├── context.py # system prompt + auto-recall from persistent memory
-│ │ │ ├── skills.py # skill loader (89 bundled + user-created via CRUD)
+│ │ │ ├── skills.py # skill loader (90 bundled + user-created via CRUD)
│ │ │ ├── tools.py # tool base class + registry
│ │ │ ├── memory.py # lightweight workspace state per run
│ │ │ ├── frontmatter.py # shared YAML frontmatter parser
@@ -1576,7 +1576,7 @@ Vibe-Trading/
│ │ ├── memory/ # Cross-session persistent memory
│ │ │ └── persistent.py # file-based memory (~/.vibe-trading/memory/)
│ │ │
-│ │ ├── tools/ # 94 auto-discovered agent tools
+│ │ ├── tools/ # 97 auto-discovered agent tools
│ │ │ ├── backtest_tool.py # run backtests
│ │ │ ├── remember_tool.py # cross-session memory (save/recall/forget)
│ │ │ ├── skill_writer_tool.py # skill CRUD (save/patch/delete/file)
@@ -1594,7 +1594,7 @@ Vibe-Trading/
│ │ ├── api/ # وحدات مسارات FastAPI
│ │ │ └── alpha_routes.py # /alpha/list, /alpha/{id}, /alpha/bench, SSE stream
│ │ │
-│ │ ├── skills/ # 89 finance skills in 9 categories (SKILL.md each)
+│ │ ├── skills/ # 90 finance skills in 9 categories (SKILL.md each)
│ │ ├── swarm/ # Swarm DAG execution engine
│ │ │ └── presets/ # 30 swarm preset YAML definitions
│ │ ├── session/ # Multi-turn chat + FTS5 session search
diff --git a/README_ja.md b/README_ja.md
index 337fe832f..a7a25f364 100644
--- a/README_ja.md
+++ b/README_ja.md
@@ -428,9 +428,9 @@ OHLCV にとどまらず、**22 の読み取り専用データツール**がフ
メイン README を読みやすく保つため、詳細な一覧は以下に折りたたんでいます。利用できる構成要素を確認したいときに開いてください。
<details>
-<summary><b>Finance Skill Library</b> <sub>9カテゴリにわたる89 skills</sub></summary>
+<summary><b>Finance Skill Library</b> <sub>9カテゴリにわたる90 skills</sub></summary>
-- 📊 89 の金融特化 skills を 9 カテゴリに整理
+- 📊 90 の金融特化 skills を 9 カテゴリに整理
- 🌐 伝統的市場から crypto & DeFi まで完全カバー
- 🔬 データ取得からクオンツリサーチまでを横断する包括的能力
@@ -443,7 +443,7 @@ OHLCV にとどまらず、**22 の読み取り専用データツール**がフ
| Crypto | 7 | `perp-funding-basis`, `liquidation-heatmap`, `stablecoin-flow`, `defi-yield`, `onchain-analysis` |
| Flow | 8 | `hk-connect-flow`, `us-etf-flow`, `edgar-sec-filings`, `financial-statement`, `adr-hshare` |
| Tool | 10 | `backtest-diagnose`, `report-generate`, `pine-script`, `doc-reader`, `web-reader`, `vnpy-export`, `trade-journal` |
-| Research | 2 | `alpha-zoo`, `strategy-dev-manager` |
+| Research | 3 | `alpha-zoo`, `strategy-dev-manager`, `strategy-discovery` |
| Risk Analysis | 1 | `ashare-pre-st-filter` |
</details>
@@ -1147,7 +1147,7 @@ curl -X POST http://localhost:8899/scheduled-runs/playbooks/premarket-brief \
## 🔌 MCP Plugin
-Vibe-Trading は MCP-compatible client 向けに 70 MCP tools を公開します。stdio subprocess として動作し、server setup は不要です。Core research tools は HK/US/crypto で API key なしに動作し、trading connector tools は選択中の connector profile を使います。LLM key が必要なのは `run_swarm` のみです。
+Vibe-Trading は MCP-compatible client 向けに 73 MCP tools を公開します。stdio subprocess として動作し、server setup は不要です。Core research tools は HK/US/crypto で API key なしに動作し、trading connector tools は選択中の connector profile を使います。LLM key が必要なのは `run_swarm` のみです。
**環境変数:** server は client 自身が spawn するため、shell の `export` は届きません —— client の `env` block に設定してください。生成された backtest code は allowed run roots 内に制限されるので、結果を自分の作業 directory に書き出すには `VIBE_TRADING_ALLOWED_RUN_ROOTS` が必要です:
@@ -1203,7 +1203,7 @@ vibe-trading-mcp --transport sse # legacy SSE (deprecated)
</details>
-**公開される MCP tools(70):** `list_skills`, `load_skill`, `start_research_goal`, `get_research_goal`, `add_goal_evidence`, `update_research_goal_status`, `backtest`, `factor_analysis`, `alpha_zoo`, `alpha_bench`, `analyze_options`, `analyze_options_payoff`, `pattern_recognition`, `read_url`, `read_document`, `web_search`, `write_file`, `read_file`, `list_swarm_presets`, `run_swarm`, `get_market_data`, `get_fund_flow`, `get_dragon_tiger`, `get_northbound_flow`, `get_margin_trading`, `get_block_trades`, `get_shareholder_count`, `get_lockup_expiry`, `get_sector_info`, `get_research_reports`, `get_stock_news`, `get_sec_filings`, `get_financial_statements`, `get_options_chain`, `get_stock_profile`, `screen_market`, `search_symbol`, `get_macro_series`, `iwencai_search`, `qveris_search`, `qveris_inspect`, `qveris_execute`, `get_institutional_holdings`, `etf_holdings`, `prediction_market`, `research_papers`, `get_swarm_status`, `get_run_result`, `list_runs`, `reap_stale_runs`, `retry_run`, `analyze_trade_journal`, `extract_shadow_strategy`, `run_shadow_backtest`, `render_shadow_report`, `scan_shadow_signals`, `trading_connections`, `trading_select_connection`, `trading_check`, `trading_account`, `trading_positions`, `trading_orders`, `trading_quote`, `trading_history`, `quantlib_call`, `cashflow_performance`, `orderbook_depth`, `sentiment`, `technical_indicators`, `get_fundamentals`.
+**公開される MCP tools(73):** `list_skills`, `load_skill`, `start_research_goal`, `get_research_goal`, `add_goal_evidence`, `update_research_goal_status`, `backtest`, `factor_analysis`, `alpha_zoo`, `alpha_bench`, `analyze_options`, `analyze_options_payoff`, `pattern_recognition`, `read_url`, `read_document`, `web_search`, `write_file`, `read_file`, `list_strategies`, `query_strategies`, `get_strategy_evidence`, `list_swarm_presets`, `run_swarm`, `get_market_data`, `get_fund_flow`, `get_dragon_tiger`, `get_northbound_flow`, `get_margin_trading`, `get_block_trades`, `get_shareholder_count`, `get_lockup_expiry`, `get_sector_info`, `get_research_reports`, `get_stock_news`, `get_sec_filings`, `get_financial_statements`, `get_options_chain`, `get_stock_profile`, `screen_market`, `search_symbol`, `get_macro_series`, `iwencai_search`, `qveris_search`, `qveris_inspect`, `qveris_execute`, `get_institutional_holdings`, `etf_holdings`, `prediction_market`, `research_papers`, `get_swarm_status`, `get_run_result`, `list_runs`, `reap_stale_runs`, `retry_run`, `analyze_trade_journal`, `extract_shadow_strategy`, `run_shadow_backtest`, `render_shadow_report`, `scan_shadow_signals`, `trading_connections`, `trading_select_connection`, `trading_check`, `trading_account`, `trading_positions`, `trading_orders`, `trading_quote`, `trading_history`, `quantlib_call`, `cashflow_performance`, `orderbook_depth`, `sentiment`, `technical_indicators`, `get_fundamentals`.
### SWARM の外部 MCP tools
@@ -1227,7 +1227,7 @@ ClawHub で見る: [clawhub.ai/skills/vibe-trading](https://clawhub.ai/skills/vi
<details>
<summary><b>OpenSpace — self-evolving skills</b></summary>
-89 の finance skills はすべて [open-space.cloud](https://open-space.cloud) に公開され、OpenSpace の self-evolution engine を通じて自律的に進化します。
+90 の finance skills はすべて [open-space.cloud](https://open-space.cloud) に公開され、OpenSpace の self-evolution engine を通じて自律的に進化します。
OpenSpace と使うには、agent config に両方の MCP servers を追加してください。
@@ -1249,7 +1249,7 @@ OpenSpace と使うには、agent config に両方の MCP servers を追加し
}
```
-OpenSpace は 89 skills を自動検出し、auto-fix、auto-improve、community sharing を可能にします。OpenSpace-connected agent では `search_skills("finance backtest")` から Vibe-Trading skills を検索できます。
+OpenSpace は 90 skills を自動検出し、auto-fix、auto-improve、community sharing を可能にします。OpenSpace-connected agent では `search_skills("finance backtest")` から Vibe-Trading skills を検索できます。
</details>
@@ -1569,13 +1569,13 @@ Vibe-Trading/
├── agent/ # バックエンド (Python)
│ ├── cli/ # CLI パッケージ — インタラクティブ TUI + サブコマンド
│ ├── api_server.py # FastAPI サーバー — runs、sessions、upload、swarm、SSE
-│ ├── mcp_server.py # MCP サーバー — OpenClaw / Claude Desktop 向け 70 tools
+│ ├── mcp_server.py # MCP サーバー — OpenClaw / Claude Desktop 向け 73 tools
│ │
│ ├── src/
│ │ ├── agent/ # ReAct エージェントコア
│ │ │ ├── loop.py # 5 層コンテキスト圧縮 + read/write ツールバッチング
│ │ │ ├── context.py # システムプロンプト + 永続メモリからの自動 recall
-│ │ │ ├── skills.py # skill ローダー(89 個同梱 + CRUD でユーザー作成)
+│ │ │ ├── skills.py # skill ローダー(90 個同梱 + CRUD でユーザー作成)
│ │ │ ├── tools.py # ツール基底クラス + レジストリ
│ │ │ ├── memory.py # run ごとの軽量ワークスペース状態
│ │ │ ├── frontmatter.py # 共有 YAML frontmatter パーサー
@@ -1584,7 +1584,7 @@ Vibe-Trading/
│ │ ├── memory/ # クロスセッション永続メモリ
│ │ │ └── persistent.py # ファイルベースメモリ (~/.vibe-trading/memory/)
│ │ │
-│ │ ├── tools/ # 94 個の自動検出エージェントツール
+│ │ ├── tools/ # 97 個の自動検出エージェントツール
│ │ │ ├── backtest_tool.py # バックテスト実行
│ │ │ ├── remember_tool.py # クロスセッションメモリ (save/recall/forget)
│ │ │ ├── skill_writer_tool.py # skill CRUD (save/patch/delete/file)
@@ -1602,7 +1602,7 @@ Vibe-Trading/
│ │ ├── api/ # FastAPI ルートモジュール
│ │ │ └── alpha_routes.py # /alpha/list、/alpha/{id}、/alpha/bench、SSE ストリーム
│ │ │
-│ │ ├── skills/ # 9 カテゴリ 89 個の finance skills(各 SKILL.md)
+│ │ ├── skills/ # 9 カテゴリ 90 個の finance skills(各 SKILL.md)
│ │ ├── swarm/ # Swarm DAG 実行エンジン
│ │ │ └── presets/ # 30 個の swarm preset YAML 定義
│ │ ├── session/ # マルチターンチャット + FTS5 セッション検索
diff --git a/README_ko.md b/README_ko.md
index e5e5b001a..b064def3c 100644
--- a/README_ko.md
+++ b/README_ko.md
@@ -428,9 +428,9 @@ OHLCV를 넘어 **22개 읽기 전용 데이터 도구**가 펀더멘털과 자
메인 README를 읽기 쉽게 유지하기 위해 상세 목록은 아래에 접어 두었습니다. 사용 가능한 구성 요소를 확인하고 싶을 때 열어보세요.
<details>
-<summary><b>금융 스킬 라이브러리</b> <sub>9개 카테고리 89개 스킬</sub></summary>
+<summary><b>금융 스킬 라이브러리</b> <sub>9개 카테고리 90개 스킬</sub></summary>
-- 📊 9개 카테고리로 구성된 89개 전문 금융 스킬
+- 📊 9개 카테고리로 구성된 90개 전문 금융 스킬
- 🌐 전통 시장부터 크립토 & DeFi까지 완전한 커버리지
- 🔬 데이터 sourcing부터 정량 리서치까지 포괄하는 기능
@@ -443,7 +443,7 @@ OHLCV를 넘어 **22개 읽기 전용 데이터 도구**가 펀더멘털과 자
| Crypto | 7 | `perp-funding-basis`, `liquidation-heatmap`, `stablecoin-flow`, `defi-yield`, `onchain-analysis` |
| Flow | 8 | `hk-connect-flow`, `us-etf-flow`, `edgar-sec-filings`, `financial-statement`, `adr-hshare` |
| Tool | 10 | `backtest-diagnose`, `report-generate`, `pine-script`, `doc-reader`, `web-reader`, `vnpy-export`, `trade-journal` |
-| Research | 2 | `alpha-zoo`, `strategy-dev-manager` |
+| Research | 3 | `alpha-zoo`, `strategy-dev-manager`, `strategy-discovery` |
| Risk Analysis | 1 | `ashare-pre-st-filter` |
</details>
@@ -1148,7 +1148,7 @@ curl -X POST http://localhost:8899/scheduled-runs/playbooks/premarket-brief \
## 🔌 MCP Plugin
-Vibe-Trading은 모든 MCP-compatible client를 위해 70개 MCP tools를 제공합니다. stdio subprocess로 실행되므로 server setup이 필요 없습니다. 핵심 research tools는 HK/US/crypto에서 API key 없이 작동하고, trading connector tools는 선택된 connector profile을 사용하며, `run_swarm`만 LLM key가 필요합니다.
+Vibe-Trading은 모든 MCP-compatible client를 위해 73개 MCP tools를 제공합니다. stdio subprocess로 실행되므로 server setup이 필요 없습니다. 핵심 research tools는 HK/US/crypto에서 API key 없이 작동하고, trading connector tools는 선택된 connector profile을 사용하며, `run_swarm`만 LLM key가 필요합니다.
**환경 변수:** server는 client가 직접 spawn하므로 shell의 `export`는 전달되지 않습니다 —— client의 `env` block에 설정하세요. 생성된 backtest code는 allowed run roots 안으로 제한되므로, 결과를 자신의 작업 directory에 쓰려면 `VIBE_TRADING_ALLOWED_RUN_ROOTS`가 필요합니다:
@@ -1204,7 +1204,7 @@ vibe-trading-mcp --transport sse # legacy SSE (deprecated)
</details>
-**노출되는 MCP tools(70):** `list_skills`, `load_skill`, `start_research_goal`, `get_research_goal`, `add_goal_evidence`, `update_research_goal_status`, `backtest`, `factor_analysis`, `alpha_zoo`, `alpha_bench`, `analyze_options`, `analyze_options_payoff`, `pattern_recognition`, `read_url`, `read_document`, `web_search`, `write_file`, `read_file`, `trading_connections`, `trading_select_connection`, `trading_check`, `trading_account`, `trading_positions`, `trading_orders`, `trading_quote`, `trading_history`, `list_swarm_presets`, `run_swarm`, `get_market_data`, `get_fund_flow`, `get_dragon_tiger`, `get_northbound_flow`, `get_margin_trading`, `get_block_trades`, `get_shareholder_count`, `get_lockup_expiry`, `get_sector_info`, `get_research_reports`, `get_stock_news`, `get_sec_filings`, `get_financial_statements`, `get_options_chain`, `get_stock_profile`, `screen_market`, `search_symbol`, `get_macro_series`, `iwencai_search`, `qveris_search`, `qveris_inspect`, `qveris_execute`, `get_institutional_holdings`, `etf_holdings`, `prediction_market`, `research_papers`, `get_swarm_status`, `get_run_result`, `list_runs`, `reap_stale_runs`, `retry_run`, `analyze_trade_journal`, `extract_shadow_strategy`, `run_shadow_backtest`, `render_shadow_report`, `scan_shadow_signals`, `quantlib_call`, `cashflow_performance`, `orderbook_depth`, `sentiment`, `technical_indicators`, `get_fundamentals`.
+**노출되는 MCP tools(73):** `list_skills`, `load_skill`, `start_research_goal`, `get_research_goal`, `add_goal_evidence`, `update_research_goal_status`, `backtest`, `factor_analysis`, `alpha_zoo`, `alpha_bench`, `analyze_options`, `analyze_options_payoff`, `pattern_recognition`, `read_url`, `read_document`, `web_search`, `write_file`, `read_file`, `list_strategies`, `query_strategies`, `get_strategy_evidence`, `trading_connections`, `trading_select_connection`, `trading_check`, `trading_account`, `trading_positions`, `trading_orders`, `trading_quote`, `trading_history`, `list_swarm_presets`, `run_swarm`, `get_market_data`, `get_fund_flow`, `get_dragon_tiger`, `get_northbound_flow`, `get_margin_trading`, `get_block_trades`, `get_shareholder_count`, `get_lockup_expiry`, `get_sector_info`, `get_research_reports`, `get_stock_news`, `get_sec_filings`, `get_financial_statements`, `get_options_chain`, `get_stock_profile`, `screen_market`, `search_symbol`, `get_macro_series`, `iwencai_search`, `qveris_search`, `qveris_inspect`, `qveris_execute`, `get_institutional_holdings`, `etf_holdings`, `prediction_market`, `research_papers`, `get_swarm_status`, `get_run_result`, `list_runs`, `reap_stale_runs`, `retry_run`, `analyze_trade_journal`, `extract_shadow_strategy`, `run_shadow_backtest`, `render_shadow_report`, `scan_shadow_signals`, `quantlib_call`, `cashflow_performance`, `orderbook_depth`, `sentiment`, `technical_indicators`, `get_fundamentals`.
### SWARM 외부 MCP tools
@@ -1228,7 +1228,7 @@ ClawHub에서 보기: [clawhub.ai/skills/vibe-trading](https://clawhub.ai/skills
<details>
<summary><b>OpenSpace — 자가 진화 스킬</b></summary>
-89개 finance skills는 모두 [open-space.cloud](https://open-space.cloud)에 게시되어 있으며 OpenSpace의 self-evolution engine을 통해 자율적으로 발전합니다.
+90개 finance skills는 모두 [open-space.cloud](https://open-space.cloud)에 게시되어 있으며 OpenSpace의 self-evolution engine을 통해 자율적으로 발전합니다.
OpenSpace와 함께 사용하려면 두 MCP server를 agent config에 추가하세요:
@@ -1250,7 +1250,7 @@ OpenSpace와 함께 사용하려면 두 MCP server를 agent config에 추가하
}
```
-OpenSpace는 89개 skills를 모두 자동 발견하여 auto-fix, auto-improve, community sharing을 활성화합니다. OpenSpace-connected agent에서 `search_skills("finance backtest")`로 Vibe-Trading skills를 검색하세요.
+OpenSpace는 90개 skills를 모두 자동 발견하여 auto-fix, auto-improve, community sharing을 활성화합니다. OpenSpace-connected agent에서 `search_skills("finance backtest")`로 Vibe-Trading skills를 검색하세요.
</details>
@@ -1566,13 +1566,13 @@ Vibe-Trading/
├── agent/ # Backend (Python)
│ ├── cli/ # CLI package — interactive TUI + subcommands
│ ├── api_server.py # FastAPI server — runs, sessions, upload, swarm, SSE
-│ ├── mcp_server.py # MCP server — 70 tools for OpenClaw / Claude Desktop
+│ ├── mcp_server.py # MCP server — 73 tools for OpenClaw / Claude Desktop
│ │
│ ├── src/
│ │ ├── agent/ # ReAct agent core
│ │ │ ├── loop.py # 5-layer compression + read/write tool batching
│ │ │ ├── context.py # system prompt + auto-recall from persistent memory
-│ │ │ ├── skills.py # skill loader (89 bundled + user-created via CRUD)
+│ │ │ ├── skills.py # skill loader (90 bundled + user-created via CRUD)
│ │ │ ├── tools.py # tool base class + registry
│ │ │ ├── memory.py # lightweight workspace state per run
│ │ │ ├── frontmatter.py # shared YAML frontmatter parser
@@ -1581,7 +1581,7 @@ Vibe-Trading/
│ │ ├── memory/ # Cross-session persistent memory
│ │ │ └── persistent.py # file-based memory (~/.vibe-trading/memory/)
│ │ │
-│ │ ├── tools/ # 94 auto-discovered agent tools
+│ │ ├── tools/ # 97 auto-discovered agent tools
│ │ │ ├── backtest_tool.py # run backtests
│ │ │ ├── remember_tool.py # cross-session memory (save/recall/forget)
│ │ │ ├── skill_writer_tool.py # skill CRUD (save/patch/delete/file)
@@ -1599,7 +1599,7 @@ Vibe-Trading/
│ │ ├── api/ # FastAPI 라우트 모듈
│ │ │ └── alpha_routes.py # /alpha/list, /alpha/{id}, /alpha/bench, SSE stream
│ │ │
-│ │ ├── skills/ # 89 finance skills in 9 categories (SKILL.md each)
+│ │ ├── skills/ # 90 finance skills in 9 categories (SKILL.md each)
│ │ ├── swarm/ # Swarm DAG execution engine
│ │ │ └── presets/ # 30 swarm preset YAML definitions
│ │ ├── session/ # Multi-turn chat + FTS5 session search
diff --git a/README_zh.md b/README_zh.md
index e94da9619..bb02d1364 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -427,9 +427,9 @@ LONGBRIDGE_ACCESS_TOKEN=...
为保持主 README 易读,详细清单折叠在下方。需要检查可用构件时可展开查看。
<details>
-<summary><b>Finance Skill Library</b> <sub>9 个类别中的 89 个 skills</sub></summary>
+<summary><b>Finance Skill Library</b> <sub>9 个类别中的 90 个 skills</sub></summary>
-- 📊 89 个专业金融 skills,分布在 9 个类别中
+- 📊 90 个专业金融 skills,分布在 9 个类别中
- 🌐 覆盖传统市场、加密与 DeFi
- 🔬 从数据源到量化研究的完整能力链路
@@ -442,7 +442,7 @@ LONGBRIDGE_ACCESS_TOKEN=...
| Crypto | 7 | `perp-funding-basis`, `liquidation-heatmap`, `stablecoin-flow`, `defi-yield`, `onchain-analysis` |
| Flow | 8 | `hk-connect-flow`, `us-etf-flow`, `edgar-sec-filings`, `financial-statement`, `adr-hshare` |
| Tool | 10 | `backtest-diagnose`, `report-generate`, `pine-script`, `doc-reader`, `web-reader`, `vnpy-export`, `trade-journal` |
-| Research | 2 | `alpha-zoo`, `strategy-dev-manager` |
+| Research | 3 | `alpha-zoo`, `strategy-dev-manager`, `strategy-discovery` |
| Risk Analysis | 1 | `ashare-pre-st-filter` |
</details>
@@ -1136,7 +1136,7 @@ POST `{}` 即按模板自身的建议节奏和默认变量排程。渲染后的
## 🔌 MCP Plugin
-Vibe-Trading 为任何 MCP-compatible client 暴露 70 个 MCP tools。它作为 stdio subprocess 运行,无需 server setup。核心 research tools 对港股/美股/加密零 API key 可用;trading connector tools 使用当前选择的 connector profile;只有 `run_swarm` 需要 LLM key。
+Vibe-Trading 为任何 MCP-compatible client 暴露 73 个 MCP tools。它作为 stdio subprocess 运行,无需 server setup。核心 research tools 对港股/美股/加密零 API key 可用;trading connector tools 使用当前选择的 connector profile;只有 `run_swarm` 需要 LLM key。
**环境变量:** server 由 client 自己 spawn,因此在 shell 里 `export` 永远传不进去 —— 请写在 client 的 `env` 块里。生成的回测代码被限制在 allowed run roots 内,所以要把结果写进你自己的工作目录,需要 `VIBE_TRADING_ALLOWED_RUN_ROOTS`:
@@ -1192,7 +1192,7 @@ vibe-trading-mcp --transport sse # legacy SSE (deprecated)
</details>
-**暴露的 MCP tools(70):** `list_skills`, `load_skill`, `start_research_goal`, `get_research_goal`, `add_goal_evidence`, `update_research_goal_status`, `backtest`, `factor_analysis`, `alpha_zoo`, `alpha_bench`, `analyze_options`, `analyze_options_payoff`, `pattern_recognition`, `read_url`, `read_document`, `web_search`, `write_file`, `read_file`, `list_swarm_presets`, `run_swarm`, `get_market_data`, `get_fund_flow`, `get_dragon_tiger`, `get_northbound_flow`, `get_margin_trading`, `get_block_trades`, `get_shareholder_count`, `get_lockup_expiry`, `get_sector_info`, `get_research_reports`, `get_stock_news`, `get_sec_filings`, `get_financial_statements`, `get_options_chain`, `get_stock_profile`, `screen_market`, `search_symbol`, `get_macro_series`, `iwencai_search`, `qveris_search`, `qveris_inspect`, `qveris_execute`, `get_institutional_holdings`, `etf_holdings`, `prediction_market`, `research_papers`, `get_swarm_status`, `get_run_result`, `list_runs`, `reap_stale_runs`, `retry_run`, `analyze_trade_journal`, `extract_shadow_strategy`, `run_shadow_backtest`, `render_shadow_report`, `scan_shadow_signals`, `trading_connections`, `trading_select_connection`, `trading_check`, `trading_account`, `trading_positions`, `trading_orders`, `trading_quote`, `trading_history`, `quantlib_call`, `cashflow_performance`, `orderbook_depth`, `sentiment`, `technical_indicators`, `get_fundamentals`.
+**暴露的 MCP tools(73):** `list_skills`, `load_skill`, `start_research_goal`, `get_research_goal`, `add_goal_evidence`, `update_research_goal_status`, `backtest`, `factor_analysis`, `alpha_zoo`, `alpha_bench`, `analyze_options`, `analyze_options_payoff`, `pattern_recognition`, `read_url`, `read_document`, `web_search`, `write_file`, `read_file`, `list_strategies`, `query_strategies`, `get_strategy_evidence`, `list_swarm_presets`, `run_swarm`, `get_market_data`, `get_fund_flow`, `get_dragon_tiger`, `get_northbound_flow`, `get_margin_trading`, `get_block_trades`, `get_shareholder_count`, `get_lockup_expiry`, `get_sector_info`, `get_research_reports`, `get_stock_news`, `get_sec_filings`, `get_financial_statements`, `get_options_chain`, `get_stock_profile`, `screen_market`, `search_symbol`, `get_macro_series`, `iwencai_search`, `qveris_search`, `qveris_inspect`, `qveris_execute`, `get_institutional_holdings`, `etf_holdings`, `prediction_market`, `research_papers`, `get_swarm_status`, `get_run_result`, `list_runs`, `reap_stale_runs`, `retry_run`, `analyze_trade_journal`, `extract_shadow_strategy`, `run_shadow_backtest`, `render_shadow_report`, `scan_shadow_signals`, `trading_connections`, `trading_select_connection`, `trading_check`, `trading_account`, `trading_positions`, `trading_orders`, `trading_quote`, `trading_history`, `quantlib_call`, `cashflow_performance`, `orderbook_depth`, `sentiment`, `technical_indicators`, `get_fundamentals`.
### SWARM 的外部 MCP tools
@@ -1216,7 +1216,7 @@ npx clawhub@latest install vibe-trading --force
<details>
<summary><b>OpenSpace — 自进化 skills</b></summary>
-全部 89 个 finance skills 都发布在 [open-space.cloud](https://open-space.cloud),并通过 OpenSpace 的自进化引擎自主演进。
+全部 90 个 finance skills 都发布在 [open-space.cloud](https://open-space.cloud),并通过 OpenSpace 的自进化引擎自主演进。
要配合 OpenSpace 使用,请将两个 MCP servers 都加入你的 agent config:
@@ -1238,7 +1238,7 @@ npx clawhub@latest install vibe-trading --force
}
```
-OpenSpace 会自动发现全部 89 个 skills,启用 auto-fix、auto-improve 和社区分享。在任意已连接 OpenSpace 的智能体中,可通过 `search_skills("finance backtest")` 搜索 Vibe-Trading skills。
+OpenSpace 会自动发现全部 90 个 skills,启用 auto-fix、auto-improve 和社区分享。在任意已连接 OpenSpace 的智能体中,可通过 `search_skills("finance backtest")` 搜索 Vibe-Trading skills。
</details>
@@ -1548,13 +1548,13 @@ Vibe-Trading/
├── agent/ # 后端(Python)
│ ├── cli/ # CLI 包 —— 交互式 TUI + 子命令
│ ├── api_server.py # FastAPI server —— runs、sessions、upload、swarm、SSE
-│ ├── mcp_server.py # MCP server —— 70 个工具,面向 OpenClaw / Claude Desktop
+│ ├── mcp_server.py # MCP server —— 73 个工具,面向 OpenClaw / Claude Desktop
│ │
│ ├── src/
│ │ ├── agent/ # ReAct agent 内核
│ │ │ ├── loop.py # 5 层上下文压缩 + 读/写工具批处理
│ │ │ ├── context.py # system prompt + 持久记忆自动召回
-│ │ │ ├── skills.py # skill loader(89 个内置 + 通过 CRUD 创建的用户 skill)
+│ │ │ ├── skills.py # skill loader(90 个内置 + 通过 CRUD 创建的用户 skill)
│ │ │ ├── tools.py # tool 基类 + 注册表
│ │ │ ├── memory.py # 每个 run 的轻量 workspace 状态
│ │ │ ├── frontmatter.py # 共享的 YAML frontmatter 解析器
@@ -1563,7 +1563,7 @@ Vibe-Trading/
│ │ ├── memory/ # 跨 session 持久记忆
│ │ │ └── persistent.py # 基于文件的记忆(~/.vibe-trading/memory/)
│ │ │
-│ │ ├── tools/ # 94 个自动发现的 agent 工具
+│ │ ├── tools/ # 97 个自动发现的 agent 工具
│ │ │ ├── backtest_tool.py # 运行回测
│ │ │ ├── remember_tool.py # 跨 session 记忆(save/recall/forget)
│ │ │ ├── skill_writer_tool.py # skill CRUD(save/patch/delete/file)
@@ -1581,7 +1581,7 @@ Vibe-Trading/
│ │ ├── api/ # FastAPI 路由模块
│ │ │ └── alpha_routes.py # /alpha/list、/alpha/{id}、/alpha/bench、SSE 流
│ │ │
-│ │ ├── skills/ # 9 个类别共 89 个 finance skills(每个一份 SKILL.md)
+│ │ ├── skills/ # 9 个类别共 90 个 finance skills(每个一份 SKILL.md)
│ │ ├── swarm/ # Swarm DAG 执行引擎
│ │ │ └── presets/ # 30 个 swarm preset YAML 定义
│ │ ├── session/ # 多轮对话 + FTS5 session 搜索
diff --git a/agent/SKILL.md b/agent/SKILL.md
index 414c5f5af..d90707083 100644
--- a/agent/SKILL.md
+++ b/agent/SKILL.md
@@ -1,7 +1,7 @@
---
name: vibe-trading
version: 0.1.13
-description: Professional finance research toolkit — backtesting (10 engines + benchmark comparison panel), factor analysis, Alpha Zoo (462 pre-built alphas across qlib158/alpha101/gtja191/academic/fundamental), options pricing, 89 finance skills, 30 multi-agent swarm teams, Trade Journal analyzer, and Shadow Account (extract → backtest → render) across 25 market-data sources (tushare, yfinance, okx, binance, akshare, baostock, tencent, mootdx, ccxt, futu, mt5, tickerall, local, eastmoney, sina, stooq, yahoo, pykrx, india_broker, qveris, longbridge, plus optional-key finnhub/alphavantage/tiingo/fmp).
+description: Professional finance research toolkit — backtesting (10 engines + benchmark comparison panel), factor analysis, Alpha Zoo (462 pre-built alphas across qlib158/alpha101/gtja191/academic/fundamental), options pricing, 90 finance skills, 30 multi-agent swarm teams, Trade Journal analyzer, and Shadow Account (extract → backtest → render) across 25 market-data sources (tushare, yfinance, okx, binance, akshare, baostock, tencent, mootdx, ccxt, futu, mt5, tickerall, local, eastmoney, sina, stooq, yahoo, pykrx, india_broker, qveris, longbridge, plus optional-key finnhub/alphavantage/tiingo/fmp).
dependencies:
python: ">=3.11,<3.14"
pip:
@@ -23,7 +23,7 @@ mcp:
# Vibe-Trading
-Professional finance research toolkit with AI-powered backtesting (10 engines), multi-agent teams, 89 specialized skills, the **Alpha Zoo** (462 pre-built quantitative alphas across qlib158 / alpha101 / gtja191 / academic / fundamental with one-line CLI benchmarking), and the Shadow Account loop — extract your implicit trading rules from a journal, backtest them across A股/港股/美股/crypto, then see where they would have served you better.
+Professional finance research toolkit with AI-powered backtesting (10 engines), multi-agent teams, 90 specialized skills, the **Alpha Zoo** (462 pre-built quantitative alphas across qlib158 / alpha101 / gtja191 / academic / fundamental with one-line CLI benchmarking), and the Shadow Account loop — extract your implicit trading rules from a journal, backtest them across A股/港股/美股/crypto, then see where they would have served you better.
## Setup
@@ -53,7 +53,7 @@ Add to your agent's MCP config:
### API Key Requirements
-Core research MCP tools work with zero API keys for HK/US/Canada/crypto. After `pip install`, backtesting, market data, factor analysis, options pricing, chart patterns, web search, document reading, trade journal analysis, shadow-account extraction/backtest/report, the Alpha Zoo (462 pre-built alphas), and all 89 skills are ready to use. IBKR tools require a local TWS / IB Gateway session; `run_swarm` requires an LLM key.
+Core research MCP tools work with zero API keys for HK/US/Canada/crypto. After `pip install`, backtesting, market data, factor analysis, options pricing, chart patterns, web search, document reading, trade journal analysis, shadow-account extraction/backtest/report, the Alpha Zoo (462 pre-built alphas), and all 90 skills are ready to use. IBKR tools require a local TWS / IB Gateway session; `run_swarm` requires an LLM key.
| Feature | Key needed | When |
|---------|-----------|------|
@@ -120,7 +120,7 @@ One-line cross-sectional IC / IR / alive-reversed-dead categorisation across fiv
Each alpha ships with `__alpha_meta__` (formula LaTeX + theme + universe + warmup + columns required), guarded by an AST purity gate + 300-row lookahead sentinel test. Use the `vibe-trading alpha {list,show,bench,compare,export-manifest}` CLI, the `/alpha/*` REST routes (browser at `/alpha-zoo`), or compose multi-factor signals via `ZooSignalEngine.from_zoo(...)`.
-### Finance Skills (89)
+### Finance Skills (90)
Comprehensive knowledge base covering:
- Technical analysis (candlestick, Elliott wave, Ichimoku, SMC, harmonic, chanlun)
- Quantitative methods (factor research, ML strategy, pair trading, multi-factor)
@@ -133,11 +133,11 @@ Comprehensive knowledge base covering:
Use `load_skill(name)` to access full methodology docs with code templates.
-## Available MCP Tools (70)
+## Available MCP Tools (73)
| Tool | Description | API Key |
|------|-------------|---------|
-| `list_skills` | List all 89 finance skills | None |
+| `list_skills` | List all 90 finance skills | None |
| `load_skill` | Load full skill documentation | None |
| `start_research_goal` | Create an auditable research goal | None |
| `get_research_goal` | Read the current research goal | None |
@@ -177,6 +177,9 @@ Use `load_skill(name)` to access full methodology docs with code templates.
| `read_document` | Extract text from PDF/DOCX/XLSX/PPTX/images | None |
| `write_file` | Write files (config, strategy code) | None |
| `read_file` | Read file contents | None |
+| `list_strategies` | Browse discoverable strategies (Alpha Zoo + SDM store) | None |
+| `query_strategies` | Evidence-gated query: regime / Sharpe / quality / cost filters | None |
+| `get_strategy_evidence` | Per-regime evidence rows for one strategy | None |
| `analyze_trade_journal` | Parse broker CSV → profile + behavior diagnostics | None |
| `extract_shadow_strategy` | Distill 3-5 if-then rules from profitable roundtrips | None |
| `run_shadow_backtest` | Multi-market backtest + delta-PnL attribution | None* |
@@ -216,7 +219,7 @@ Use `load_skill(name)` to access full methodology docs with code templates.
pip install vibe-trading-ai
```
-That's it — no API keys needed for HK/US/Canada/crypto markets. Start using `backtest`, `get_market_data`, `analyze_options`, `analyze_trade_journal`, `extract_shadow_strategy`, `web_search`, the **Alpha Zoo** (`vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025`), and all 89 skills immediately.
+That's it — no API keys needed for HK/US/Canada/crypto markets. Start using `backtest`, `get_market_data`, `analyze_options`, `analyze_trade_journal`, `extract_shadow_strategy`, `web_search`, the **Alpha Zoo** (`vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025`), and all 90 skills immediately.
## Loading Tools from External MCP Servers
diff --git a/agent/mcp_server.py b/agent/mcp_server.py
index 57165cfdc..83ac70e71 100644
--- a/agent/mcp_server.py
+++ b/agent/mcp_server.py
@@ -6,7 +6,8 @@ Zero API key required for HK/US/crypto research markets (yfinance, OKX,
AKShare are free). Trading connector tools are profile-scoped and require the
selected connector's own local app or OAuth setup.
-Surfaces 70 tools: skills, research goals, backtest/factor/options/pattern
+Surfaces 73 tools: skills, research goals, strategy discovery,
+backtest/factor/options/pattern
analysis, market data, fundamentals & capital-flow & news & discovery
(get_fund_flow / get_dragon_tiger / get_northbound_flow / get_margin_trading /
get_block_trades / get_shareholder_count / get_lockup_expiry / get_sector_info /
@@ -1148,6 +1149,124 @@ def read_file(path: str) -> str:
return registry.execute("read_file", {"path": path})
+# ---------------------------------------------------------------------------
+# Strategy discovery tools
+# ---------------------------------------------------------------------------
+
+
+def _strategy_discovery_execute(tool_name: str, params: dict[str, Any]) -> str:
+ """Delegate to a strategy-discovery agent tool with an honest error envelope.
+
+ Registry or facade failures never propagate to the MCP client as a bare
+ exception — silent, confident failure is exactly the mode this feature
+ exists to prevent (see the phantom-tool rejection of PR #896). The
+ envelope carries a generic message only; raw exception text can leak
+ internal paths and stays in the server logs via ``logger.exception``.
+ """
+ try:
+ registry = _get_registry()
+ return registry.execute(tool_name, params)
+ except Exception: # noqa: BLE001 - honest error beats a raw traceback
+ logger.exception("strategy discovery tool %s unavailable", tool_name)
+ return json.dumps(
+ {
+ "status": "error",
+ "error": "strategy discovery unavailable; see server logs",
+ },
+ ensure_ascii=False,
+ )
+
+
+def list_strategies(limit: int = 20, offset: int = 0, source: str | None = None) -> str:
+ """List discoverable strategies across the Alpha Zoo and the SDM strategy store.
+
+ Read-only catalogue of what strategies exist and what state they are in.
+ Rows carry identification metadata plus evidence status; use
+ get_strategy_evidence for the per-regime evidence behind any strategy.
+ Nothing returned is a recommendation — rows below the evidence threshold
+ are flagged insufficient/marginal rather than recommended.
+
+ Args:
+ limit: Maximum number of strategies to return (default 20).
+ offset: Pagination offset for stable browsing (default 0).
+ source: Optional source filter — "alpha_zoo" or "sdm". Omit to
+ browse both sources.
+ """
+ return _strategy_discovery_execute(
+ "list_strategies",
+ {"limit": limit, "offset": offset, "source": source},
+ )
+
+
+def query_strategies(
+ regime: str | None = None,
+ min_sharpe: float | None = None,
+ min_evidence_quality: str = "adequate",
+ min_trades: int = 10,
+ cost_feasible: bool = True,
+ limit: int = 10,
+) -> str:
+ """Query strategies whose computed per-regime evidence passes the filters.
+
+ Evidence-gated discovery: strategies are ranked by per-regime evidence
+ rows from reproducible backtests instead of boolean scenario tags.
+ Strategies below the evidence thresholds (trade count, coverage) are
+ flagged insufficient/marginal rather than recommended, and the
+ sizing-corrected cost screen keeps only strategies that clear their
+ breakeven.
+
+ Args:
+ regime: Optional market-regime filter — "bear_market",
+ "bull_market", or "structural". Omit to query across all regimes.
+ min_sharpe: Optional minimum Sharpe on the per-regime evidence rows.
+ min_evidence_quality: Minimum evidence quality to keep — "adequate"
+ (default), "marginal", "insufficient", or "any". "any" only
+ removes the quality floor; rows must still pass the other
+ filters (min_trades, cost_feasible, min_sharpe) to be kept.
+ min_trades: Minimum executed-trade count for evidence to count
+ (default 10; fewer trades reads as insufficient evidence).
+ cost_feasible: Keep only strategies that pass the sizing-corrected
+ cost-breakeven screen (default True).
+ limit: Maximum number of strategies to return (default 10).
+ """
+ return _strategy_discovery_execute(
+ "query_strategies",
+ {
+ "regime": regime,
+ "min_sharpe": min_sharpe,
+ "min_evidence_quality": min_evidence_quality,
+ "min_trades": min_trades,
+ "cost_feasible": cost_feasible,
+ "limit": limit,
+ },
+ )
+
+
+def get_strategy_evidence(strategy_id: str, regime: str | None = None) -> str:
+ """Return the computed per-regime evidence rows for one strategy.
+
+ Read-only evidence detail: shows what reproducible backtests support the
+ strategy in each regime — trade count, coverage, Sharpe, and the
+ sizing-corrected cost breakeven. Rows below the evidence thresholds are
+ flagged insufficient/marginal rather than recommended; the facade refuses
+ regime assessments without computed evidence, so absent regimes are an
+ honest empty, not a guess.
+
+ Args:
+ strategy_id: Strategy identifier from list_strategies or
+ query_strategies.
+ regime: Optional regime filter — "bear_market", "bull_market", or
+ "structural". Omit for every regime with evidence.
+ """
+ return _strategy_discovery_execute(
+ "get_strategy_evidence",
+ {"strategy_id": strategy_id, "regime": regime},
+ )
+
+
# ---------------------------------------------------------------------------
# Trading connector tools
# ---------------------------------------------------------------------------
diff --git a/agent/src/agent/context.py b/agent/src/agent/context.py
index c33f8a417..f25a385a4 100644
--- a/agent/src/agent/context.py
+++ b/agent/src/agent/context.py
@@ -78,7 +78,7 @@ skill document, not recalled memory. They are not defaults to be tuned.
## Task Routing
Decide which workflow to use based on the request:
-
+{strategy_discovery_routing}
**Backtest** — user wants to create, test, or optimize a trading strategy:
1. `load_skill("strategy-generate")` — read the SignalEngine contract
2. `write_file("config.json", ...)` — source, codes, dates, parameters. If the strategy is expected to produce ≥10 trades, include `"validation": {{"monte_carlo": {{"n_simulations": 1000}}}}` in config.json for Monte Carlo testing
@@ -267,6 +267,16 @@ class ContextBuilder:
snapshot=self._persistent_memory.snapshot,
)
+ # Strategy-discovery routing text is injected only when all three
+ # discovery tools are actually registered (phantom-tool fail-safe),
+ # and prompt construction must never break startup.
+ try:
+ from src.strategy_discovery.guard import routing_block
+
+ routing = routing_block(self.registry)
+ except Exception: # noqa: BLE001
+ routing = ""
+
return _SYSTEM_PROMPT.format(
tool_count=len(self.registry._tools),
skill_count=len(self.skills_loader.skills),
@@ -275,6 +285,7 @@ class ContextBuilder:
skill_descriptions=self.skills_loader.get_descriptions(),
memory_summary=self.memory.to_summary(),
memory_section=memory_section,
+ strategy_discovery_routing=routing,
current_datetime=now.strftime("%A, %B %d, %Y %H:%M UTC"),
)
diff --git a/agent/src/config/env_schema.py b/agent/src/config/env_schema.py
index 7f68eec92..51bfff6bb 100644
--- a/agent/src/config/env_schema.py
+++ b/agent/src/config/env_schema.py
@@ -420,6 +420,9 @@ class PathConfig(_EnvBase):
vibe_trading_strategy_store_db_path: str = Field(
alias="VIBE_TRADING_STRATEGY_STORE_DB_PATH", default="",
)
+ vibe_trading_strategy_discovery_db_path: str = Field(
+ alias="VIBE_TRADING_STRATEGY_DISCOVERY_DB_PATH", default="",
+ )
# ---------------------------------------------------------------------------
diff --git a/agent/src/skills/strategy-discovery/SKILL.md b/agent/src/skills/strategy-discovery/SKILL.md
new file mode 100644
index 000000000..914df09bb
--- /dev/null
+++ b/agent/src/skills/strategy-discovery/SKILL.md
@@ -0,0 +1,125 @@
+---
+name: strategy-discovery
+description: "Strategy Discovery: evidence-gated read-only facade over Alpha Zoo + the SDM strategy store — answers what strategies exist and what state they are in, with per-regime evidence instead of scenario tags."
+category: research
+---
+
+# Strategy Discovery
+
+## Purpose
+
+Strategy Discovery is the single read-only entry point for two questions: **what strategies exist**, and **what state are they in**. It fronts the Alpha Zoo registry and the SDM strategy store with one facade and answers with computed evidence instead of labels.
+
+It supersedes the earlier closed-registry attempt. That design attached boolean scenario tags (works in bear markets: yes/no) to a curated list. This skill replaces tags with **per-regime evidence rows**: every claim that a strategy works in a regime must come from a computed, reproducible backtest stored as evidence, never from curation or inference.
+
+The surface is read-only. It never registers, mutates, or deletes strategies. To add or change strategies, use the `strategy-dev-manager` and `alpha-zoo` workflows — Strategy Discovery only reports what those workflows have produced.
+
+## When to Use
+
+Decision tree for routing user requests:
+
+- User asks **what strategies exist** / "list available strategies" → `list_strategies(limit=..., offset=..., source=...)`
+- User asks **which strategy fits a regime or threshold** ("what works in bear markets?", "anything with Sharpe above 1?") → `query_strategies(regime=..., min_sharpe=..., ...)`
+- User asks for **the evidence behind one specific strategy** → `get_strategy_evidence(strategy_id=..., regime=...)`
+- User asks to **create, backtest, or register** a strategy → this is NOT this skill; route to `strategy-generate` / `strategy-dev-manager` / `alpha-zoo`
+
+This skill has **no CLI surface** — there is no `vibe-trading strategy-discovery` command and no CLI flags. The only access path is the three tools (`list_strategies`, `query_strategies`, `get_strategy_evidence`), available through the agent registry and the MCP server under the same names. Do not invent flags or subcommands.
+
+## Tools
+
+### list_strategies
+
+Browse the catalogue.
+
+| Parameter | Type | Default | Meaning |
+|-----------|------|---------|---------|
+| `limit` | integer | 20 | Maximum number of rows to return |
+| `offset` | integer | 0 | Pagination offset |
+| `source` | string | none | Optional filter: `alpha_zoo` or `sdm`; omit for both |
+
+Returns identification metadata plus evidence status. This is a catalogue listing, not a ranking — use `query_strategies` for filtered, evidence-ranked results.
+
+### query_strategies
+
+Evidence-gated query.
+
+| Parameter | Type | Default | Meaning |
+|-----------|------|---------|---------|
+| `regime` | string | none | `bear_market`, `bull_market`, or `structural`; omit for all regimes |
+| `min_sharpe` | number | none | Minimum Sharpe on the evidence rows |
+| `min_evidence_quality` | string | `adequate` | `adequate` \| `marginal` \| `insufficient` \| `any`. `any` only removes the quality floor — rows must still pass the other filters (`min_trades`, `cost_feasible`, `min_sharpe`) to be kept |
+| `min_trades` | integer | 10 | Minimum executed-trade count for evidence to count |
+| `cost_feasible` | boolean | true | Keep only rows that clear the cost screen. Fail-closed: rows whose breakeven is unverifiable (`null`, see Multi-position caveat) are excluded; set `false` to inspect them with their warnings |
+| `limit` | integer | 10 | Maximum number of rows to return |
+
+### get_strategy_evidence
+
+Per-regime evidence detail for one strategy.
+
+| Parameter | Type | Default | Meaning |
+|-----------|------|---------|---------|
+| `strategy_id` | string | — | Required. Identifier from `list_strategies` / `query_strategies` |
+| `regime` | string | none | Optional regime filter (same values as `query_strategies`) |
+
+Returns the per-regime evidence rows: trade count, coverage window, Sharpe, cost breakeven, and the resulting evidence-quality flag.
+
+## Evidence Row Contract
+
+Every row is self-describing — the metadata travels with the numbers:
+
+| Field | Meaning |
+|-------|---------|
+| `evidence_stage` | Pipeline stage that produced the row: `hypothesis` \| `backtest` \| `holdout` \| `shadow` \| `live_canary` \| `retired`. The harness writes only `backtest` today (it computes over backtest artifacts); the other stages are reserved. A row answers "backtest evidence exists; no holdout/shadow/live evidence exists yet" — never more than the stage it carries |
+| `provenance` | The reproducible backtest run directory the row was computed from (`artifacts/trades.csv` + `artifacts/equity.csv` inside it). The run directory holds the config and signal engine that produced the figures, so every row is traceable to a reproducible artifact |
+| `regime_definition` | JSON naming the regime-labeling parameters used (rolling benchmark window, bear/bull thresholds, Sharpe annualization) — the definition travels with the data, not hidden in code constants |
+| `breakeven_fee_bps` | Sizing-corrected cost breakeven, or `null` when the cost screen is unverifiable (see Multi-position caveat) |
+| `warnings` | Stable machine-readable prefixes: `insufficient-trades:`, `short-coverage:`, `cost-sensitive:`, `borderline-evidence:`, `multi-position-breakeven:` |
+
+## Evidence Thresholds
+
+Evidence quality is derived from the computed rows, not asserted:
+
+| Condition | Flag | Meaning |
+|-----------|------|---------|
+| Trade count < 10 | `insufficient` | Too few trades to say anything; the row carries no claim |
+| Coverage < 2 years | `marginal` | Real but short sample; report with the caveat, not as proof |
+| Breakeven < 5 bps | `cost_sensitive` | Gross edge is thinner than realistic per-trade costs |
+| Right at a boundary (e.g. exactly 10 trades) | borderline caveat | Report the raw numbers alongside the flag; the flag alone is not the story |
+
+Rows flagged `insufficient` or `marginal` are returned so the caller can see the gap — they are **flagged, never recommended**. Filtering them out is what `min_evidence_quality` and `min_trades` are for.
+
+## Cost Screen
+
+The feasibility screen uses the sizing-corrected breakeven, in basis points:
+
+```
+breakeven_bps = ln(1 + g) / (2 · n · s) · 10⁴
+```
+
+where `g` is the gross edge over the evidence window, `n` is the number of trades, and `s` is the average position sizing. A strategy is cost-feasible only when its breakeven is thick enough (`cost_feasible=true` keeps the passing rows; a sub-5 bps breakeven reads as `cost_sensitive` above).
+
+The facade deliberately **does not report an `estimated_net_sharpe`**. A net Sharpe requires picking concrete cost assumptions, and any choice there would present an unverified estimate as evidence. The honest number is the breakeven itself — it tells the caller how much per-trade cost the gross edge tolerates, and leaves the cost assumption to them.
+
+## Multi-position caveat
+
+`breakeven_fee_bps` is exact only for strategies holding **one position at a time**. Per the #969 discussion (sergio12S), the aggregate form has **no closed form for multi-sleeve / multi-name strategies** — the portfolio break-even equation needs per-sleeve returns and trade counts, which aggregate figures do not contain; measured error is 1.1–6.5x versus per-position accounting, and the error is not a constant factor.
+
+The harness therefore **refuses to store an aggregate breakeven**: any run that held more than one concurrent position — or whose artifacts make concurrency undetectable — gets `breakeven_fee_bps = null` on every row, plus a stable `multi-position-breakeven:` warning. A null is a better answer than a number that is wrong by a factor between 1.1 and 6.5.
+
+Consequences for queries:
+
+- `cost_feasible=true` (default) is **fail-closed**: a null breakeven means the cost screen is unverifiable, which is not a pass — such rows are excluded from default results.
+- The rows are not lost: query with `cost_feasible=false` or call `get_strategy_evidence` to see them with their warnings.
+- Single-position runs keep the exact sizing-corrected breakeven and are unaffected.
+
+## Honest-Empty Semantics
+
+The facade refuses regime assessments without computed evidence. If a strategy has no backtest evidence for a regime, `get_strategy_evidence` returns an honest empty for that regime instead of a guess; `query_strategies` likewise never fabricates rows to satisfy a filter.
+
+An empty result is an answer, not an error: it means "no computed evidence exists for this request." There is **no user-runnable command or workflow** that changes that. The evidence store is populated only by the evidence harness **library API** (`src.strategy_discovery.evidence_harness.rebuild_evidence` over reproducible run artifacts); automated workflow wiring is still pending, so until then evidence rows come from harness runs executed by developers/integrators. Never relax a threshold or narrate from a scenario tag instead.
+
+## Composition Guarantee
+
+- **Reads only**: the Alpha Zoo Registry, the SDM strategy store, and the facade-owned evidence cache DB. Modifies nothing in any of them.
+- **Cache is disposable**: the evidence cache DB is owned by the facade, deletable, and rebuildable from the two authoritative sources. Its location can be overridden with the `VIBE_TRADING_STRATEGY_DISCOVERY_DB_PATH` environment variable; unset means the default location.
+- **No other state**: no network calls, no writes outside the cache, no side effects on the registries it reads.
diff --git a/agent/src/strategy_discovery/__init__.py b/agent/src/strategy_discovery/__init__.py
new file mode 100644
index 000000000..837daa28d
--- /dev/null
+++ b/agent/src/strategy_discovery/__init__.py
@@ -0,0 +1,75 @@
+"""Strategy Discovery: an evidence-gated facade over Alpha Zoo + SDM.
+
+Read-only core package for GitHub issue #969 (supersedes the rejected #896):
+a unified strategy catalog, per-regime evidence queries gated on harness-
+computed data, and the harness that turns reproducible run artifacts into
+evidence rows. The package never ships seed performance data — stores start
+empty and every number served to the agent comes from real backtest runs.
+
+Import policy: this package stays cheap to import. Submodules only depend on
+the standard library and each other at module level; heavy integrations
+(``src.factors.registry``, ``src.strategy_store``) are imported lazily inside
+facade methods, and no network I/O happens at import time.
+"""
+
+from __future__ import annotations
+
+from src.strategy_discovery.evidence_harness import (
+ compute_evidence_for_run,
+ rebuild_evidence,
+)
+from src.strategy_discovery.evidence_store import EvidenceStore
+from src.strategy_discovery.facade import StrategyDiscoveryFacade
+from src.strategy_discovery.guard import (
+ ROUTING_BLOCK,
+ STRATEGY_DISCOVERY_TOOLS,
+ routing_block,
+ tools_registered,
+)
+from src.strategy_discovery.models import (
+ BORDERLINE_BREAKEVEN_BPS,
+ BORDERLINE_COVERAGE_BUFFER_DAYS,
+ BORDERLINE_TRADE_BUFFER,
+ COST_SENSITIVE_BREAKEVEN_BPS,
+ EVIDENCE_STAGES,
+ MIN_COVERAGE_DAYS,
+ MIN_TRADES,
+ QUALITY_ADEQUATE,
+ QUALITY_INSUFFICIENT,
+ QUALITY_MARGINAL,
+ QUALITY_ORDER,
+ REGIMES,
+ EvidenceRow,
+ StrategySummary,
+ breakeven_fee_bps,
+ classify_quality,
+ coverage_days_from_ranges,
+)
+
+__all__ = [
+ "EvidenceRow",
+ "StrategySummary",
+ "StrategyDiscoveryFacade",
+ "EvidenceStore",
+ "REGIMES",
+ "EVIDENCE_STAGES",
+ "QUALITY_ADEQUATE",
+ "QUALITY_MARGINAL",
+ "QUALITY_INSUFFICIENT",
+ "QUALITY_ORDER",
+ "MIN_TRADES",
+ "MIN_COVERAGE_DAYS",
+ "COST_SENSITIVE_BREAKEVEN_BPS",
+ "BORDERLINE_TRADE_BUFFER",
+ "BORDERLINE_BREAKEVEN_BPS",
+ "BORDERLINE_COVERAGE_BUFFER_DAYS",
+ "breakeven_fee_bps",
+ "classify_quality",
+ "coverage_days_from_ranges",
+ "STRATEGY_DISCOVERY_TOOLS",
+ "ROUTING_BLOCK",
+ "tools_registered",
+ "routing_block",
+ "compute_evidence_for_run",
+ "rebuild_evidence",
+]
diff --git a/agent/src/strategy_discovery/evidence_harness.py b/agent/src/strategy_discovery/evidence_harness.py
new file mode 100644
index 000000000..de2945cff
--- /dev/null
+++ b/agent/src/strategy_discovery/evidence_harness.py
@@ -0,0 +1,520 @@
+"""Evidence harness: compute per-regime evidence from real backtest artifacts.
+
+Builds on the artifact readers in :mod:`run_artifacts`; this module owns the
+regime labeling and the per-regime metrics. Conventions:
+
+* Trade counting — engine ``trades.csv`` artifacts hold TWO rows per round
+ trip (entry row ``pnl=0.0`` + exit row with realized pnl); only exit rows
+ are counted, so a round trip contributes exactly one trade. Legacy
+ one-row-per-trade artifacts are detected via the marker column and keep
+ counting every row (see :func:`run_artifacts.read_trade_activity`).
+* Regime labeling — each bar is labeled by the rolling cumulative benchmark
+ return over the trailing ``benchmark_window`` bars ending at that bar
+ (``<= bear_threshold`` → bear_market, ``>= bull_threshold`` → bull_market,
+ else structural). Bars without enough history or a usable benchmark value
+ are labeled ``structural`` and documented as warm-up, never guessed.
+* Per-regime metrics use only regime bars: compounded strategy/benchmark
+ returns are products of per-bar returns across the union of the regime's
+ bars; Sharpe is mean/std of per-bar strategy returns inside regime bars,
+ annualized with ``sqrt(252)`` (bars assumed daily); max drawdown tracks
+ the strategy equity peak across regime bars.
+* Multi-position null — the sizing-corrected breakeven identity is exact
+ only for strategies holding one position at a time. For runs that held
+ several positions at once the aggregate form is structurally invalid
+ (no closed form; measured error 1.1x-6.5x — issue #969, sergio12S), so
+ those rows carry ``breakeven_fee_bps = None`` instead of a wrong number,
+ plus a stable ``multi-position-breakeven:`` warning. Runs whose artifacts
+ make concurrency undetectable are treated the same way (fail-closed).
+
+Missing inputs return ``[]`` with a warning: honest empty beats fabricated
+rows every time.
+"""
+
+from __future__ import annotations
+
+import bisect
+import json
+import logging
+import math
+import statistics
+from collections.abc import Mapping, Sequence
+from datetime import date
+from pathlib import Path
+
+from src.strategy_discovery.evidence_store import EvidenceStore
+from src.strategy_discovery.models import (
+ COST_SENSITIVE_BREAKEVEN_BPS,
+ REGIMES,
+ EvidenceRow,
+ breakeven_fee_bps,
+ build_warnings,
+ classify_quality,
+ coverage_days_from_ranges,
+)
+from src.strategy_discovery.run_artifacts import (
+ parse_finite_float,
+ read_equity_series,
+ read_trade_activity,
+)
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Regime thresholds — named, documented, configurable (not magic numbers).
+# ---------------------------------------------------------------------------
+
+#: Rolling window in bars used to classify each bar's market regime.
+#: Default 252 ≈ one trading year of daily bars.
+DEFAULT_BENCHMARK_WINDOW = 252
+
+#: Rolling benchmark return at or below this value labels a bar bear_market.
+DEFAULT_BEAR_THRESHOLD = -0.10
+
+#: Rolling benchmark return at or above this value labels a bar bull_market.
+DEFAULT_BULL_THRESHOLD = 0.15
+
+#: Annualization factor for Sharpe: bars are assumed daily, so the per-bar
+#: Sharpe is scaled by sqrt(252). Documented convention, not a hidden magic.
+SHARPE_ANNUALIZATION_BARS = 252
+
+#: Stage of every harness-produced row: the harness computes exclusively
+#: over backtest run artifacts, so no other stage is honest today.
+HARNESS_EVIDENCE_STAGE = "backtest"
+
+
+def describe_regime_definition(
+ benchmark_window: int, bear_threshold: float, bull_threshold: float
+) -> str:
+ """Canonical JSON naming the regime-labeling parameters of a compute run.
+
+ Stored on every evidence row so the definition travels with the data
+ instead of living only in code constants (issue #969, initial-d).
+ """
+ return json.dumps(
+ {
+ "benchmark_window": benchmark_window,
+ "bear_threshold": bear_threshold,
+ "bull_threshold": bull_threshold,
+ "sharpe_annualization_bars": SHARPE_ANNUALIZATION_BARS,
+ },
+ sort_keys=True,
+ )
+
+
+#: Stable warning prefix for the multi-position breakeven caveat, kept in
+#: the same prefix-token style as ``models.build_warnings`` so downstream
+#: tools can match it without parsing prose.
+MULTI_POSITION_WARNING_PREFIX = "multi-position-breakeven:"
+
+#: Why the aggregate breakeven is refused for multi-position runs (issue
+#: #969 discussion, sergio12S): the portfolio break-even equation has no
+#: closed form and needs per-sleeve returns and trade counts, which the
+#: aggregate figures do not contain. A null is a better answer than a
+#: number that is wrong by a factor between 1.1 and 6.5.
+_MULTI_POSITION_CAVEAT_BODY = (
+ "the sizing-corrected breakeven identity is only exact for "
+ "single-position strategies; the aggregate form is structurally "
+ "invalid for multi-position/multi-name runs (no closed form, measured "
+ "error 1.1-6.5x), so breakeven_fee_bps is null and the cost screen is "
+ "unverifiable — inspect such rows with cost_feasible=false"
+)
+
+
+def _breakeven_caveat(max_concurrent: int | None) -> str | None:
+ """Run-level caveat that nulls the breakeven, or ``None``.
+
+ ``max_concurrent`` comes from the entry/exit pairs in ``trades.csv``:
+ above 1 the breakeven arithmetic (aggregate return divided by
+ aggregate trade count) is structurally invalid, so every evidence row
+ of that run carries ``breakeven_fee_bps = None`` plus the caveat.
+ ``None`` (missing entry/exit marker → concurrency undetectable) is
+ treated the same way — fail-closed, never a silent aggregate number.
+ Single-position runs need no caveat.
+ """
+ if max_concurrent is None:
+ return (
+ f"{MULTI_POSITION_WARNING_PREFIX} trades.csv lacks the engine "
+ f"entry/exit marker (zero-pnl rows), so position concurrency "
+ f"is unknown; {_MULTI_POSITION_CAVEAT_BODY}"
+ )
+ if max_concurrent > 1:
+ return (
+ f"{MULTI_POSITION_WARNING_PREFIX} run held up to "
+ f"{max_concurrent} concurrent positions; "
+ f"{_MULTI_POSITION_CAVEAT_BODY}"
+ )
+ return None
+
+
+# ---------------------------------------------------------------------------
+# Regime labeling
+# ---------------------------------------------------------------------------
+
+
+def _label_regimes(
+ benchmarks: Sequence[float | None],
+ benchmark_window: int,
+ bear_threshold: float,
+ bull_threshold: float,
+) -> list[str]:
+ """Regime label per bar from the trailing rolling benchmark return.
+
+ Bars without ``benchmark_window`` bars of history, or without finite
+ positive benchmark anchors at both ends of the window, are labeled
+ ``structural`` and documented as warm-up / unlabeled — never guessed.
+ """
+ return [
+ _regime_for_bar(
+ index, benchmarks, benchmark_window, bear_threshold, bull_threshold
+ )
+ for index in range(len(benchmarks))
+ ]
+
+
+def _regime_for_bar(
+ index: int,
+ benchmarks: Sequence[float | None],
+ benchmark_window: int,
+ bear_threshold: float,
+ bull_threshold: float,
+) -> str:
+ if index < benchmark_window:
+ return REGIMES[2] # warm-up: not enough history for a rolling label
+ current = benchmarks[index]
+ anchor = benchmarks[index - benchmark_window]
+ if (
+ current is None
+ or anchor is None
+ or not math.isfinite(current)
+ or not math.isfinite(anchor)
+ or anchor <= 0
+ ):
+ return REGIMES[2]
+ rolling_return = current / anchor - 1.0
+ if rolling_return <= bear_threshold:
+ return REGIMES[0] # bear_market
+ if rolling_return >= bull_threshold:
+ return REGIMES[1] # bull_market
+ return REGIMES[2]
+
+
+# ---------------------------------------------------------------------------
+# Per-regime metric helpers
+# ---------------------------------------------------------------------------
+
+
+def _month_spans(bar_indices: Sequence[int], dates: Sequence[date]) -> tuple[str, ...]:
+ """Contiguous runs of regime bars as ``YYYY-MM to YYYY-MM`` strings."""
+ if not bar_indices:
+ return ()
+ spans: list[str] = []
+ run_start = previous = bar_indices[0]
+ for index in bar_indices[1:]:
+ if index == previous + 1:
+ previous = index
+ continue
+ spans.append(f"{dates[run_start]:%Y-%m} to {dates[previous]:%Y-%m}")
+ run_start = previous = index
+ spans.append(f"{dates[run_start]:%Y-%m} to {dates[previous]:%Y-%m}")
+ return tuple(spans)
+
+
+def _bar_returns(bar_indices: Sequence[int], series: Sequence[float]) -> list[float]:
+ """Per-bar simple returns for the given bars (previous bar may be any regime)."""
+ returns: list[float] = []
+ for index in bar_indices:
+ if index <= 0:
+ continue
+ previous = series[index - 1]
+ current = series[index]
+ if previous <= 0 or not math.isfinite(current):
+ continue
+ returns.append(current / previous - 1.0)
+ return returns
+
+
+def _compounded(returns: Sequence[float]) -> float:
+ """Compounded return from per-bar simple returns (empty product → 0.0)."""
+ growth = 1.0
+ for ret in returns:
+ growth *= 1.0 + ret
+ return growth - 1.0
+
+
+def _max_drawdown(
+ bar_indices: Sequence[int], equities: Sequence[float]
+) -> float | None:
+ """Peak-to-trough drawdown of strategy equity across the regime bars."""
+ peak: float | None = None
+ max_dd: float | None = None
+ for index in bar_indices:
+ equity = equities[index]
+ if not math.isfinite(equity) or equity <= 0:
+ continue
+ if peak is None or equity > peak:
+ peak = equity
+ if peak is None or peak <= 0:
+ continue
+ drawdown = equity / peak - 1.0
+ if max_dd is None or drawdown < max_dd:
+ max_dd = drawdown
+ if max_dd is None:
+ return None
+ return min(0.0, max_dd)
+
+
+def _resolve_position_size(
+ explicit: float | None, exposures: Sequence[float]
+) -> float | None:
+ """Explicit sizing wins; otherwise the mean recorded exposure; else unknown."""
+ if explicit is not None:
+ size = parse_finite_float(explicit)
+ if size is None or size <= 0:
+ logger.warning(
+ "invalid explicit position_size %r; treating as unknown", explicit
+ )
+ return None
+ return size
+ if exposures:
+ mean_exposure = statistics.fmean(exposures)
+ if math.isfinite(mean_exposure) and mean_exposure > 0:
+ return mean_exposure
+ return None
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def compute_evidence_for_run(
+ strategy_id: str,
+ run_dir: str | Path,
+ *,
+ benchmark_window: int = DEFAULT_BENCHMARK_WINDOW,
+ bear_threshold: float = DEFAULT_BEAR_THRESHOLD,
+ bull_threshold: float = DEFAULT_BULL_THRESHOLD,
+ position_size: float | None = None,
+ today: str | None = None,
+) -> list[EvidenceRow]:
+ """Compute per-regime evidence rows from one run's artifact directory.
+
+ Returns ``[]`` (with a warning) whenever the required artifacts are
+ absent or unusable — the harness never fabricates missing data.
+ """
+ if benchmark_window <= 0:
+ raise ValueError("benchmark_window must be a positive integer")
+ if bear_threshold >= bull_threshold:
+ raise ValueError("bear_threshold must be strictly below bull_threshold")
+
+ run_path = Path(run_dir)
+ trades_path = run_path / "artifacts" / "trades.csv"
+ equity_path = run_path / "artifacts" / "equity.csv"
+ if not trades_path.is_file() or not equity_path.is_file():
+ logger.warning(
+ "strategy %s: missing trades.csv and/or equity.csv under %s — "
+ "no evidence computed (honest empty, nothing fabricated)",
+ strategy_id,
+ run_path / "artifacts",
+ )
+ return []
+
+ activity = read_trade_activity(trades_path)
+ if activity is None or not activity[0]:
+ logger.warning(
+ "strategy %s: trades.csv unusable or empty — no evidence computed",
+ strategy_id,
+ )
+ return []
+ trade_dates, max_concurrent = activity
+ series = read_equity_series(equity_path)
+ if series is None:
+ logger.warning(
+ "strategy %s: equity.csv unusable or empty — no evidence computed",
+ strategy_id,
+ )
+ return []
+ dates, equities, benchmarks, exposures = series
+
+ regime_per_bar = _label_regimes(
+ benchmarks, benchmark_window, bear_threshold, bull_threshold
+ )
+
+ # Bucket trades into the regime of the most recent bar on/before their date.
+ trades_per_regime: dict[str, int] = {}
+ unlabeled_trades = 0
+ for trade_date in trade_dates:
+ bar_index = bisect.bisect_right(dates, trade_date) - 1
+ if bar_index < 0:
+ unlabeled_trades += 1 # trade predates the equity window
+ continue
+ regime = regime_per_bar[bar_index]
+ trades_per_regime[regime] = trades_per_regime.get(regime, 0) + 1
+ if unlabeled_trades:
+ logger.info(
+ "strategy %s: %d trade(s) predate the equity window and were excluded",
+ strategy_id,
+ unlabeled_trades,
+ )
+
+ resolved_size = _resolve_position_size(position_size, exposures)
+ breakeven_caveat = _breakeven_caveat(max_concurrent)
+ last_verified = (
+ today if isinstance(today, str) and today else date.today().isoformat()
+ )
+ regime_definition = describe_regime_definition(
+ benchmark_window, bear_threshold, bull_threshold
+ )
+ provenance = str(run_dir)
+
+ rows: list[EvidenceRow] = []
+ for regime in REGIMES:
+ trades_in_regime = trades_per_regime.get(regime, 0)
+ if trades_in_regime < 1:
+ continue
+ bar_indices = [i for i, label in enumerate(regime_per_bar) if label == regime]
+
+ strategy_returns = _bar_returns(bar_indices, equities)
+ compounded_return = _compounded(strategy_returns)
+
+ benchmark_compounded: float | None = None
+ if all(value is not None for value in benchmarks):
+ benchmark_returns = _bar_returns(bar_indices, benchmarks) # type: ignore[arg-type]
+ benchmark_compounded = _compounded(benchmark_returns)
+ excess = (
+ compounded_return - benchmark_compounded
+ if benchmark_compounded is not None
+ else None
+ )
+
+ sharpe: float | None = None
+ if len(strategy_returns) >= 2:
+ stdev = statistics.stdev(strategy_returns)
+ if math.isfinite(stdev) and stdev > 0:
+ sharpe = (
+ statistics.fmean(strategy_returns)
+ / stdev
+ * math.sqrt(SHARPE_ANNUALIZATION_BARS)
+ )
+
+ max_dd = _max_drawdown(bar_indices, equities)
+ date_ranges = _month_spans(bar_indices, dates)
+
+ if breakeven_caveat is None:
+ breakeven = breakeven_fee_bps(
+ compounded_return, trades_in_regime, resolved_size
+ )
+ cost_sensitive = (
+ breakeven is not None and breakeven < COST_SENSITIVE_BREAKEVEN_BPS
+ )
+ else:
+ # Multi-position (or undetectable concurrency): the aggregate
+ # breakeven is structurally invalid, so null it fail-closed
+ # instead of storing a wrong number (issue #969, sergio12S).
+ breakeven = None
+ cost_sensitive = False
+ coverage_days = coverage_days_from_ranges(date_ranges)
+ quality = classify_quality(trades_in_regime, coverage_days)
+ warnings = build_warnings(
+ trades_in_regime, coverage_days, breakeven, quality, cost_sensitive
+ )
+ if breakeven_caveat is not None:
+ warnings = (*warnings, breakeven_caveat)
+
+ rows.append(
+ EvidenceRow(
+ strategy_id=strategy_id,
+ regime=regime,
+ trades_in_regime=trades_in_regime,
+ position_size=resolved_size,
+ return_in_regime=compounded_return,
+ benchmark_in_regime=benchmark_compounded,
+ excess_in_regime=excess,
+ sharpe_in_regime=sharpe,
+ max_drawdown_in_regime=max_dd,
+ date_ranges=date_ranges,
+ breakeven_fee_bps=breakeven,
+ cost_sensitive=cost_sensitive,
+ evidence_quality=quality,
+ warnings=warnings,
+ last_verified=last_verified,
+ evidence_stage=HARNESS_EVIDENCE_STAGE,
+ provenance=provenance,
+ regime_definition=regime_definition,
+ )
+ )
+ return rows
+
+
+def rebuild_evidence(runs: Sequence[Mapping], store: EvidenceStore) -> dict:
+ """Clear the store and rebuild it from a sequence of run specifications.
+
+ Each mapping needs ``strategy_id`` and ``run_dir``; an optional
+ ``position_size`` overrides exposure-derived sizing. Runs that yield no
+ computable evidence are reported in ``skipped`` with a reason — nothing
+ is invented for them.
+ """
+ skipped: list[dict] = []
+ all_rows: list[EvidenceRow] = []
+ ok_strategies: set[str] = set()
+
+ store.clear()
+
+ for index, spec in enumerate(runs):
+ if not isinstance(spec, Mapping):
+ skipped.append(
+ {
+ "run_dir": None,
+ "reason": f"run spec at index {index} is not a mapping",
+ }
+ )
+ continue
+ strategy_id = spec.get("strategy_id")
+ run_dir = spec.get("run_dir")
+ if (
+ not isinstance(strategy_id, str)
+ or not strategy_id.strip()
+ or run_dir is None
+ or not str(run_dir).strip()
+ ):
+ skipped.append(
+ {
+ "run_dir": None if run_dir is None else str(run_dir),
+ "reason": "missing strategy_id or run_dir",
+ }
+ )
+ continue
+ try:
+ rows = compute_evidence_for_run(
+ strategy_id, run_dir, position_size=spec.get("position_size")
+ )
+ except Exception as exc: # noqa: BLE001 — one bad run must not sink the rebuild
+ logger.exception(
+ "evidence computation failed for %s (%s)", strategy_id, run_dir
+ )
+ skipped.append(
+ {"run_dir": str(run_dir), "reason": f"computation failed: {exc}"}
+ )
+ continue
+ if not rows:
+ skipped.append(
+ {
+ "run_dir": str(run_dir),
+ "reason": (
+ "no computable evidence (missing/empty trades.csv or equity.csv, "
+ "or no trades labelable on the equity window)"
+ ),
+ }
+ )
+ continue
+ all_rows.extend(rows)
+ ok_strategies.add(strategy_id)
+
+ written = store.upsert_rows(all_rows)
+ return {
+ "status": "ok",
+ "runs": len(runs),
+ "strategies": len(ok_strategies),
+ "rows": written,
+ "skipped": skipped,
+ }
diff --git a/agent/src/strategy_discovery/evidence_store.py b/agent/src/strategy_discovery/evidence_store.py
new file mode 100644
index 000000000..4db96ac8e
--- /dev/null
+++ b/agent/src/strategy_discovery/evidence_store.py
@@ -0,0 +1,369 @@
+"""SQLite persistence for per-regime strategy evidence.
+
+``EvidenceStore`` is a deliberately small key/value-style store keyed on
+``(strategy_id, regime)``. It exists so the discovery facade can answer
+evidence-gated questions from durable, reproducible harness output — never
+from invented numbers. The table starts empty and is only populated by
+``evidence_harness.rebuild_evidence`` (or explicit ``upsert_rows`` calls).
+
+Connection discipline: one short-lived ``sqlite3`` connection per operation
+(context-managed), matching the read-mostly, multi-process-friendly access
+pattern of the rest of the agent. Non-finite floats (NaN/Inf) are rejected
+before they ever reach the database.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import math
+import sqlite3
+from collections.abc import Sequence
+from contextlib import contextmanager
+from pathlib import Path
+
+from src.strategy_discovery.models import (
+ EVIDENCE_STAGES,
+ QUALITY_INSUFFICIENT,
+ REGIMES,
+ EvidenceRow,
+)
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_DB_FILENAME = "strategy_discovery.db"
+
+_FLOAT_FIELDS = (
+ "position_size",
+ "return_in_regime",
+ "benchmark_in_regime",
+ "excess_in_regime",
+ "sharpe_in_regime",
+ "max_drawdown_in_regime",
+ "breakeven_fee_bps",
+)
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS strategy_regime_evidence (
+ strategy_id TEXT NOT NULL,
+ regime TEXT NOT NULL,
+ trades_in_regime INTEGER NOT NULL,
+ position_size REAL,
+ return_in_regime REAL,
+ benchmark_in_regime REAL,
+ excess_in_regime REAL,
+ sharpe_in_regime REAL,
+ max_drawdown_in_regime REAL,
+ date_ranges TEXT NOT NULL,
+ breakeven_fee_bps REAL,
+ cost_sensitive INTEGER NOT NULL DEFAULT 0,
+ evidence_quality TEXT NOT NULL,
+ warnings TEXT NOT NULL,
+ last_verified TEXT NOT NULL DEFAULT '',
+ evidence_stage TEXT NOT NULL DEFAULT 'backtest',
+ provenance TEXT NOT NULL DEFAULT '',
+ regime_definition TEXT NOT NULL DEFAULT '',
+ PRIMARY KEY (strategy_id, regime)
+)
+"""
+
+#: Columns that must exist; a cache DB missing any of them predates the
+#: provenance/stage contract and is dropped + recreated (the cache is
+#: disposable — rows only ever come from a harness rebuild).
+_REQUIRED_COLUMNS = (
+ "strategy_id",
+ "regime",
+ "trades_in_regime",
+ "position_size",
+ "return_in_regime",
+ "benchmark_in_regime",
+ "excess_in_regime",
+ "sharpe_in_regime",
+ "max_drawdown_in_regime",
+ "date_ranges",
+ "breakeven_fee_bps",
+ "cost_sensitive",
+ "evidence_quality",
+ "warnings",
+ "last_verified",
+ "evidence_stage",
+ "provenance",
+ "regime_definition",
+)
+
+_INSERT_SQL = """
+INSERT OR REPLACE INTO strategy_regime_evidence (
+ strategy_id, regime, trades_in_regime, position_size,
+ return_in_regime, benchmark_in_regime, excess_in_regime,
+ sharpe_in_regime, max_drawdown_in_regime, date_ranges,
+ breakeven_fee_bps, cost_sensitive, evidence_quality, warnings,
+ last_verified, evidence_stage, provenance, regime_definition
+) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+"""
+
+
+def _env_override_db_path() -> Path | None:
+ """Resolve the ``vibe_trading_strategy_discovery_db_path`` EnvConfig field.
+
+ The field is defined on the env schema (``src.config.env_schema``); a
+ sibling change adds it, so access happens lazily and defensively: any
+ import/resolution problem simply yields ``None`` and the caller falls back
+ to the default location. Never raises, never reads ``os.environ``
+ directly (the repository's AST CI gate forbids that here).
+ """
+ try:
+ from src.config.accessor import get_env_config
+
+ paths = get_env_config().paths
+ raw = getattr(paths, "vibe_trading_strategy_discovery_db_path", "") or ""
+ except Exception: # noqa: BLE001 — degrade to default path, never crash
+ logger.debug("strategy_discovery env override unavailable", exc_info=True)
+ return None
+ raw = raw.strip()
+ if not raw:
+ return None
+ return Path(raw).expanduser()
+
+
+def _default_db_path() -> Path:
+ """Default database location: ``<runtime-root>/strategy_discovery.db``.
+
+ Uses the shared runtime root helper (which honours ``VIBE_TRADING_HOME``)
+ when available, falling back to ``~/.vibe-trading`` otherwise.
+ """
+ try:
+ from src.config.paths import get_runtime_root
+
+ return get_runtime_root() / _DEFAULT_DB_FILENAME
+ except Exception: # noqa: BLE001 — config layer optional for this package
+ return Path.home() / ".vibe-trading" / _DEFAULT_DB_FILENAME
+
+
+def _validate_row_for_write(row: EvidenceRow) -> None:
+ """Reject rows containing NaN/Inf or otherwise unwritable values."""
+ if not isinstance(row.trades_in_regime, int) or not math.isfinite(
+ row.trades_in_regime
+ ):
+ raise ValueError(
+ f"evidence row {row.strategy_id}/{row.regime}: trades_in_regime must be a finite int"
+ )
+ for field_name in _FLOAT_FIELDS:
+ value = getattr(row, field_name)
+ if value is not None and not math.isfinite(value):
+ raise ValueError(
+ f"evidence row {row.strategy_id}/{row.regime}: "
+ f"{field_name} is non-finite ({value!r}); refusing to persist"
+ )
+
+
+class EvidenceStore:
+ """Persistent store of (strategy, regime) evidence rows.
+
+ Starts empty — no seed data ships with the package. Rows only ever come
+ from the evidence harness computing over real backtest run artifacts.
+ """
+
+ TABLE = "strategy_regime_evidence"
+
+ def __init__(self, db_path: str | Path | None = None) -> None:
+ """Open (and initialize) the evidence database.
+
+ Args:
+ db_path: Explicit database file. When ``None``, an env override
+ (``vibe_trading_strategy_discovery_db_path`` on ``EnvConfig``)
+ is consulted lazily; absent that, the default runtime-root
+ location is used. Parent directories are created.
+ """
+ if db_path is not None:
+ resolved = Path(db_path).expanduser()
+ else:
+ override = _env_override_db_path()
+ resolved = override if override is not None else _default_db_path()
+ self.db_path = resolved
+ self.db_path.parent.mkdir(parents=True, exist_ok=True)
+ with self._connect() as conn:
+ conn.execute(_SCHEMA)
+ self._migrate_stale_schema(conn)
+
+ @staticmethod
+ def _migrate_stale_schema(conn) -> None:
+ """Drop and recreate a cache DB that predates the current schema.
+
+ ``CREATE TABLE IF NOT EXISTS`` never alters an existing table, so a
+ DB written before the provenance/stage columns existed would keep
+ serving rows without them. The cache is disposable by contract, so
+ the honest response is to drop it (a rebuild regenerates every row).
+ """
+ present = {
+ record["name"]
+ for record in conn.execute(
+ f"PRAGMA table_info({EvidenceStore.TABLE})"
+ ).fetchall()
+ }
+ missing = [c for c in _REQUIRED_COLUMNS if c not in present]
+ if not missing:
+ return
+ logger.warning(
+ "strategy_discovery cache %s predates columns %s; dropping the "
+ "disposable cache so a harness rebuild can repopulate it",
+ EvidenceStore.TABLE,
+ ", ".join(missing),
+ )
+ conn.execute(f"DROP TABLE {EvidenceStore.TABLE}")
+ conn.execute(_SCHEMA)
+
+ # -- connection helpers --------------------------------------------------
+
+ @contextmanager
+ def _connect(self):
+ """Yield one short-lived connection; commit on success, rollback on error."""
+ conn = sqlite3.connect(str(self.db_path))
+ conn.row_factory = sqlite3.Row
+ try:
+ yield conn
+ except Exception:
+ conn.rollback()
+ raise
+ else:
+ conn.commit()
+ finally:
+ conn.close()
+
+ # -- writes --------------------------------------------------------------
+
+ def upsert_rows(self, rows: Sequence[EvidenceRow]) -> int:
+ """Insert or replace evidence rows. Returns the number of rows written.
+
+ Raises:
+ ValueError: When any row carries a NaN/Inf numeric field.
+ """
+ count = 0
+ with self._connect() as conn:
+ for row in rows:
+ _validate_row_for_write(row)
+ conn.execute(
+ _INSERT_SQL,
+ (
+ row.strategy_id,
+ row.regime,
+ row.trades_in_regime,
+ row.position_size,
+ row.return_in_regime,
+ row.benchmark_in_regime,
+ row.excess_in_regime,
+ row.sharpe_in_regime,
+ row.max_drawdown_in_regime,
+ json.dumps(list(row.date_ranges), ensure_ascii=False),
+ row.breakeven_fee_bps,
+ 1 if row.cost_sensitive else 0,
+ row.evidence_quality,
+ json.dumps(list(row.warnings), ensure_ascii=False),
+ row.last_verified,
+ row.evidence_stage,
+ row.provenance,
+ row.regime_definition,
+ ),
+ )
+ count += 1
+ return count
+
+ def clear(self) -> None:
+ """Delete every evidence row (used by harness rebuilds)."""
+ with self._connect() as conn:
+ conn.execute(f"DELETE FROM {self.TABLE}")
+
+ # -- reads ---------------------------------------------------------------
+
+ def get_rows(
+ self,
+ strategy_id: str | None = None,
+ regime: str | None = None,
+ ) -> list[EvidenceRow]:
+ """Read evidence rows, optionally filtered, ordered by (strategy_id, regime)."""
+ clauses: list[str] = []
+ params: list[object] = []
+ if strategy_id is not None:
+ clauses.append("strategy_id = ?")
+ params.append(strategy_id)
+ if regime is not None:
+ clauses.append("regime = ?")
+ params.append(regime)
+ where = f"WHERE {' AND '.join(clauses)}" if clauses else ""
+ sql = (
+ f"SELECT * FROM {self.TABLE} {where} " "ORDER BY strategy_id, regime"
+ ).strip()
+ rows: list[EvidenceRow] = []
+ with self._connect() as conn:
+ for record in conn.execute(sql, params).fetchall():
+ row = self._row_from_record(record)
+ if row is None:
+ continue
+ rows.append(row)
+ return rows
+
+ def strategy_ids(self) -> list[str]:
+ """Distinct strategy ids that have evidence, sorted."""
+ sql = f"SELECT DISTINCT strategy_id FROM {self.TABLE} ORDER BY strategy_id"
+ with self._connect() as conn:
+ return [record["strategy_id"] for record in conn.execute(sql).fetchall()]
+
+ def row_count(self) -> int:
+ """Total number of stored evidence rows."""
+ with self._connect() as conn:
+ record = conn.execute(f"SELECT COUNT(*) AS n FROM {self.TABLE}").fetchone()
+ return int(record["n"])
+
+ # -- conversion ----------------------------------------------------------
+
+ @staticmethod
+ def _row_from_record(record: sqlite3.Row) -> EvidenceRow | None:
+ """Convert a database record back into an ``EvidenceRow``.
+
+ Returns ``None`` for records whose regime is outside ``REGIMES``.
+ Such rows can only reach the store through external tampering (the
+ write path validates regimes via ``EvidenceRow``); the honest
+ behaviour for a never-invent store is to drop them from reads rather
+ than remap onto a documented regime and present fabricated state.
+ """
+ regime = record["regime"]
+ if regime not in REGIMES:
+ logger.warning(
+ "evidence row %s carries unknown regime %r; skipping it "
+ "(possible externally tampered evidence database)",
+ record["strategy_id"],
+ regime,
+ )
+ return None
+ keys = set(record.keys())
+ stage = record["evidence_stage"] if "evidence_stage" in keys else "backtest"
+ if stage not in EVIDENCE_STAGES:
+ logger.warning(
+ "evidence row %s carries unknown evidence_stage %r; "
+ "skipping it (possible externally tampered evidence database)",
+ record["strategy_id"],
+ stage,
+ )
+ return None
+ return EvidenceRow(
+ strategy_id=record["strategy_id"],
+ regime=regime,
+ trades_in_regime=int(record["trades_in_regime"]),
+ position_size=record["position_size"],
+ return_in_regime=record["return_in_regime"],
+ benchmark_in_regime=record["benchmark_in_regime"],
+ excess_in_regime=record["excess_in_regime"],
+ sharpe_in_regime=record["sharpe_in_regime"],
+ max_drawdown_in_regime=record["max_drawdown_in_regime"],
+ date_ranges=tuple(json.loads(record["date_ranges"] or "[]")),
+ breakeven_fee_bps=record["breakeven_fee_bps"],
+ cost_sensitive=bool(record["cost_sensitive"]),
+ evidence_quality=record["evidence_quality"] or QUALITY_INSUFFICIENT,
+ warnings=tuple(json.loads(record["warnings"] or "[]")),
+ last_verified=record["last_verified"] or "",
+ evidence_stage=stage,
+ provenance=(record["provenance"] if "provenance" in keys else "") or "",
+ regime_definition=(
+ record["regime_definition"] if "regime_definition" in keys else ""
+ )
+ or "",
+ )
diff --git a/agent/src/strategy_discovery/facade.py b/agent/src/strategy_discovery/facade.py
new file mode 100644
index 000000000..a14a0a4ca
--- /dev/null
+++ b/agent/src/strategy_discovery/facade.py
@@ -0,0 +1,501 @@
+"""Evidence-gated facade over Alpha Zoo and the SDM strategy store.
+
+``StrategyDiscoveryFacade`` unifies the two strategy surfaces (Alpha Zoo
+registry + Strategy Development Manager store) behind one read-only catalog
+and answers per-regime questions **only from harness-computed evidence**. It
+never invents performance numbers: when the evidence table is empty it says
+so, and when a dependency degrades (registry failed to load, store
+unreachable) it logs a warning and returns an honest partial result instead
+of raising.
+
+Heavy dependencies (``src.factors.registry``, ``src.strategy_store``) are
+imported lazily inside methods — module import stays cheap and tests can
+inject fakes through the constructor.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import logging
+import math
+from typing import Any
+
+from src.strategy_discovery.evidence_store import EvidenceStore
+from src.strategy_discovery.models import (
+ BORDERLINE_BREAKEVEN_BPS,
+ BORDERLINE_COVERAGE_BUFFER_DAYS,
+ BORDERLINE_TRADE_BUFFER,
+ MIN_COVERAGE_DAYS,
+ MIN_TRADES,
+ QUALITY_ORDER,
+ REGIMES,
+ StrategySummary,
+ coverage_days_from_ranges,
+)
+
+logger = logging.getLogger(__name__)
+
+_VALID_SOURCES = ("alpha_zoo", "sdm")
+
+#: Upper bound used when draining the SDM artifact list for catalog display.
+_SDM_SCAN_LIMIT = 100_000
+
+#: Extra warning appended to rows that pass every filter but sit inside the
+#: #969 adversarial buffer bands. Verbatim contract text — tools match it.
+_BORDERLINE_WARNING = (
+ "borderline-evidence: just inside one or more thresholds — "
+ "cite the raw figures, not the verdict"
+)
+
+#: Note attached to query results when the evidence table is completely empty.
+#: Honest wording: there is NO user-runnable CLI/workflow that populates the
+#: store — rows land only via the evidence harness library API.
+_EMPTY_EVIDENCE_NOTE = (
+ "No per-regime evidence computed yet. The evidence store is populated only "
+ "by the evidence harness library API "
+ "(src.strategy_discovery.evidence_harness.rebuild_evidence over "
+ "reproducible run artifacts); automated workflow wiring is still pending, "
+ "so until then rows come from harness runs executed by developers/"
+ "integrators. The facade refuses to assess regimes without evidence."
+)
+
+
+def _error(message: str) -> dict[str, Any]:
+ """Standard error envelope shared with the other agent tool modules."""
+ return {"status": "error", "error": message}
+
+
+def _json_safe(value: Any) -> Any:
+ """Deep-copy *value* replacing non-finite floats with ``None``.
+
+ Guarantees every returned envelope serializes under strict JSON (no
+ NaN/Infinity tokens) without silently shifting finite numbers.
+ """
+ if isinstance(value, dict):
+ return {key: _json_safe(item) for key, item in value.items()}
+ if isinstance(value, (list, tuple)):
+ return [_json_safe(item) for item in value]
+ if isinstance(value, float) and not math.isfinite(value):
+ return None
+ return value
+
+
+def _is_int(value: Any) -> bool:
+ """True for real integers only (bool is explicitly excluded)."""
+ return isinstance(value, int) and not isinstance(value, bool)
+
+
+class StrategyDiscoveryFacade:
+ """Read-only unified discovery surface over Alpha Zoo + SDM + evidence."""
+
+ def __init__(
+ self,
+ evidence_store: EvidenceStore | None = None,
+ sdm_store=None,
+ alpha_registry=None,
+ ) -> None:
+ """Wire the facade. Every dependency is injectable for tests.
+
+ Args:
+ evidence_store: Evidence backend. Default constructed lazily on
+ first use (``EvidenceStore()``).
+ sdm_store: SDM artifact store. Default resolved lazily through
+ ``src.strategy_store._shared.get_store()``.
+ alpha_registry: Alpha Zoo registry. Default resolved lazily via
+ the process-wide shared
+ ``src.factors.registry.get_default_registry()`` singleton —
+ constructing a ``Registry()`` per facade instance would re-run
+ the AST scan of every zoo module (~0.85s) on each construction.
+ """
+ self._evidence_store = evidence_store
+ self._sdm_store = sdm_store
+ self._alpha_registry = alpha_registry
+ self._evidence_store_failed = False
+ self._sdm_failed = False
+ self._alpha_failed = False
+
+ # -- lazy dependency resolution -------------------------------------------
+
+ def _get_evidence_store(self) -> EvidenceStore | None:
+ """Return the evidence store, constructing the default lazily."""
+ if self._evidence_store is None and not self._evidence_store_failed:
+ try:
+ self._evidence_store = EvidenceStore()
+ except Exception: # noqa: BLE001 — degrade, never crash the facade
+ logger.warning(
+ "EvidenceStore default construction failed; evidence lookups "
+ "degrade to empty results",
+ exc_info=True,
+ )
+ self._evidence_store_failed = True
+ return self._evidence_store
+
+ def _get_sdm_store(self) -> Any:
+ """Return the SDM store, lazily importing the shared singleton."""
+ if self._sdm_store is None and not self._sdm_failed:
+ try:
+ # Local import; intentional — keeps module import dependency-free.
+ from src.strategy_store._shared import get_store
+
+ self._sdm_store = get_store()
+ except Exception: # noqa: BLE001 — degrade to zero SDM entries
+ logger.warning(
+ "SDM strategy store unavailable; SDM catalog entries degraded to none",
+ exc_info=True,
+ )
+ self._sdm_failed = True
+ return self._sdm_store
+
+ def _get_alpha_registry(self) -> Any:
+ """Return the Alpha Zoo registry, tolerating a failed zoo load.
+
+ The default resolution goes through the process-wide
+ ``get_default_registry()`` singleton: building a fresh ``Registry()``
+ AST-scans every zoo module (~0.85s), which must not happen per facade
+ instance. Constructor-injected registries (tests) bypass this path.
+ """
+ if self._alpha_registry is None and not self._alpha_failed:
+ try:
+ # Local import; intentional — zoo scan must never block package import.
+ from src.factors.registry import get_default_registry
+
+ self._alpha_registry = get_default_registry()
+ except Exception: # noqa: BLE001 — degrade to zero alphas
+ logger.warning(
+ "Alpha Zoo registry unavailable; alpha catalog entries degraded to none",
+ exc_info=True,
+ )
+ self._alpha_failed = True
+ return self._alpha_registry
+
+ # -- catalog construction --------------------------------------------------
+
+ @staticmethod
+ def _join_meta_list(value: Any) -> str | None:
+ """Render a meta list/tuple field as a comma-joined string (or None)."""
+ if isinstance(value, (list, tuple)) and value:
+ return ", ".join(str(item) for item in value)
+ if isinstance(value, str) and value:
+ return value
+ return None
+
+ def _alpha_description(self, meta: dict[str, Any]) -> str | None:
+ """Build a display description from alpha meta (theme + notes joined)."""
+ parts: list[str] = []
+ theme = self._join_meta_list(meta.get("theme"))
+ if theme:
+ parts.append(f"themes: {theme}")
+ notes = meta.get("notes")
+ if isinstance(notes, str) and notes.strip():
+ parts.append(notes.strip())
+ return "; ".join(parts) or None
+
+ def _alpha_summaries(self) -> list[StrategySummary]:
+ """Catalog entries for every loaded Alpha Zoo alpha (sorted)."""
+ registry = self._get_alpha_registry()
+ if registry is None:
+ return []
+ try:
+ alpha_ids = registry.list()
+ except Exception: # noqa: BLE001 — degrade to zero alphas
+ logger.warning("Alpha Zoo registry listing failed", exc_info=True)
+ return []
+
+ summaries: list[StrategySummary] = []
+ for alpha_id in alpha_ids:
+ try:
+ alpha = registry.get(alpha_id)
+ except Exception: # noqa: BLE001 — skip a broken entry, keep the rest
+ logger.warning("Alpha Zoo entry %s unreadable", alpha_id, exc_info=True)
+ continue
+ meta = getattr(alpha, "meta", None) or {}
+ summaries.append(
+ StrategySummary(
+ strategy_id=f"alpha_zoo:{alpha.id}",
+ name=meta.get("nickname") or alpha.id,
+ source="alpha_zoo",
+ description=self._alpha_description(meta),
+ status=None,
+ universe=self._join_meta_list(meta.get("universe")),
+ )
+ )
+ summaries.sort(key=lambda summary: summary.strategy_id)
+ return summaries
+
+ def _sdm_summaries(self) -> list[StrategySummary]:
+ """Catalog entries for every SDM artifact (sorted)."""
+ store = self._get_sdm_store()
+ if store is None:
+ return []
+ try:
+ try:
+ artifacts = store.list_artifacts(limit=_SDM_SCAN_LIMIT)
+ except TypeError:
+ # Injected fakes may expose a no-arg list_artifacts().
+ artifacts = store.list_artifacts()
+ except Exception: # noqa: BLE001 — degrade to zero SDM entries
+ logger.warning("SDM artifact listing failed", exc_info=True)
+ return []
+
+ summaries: list[StrategySummary] = []
+ for artifact in artifacts:
+ try:
+ status = getattr(artifact.status, "value", artifact.status)
+ signal_definition = getattr(artifact, "signal_definition", None) or None
+ summaries.append(
+ StrategySummary(
+ strategy_id=f"sdm:{artifact.id}",
+ name=str(artifact.name),
+ source="sdm",
+ description=(
+ signal_definition[:300] if signal_definition else None
+ ),
+ status=status if status is not None else None,
+ universe=getattr(artifact, "universe", None),
+ )
+ )
+ except Exception: # noqa: BLE001 — skip a broken entry, keep the rest
+ logger.warning("SDM artifact unreadable", exc_info=True)
+ continue
+ summaries.sort(key=lambda summary: summary.strategy_id)
+ return summaries
+
+ def _evidence_by_strategy(self) -> dict[str, tuple[str, ...]]:
+ """Map strategy_id -> sorted regimes that have evidence rows."""
+ store = self._get_evidence_store()
+ grouped: dict[str, set[str]] = {}
+ if store is None:
+ return {}
+ try:
+ for row in store.get_rows():
+ grouped.setdefault(row.strategy_id, set()).add(row.regime)
+ except Exception: # noqa: BLE001 — evidence enrichment is best-effort
+ logger.warning(
+ "Evidence enrichment lookup failed; omitting evidence flags",
+ exc_info=True,
+ )
+ return {}
+ return {
+ strategy_id: tuple(sorted(regimes))
+ for strategy_id, regimes in grouped.items()
+ }
+
+ # -- public API --------------------------------------------------------------
+
+ def list_strategies(
+ self,
+ limit: int = 20,
+ offset: int = 0,
+ source: str | None = None,
+ ) -> dict:
+ """Unified catalog: alpha_zoo entries first, then sdm entries."""
+ if not _is_int(limit) or limit <= 0:
+ return _error("limit must be a positive integer")
+ if not _is_int(offset) or offset < 0:
+ return _error("offset must be a non-negative integer")
+ if source is not None and source not in _VALID_SOURCES:
+ return _error(
+ f"source must be one of {'|'.join(_VALID_SOURCES)} or omitted, got {source!r}"
+ )
+
+ try:
+ items: list[StrategySummary] = []
+ if source in (None, "alpha_zoo"):
+ items.extend(self._alpha_summaries())
+ if source in (None, "sdm"):
+ items.extend(self._sdm_summaries())
+
+ evidence_map = self._evidence_by_strategy()
+ enriched: list[StrategySummary] = []
+ for summary in items:
+ regimes = evidence_map.get(summary.strategy_id, ())
+ enriched.append(
+ dataclasses.replace(
+ summary,
+ has_evidence=bool(regimes),
+ regimes_with_evidence=regimes,
+ )
+ )
+
+ page = enriched[offset : offset + limit]
+ envelope: dict[str, Any] = {
+ "status": "ok",
+ "total": len(enriched),
+ "returned": len(page),
+ "offset": offset,
+ "source": source,
+ "items": [dataclasses.asdict(summary) for summary in page],
+ }
+ return _json_safe(envelope)
+ except Exception: # noqa: BLE001 — never raise from the public facade
+ logger.exception("list_strategies failed")
+ return _error("list_strategies failed internally; see logs")
+
+ def query_strategies(
+ self,
+ regime: str | None = None,
+ min_sharpe: float | None = None,
+ min_evidence_quality: str = "adequate",
+ min_trades: int = 10,
+ cost_feasible: bool = True,
+ limit: int = 10,
+ ) -> dict:
+ """Evidence-gated query: only rows backed by stored evidence qualify."""
+ if regime is not None and regime not in REGIMES:
+ return _error(
+ f"unknown regime {regime!r}; valid regimes: {', '.join(REGIMES)}"
+ )
+ if min_evidence_quality != "any" and min_evidence_quality not in QUALITY_ORDER:
+ return _error(
+ "min_evidence_quality must be one of "
+ f"{', '.join(sorted(QUALITY_ORDER))} or 'any'"
+ )
+ if not _is_int(min_trades) or min_trades < 0:
+ return _error("min_trades must be a non-negative integer")
+ if min_sharpe is not None and not (
+ isinstance(min_sharpe, (int, float))
+ and not isinstance(min_sharpe, bool)
+ and math.isfinite(min_sharpe)
+ ):
+ return _error("min_sharpe must be a finite number or None")
+ if not _is_int(limit) or limit <= 0:
+ return _error("limit must be a positive integer")
+
+ try:
+ store = self._get_evidence_store()
+ rows = []
+ table_empty = True
+ if store is not None:
+ try:
+ rows = store.get_rows(regime=regime)
+ table_empty = store.row_count() == 0
+ except Exception: # noqa: BLE001 — degrade to no evidence
+ logger.warning(
+ "Evidence query failed; returning no evidence rows",
+ exc_info=True,
+ )
+ rows = []
+ table_empty = True
+
+ quality_floor = (
+ QUALITY_ORDER[min_evidence_quality]
+ if min_evidence_quality != "any"
+ else -1
+ )
+
+ def passes(row) -> bool:
+ if QUALITY_ORDER.get(row.evidence_quality, 0) < quality_floor:
+ return False
+ if row.trades_in_regime < min_trades:
+ return False
+ if cost_feasible and (
+ row.breakeven_fee_bps is None or row.cost_sensitive
+ ):
+ # Fail-closed: a null breakeven means the cost screen is
+ # unverifiable (multi-position run), which is not a pass.
+ return False
+ if min_sharpe is not None and (
+ row.sharpe_in_regime is None or row.sharpe_in_regime < min_sharpe
+ ):
+ return False
+ return True
+
+ filtered = [row for row in rows if passes(row)]
+ filtered.sort(
+ key=lambda row: (
+ -QUALITY_ORDER.get(row.evidence_quality, 0),
+ -row.trades_in_regime,
+ row.strategy_id,
+ row.regime,
+ )
+ )
+
+ items: list[dict[str, Any]] = []
+ for row in filtered[:limit]:
+ data = dataclasses.asdict(row)
+ borderline = self._is_borderline(row)
+ data["borderline"] = borderline
+ if borderline:
+ data["warnings"] = [*data["warnings"], _BORDERLINE_WARNING]
+ items.append(data)
+
+ envelope: dict[str, Any] = {
+ "status": "ok",
+ "count": len(filtered),
+ "returned": len(items),
+ "filters": {
+ "regime": regime,
+ "min_sharpe": min_sharpe,
+ "min_evidence_quality": min_evidence_quality,
+ "min_trades": min_trades,
+ "cost_feasible": cost_feasible,
+ },
+ "items": items,
+ }
+ if table_empty:
+ envelope["note"] = _EMPTY_EVIDENCE_NOTE
+ return _json_safe(envelope)
+ except Exception: # noqa: BLE001 — never raise from the public facade
+ logger.exception("query_strategies failed")
+ return _error("query_strategies failed internally; see logs")
+
+ def get_strategy_evidence(
+ self, strategy_id: str, regime: str | None = None
+ ) -> dict:
+ """Full per-regime evidence breakdown for one strategy."""
+ if not isinstance(strategy_id, str) or not strategy_id.strip():
+ return _error("strategy_id is required (non-empty string)")
+ if regime is not None and regime not in REGIMES:
+ return _error(
+ f"unknown regime {regime!r}; valid regimes: {', '.join(REGIMES)}"
+ )
+
+ try:
+ rows = []
+ store = self._get_evidence_store()
+ if store is not None:
+ try:
+ rows = store.get_rows(strategy_id=strategy_id, regime=regime)
+ except Exception: # noqa: BLE001 — degrade to no evidence
+ logger.warning(
+ "Evidence lookup failed for %s; returning no rows",
+ strategy_id,
+ exc_info=True,
+ )
+ rows = []
+
+ envelope: dict[str, Any] = {
+ "status": "ok",
+ "strategy_id": strategy_id,
+ "regime": regime,
+ "found": bool(rows),
+ "rows": [dataclasses.asdict(row) for row in rows],
+ }
+ if not rows:
+ scope = f" in regime {regime!r}" if regime is not None else ""
+ envelope["note"] = (
+ f"No evidence rows found for strategy_id {strategy_id!r}{scope}. "
+ "Evidence rows are written only by the evidence harness "
+ "library API over reproducible run artifacts."
+ )
+ return _json_safe(envelope)
+ except Exception: # noqa: BLE001 — never raise from the public facade
+ logger.exception("get_strategy_evidence failed")
+ return _error("get_strategy_evidence failed internally; see logs")
+
+ # -- internals ---------------------------------------------------------------
+
+ @staticmethod
+ def _is_borderline(row) -> bool:
+ """True when a passing row sits inside the #969 adversarial buffer bands."""
+ if row.trades_in_regime < MIN_TRADES + BORDERLINE_TRADE_BUFFER:
+ return True
+ if (
+ row.breakeven_fee_bps is not None
+ and row.breakeven_fee_bps < BORDERLINE_BREAKEVEN_BPS
+ ):
+ return True
+ coverage = coverage_days_from_ranges(row.date_ranges)
+ if coverage < MIN_COVERAGE_DAYS + BORDERLINE_COVERAGE_BUFFER_DAYS:
+ return True
+ return False
diff --git a/agent/src/strategy_discovery/guard.py b/agent/src/strategy_discovery/guard.py
new file mode 100644
index 000000000..d8dad3b51
--- /dev/null
+++ b/agent/src/strategy_discovery/guard.py
@@ -0,0 +1,62 @@
+"""Registration guard for the strategy-discovery tool trio.
+
+This module is the single source of truth for the Strategy Discovery routing
+text injected into the agent's Task-Routing prompt section, and for checking
+whether the three read-only discovery tools are actually registered. It is
+fail-safe by design: when any tool is missing (or the registry object does
+not quack as expected) the routing block is omitted rather than advertising
+tools the agent cannot call — the exact failure mode of the rejected #896.
+
+The module must stay dependency-free: context builders import it eagerly, so
+it may never pull in the facade, the store, or any heavy module.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+#: The three read-only discovery tools. All three must be registered before
+#: any routing text is emitted (atomic advertisement).
+STRATEGY_DISCOVERY_TOOLS = (
+ "list_strategies",
+ "query_strategies",
+ "get_strategy_evidence",
+)
+
+ROUTING_BLOCK: str = """**Strategy Discovery** — user asks what strategies exist, which fit a market regime (bear/bull/structural), or what state registered strategies are in:
+1. `list_strategies()` — unified catalog across Alpha Zoo + SDM store
+2. `query_strategies(regime=...)` — evidence-gated per-regime results; report trades, date coverage, breakeven and warnings verbatim; NEVER present insufficient or marginal evidence as a recommendation
+3. `get_strategy_evidence(strategy_id=...)` — full per-regime evidence breakdown
+Never recommend a strategy whose supporting regime evidence is missing or insufficient."""
+
+
+def tools_registered(registry: Any) -> bool:
+ """Return True when all strategy-discovery tools exist in *registry*.
+
+ Accepts any registry-like object: prefers ``registry.has(name)`` when
+ available, otherwise membership in ``registry._tools``. Errors are treated
+ as "not registered" so prompt assembly can never crash here.
+ """
+ try:
+ has = getattr(registry, "has", None)
+ if callable(has):
+ return all(bool(has(name)) for name in STRATEGY_DISCOVERY_TOOLS)
+ tools = getattr(registry, "_tools", {})
+ return all(name in tools for name in STRATEGY_DISCOVERY_TOOLS)
+ except Exception: # noqa: BLE001 — fail-safe omission, never raise
+ return False
+
+
+def routing_block(registry: Any) -> str:
+ """Routing text to splice into the Task-Routing section.
+
+ Returns :data:`ROUTING_BLOCK` only when *every* tool in
+ :data:`STRATEGY_DISCOVERY_TOOLS` is registered; otherwise ``""``. Never
+ raises — a partially wired registry simply yields no routing text.
+ """
+ try:
+ if tools_registered(registry):
+ return ROUTING_BLOCK
+ return ""
+ except Exception: # noqa: BLE001 — fail-safe omission, never raise
+ return ""
diff --git a/agent/src/strategy_discovery/models.py b/agent/src/strategy_discovery/models.py
new file mode 100644
index 000000000..e2322a8aa
--- /dev/null
+++ b/agent/src/strategy_discovery/models.py
@@ -0,0 +1,291 @@
+"""Pure data models and threshold logic for strategy-discovery evidence.
+
+This module is intentionally I/O-free so it can be imported cheaply and unit
+tested without a database or the network. It defines the two frozen dataclasses
+(``EvidenceRow``, ``StrategySummary``) that flow between the evidence store,
+the evidence harness, and the facade, plus the small set of pure helper
+functions used to classify evidence quality, compute the sizing-corrected
+breakeven fee, and derive the month-granularity date coverage span.
+
+The numeric thresholds here are the single source of truth for what counts as
+``adequate`` / ``marginal`` / ``insufficient`` evidence. The facade and the
+harness import these constants rather than re-deriving them, so the #969
+adversarial borders (buffered "borderline" bands) stay consistent everywhere.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass, field
+from datetime import date, timedelta
+
+# ---------------------------------------------------------------------------
+# Regime vocabulary
+# ---------------------------------------------------------------------------
+
+#: Canonical market-regime labels. Evidence rows must carry exactly one of
+#: these; ``EvidenceRow.__post_init__`` rejects anything else.
+REGIMES = ("bear_market", "bull_market", "structural")
+
+#: Evidence-stage ladder (issue #969 discussion, initial-d). Every row names
+#: the stage of the pipeline that produced it; today only ``backtest`` is
+#: written (the harness computes over backtest artifacts), the remaining
+#: stages are reserved so holdout/shadow/live evidence can join later
+#: without a schema change.
+EVIDENCE_STAGES = (
+ "hypothesis",
+ "backtest",
+ "holdout",
+ "shadow",
+ "live_canary",
+ "retired",
+)
+
+# ---------------------------------------------------------------------------
+# Evidence-quality ladder
+# ---------------------------------------------------------------------------
+
+QUALITY_ADEQUATE = "adequate"
+QUALITY_MARGINAL = "marginal"
+QUALITY_INSUFFICIENT = "insufficient"
+
+#: Ordering used to compare quality floors and to sort results best-first.
+QUALITY_ORDER = {
+ QUALITY_ADEQUATE: 2,
+ QUALITY_MARGINAL: 1,
+ QUALITY_INSUFFICIENT: 0,
+}
+
+# ---------------------------------------------------------------------------
+# Thresholds (single source of truth)
+# ---------------------------------------------------------------------------
+
+#: Minimum number of trades inside a regime before the evidence can rise
+#: above "insufficient".
+MIN_TRADES = 10
+
+#: Minimum calendar span (in days) of the evidence window. Below this the
+#: evidence is capped at "marginal" even with plenty of trades.
+MIN_COVERAGE_DAYS = 730
+
+#: Breakeven fee (in basis points) below which a strategy is considered too
+#: cost-sensitive to recommend without an explicit cost feasibility check.
+COST_SENSITIVE_BREAKEVEN_BPS = 5.0
+
+#: A row that passes the hard thresholds but sits inside these buffered bands
+#: is flagged "borderline" so callers cite the raw figures, not the verdict.
+BORDERLINE_TRADE_BUFFER = 5
+BORDERLINE_BREAKEVEN_BPS = 10.0
+BORDERLINE_COVERAGE_BUFFER_DAYS = 365
+
+# ---------------------------------------------------------------------------
+# Dataclasses
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class EvidenceRow:
+ """A single (strategy, regime) evidence record.
+
+ All return-like fields are decimal fractions (``0.083`` == +8.3%) so the
+ facade can render them without guessing at units. Optional fields are
+ ``None`` when the underlying artifact simply did not record them — we
+ never invent a placeholder number.
+ """
+
+ strategy_id: str
+ regime: str
+ trades_in_regime: int
+ #: Average deployed equity fraction in (0, 1]; ``None`` when unknown.
+ position_size: float | None = None
+ return_in_regime: float | None = None
+ benchmark_in_regime: float | None = None
+ excess_in_regime: float | None = None
+ sharpe_in_regime: float | None = None
+ max_drawdown_in_regime: float | None = None
+ #: Each entry is "YYYY-MM to YYYY-MM". Kept as a tuple so the dataclass
+ #: stays hashable / frozen-friendly.
+ date_ranges: tuple[str, ...] = ()
+ breakeven_fee_bps: float | None = None
+ cost_sensitive: bool = False
+ evidence_quality: str = QUALITY_INSUFFICIENT
+ warnings: tuple[str, ...] = ()
+ #: ISO date string ("YYYY-MM-DD") of the last harness verification.
+ last_verified: str = ""
+ #: Pipeline stage that produced this row; one of ``EVIDENCE_STAGES``.
+ evidence_stage: str = "backtest"
+ #: Reproducible artifact reference: the backtest run directory whose
+ #: ``artifacts/`` this row was computed from.
+ provenance: str = ""
+ #: JSON string naming the regime-labeling parameters (window, bear/bull
+ #: thresholds, Sharpe annualization) used when this row was computed.
+ regime_definition: str = ""
+
+ def __post_init__(self) -> None:
+ if self.regime not in REGIMES:
+ raise ValueError(
+ f"invalid regime {self.regime!r}; expected one of {REGIMES}"
+ )
+ if self.evidence_stage not in EVIDENCE_STAGES:
+ raise ValueError(
+ f"invalid evidence_stage {self.evidence_stage!r}; "
+ f"expected one of {EVIDENCE_STAGES}"
+ )
+
+
+@dataclass(frozen=True)
+class StrategySummary:
+ """Catalog entry surfaced by :meth:`StrategyDiscoveryFacade.list_strategies`.
+
+ ``source`` is ``"alpha_zoo"`` or ``"sdm"``. ``status`` mirrors the SDM
+ lifecycle state and is ``None`` for alpha-zoo entries, which have no
+ lifecycle.
+ """
+
+ strategy_id: str
+ name: str
+ source: str
+ description: str | None = None
+ status: str | None = None
+ universe: str | None = None
+ has_evidence: bool = False
+ regimes_with_evidence: tuple[str, ...] = field(default=())
+
+
+# ---------------------------------------------------------------------------
+# Pure helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_month_first(token: str) -> date | None:
+ """Parse a ``YYYY-MM`` token into the first day of that month."""
+ token = token.strip()
+ match = re.fullmatch(r"(\d{4})-(\d{1,2})", token)
+ if match is None:
+ return None
+ year = int(match.group(1))
+ month = int(match.group(2))
+ if not 1 <= month <= 12:
+ return None
+ return date(year, month, 1)
+
+
+def _month_last_day_anchor(start_of_month: date) -> date:
+ """Return the last calendar day of the month containing ``start_of_month``."""
+ if start_of_month.month == 12:
+ return date(start_of_month.year, 12, 31)
+ return date(start_of_month.year, start_of_month.month + 1, 1) - timedelta(days=1)
+
+
+def coverage_days_from_ranges(date_ranges) -> int:
+ """Span from the earliest range start to the latest range end, in days.
+
+ Each entry is parsed as ``"YYYY-MM to YYYY-MM"``; the span runs from the
+ first day of the earliest start month to the last day of the latest end
+ month. Malformed entries contribute nothing. Returns ``0`` when no entry
+ parses cleanly (an honest zero rather than a fabricated span).
+ """
+ min_start: date | None = None
+ max_end: date | None = None
+
+ for entry in date_ranges:
+ if not isinstance(entry, str):
+ continue
+ pieces = [p for p in re.split(r"\s+to\s+", entry.strip(), flags=re.IGNORECASE)]
+ if len(pieces) != 2:
+ continue
+ start = _parse_month_first(pieces[0])
+ end_start = _parse_month_first(pieces[1])
+ if start is None or end_start is None:
+ continue
+ end = _month_last_day_anchor(end_start)
+ if min_start is None or start < min_start:
+ min_start = start
+ if max_end is None or end > max_end:
+ max_end = end
+
+ if min_start is None or max_end is None:
+ return 0
+ return max(0, (max_end - min_start).days)
+
+
+def classify_quality(trades_in_regime: int, coverage_days: int) -> str:
+ """Map (trade count, coverage span) onto the quality ladder."""
+ if trades_in_regime < MIN_TRADES:
+ return QUALITY_INSUFFICIENT
+ if coverage_days < MIN_COVERAGE_DAYS:
+ return QUALITY_MARGINAL
+ return QUALITY_ADEQUATE
+
+
+def breakeven_fee_bps(
+ gross_return: float,
+ trades: int,
+ position_size: float | None = None,
+) -> float | None:
+ """Sizing-corrected breakeven transaction fee in basis points.
+
+ Identity (per sergio12S, #969)::
+
+ breakeven_bps = ln(1 + gross_return) / (2 * trades * position_size) * 10_000
+
+ ``position_size`` defaults to ``1.0`` (full capital deployed) when
+ ``None``. Returns ``None`` whenever the inputs are not usable (zero /
+ negative trades, a return at or below -100%, a non-positive position
+ size, or any non-finite value) rather than producing a meaningless or
+ infinite number.
+ """
+ s = 1.0 if position_size is None else position_size
+ try:
+ gross = float(gross_return)
+ n_trades = float(trades)
+ size = float(s)
+ except (TypeError, ValueError):
+ return None
+
+ if not (math.isfinite(gross) and math.isfinite(n_trades) and math.isfinite(size)):
+ return None
+ if n_trades <= 0 or gross <= -1.0 or size <= 0:
+ return None
+
+ return math.log(1.0 + gross) / (2.0 * n_trades * size) * 10_000.0
+
+
+def build_warnings(
+ trades_in_regime: int,
+ coverage_days: int,
+ breakeven: float | None,
+ quality: str,
+ cost_sensitive: bool,
+) -> tuple[str, ...]:
+ """Stable, machine-readable warning strings for an evidence row.
+
+ Prefixes are fixed tokens (``insufficient-trades:``, ``short-coverage:``,
+ ``cost-sensitive:``) so downstream tools can match them without parsing
+ prose. Only conditions that actually hold emit a warning.
+ """
+ warnings: list[str] = []
+
+ if trades_in_regime < MIN_TRADES:
+ warnings.append(
+ f"insufficient-trades: {trades_in_regime} < {MIN_TRADES} trades in regime"
+ )
+
+ if coverage_days < MIN_COVERAGE_DAYS:
+ warnings.append(
+ f"short-coverage: {coverage_days} days < {MIN_COVERAGE_DAYS} day window"
+ )
+
+ if cost_sensitive:
+ breakeven_text = (
+ f"{breakeven:.2f} bps"
+ if isinstance(breakeven, float) and math.isfinite(breakeven)
+ else "unknown"
+ )
+ warnings.append(
+ f"cost-sensitive: breakeven {breakeven_text} "
+ f"below {COST_SENSITIVE_BREAKEVEN_BPS:.1f} bps threshold"
+ )
+
+ return tuple(warnings)
diff --git a/agent/src/strategy_discovery/run_artifacts.py b/agent/src/strategy_discovery/run_artifacts.py
new file mode 100644
index 000000000..656aec3d2
--- /dev/null
+++ b/agent/src/strategy_discovery/run_artifacts.py
@@ -0,0 +1,300 @@
+"""Read-only parsing of backtest run artifacts for the evidence harness.
+
+Pure CSV I/O over ``run_dir/artifacts`` — no network, no invention. The
+harness reads only what a reproducible run actually recorded.
+
+Real engine schema (``backtest/engines/base.py::_write_artifacts``, the
+writer every reproducible run goes through):
+
+* ``trades.csv`` — columns ``timestamp, code, side, price, qty, reason,
+ pnl, holding_days, return_pct`` with TWO rows per round trip: an entry
+ row (``reason="signal"``, ``pnl=0.0``, ``holding_days=0``) followed by
+ the exit row carrying the realized ``pnl``.
+* ``equity.csv`` — date column ``timestamp`` (the engine's index name)
+ plus ``ret, equity, drawdown, benchmark_equity, active_ret``.
+
+Entry/exit convention. The engine writes no dedicated marker column, and
+``reason`` is not one either — exits can also carry ``reason="signal"``
+(the base engine closes positions on signal). This reader therefore
+mirrors the repo's own artifact-reload convention in
+``backtest/validation.py``: a row is a closed-trade (exit) row iff its
+``pnl`` parses to a nonzero finite value, while ``pnl == 0.0`` rows are
+entry rows. Files with no zero-pnl rows at all are treated as legacy
+one-row-per-trade artifacts where every dated row is a meaningful closed
+trade. Documented limitation (shared with ``validation.py``): an
+exact-break-even exit (``pnl == 0.0``) is indistinguishable from an entry
+row and is not counted as a round trip.
+
+Legacy artifacts keep parsing through column aliases (``date`` for
+``timestamp``, ``benchmark`` for ``benchmark_equity``). Unusable files —
+missing date/equity columns, decode errors, OS errors, malformed CSV —
+return ``None`` with a logged warning instead of raising; malformed rows
+are skipped rather than guessed at.
+"""
+
+from __future__ import annotations
+
+import csv
+import logging
+import math
+from collections.abc import Sequence
+from datetime import date, datetime
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+#: Accepted names for the trade-date column in ``trades.csv``. The engine
+#: names it ``timestamp``; the remaining names are legacy aliases kept for
+#: older artifacts. Real engine name first, legacy after.
+TRADE_DATE_ALIASES = ("timestamp", "date", "trade_date", "exit_date")
+
+#: Accepted names for the date column in ``equity.csv``. The engine writes
+#: its date index as ``timestamp``; ``date`` is the legacy alias.
+EQUITY_DATE_ALIASES = ("timestamp", "date")
+
+#: Accepted names for the strategy equity column in ``equity.csv``.
+EQUITY_COLUMN_ALIASES = ("equity", "nav", "value")
+
+#: Accepted names for the benchmark column in ``equity.csv``. The engine
+#: writes ``benchmark_equity``; ``benchmark`` is the legacy alias.
+_BENCHMARK_ALIASES = ("benchmark_equity", "benchmark")
+_EXPOSURE_ALIASES = ("exposure",)
+
+#: Engine marker columns in ``trades.csv`` used for entry/exit detection
+#: and per-code position pairing.
+_PNL_ALIASES = ("pnl",)
+_CODE_ALIASES = ("code",)
+
+#: Errors that mean "artifact unreadable" rather than "bug": non-UTF-8
+#: bytes, missing files/permissions, and malformed CSV (NUL bytes, broken
+#: quoting, oversized fields). Readers degrade to ``None`` on all of these.
+_UNREADABLE_ERRORS = (OSError, UnicodeDecodeError, csv.Error)
+
+
+def parse_iso_date(token: object) -> date | None:
+ """Best-effort ISO date parse; ``None`` when the token is unusable."""
+ text = str(token or "").strip()
+ if not text:
+ return None
+ try:
+ return date.fromisoformat(text[:10])
+ except ValueError:
+ pass
+ try:
+ return datetime.strptime(text[:10], "%Y%m%d").date()
+ except ValueError:
+ return None
+
+
+def parse_finite_float(token: object) -> float | None:
+ """Parse a float; ``None`` for missing/malformed/non-finite tokens."""
+ try:
+ value = float(str(token).strip())
+ except (TypeError, ValueError):
+ return None
+ return value if math.isfinite(value) else None
+
+
+def _find_column(fieldnames: Sequence[str], aliases: Sequence[str]) -> str | None:
+ """Match a header name against aliases, case-insensitively."""
+ normalized = {name.strip().lower(): name for name in fieldnames if name}
+ for alias in aliases:
+ if alias in normalized:
+ return normalized[alias]
+ return None
+
+
+def _max_concurrent_positions(intervals: Sequence[tuple[date, date]]) -> int:
+ """Peak number of overlapping ``(entry, exit)`` holding intervals.
+
+ Entries are processed before exits on the same date, so a same-day
+ round trip still registers as one open position. That choice is
+ deliberate: the feed into the multi-position breakeven caveat should
+ over-flag rather than under-flag.
+ """
+ if not intervals:
+ return 0
+ events: list[tuple[date, int]] = []
+ for entry_date, exit_date in intervals:
+ start, end = sorted((entry_date, exit_date))
+ events.append((start, 1))
+ events.append((end, -1))
+ # Same-date ordering: +1 (entry) before -1 (exit).
+ events.sort(key=lambda event: (event[0], -event[1]))
+ current = peak = 0
+ for _, delta in events:
+ current += delta
+ if current > peak:
+ peak = current
+ return peak
+
+
+def read_trade_activity(path: Path) -> tuple[list[date], int | None] | None:
+ """Round-trip exit dates and peak concurrency from ``trades.csv``.
+
+ Returns ``(exit_dates, max_concurrent)``:
+
+ * ``exit_dates`` — one date per closed round trip, sorted. Engine
+ artifacts hold two rows per round trip (entry row ``pnl=0.0`` plus
+ exit row with realized pnl); only exit rows count, so a round trip
+ is counted once, never twice. Legacy one-row-per-trade artifacts
+ (no zero-pnl marker rows) count every dated row.
+ * ``max_concurrent`` — peak simultaneously open positions derived
+ from the entry/exit pairs (FIFO per code, matching the engine's
+ one-position-per-symbol book), or ``None`` when the file lacks the
+ zero-pnl entry marker and concurrency is undetectable.
+
+ Returns ``None`` when the file is unusable: no date column, decode /
+ OS / CSV errors, or no usable content. Rows with unparseable dates
+ are skipped, never fatal. See the module docstring for the entry/exit
+ marker convention.
+ """
+ try:
+ with path.open(newline="", encoding="utf-8-sig") as handle:
+ reader = csv.DictReader(handle)
+ fieldnames = reader.fieldnames or []
+ date_column = _find_column(fieldnames, TRADE_DATE_ALIASES)
+ if date_column is None:
+ logger.warning(
+ "trades.csv at %s has no date column (expected one of %s)",
+ path,
+ ", ".join(TRADE_DATE_ALIASES),
+ )
+ return None
+ pnl_column = _find_column(fieldnames, _PNL_ALIASES)
+ code_column = _find_column(fieldnames, _CODE_ALIASES)
+
+ rows: list[tuple[date, str, float | None]] = []
+ for record in reader:
+ trade_date = parse_iso_date(record.get(date_column))
+ if trade_date is None:
+ continue # reject unparseable dates row-by-row
+ pnl = (
+ parse_finite_float(record.get(pnl_column))
+ if pnl_column is not None
+ else None
+ )
+ code = (
+ str(record.get(code_column) or "").strip()
+ if code_column is not None
+ else ""
+ )
+ rows.append((trade_date, code, pnl))
+ except _UNREADABLE_ERRORS as exc:
+ logger.warning(
+ "trades.csv at %s is unreadable (%s); treated as unusable", path, exc
+ )
+ return None
+
+ if not rows:
+ return [], None
+
+ # The engine writes entry rows with pnl=0.0 and exit rows with realized
+ # pnl (backtest/engines/base.py::_write_artifacts); backtest/validation.py
+ # reloads the same artifacts with `pnl != 0` as the exit-row filter. When
+ # no marker row exists, every dated row is a closed trade (legacy
+ # one-row-per-trade artifacts) and concurrency is undetectable.
+ has_entry_marker = any(pnl is not None and pnl == 0.0 for _, _, pnl in rows)
+ if not has_entry_marker:
+ return sorted(trade_date for trade_date, _, _ in rows), None
+
+ exit_dates: list[date] = []
+ open_entries: dict[str, list[date]] = {}
+ intervals: list[tuple[date, date]] = []
+ for trade_date, code, pnl in rows:
+ if pnl is None:
+ continue # unclassifiable without a usable pnl marker
+ if pnl != 0.0:
+ # Exit row: one closed round trip.
+ exit_dates.append(trade_date)
+ pending = open_entries.get(code)
+ if pending:
+ intervals.append((pending.pop(0), trade_date))
+ else:
+ # Entry row (engine marker pnl == 0.0).
+ open_entries.setdefault(code, []).append(trade_date)
+ exit_dates.sort()
+ return exit_dates, _max_concurrent_positions(intervals)
+
+
+def read_trade_dates(path: Path) -> list[date] | None:
+ """Closed-trade dates from ``trades.csv``; ``None`` when unusable.
+
+ One date per round trip: engine artifacts carry entry+exit row pairs
+ and only exit rows count. Thin wrapper around
+ :func:`read_trade_activity`, which documents the marker convention
+ and the legacy one-row-per-trade behavior.
+ """
+ activity = read_trade_activity(path)
+ if activity is None:
+ return None
+ exit_dates, _ = activity
+ return exit_dates
+
+
+def read_equity_series(
+ path: Path,
+) -> tuple[list[date], list[float], list[float | None], list[float]] | None:
+ """(dates, equity, benchmark-or-None-per-bar, exposures) from ``equity.csv``.
+
+ Column aliases: the date column is ``timestamp`` in engine artifacts
+ (legacy ``date`` still parses); the benchmark column is
+ ``benchmark_equity`` in engine artifacts (legacy ``benchmark`` still
+ parses). Rows without a parseable date and finite positive equity
+ value are skipped. Returns ``None`` when the file lacks a usable
+ date/equity column pair, contains no usable rows, or is unreadable
+ (decode / OS / CSV errors degrade instead of raising).
+ """
+ try:
+ with path.open(newline="", encoding="utf-8-sig") as handle:
+ reader = csv.DictReader(handle)
+ fieldnames = reader.fieldnames or []
+ date_column = _find_column(fieldnames, EQUITY_DATE_ALIASES)
+ equity_column = _find_column(fieldnames, EQUITY_COLUMN_ALIASES)
+ if date_column is None or equity_column is None:
+ logger.warning(
+ "equity.csv at %s lacks a date/equity column pair "
+ "(date aliases: %s; equity aliases: %s)",
+ path,
+ ", ".join(EQUITY_DATE_ALIASES),
+ ", ".join(EQUITY_COLUMN_ALIASES),
+ )
+ return None
+ benchmark_column = _find_column(fieldnames, _BENCHMARK_ALIASES)
+ exposure_column = _find_column(fieldnames, _EXPOSURE_ALIASES)
+
+ records: dict[date, tuple[float, float | None, float | None]] = {}
+ for record in reader:
+ bar_date = parse_iso_date(record.get(date_column))
+ equity = parse_finite_float(record.get(equity_column))
+ if bar_date is None or equity is None or equity <= 0:
+ continue
+ benchmark = (
+ parse_finite_float(record.get(benchmark_column))
+ if benchmark_column is not None
+ else None
+ )
+ exposure = (
+ parse_finite_float(record.get(exposure_column))
+ if exposure_column is not None
+ else None
+ )
+ if bar_date in records: # duplicate dates: keep the first bar
+ continue
+ records[bar_date] = (equity, benchmark, exposure)
+ except _UNREADABLE_ERRORS as exc:
+ logger.warning(
+ "equity.csv at %s is unreadable (%s); treated as unusable", path, exc
+ )
+ return None
+
+ if not records:
+ return None
+ ordered = sorted(records.items())
+ dates = [bar_date for bar_date, _ in ordered]
+ equities = [values[0] for _, values in ordered]
+ benchmarks = [values[1] for _, values in ordered]
+ exposures = [
+ values[2] for _, values in ordered if values[2] is not None and values[2] > 0
+ ]
+ return dates, equities, benchmarks, exposures
diff --git a/agent/src/tools/strategy_discovery_tool.py b/agent/src/tools/strategy_discovery_tool.py
new file mode 100644
index 000000000..460026c0e
--- /dev/null
+++ b/agent/src/tools/strategy_discovery_tool.py
@@ -0,0 +1,338 @@
+"""Strategy-discovery agent tools: evidence-gated read-only discovery surface.
+
+Three tools — ``list_strategies`` / ``query_strategies`` /
+``get_strategy_evidence`` — expose the Strategy Discovery facade over the
+Alpha Zoo registry and the SDM strategy store. The surface is evidence-gated:
+strategies carry computed per-regime evidence rows instead of boolean
+scenario tags, and anything below the evidence thresholds is flagged
+``insufficient`` / ``marginal`` rather than recommended.
+
+All three tools are read-only. The facade is constructed lazily inside each
+``execute()`` (never at import time), parameter types are coerced/validated
+defensively (bad input yields an error envelope, never a traceback), and any
+unexpected exception is wrapped into the standard ``{"status": "error", ...}``
+envelope.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from src.agent.tools import BaseTool
+
+logger = logging.getLogger(__name__)
+
+# Documented evidence-quality ladder. "any" only removes the quality floor;
+# the other filters (min_trades, cost_feasible, min_sharpe) still apply, so
+# it does NOT literally keep every stored row. The facade interprets levels.
+_EVIDENCE_QUALITIES = ("adequate", "marginal", "insufficient", "any")
+
+#: Length cap for free-text string parameters. Values are identifiers
+#: (e.g. "alpha_zoo:<id>"), so anything larger is malformed or hostile.
+_MAX_STRING_PARAM_CHARS = 500
+
+
+def _err(msg: str) -> str:
+ return json.dumps({"status": "error", "error": msg}, ensure_ascii=False)
+
+
+def _get_facade() -> Any:
+ """Construct the facade lazily so importing this module never touches the
+ strategy-discovery storage layer until a tool actually runs."""
+ from src.strategy_discovery import StrategyDiscoveryFacade
+
+ return StrategyDiscoveryFacade()
+
+
+def _envelope(result: Any) -> str:
+ """Serialize a facade envelope defensively.
+
+ The facade contract returns ``{"status": "ok", ...}`` or
+ ``{"status": "error", "error": ...}`` dicts; anything else is wrapped
+ so the agent always receives parseable JSON.
+ """
+ if not isinstance(result, dict):
+ result = {"status": "ok", "result": result}
+ return json.dumps(result, ensure_ascii=False)
+
+
+def _coerce_int(value: Any, name: str, default: int) -> int:
+ """Coerce an integer parameter; raise ``ValueError`` on bad input."""
+ if value is None:
+ return default
+ if isinstance(value, bool): # bool is an int subclass — reject explicitly
+ raise ValueError(f"{name} must be an integer, got {value!r}")
+ try:
+ return int(value)
+ except (TypeError, ValueError, OverflowError) as exc:
+ raise ValueError(f"{name} must be an integer, got {value!r}") from exc
+
+
+def _coerce_opt_float(value: Any, name: str) -> float | None:
+ """Coerce an optional numeric parameter; reject NaN/inf and bad types."""
+ if value is None:
+ return None
+ if isinstance(value, bool):
+ raise ValueError(f"{name} must be a number, got {value!r}")
+ try:
+ result = float(value)
+ except (TypeError, ValueError, OverflowError) as exc:
+ raise ValueError(f"{name} must be a number, got {value!r}") from exc
+ if result != result or result in (float("inf"), float("-inf")):
+ raise ValueError(f"{name} must be a finite number, got {value!r}")
+ return result
+
+
+def _coerce_opt_str(value: Any, name: str) -> str | None:
+ """Coerce an optional string parameter; blank/None become ``None``."""
+ if value is None:
+ return None
+ if not isinstance(value, str):
+ raise ValueError(f"{name} must be a string, got {value!r}")
+ if len(value) > _MAX_STRING_PARAM_CHARS:
+ raise ValueError(
+ f"{name} is too long ({len(value)} chars; "
+ f"max {_MAX_STRING_PARAM_CHARS})"
+ )
+ text = value.strip()
+ return text or None
+
+
+def _coerce_bool(value: Any, name: str, default: bool) -> bool:
+ """Coerce a boolean parameter, tolerating common LLM string forms."""
+ if value is None:
+ return default
+ if isinstance(value, bool):
+ return value
+ if isinstance(value, str):
+ lowered = value.strip().lower()
+ if lowered in {"true", "1", "yes"}:
+ return True
+ if lowered in {"false", "0", "no"}:
+ return False
+ raise ValueError(f"{name} must be a boolean, got {value!r}")
+
+
+class ListStrategiesTool(BaseTool):
+ """List discoverable strategies from Alpha Zoo and the SDM store."""
+
+ name = "list_strategies"
+ description = (
+ "List discoverable strategies across the Alpha Zoo registry and the "
+ "SDM strategy store. Read-only catalogue of what strategies exist "
+ "(identification metadata only). Rows carry evidence status; use "
+ "get_strategy_evidence for the per-regime evidence behind any "
+ "strategy. Nothing here is a recommendation — rows below the "
+ "evidence threshold are flagged insufficient/marginal, not "
+ "recommended."
+ )
+ parameters = {
+ "type": "object",
+ "properties": {
+ "limit": {
+ "type": "integer",
+ "default": 20,
+ "description": "Maximum number of strategies to return (default 20).",
+ },
+ "offset": {
+ "type": "integer",
+ "default": 0,
+ "description": "Pagination offset for stable browsing (default 0).",
+ },
+ "source": {
+ "type": "string",
+ "description": (
+ "Optional source filter: alpha_zoo|sdm. Omit to browse "
+ "both sources."
+ ),
+ },
+ },
+ "required": [],
+ }
+ is_readonly = True
+ repeatable = True
+
+ def execute(self, **kwargs: Any) -> str:
+ try:
+ limit = _coerce_int(kwargs.get("limit"), "limit", 20)
+ offset = _coerce_int(kwargs.get("offset"), "offset", 0)
+ source = _coerce_opt_str(kwargs.get("source"), "source")
+ except ValueError as exc:
+ return _err(str(exc))
+ if limit <= 0:
+ return _err("limit must be > 0")
+ if offset < 0:
+ return _err("offset must be >= 0")
+ try:
+ facade = _get_facade()
+ result = facade.list_strategies(limit=limit, offset=offset, source=source)
+ except Exception:
+ # Full detail goes to the server logs only; the envelope must not
+ # echo raw exception text (it can leak internal paths).
+ logger.exception("list_strategies failed")
+ return _err("list_strategies failed internally; see server logs")
+ return _envelope(result)
+
+
+class QueryStrategiesTool(BaseTool):
+ """Query strategies whose computed per-regime evidence passes filters."""
+
+ name = "query_strategies"
+ description = (
+ "Query the strategy store for strategies whose computed evidence "
+ "passes the given filters. Evidence-gated: results are ranked by "
+ "per-regime evidence rows from reproducible backtests, not scenario "
+ "tags. Strategies below the evidence thresholds are flagged "
+ "insufficient/marginal rather than recommended. The cost screen "
+ "keeps only strategies that clear the sizing-corrected breakeven."
+ )
+ parameters = {
+ "type": "object",
+ "properties": {
+ "regime": {
+ "type": "string",
+ "description": (
+ "Optional market-regime filter: "
+ "bear_market/bull_market/structural. Omit to query all "
+ "regimes."
+ ),
+ },
+ "min_sharpe": {
+ "type": "number",
+ "description": "Optional minimum Sharpe on the evidence rows.",
+ },
+ "min_evidence_quality": {
+ "type": "string",
+ "enum": list(_EVIDENCE_QUALITIES),
+ "default": "adequate",
+ "description": (
+ "Minimum evidence quality to keep: adequate (default), "
+ "marginal, insufficient, or any. 'any' only removes the "
+ "quality floor — rows must still pass the other filters "
+ "(min_trades, cost_feasible, min_sharpe) to be kept."
+ ),
+ },
+ "min_trades": {
+ "type": "integer",
+ "default": 10,
+ "description": (
+ "Minimum executed-trade count for evidence to count "
+ "(default 10)."
+ ),
+ },
+ "cost_feasible": {
+ "type": "boolean",
+ "default": True,
+ "description": (
+ "Keep only strategies that pass the sizing-corrected "
+ "cost-breakeven screen (default true)."
+ ),
+ },
+ "limit": {
+ "type": "integer",
+ "default": 10,
+ "description": "Maximum number of strategies to return (default 10).",
+ },
+ },
+ "required": [],
+ }
+ is_readonly = True
+ repeatable = True
+
+ def execute(self, **kwargs: Any) -> str:
+ try:
+ regime = _coerce_opt_str(kwargs.get("regime"), "regime")
+ min_sharpe = _coerce_opt_float(kwargs.get("min_sharpe"), "min_sharpe")
+ min_trades = _coerce_int(kwargs.get("min_trades"), "min_trades", 10)
+ cost_feasible = _coerce_bool(
+ kwargs.get("cost_feasible"), "cost_feasible", True
+ )
+ limit = _coerce_int(kwargs.get("limit"), "limit", 10)
+ except ValueError as exc:
+ return _err(str(exc))
+
+ quality_raw = kwargs.get("min_evidence_quality")
+ quality = "adequate" if quality_raw is None else quality_raw
+ if not isinstance(quality, str) or quality not in _EVIDENCE_QUALITIES:
+ return _err(
+ "min_evidence_quality must be one of "
+ "adequate|marginal|insufficient|any, got "
+ f"{quality_raw!r}"
+ )
+ if min_trades < 0:
+ return _err("min_trades must be >= 0")
+ if limit <= 0:
+ return _err("limit must be > 0")
+
+ try:
+ facade = _get_facade()
+ result = facade.query_strategies(
+ regime=regime,
+ min_sharpe=min_sharpe,
+ min_evidence_quality=quality,
+ min_trades=min_trades,
+ cost_feasible=cost_feasible,
+ limit=limit,
+ )
+ except Exception:
+ # Full detail goes to the server logs only; the envelope must not
+ # echo raw exception text (it can leak internal paths).
+ logger.exception("query_strategies failed")
+ return _err("query_strategies failed internally; see server logs")
+ return _envelope(result)
+
+
+class GetStrategyEvidenceTool(BaseTool):
+ """Return the per-regime evidence rows for one strategy."""
+
+ name = "get_strategy_evidence"
+ description = (
+ "Return the computed per-regime evidence rows for one strategy. "
+ "Shows what reproducible backtests support the strategy in each "
+ "regime (trade count, coverage, Sharpe, cost breakeven). Rows below "
+ "the evidence thresholds are flagged insufficient/marginal rather "
+ "than recommended; the facade refuses regime assessments without "
+ "computed evidence."
+ )
+ parameters = {
+ "type": "object",
+ "properties": {
+ "strategy_id": {
+ "type": "string",
+ "description": (
+ "Strategy identifier from list_strategies or " "query_strategies."
+ ),
+ },
+ "regime": {
+ "type": "string",
+ "description": (
+ "Optional regime filter: "
+ "bear_market/bull_market/structural. Omit for all "
+ "regimes."
+ ),
+ },
+ },
+ "required": ["strategy_id"],
+ }
+ is_readonly = True
+ repeatable = True
+
+ def execute(self, **kwargs: Any) -> str:
+ try:
+ strategy_id = _coerce_opt_str(kwargs.get("strategy_id"), "strategy_id")
+ regime = _coerce_opt_str(kwargs.get("regime"), "regime")
+ except ValueError as exc:
+ return _err(str(exc))
+ if not strategy_id:
+ return _err("get_strategy_evidence requires strategy_id (string)")
+ try:
+ facade = _get_facade()
+ result = facade.get_strategy_evidence(strategy_id, regime=regime)
+ except Exception:
+ # Full detail goes to the server logs only; the envelope must not
+ # echo raw exception text (it can leak internal paths).
+ logger.exception("get_strategy_evidence failed")
+ return _err("get_strategy_evidence failed internally; see server logs")
+ return _envelope(result)
diff --git a/agent/tests/test_context_attribution_layers.py b/agent/tests/test_context_attribution_layers.py
index 7bb23ef23..bfdbb1a6f 100644
--- a/agent/tests/test_context_attribution_layers.py
+++ b/agent/tests/test_context_attribution_layers.py
@@ -78,6 +78,7 @@ class TestAttributionPromptIntegrity:
skill_descriptions="[test skills]",
memory_summary="[test memory]",
memory_section="[test section]",
+ strategy_discovery_routing="[test routing]",
current_datetime="2025-01-01 12:00:00",
)
assert len(result) > 1000
@@ -86,6 +87,7 @@ class TestAttributionPromptIntegrity:
assert "{tool_count}" not in result
assert "{skill_count}" not in result
assert "{data_source_count}" not in result
+ assert "{strategy_discovery_routing}" not in result
def test_strategy_routing_thresholds_present(self):
"""Verify strategy routing classification is defined."""
diff --git a/agent/tests/test_strategy_discovery_facade.py b/agent/tests/test_strategy_discovery_facade.py
new file mode 100644
index 000000000..2589921b4
--- /dev/null
+++ b/agent/tests/test_strategy_discovery_facade.py
@@ -0,0 +1,634 @@
+"""Frozen-contract tests for ``StrategyDiscoveryFacade`` — issue #969.
+
+The facade is a read-only, in-memory query layer over three injected
+dependencies (all fakes here, no network, no real stores on disk except a
+tmp-path EvidenceStore):
+
+* ``evidence_store`` — real ``EvidenceStore`` on tmp_path (sibling A package)
+* ``sdm_store`` — fake with ``list_artifacts(**kw)`` returning objects
+ with .id/.name/.status(.value)/.universe/
+ .signal_definition/.created_at
+* ``alpha_registry`` — fake with ``list(**kw) -> [ids]`` and
+ ``get(id) -> obj(.id/.zoo/.meta dict)``
+
+Pinned behaviors: alpha-first merged listing with the ok envelope, quality
+floor via QUALITY_ORDER, min_trades / cost_feasible / min_sharpe filters,
+unknown-regime error carrying the valid regime list, honest empty evidence
+(AC8), per-regime row item shape (AC4), the adversarial borderline scenario
+(AC9), and "facade never returns rows the store does not have" (AC3).
+"""
+
+from __future__ import annotations
+
+import pytest
+
+try:
+ from src.strategy_discovery import models as sd_models
+ from src.strategy_discovery.evidence_store import EvidenceStore
+ from src.strategy_discovery.facade import StrategyDiscoveryFacade
+
+ FACADE_AVAILABLE = True
+except ImportError:
+ sd_models = None
+ StrategyDiscoveryFacade = None
+ EvidenceStore = None
+ FACADE_AVAILABLE = False
+
+requires_facade = pytest.mark.skipif(
+ not FACADE_AVAILABLE,
+ reason="waiting on sibling A: src.strategy_discovery facade/models/evidence_store not landed yet (issue #969)",
+)
+
+EVIDENCE_FIELDS = (
+ "strategy_id",
+ "regime",
+ "trades_in_regime",
+ "position_size",
+ "return_in_regime",
+ "benchmark_in_regime",
+ "excess_in_regime",
+ "sharpe_in_regime",
+ "max_drawdown_in_regime",
+ "date_ranges",
+ "breakeven_fee_bps",
+ "cost_sensitive",
+ "evidence_quality",
+ "warnings",
+ "last_verified",
+ "evidence_stage",
+ "provenance",
+ "regime_definition",
+)
+
+
+# ---------------------------------------------------------------------------
+# Fakes (the contract is duck-typed: only these surfaces are touched)
+# ---------------------------------------------------------------------------
+
+
+class FakeAlpha:
+ def __init__(self, alpha_id, zoo="testzoo", meta=None):
+ self.id = alpha_id
+ self.zoo = zoo
+ self.meta = {
+ "name": f"Alpha {alpha_id}",
+ "description": f"desc {alpha_id}",
+ "universe": "csi300",
+ }
+ if meta:
+ self.meta.update(meta)
+
+
+class FakeAlphaRegistry:
+ def __init__(self, alphas):
+ self._alphas = {a.id: a for a in alphas}
+ self.list_calls = []
+ self.get_calls = []
+
+ def list(self, **kwargs):
+ self.list_calls.append(kwargs)
+ return sorted(self._alphas.keys())
+
+ def get(self, alpha_id):
+ self.get_calls.append(alpha_id)
+ return self._alphas.get(alpha_id)
+
+
+class _EnumLike:
+ def __init__(self, value):
+ self.value = value
+
+
+class FakeArtifact:
+ def __init__(self, artifact_id, name=None, status="active", universe="us_equity"):
+ self.id = artifact_id
+ self.name = name or f"SDM {artifact_id}"
+ self.status = _EnumLike(status)
+ self.universe = universe
+ self.signal_definition = "close > open"
+ self.created_at = "2026-01-01T00:00:00Z"
+
+
+class FakeSdmStore:
+ def __init__(self, artifacts=None):
+ self._artifacts = list(artifacts or [])
+ self.list_calls = []
+
+ def list_artifacts(self, **kwargs):
+ self.list_calls.append(kwargs)
+ return list(self._artifacts)
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+def _make_store(tmp_path):
+ return EvidenceStore(tmp_path / "evidence.db")
+
+
+def _make_facade(tmp_path, *, alpha_ids=("a1", "a2"), artifacts=(), rows=()):
+ store = _make_store(tmp_path)
+ if rows:
+ store.upsert_rows(list(rows))
+ alpha_registry = FakeAlphaRegistry([FakeAlpha(a) for a in alpha_ids])
+ artifacts = (
+ artifacts
+ if not isinstance(artifacts, tuple)
+ else [FakeArtifact(a) for a in artifacts]
+ )
+ sdm_store = FakeSdmStore(artifacts)
+ facade = StrategyDiscoveryFacade(
+ evidence_store=store,
+ sdm_store=sdm_store,
+ alpha_registry=alpha_registry,
+ )
+ return facade, store
+
+
+def _row(strategy_id, regime, **overrides):
+ fields = dict(
+ strategy_id=strategy_id,
+ regime=regime,
+ trades_in_regime=12,
+ position_size=1.0,
+ return_in_regime=0.083,
+ benchmark_in_regime=-0.246,
+ excess_in_regime=0.329,
+ sharpe_in_regime=0.72,
+ max_drawdown_in_regime=-0.152,
+ date_ranges=("2018-01 to 2018-12", "2022-01 to 2022-12"),
+ breakeven_fee_bps=45.2,
+ cost_sensitive=False,
+ evidence_quality="adequate",
+ warnings=(),
+ last_verified="2026-08-01",
+ )
+ fields.update(overrides)
+ return sd_models.EvidenceRow(**fields)
+
+
+# ---------------------------------------------------------------------------
+# list_strategies
+# ---------------------------------------------------------------------------
+
+
+@requires_facade
+class TestListStrategies:
+ def test_ok_envelope_and_alpha_first_ordering(self, tmp_path) -> None:
+ facade, _ = _make_facade(
+ tmp_path, alpha_ids=("b2", "a1"), artifacts=("zeta", "beta")
+ )
+ payload = facade.list_strategies(limit=50, offset=0)
+ assert payload["status"] == "ok"
+ assert payload["total"] == 4
+ assert payload["returned"] == 4
+ assert payload["offset"] == 0
+ assert isinstance(payload["items"], list)
+ # Alpha zoo entries come first (sorted), then sdm entries (sorted),
+ # each with its source prefix (AC: unified catalog ordering).
+ assert [i["strategy_id"] for i in payload["items"]] == [
+ "alpha_zoo:a1",
+ "alpha_zoo:b2",
+ "sdm:beta",
+ "sdm:zeta",
+ ]
+
+ def test_sources_and_metadata(self, tmp_path) -> None:
+ facade, _ = _make_facade(tmp_path, alpha_ids=("a1",), artifacts=("s1",))
+ items = {i["strategy_id"]: i for i in facade.list_strategies(limit=50)["items"]}
+ alpha_item = items["alpha_zoo:a1"]
+ sdm_item = items["sdm:s1"]
+ assert alpha_item["source"] == "alpha_zoo"
+ assert sdm_item["source"] == "sdm"
+ assert isinstance(alpha_item["name"], str) and alpha_item["name"]
+ assert sdm_item["name"] == "SDM s1"
+ assert sdm_item["status"] == "active" # enum-like .status.value surfaced
+ assert sdm_item["universe"] == "us_equity"
+
+ def test_has_evidence_and_regimes_from_store(self, tmp_path) -> None:
+ facade, _ = _make_facade(
+ tmp_path,
+ alpha_ids=("a1", "a2"),
+ rows=(
+ _row("alpha_zoo:a1", "bear_market"),
+ _row("alpha_zoo:a1", "bull_market"),
+ ),
+ )
+ items = {i["strategy_id"]: i for i in facade.list_strategies(limit=50)["items"]}
+ assert items["alpha_zoo:a1"]["has_evidence"] is True
+ assert set(items["alpha_zoo:a1"]["regimes_with_evidence"]) == {
+ "bear_market",
+ "bull_market",
+ }
+ assert items["alpha_zoo:a2"]["has_evidence"] is False
+ # Envelope items are plain dicts (asdict/JSON), so an empty regime set
+ # serializes as []; the model-level default stays the pinned () .
+ assert items["alpha_zoo:a2"]["regimes_with_evidence"] in ([], ())
+
+ def test_source_filters(self, tmp_path) -> None:
+ facade, _ = _make_facade(tmp_path, alpha_ids=("a1",), artifacts=("s1",))
+ only_alpha = facade.list_strategies(limit=50, source="alpha_zoo")
+ only_sdm = facade.list_strategies(limit=50, source="sdm")
+ assert [i["source"] for i in only_alpha["items"]] == ["alpha_zoo"]
+ assert [i["source"] for i in only_sdm["items"]] == ["sdm"]
+
+ def test_unknown_source_is_error_envelope(self, tmp_path) -> None:
+ facade, _ = _make_facade(tmp_path)
+ payload = facade.list_strategies(limit=5, source="bogus_source")
+ assert payload["status"] == "error"
+ assert payload.get("error"), "error envelope must carry an actionable message"
+
+ def test_pagination_limit_offset(self, tmp_path) -> None:
+ facade, _ = _make_facade(
+ tmp_path, alpha_ids=("a1", "a2", "a3"), artifacts=("s1", "s2")
+ )
+ page = facade.list_strategies(limit=2, offset=1)
+ assert page["total"] == 5
+ assert page["returned"] == 2
+ assert page["offset"] == 1
+ ids = [i["strategy_id"] for i in page["items"]]
+ assert ids == ["alpha_zoo:a2", "alpha_zoo:a3"]
+ # Offset past the end yields an empty page, not an error.
+ tail = facade.list_strategies(limit=10, offset=50)
+ assert tail["status"] == "ok"
+ assert tail["items"] == []
+ assert tail["returned"] == 0
+
+
+# ---------------------------------------------------------------------------
+# query_strategies
+# ---------------------------------------------------------------------------
+
+
+@requires_facade
+class TestQueryStrategies:
+ def _seed_quality_ladder(self, tmp_path):
+ return _make_facade(
+ tmp_path,
+ alpha_ids=("a1",),
+ rows=(
+ _row(
+ "alpha_zoo:a1",
+ "bear_market",
+ trades_in_regime=12,
+ evidence_quality="adequate",
+ sharpe_in_regime=0.9,
+ ),
+ _row(
+ "alpha_zoo:a1",
+ "bull_market",
+ trades_in_regime=12,
+ evidence_quality="marginal",
+ sharpe_in_regime=0.8,
+ ),
+ _row(
+ "alpha_zoo:a1",
+ "structural",
+ trades_in_regime=12,
+ evidence_quality="insufficient",
+ sharpe_in_regime=0.7,
+ ),
+ ),
+ )
+
+ def test_quality_floors_via_quality_order(self, tmp_path) -> None:
+ facade, _ = self._seed_quality_ladder(tmp_path)
+ # Default floor is "adequate"; "marginal" admits adequate+marginal;
+ # "any" keeps every row including insufficient (QUALITY_ORDER based).
+ assert {i["regime"] for i in facade.query_strategies()["items"]} == {
+ "bear_market"
+ }
+ assert {
+ i["regime"]
+ for i in facade.query_strategies(min_evidence_quality="marginal")["items"]
+ } == {"bear_market", "bull_market"}
+ assert len(facade.query_strategies(min_evidence_quality="any")["items"]) == 3
+
+ def test_min_trades_filter(self, tmp_path) -> None:
+ facade, _ = _make_facade(
+ tmp_path,
+ alpha_ids=("a1",),
+ rows=(
+ _row("alpha_zoo:a1", "bear_market", trades_in_regime=11),
+ _row("alpha_zoo:a1", "bull_market", trades_in_regime=12),
+ ),
+ )
+ payload = facade.query_strategies(min_trades=12, min_evidence_quality="any")
+ assert {i["regime"] for i in payload["items"]} == {"bull_market"}
+
+ def test_cost_feasible_drops_cost_sensitive_rows(self, tmp_path) -> None:
+ facade, _ = _make_facade(
+ tmp_path,
+ alpha_ids=("a1",),
+ rows=(
+ _row(
+ "alpha_zoo:a1",
+ "bear_market",
+ cost_sensitive=True,
+ breakeven_fee_bps=2.0,
+ ),
+ _row(
+ "alpha_zoo:a1",
+ "bull_market",
+ cost_sensitive=False,
+ breakeven_fee_bps=45.0,
+ ),
+ ),
+ )
+ feasible = facade.query_strategies(cost_feasible=True)
+ assert {i["regime"] for i in feasible["items"]} == {"bull_market"}
+ everything = facade.query_strategies(cost_feasible=False)
+ assert {i["regime"] for i in everything["items"]} == {
+ "bear_market",
+ "bull_market",
+ }
+
+ def test_cost_feasible_is_fail_closed_on_null_breakeven(self, tmp_path) -> None:
+ # sergio12S (#969): a null breakeven means the cost screen is
+ # unverifiable (multi-position run) — unverifiable is not a pass, so
+ # the default filter drops the row; cost_feasible=False reveals it.
+ facade, _ = _make_facade(
+ tmp_path,
+ alpha_ids=("a1",),
+ rows=(
+ _row(
+ "alpha_zoo:a1",
+ "bear_market",
+ breakeven_fee_bps=None,
+ cost_sensitive=False,
+ warnings=("multi-position-breakeven: sample caveat",),
+ ),
+ _row(
+ "alpha_zoo:a1",
+ "bull_market",
+ breakeven_fee_bps=45.0,
+ cost_sensitive=False,
+ ),
+ ),
+ )
+ feasible = facade.query_strategies(cost_feasible=True)
+ assert {i["regime"] for i in feasible["items"]} == {
+ "bull_market"
+ }, "a null-breakeven row must not pass the default cost screen"
+ everything = facade.query_strategies(cost_feasible=False)
+ items = {i["regime"]: i for i in everything["items"]}
+ assert set(items) == {"bear_market", "bull_market"}
+ assert items["bear_market"]["breakeven_fee_bps"] is None
+ assert any(
+ w.startswith("multi-position-breakeven:")
+ for w in items["bear_market"]["warnings"]
+ ), "the revealed row must keep its unverifiability warning"
+
+ def test_min_sharpe_drops_none_sharpe_and_low_sharpe(self, tmp_path) -> None:
+ facade, _ = _make_facade(
+ tmp_path,
+ alpha_ids=("a1",),
+ rows=(
+ _row("alpha_zoo:a1", "bear_market", sharpe_in_regime=None),
+ _row("alpha_zoo:a1", "bull_market", sharpe_in_regime=0.4),
+ _row("alpha_zoo:a1", "structural", sharpe_in_regime=0.9),
+ ),
+ )
+ payload = facade.query_strategies(min_sharpe=0.5)
+ assert {i["regime"] for i in payload["items"]} == {"structural"}
+
+ def test_unknown_regime_error_lists_valid_regimes(self, tmp_path) -> None:
+ facade, _ = _make_facade(tmp_path, rows=(_row("alpha_zoo:a1", "bear_market"),))
+ payload = facade.query_strategies(regime="sideways")
+ assert payload["status"] == "error"
+ message = str(payload.get("error", ""))
+ for regime in ("bear_market", "bull_market", "structural"):
+ assert (
+ regime in message
+ ), f"valid regime {regime} missing from error: {message!r}"
+
+ def test_empty_store_returns_honest_note(self, tmp_path) -> None:
+ # AC8: an empty evidence store yields an ok envelope with a note that
+ # no evidence has been computed — never rows, never an error. The
+ # note must point at the evidence harness LIBRARY API (the only write
+ # path) and never suggest a user-runnable workflow/CLI exists.
+ facade, _ = _make_facade(tmp_path, alpha_ids=("a1",))
+ payload = facade.query_strategies(min_evidence_quality="any")
+ assert payload["status"] == "ok"
+ assert payload["items"] == []
+ note = payload.get("note", "")
+ assert (
+ note
+ ), "empty store query must carry a 'note' explaining no evidence exists"
+ assert isinstance(note, str)
+ assert "rebuild_evidence" in note, (
+ "the note must name the harness library API as the only write "
+ f"path: {note!r}"
+ )
+ assert (
+ "vibe-trading" not in note
+ ), f"the note must not suggest a CLI command exists: {note!r}"
+
+ def test_item_shape_carries_every_evidence_field_plus_borderline(
+ self, tmp_path
+ ) -> None:
+ # AC4: per-regime rows, not boolean tags — every EvidenceRow field is
+ # surfaced on the item, plus the facade-computed "borderline" flag.
+ facade, _ = _make_facade(
+ tmp_path, alpha_ids=("a1",), rows=(_row("alpha_zoo:a1", "bear_market"),)
+ )
+ payload = facade.query_strategies(regime="bear_market")
+ item = payload["items"][0]
+ for field in EVIDENCE_FIELDS:
+ assert field in item, f"query item missing EvidenceRow field: {field}"
+ assert "borderline" in item
+ assert isinstance(item["borderline"], bool)
+ assert item["strategy_id"] == "alpha_zoo:a1"
+ assert item["regime"] == "bear_market"
+
+ def test_facade_never_returns_rows_missing_from_store(self, tmp_path) -> None:
+ # AC3: evidence comes only from reproducible runs written through the
+ # store — nothing the store does not have may surface through queries.
+ facade, store = _make_facade(
+ tmp_path,
+ alpha_ids=("a1", "a2"),
+ artifacts=("s1",),
+ rows=(
+ _row("alpha_zoo:a1", "bear_market"),
+ _row("sdm:s1", "bull_market"),
+ ),
+ )
+ payload = facade.query_strategies(min_evidence_quality="any")
+ assert payload["items"], "seeded store should produce items"
+ for item in payload["items"]:
+ stored = store.get_rows(
+ strategy_id=item["strategy_id"], regime=item["regime"]
+ )
+ assert (
+ stored
+ ), f"facade returned a row the store does not have: {item['strategy_id']}/{item['regime']}"
+
+
+# ---------------------------------------------------------------------------
+# The adversarial borderline scenario (AC9)
+# ---------------------------------------------------------------------------
+
+
+@requires_facade
+class TestBorderlineAdversarial:
+ """Row that passes every threshold but sits inside ALL borderline buffers.
+
+ trades=11 (> MIN_TRADES=10 but < 10+BORDERLINE_TRADE_BUFFER=15)
+ coverage ["2024-01 to 2026-02"] ≈ 2.1y (>= 730d, < 730+365=1095d)
+ breakeven=5.1 bps (>= 5.0 cost threshold but < BORDERLINE_BREAKEVEN_BPS=10)
+ """
+
+ def _seed(self, tmp_path):
+ borderline = _row(
+ "alpha_zoo:edge",
+ "bear_market",
+ trades_in_regime=11,
+ date_ranges=("2024-01 to 2026-02",),
+ breakeven_fee_bps=5.1,
+ cost_sensitive=False,
+ evidence_quality="adequate",
+ sharpe_in_regime=0.8,
+ )
+ comfortable = _row(
+ "alpha_zoo:solid",
+ "bear_market",
+ trades_in_regime=200,
+ date_ranges=("2019-01 to 2024-12",), # 2191 days > 1095
+ breakeven_fee_bps=120.0,
+ cost_sensitive=False,
+ evidence_quality="adequate",
+ sharpe_in_regime=1.1,
+ )
+ return _make_facade(
+ tmp_path, alpha_ids=("edge", "solid"), rows=(borderline, comfortable)
+ )
+
+ def test_borderline_row_passes_filters_but_is_flagged(self, tmp_path) -> None:
+ # Guard the fixture itself: coverage ~2.1 years vs 5+ years.
+ assert sd_models.coverage_days_from_ranges(["2024-01 to 2026-02"]) == 789
+ assert sd_models.coverage_days_from_ranges(["2019-01 to 2024-12"]) == 2191
+
+ facade, _ = self._seed(tmp_path)
+ payload = facade.query_strategies(
+ regime="bear_market",
+ min_evidence_quality="adequate",
+ min_trades=10,
+ cost_feasible=True,
+ )
+ assert payload["status"] == "ok"
+ items = {i["strategy_id"]: i for i in payload["items"]}
+ assert (
+ "alpha_zoo:edge" in items
+ ), "the 11-trade/2.1y/5.1bps row passes all thresholds and must not be filtered out"
+ edge = items["alpha_zoo:edge"]
+ assert edge["borderline"] is True
+ warns = edge.get("warnings") or []
+ assert any(
+ isinstance(w, str) and w.startswith("borderline-evidence:") for w in warns
+ ), f"borderline row must carry a 'borderline-evidence:' warning, got {warns!r}"
+
+ def test_comfortable_row_is_not_borderline(self, tmp_path) -> None:
+ facade, _ = self._seed(tmp_path)
+ payload = facade.query_strategies(regime="bear_market")
+ items = {i["strategy_id"]: i for i in payload["items"]}
+ solid = items["alpha_zoo:solid"]
+ assert solid["borderline"] is False
+ warns = solid.get("warnings") or []
+ assert not any(
+ isinstance(w, str) and w.startswith("borderline-evidence:") for w in warns
+ ), f"comfortable row must not be flagged borderline, got {warns!r}"
+
+
+# ---------------------------------------------------------------------------
+# get_strategy_evidence
+# ---------------------------------------------------------------------------
+
+
+@requires_facade
+class TestGetStrategyEvidence:
+ def test_found_with_rows_and_regime_filter(self, tmp_path) -> None:
+ facade, _ = _make_facade(
+ tmp_path,
+ alpha_ids=("a1",),
+ rows=(
+ _row("alpha_zoo:a1", "bear_market"),
+ _row("alpha_zoo:a1", "bull_market"),
+ ),
+ )
+ payload = facade.get_strategy_evidence("alpha_zoo:a1")
+ assert payload["status"] == "ok"
+ assert payload["strategy_id"] == "alpha_zoo:a1"
+ assert payload["found"] is True
+ assert len(payload["rows"]) == 2
+ for row in payload["rows"]:
+ for field in EVIDENCE_FIELDS:
+ assert field in row, f"get_strategy_evidence row missing field: {field}"
+
+ filtered = facade.get_strategy_evidence("alpha_zoo:a1", regime="bear_market")
+ assert filtered["found"] is True
+ assert len(filtered["rows"]) == 1
+ assert filtered["rows"][0]["regime"] == "bear_market"
+
+ def test_missing_strategy_is_honest_empty_not_error(self, tmp_path) -> None:
+ # AC8 pinned envelope: status ok, found=False, empty rows, and a note
+ # explaining no evidence exists. This is NOT an error envelope.
+ facade, _ = _make_facade(tmp_path, alpha_ids=("a1",))
+ payload = facade.get_strategy_evidence("alpha_zoo:does_not_exist")
+ assert (
+ payload["status"] == "ok"
+ ), f"missing strategy must stay 'ok', got {payload!r}"
+ assert payload["strategy_id"] == "alpha_zoo:does_not_exist"
+ assert "regime" in payload
+ assert payload["found"] is False
+ assert payload["rows"] == []
+ assert payload.get("note"), "honest-empty envelope must carry a note"
+
+
+# ---------------------------------------------------------------------------
+# Default Alpha Zoo registry resolution (process-cached singleton)
+# ---------------------------------------------------------------------------
+
+
+@requires_facade
+class TestDefaultAlphaRegistryResolution:
+ """The default registry must come from the process-wide
+ ``get_default_registry()`` singleton — constructing ``Registry()`` per
+ facade instance would re-run the zoo AST scan (~0.85s) every time."""
+
+ def test_default_resolution_uses_shared_singleton(
+ self, tmp_path, monkeypatch
+ ) -> None:
+ sentinel = FakeAlphaRegistry([FakeAlpha("z1")])
+ calls = []
+
+ def fake_get_default_registry():
+ calls.append(1)
+ return sentinel
+
+ monkeypatch.setattr(
+ "src.factors.registry.get_default_registry", fake_get_default_registry
+ )
+ facade = StrategyDiscoveryFacade(
+ evidence_store=_make_store(tmp_path),
+ sdm_store=FakeSdmStore([]),
+ )
+ assert facade._get_alpha_registry() is sentinel
+ assert facade._get_alpha_registry() is sentinel
+ assert calls == [1], "singleton accessor must be hit once, then cached"
+
+ def test_injected_registry_bypasses_singleton(self, tmp_path, monkeypatch) -> None:
+ def fake_get_default_registry():
+ raise AssertionError("injected registry must not touch the singleton")
+
+ monkeypatch.setattr(
+ "src.factors.registry.get_default_registry", fake_get_default_registry
+ )
+ injected = FakeAlphaRegistry([FakeAlpha("i1")])
+ facade = StrategyDiscoveryFacade(
+ evidence_store=_make_store(tmp_path),
+ sdm_store=FakeSdmStore([]),
+ alpha_registry=injected,
+ )
+ assert facade._get_alpha_registry() is injected
diff --git a/agent/tests/test_strategy_discovery_guard.py b/agent/tests/test_strategy_discovery_guard.py
new file mode 100644
index 000000000..5491188bd
--- /dev/null
+++ b/agent/tests/test_strategy_discovery_guard.py
@@ -0,0 +1,110 @@
+"""Frozen-contract tests for ``src.strategy_discovery.guard`` — issue #969.
+
+The phantom-tool guard (AC2) validates that every Strategy Discovery tool
+referenced by prompt routing text is actually registered, and fails safe:
+missing tool → empty routing block, garbage registry → never raises.
+
+Registries here are real ``ToolRegistry`` instances populated with minimal
+``BaseTool`` stubs, so any presence-check implementation (``get``,
+``__contains__``, ``tool_names``) works against them.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from src.agent.tools import BaseTool, ToolRegistry
+
+try:
+ from src.strategy_discovery import guard as sd_guard
+
+ GUARD_AVAILABLE = True
+except ImportError:
+ sd_guard = None
+ GUARD_AVAILABLE = False
+
+requires_guard = pytest.mark.skipif(
+ not GUARD_AVAILABLE,
+ reason="waiting on sibling A: src.strategy_discovery.guard not landed yet (issue #969)",
+)
+
+EXPECTED_TOOLS = ("list_strategies", "query_strategies", "get_strategy_evidence")
+
+
+class _StubTool(BaseTool):
+ """Minimal registered tool carrying only a name."""
+
+ description = "strategy discovery stub"
+ parameters = {"type": "object", "properties": {}, "required": []}
+
+ def __init__(self, name: str) -> None:
+ self.name = name
+
+ def execute(self, **kwargs) -> str:
+ return json.dumps({"status": "ok"})
+
+
+def _registry_with(names) -> ToolRegistry:
+ registry = ToolRegistry()
+ for name in names:
+ registry.register(_StubTool(name))
+ return registry
+
+
+@requires_guard
+class TestToolNames:
+ def test_strategy_discovery_tools_tuple_exact(self) -> None:
+ assert tuple(sd_guard.STRATEGY_DISCOVERY_TOOLS) == EXPECTED_TOOLS
+
+
+@requires_guard
+class TestToolsRegistered:
+ def test_all_tools_registered(self) -> None:
+ assert sd_guard.tools_registered(_registry_with(EXPECTED_TOOLS)) is True
+ # Extra unrelated tools must not break the registration check.
+ assert (
+ sd_guard.tools_registered(
+ _registry_with(EXPECTED_TOOLS + ("backtest", "read_file"))
+ )
+ is True
+ )
+
+ def test_missing_tools_is_false(self) -> None:
+ assert (
+ sd_guard.tools_registered(
+ _registry_with(("list_strategies", "get_strategy_evidence"))
+ )
+ is False
+ )
+ assert sd_guard.tools_registered(ToolRegistry()) is False
+
+
+@requires_guard
+class TestRoutingBlock:
+ def test_block_present_with_all_tools(self) -> None:
+ block = sd_guard.routing_block(_registry_with(EXPECTED_TOOLS))
+ assert isinstance(block, str)
+ assert (
+ block.strip()
+ ), "routing block must be non-empty when all tools are registered"
+ for tool_name in EXPECTED_TOOLS:
+ assert tool_name in block, f"routing block must name {tool_name}"
+
+ def test_block_empty_when_any_tool_missing(self) -> None:
+ # Fail-safe: no capability advertised that cannot be delivered.
+ for missing in EXPECTED_TOOLS:
+ partial = [n for n in EXPECTED_TOOLS if n != missing]
+ block = sd_guard.routing_block(_registry_with(partial))
+ assert (
+ block == ""
+ ), f"routing block must be empty when {missing} is unregistered, got {block!r}"
+
+ def test_block_empty_on_empty_registry(self) -> None:
+ assert sd_guard.routing_block(ToolRegistry()) == ""
+
+ def test_never_raises_on_garbage_registry(self) -> None:
+ # The contract pins "never raises on garbage registry (object())".
+ assert sd_guard.routing_block(object()) == ""
+ assert sd_guard.routing_block(None) == ""
diff --git a/agent/tests/test_strategy_discovery_harness.py b/agent/tests/test_strategy_discovery_harness.py
new file mode 100644
index 000000000..64b4fd4d1
--- /dev/null
+++ b/agent/tests/test_strategy_discovery_harness.py
@@ -0,0 +1,687 @@
+"""Frozen-contract tests for ``src.strategy_discovery.evidence_harness`` — #969.
+
+AC3 (evidence from reproducible runs only) is exercised here end to end on
+synthetic run directories built in tmp_path with the REAL engine artifact
+schema (``backtest/engines/base.py::_write_artifacts``):
+
+* ``artifacts/trades.csv`` — columns ``timestamp, code, side, price, qty,
+ reason, pnl, holding_days, return_pct`` with TWO rows per round trip:
+ an entry row (``reason="signal"``, ``pnl=0.0``, ``holding_days=0``)
+ followed by the exit row carrying the realized pnl. Round trips must be
+ counted ONCE (exit rows only); exit rows may reuse ``reason="signal"``
+ (the base engine closes positions on signal), so the marker is pnl, not
+ reason.
+* ``artifacts/equity.csv`` — date column ``timestamp`` (the engine's index
+ name) plus ``ret, equity, drawdown, benchmark_equity, active_ret``.
+ Benchmark values live in ``benchmark_equity``.
+
+The benchmark series is a piecewise-constant-slope curve engineered so
+that, with ``benchmark_window=5`` and thresholds of ±0.05, days
+2024-01-14..16 are a bear window, 2024-01-21..24 a bull window, and
+2024-01-07..08 structural — regardless of whether the harness measures
+the window return as an endpoint ratio or a mean of daily changes (both
+agree inside the segments; the self-check class pins this).
+
+Legacy one-row-per-trade artifacts (``date``/``benchmark`` columns, no
+zero-pnl entry marker) stay covered through the alias + detection paths.
+Deterministic: all dates are fixed strings, no wall-clock reads.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import math
+import re
+from collections.abc import Sequence
+from datetime import date, timedelta
+from pathlib import Path
+
+import pandas as pd
+import pytest
+
+try:
+ from src.strategy_discovery import evidence_harness as sd_harness
+ from src.strategy_discovery import models as sd_models
+ from src.strategy_discovery import run_artifacts as sd_artifacts
+
+ HARNESS_AVAILABLE = True
+except ImportError:
+ sd_harness = None
+ sd_models = None
+ sd_artifacts = None
+ HARNESS_AVAILABLE = False
+
+requires_harness = pytest.mark.skipif(
+ not HARNESS_AVAILABLE,
+ reason="waiting on sibling A: src.strategy_discovery.evidence_harness not landed yet (issue #969)",
+)
+
+START = date(2024, 1, 1)
+DAYS = 39
+BEAR_DAYS = {date(2024, 1, 14), date(2024, 1, 15), date(2024, 1, 16)}
+BULL_DAYS = {date(2024, 1, 21), date(2024, 1, 22), date(2024, 1, 23), date(2024, 1, 24)}
+STRUCTURAL_DAYS = {date(2024, 1, 7), date(2024, 1, 8)}
+EXPECTED_COUNTS = {"bear_market": 3, "bull_market": 4, "structural": 2}
+ALL_TRADE_DAYS = sorted(BEAR_DAYS | BULL_DAYS | STRUCTURAL_DAYS)
+
+#: Exact column order written by base.py::_write_artifacts.
+ENGINE_TRADE_COLUMNS = [
+ "timestamp",
+ "code",
+ "side",
+ "price",
+ "qty",
+ "reason",
+ "pnl",
+ "holding_days",
+ "return_pct",
+]
+ENGINE_EQUITY_COLUMNS = ["ret", "equity", "drawdown", "benchmark_equity", "active_ret"]
+
+
+def _benchmark_series() -> pd.Series:
+ """Piecewise benchmark: flat, -5.5%/day decline, +6%/day rally, flat.
+
+ Segments (1-based days → 0-based index i): Jan 1-8 flat 100.0; Jan 9-16
+ (i 8..15) daily x0.945; Jan 17-24 (i 16..23) daily x1.06 from the bear
+ end; Jan 25 - Feb 8 flat at the bull end.
+ """
+ bear_end = 100.0 * (0.945**8)
+ bull_end = bear_end * (1.06**8)
+ values = (
+ [100.0] * 8
+ + [100.0 * (0.945 ** (i - 7)) for i in range(8, 16)]
+ + [bear_end * (1.06 ** (i - 15)) for i in range(16, 24)]
+ + [bull_end] * 15
+ )
+ assert len(values) == DAYS
+ index = [START + timedelta(days=i) for i in range(DAYS)]
+ return pd.Series(values, index=pd.DatetimeIndex(index), name="benchmark_equity")
+
+
+def _engine_equity_frame() -> pd.DataFrame:
+ """equity.csv exactly as backtest/engines/base.py::_write_artifacts."""
+ bench = _benchmark_series()
+ equity = pd.Series(
+ [1_000_000.0 * (1.001**i) for i in range(DAYS)], index=bench.index
+ )
+ port_ret = equity.pct_change().fillna(0.0)
+ peak = equity.cummax()
+ drawdown = (equity - peak) / peak.replace(0, 1)
+ bench_ret = bench.pct_change().fillna(0.0)
+ eq_df = pd.DataFrame(
+ {
+ "ret": port_ret,
+ "equity": equity,
+ "drawdown": drawdown,
+ "benchmark_equity": bench,
+ "active_ret": port_ret - bench_ret,
+ },
+ index=bench.index,
+ )
+ eq_df.index.name = "timestamp"
+ return eq_df
+
+
+def _entry_row(trade_date: date, code: str) -> dict:
+ return {
+ "timestamp": trade_date.strftime("%Y-%m-%d"),
+ "code": code,
+ "side": "buy",
+ "price": 10.0,
+ "qty": 100.0,
+ "reason": "signal",
+ "pnl": 0.0,
+ "holding_days": 0,
+ "return_pct": 0.0,
+ }
+
+
+def _exit_row(
+ trade_date: date, code: str, *, pnl: float = 50.0, reason: str = "signal"
+) -> dict:
+ return {
+ "timestamp": trade_date.strftime("%Y-%m-%d"),
+ "code": code,
+ "side": "sell",
+ "price": 10.5,
+ "qty": 100.0,
+ "reason": reason,
+ "pnl": pnl,
+ "holding_days": 0,
+ "return_pct": 0.5,
+ }
+
+
+def _engine_trade_rows(
+ round_trips: Sequence[tuple[date, str, float, str]],
+) -> list[dict]:
+ """Entry+exit row pairs, exactly as the engine writer emits them."""
+ rows: list[dict] = []
+ for exit_date, code, pnl, exit_reason in round_trips:
+ # Same-day round trips keep per-code holding intervals disjoint, so
+ # the fixture is single-position by construction.
+ rows.append(_entry_row(exit_date, code))
+ rows.append(_exit_row(exit_date, code, pnl=pnl, reason=exit_reason))
+ return rows
+
+
+def _write_trades_csv(artifacts: Path, rows: list[dict]) -> None:
+ pd.DataFrame(rows, columns=ENGINE_TRADE_COLUMNS).to_csv(
+ artifacts / "trades.csv", index=False
+ )
+
+
+def _write_run_fixture(
+ base_dir: Path, *, include_trades: bool = True, include_equity: bool = True
+) -> Path:
+ """Real engine-schema run_dir: 9 same-day round trips, one position."""
+ run_dir = base_dir / "run_fixture"
+ artifacts = run_dir / "artifacts"
+ artifacts.mkdir(parents=True, exist_ok=True)
+
+ if include_equity:
+ _engine_equity_frame().to_csv(artifacts / "equity.csv")
+
+ if include_trades:
+ round_trips = [
+ (
+ trade_date,
+ "TEST.SH",
+ 50.0,
+ # Exits reuse reason="signal" (base engine closes on signal
+ # too) — the entry/exit marker must be pnl, not reason.
+ "signal" if i < 8 else "end",
+ )
+ for i, trade_date in enumerate(ALL_TRADE_DAYS)
+ ]
+ _write_trades_csv(artifacts, _engine_trade_rows(round_trips))
+
+ return run_dir
+
+
+def _write_multi_position_fixture(base_dir: Path) -> Path:
+ """Two overlapping holdings: AAA Jan 14-16 and BBB Jan 15-21 → peak 2."""
+ run_dir = base_dir / "multi_position_run"
+ artifacts = run_dir / "artifacts"
+ artifacts.mkdir(parents=True, exist_ok=True)
+ _engine_equity_frame().to_csv(artifacts / "equity.csv")
+
+ rows = [
+ _entry_row(date(2024, 1, 14), "AAA.US"),
+ _entry_row(date(2024, 1, 15), "BBB.US"),
+ _exit_row(date(2024, 1, 16), "AAA.US", pnl=30.0, reason="stop_loss"),
+ _exit_row(date(2024, 1, 21), "BBB.US", pnl=40.0, reason="take_profit"),
+ ]
+ _write_trades_csv(artifacts, rows)
+ return run_dir
+
+
+def _write_legacy_fixture(base_dir: Path) -> Path:
+ """Legacy one-row-per-trade artifacts: date/benchmark aliases, no marker."""
+ run_dir = base_dir / "legacy_run"
+ artifacts = run_dir / "artifacts"
+ artifacts.mkdir(parents=True, exist_ok=True)
+
+ bench = _benchmark_series()
+ legacy_equity = pd.DataFrame(
+ {
+ "date": [d.strftime("%Y-%m-%d") for d in bench.index],
+ "equity": [1_000_000.0 * (1.001**i) for i in range(DAYS)],
+ "benchmark": bench.values,
+ }
+ )
+ legacy_equity.to_csv(artifacts / "equity.csv", index=False)
+
+ legacy_rows = [
+ {
+ "date": trade_date.strftime("%Y-%m-%d"),
+ "code": "TEST.SH",
+ "side": "sell",
+ "pnl": 50.0,
+ "return_pct": 0.5,
+ }
+ for trade_date in ALL_TRADE_DAYS
+ ]
+ pd.DataFrame(legacy_rows).to_csv(artifacts / "trades.csv", index=False)
+ return run_dir
+
+
+def _call_compute(strategy_id, run_dir, **candidates):
+ """Call compute_evidence_for_run binding args by name, filtering kwargs
+ not in the signature so the fixture stays tolerant of additive changes."""
+ func = sd_harness.compute_evidence_for_run
+ sig = inspect.signature(func)
+ has_varkw = any(
+ p.kind is inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+ )
+ if has_varkw:
+ kwargs = dict(candidates)
+ else:
+ kwargs = {k: v for k, v in candidates.items() if k in sig.parameters}
+ return func(strategy_id=strategy_id, run_dir=run_dir, **kwargs)
+
+
+def _compute_with_fixture_windows(run_dir):
+ """Shared call shape: fixture-engineered windows + pinned today."""
+ return _call_compute(
+ "sdm:fixture_run",
+ run_dir,
+ benchmark_window=5,
+ bear_threshold=-0.05,
+ bull_threshold=0.05,
+ today="2026-08-01",
+ )
+
+
+# ---------------------------------------------------------------------------
+# Fixture self-check — pure pandas, runs TODAY without the sibling package
+# ---------------------------------------------------------------------------
+
+
+class TestFixtureSelfCheck:
+ def test_benchmark_windows_are_unambiguous_for_both_regime_models(
+ self, tmp_path
+ ) -> None:
+ bench = _benchmark_series()
+ ratio_model = bench / bench.shift(5) - 1.0
+ mean_model = bench.pct_change().rolling(5).mean()
+
+ for trade_date, expected in (
+ *[(d, "bear_market") for d in sorted(BEAR_DAYS)],
+ *[(d, "bull_market") for d in sorted(BULL_DAYS)],
+ *[(d, "structural") for d in sorted(STRUCTURAL_DAYS)],
+ ):
+ r_ratio = ratio_model.loc[pd.Timestamp(trade_date)]
+ r_mean = mean_model.loc[pd.Timestamp(trade_date)]
+ for value in (r_ratio, r_mean):
+ assert math.isfinite(value), f"{trade_date}: window value not finite"
+ if expected == "bear_market":
+ assert (
+ value < -0.05
+ ), f"{trade_date} should be a bear window (got {value:.4f})"
+ elif expected == "bull_market":
+ assert (
+ value > 0.05
+ ), f"{trade_date} should be a bull window (got {value:.4f})"
+ else:
+ assert (
+ -0.05 <= value <= 0.05
+ ), f"{trade_date} should be structural (got {value:.4f})"
+
+ def test_trade_fixture_shape_matches_engine_schema(self, tmp_path) -> None:
+ run_dir = _write_run_fixture(tmp_path)
+ trades = pd.read_csv(run_dir / "artifacts" / "trades.csv")
+ equity = pd.read_csv(run_dir / "artifacts" / "equity.csv")
+
+ assert list(trades.columns) == ENGINE_TRADE_COLUMNS
+ # 9 round trips → 18 rows: entry rows (pnl == 0) + exit rows (pnl > 0).
+ assert len(trades) == 18
+ assert int((trades["pnl"] == 0.0).sum()) == 9
+ assert int((trades["pnl"] > 0).sum()) == 9
+ assert (trades["reason"] != "").all()
+
+ assert list(equity.columns) == ["timestamp", *ENGINE_EQUITY_COLUMNS]
+ assert len(equity) == DAYS
+ assert "benchmark" not in equity.columns, "no dual benchmark columns"
+ assert "date" not in equity.columns, "no dual date columns"
+
+
+# ---------------------------------------------------------------------------
+# compute_evidence_for_run on the REAL engine schema
+# ---------------------------------------------------------------------------
+
+
+@requires_harness
+class TestComputeEvidence:
+ def test_real_schema_yields_rows_with_expected_attribution(self, tmp_path) -> None:
+ run_dir = _write_run_fixture(tmp_path)
+ rows = _compute_with_fixture_windows(run_dir)
+ assert isinstance(rows, list)
+ assert rows, "real engine-schema artifacts must produce evidence rows"
+ counts = {row.regime: row.trades_in_regime for row in rows}
+ regimes = {row.regime for row in rows}
+ assert regimes == set(EXPECTED_COUNTS), f"unexpected regime set: {regimes}"
+ for regime, expected in EXPECTED_COUNTS.items():
+ assert (
+ counts[regime] == expected
+ ), f"regime {regime}: expected {expected} trades, harness counted {counts[regime]}"
+ for row in rows:
+ assert (
+ row.last_verified == "2026-08-01"
+ ), f"{row.regime}: explicit today= must pin last_verified, got {row.last_verified!r}"
+
+ def test_entry_rows_are_excluded_from_trade_counts(self, tmp_path) -> None:
+ trades_path = _write_run_fixture(tmp_path) / "artifacts" / "trades.csv"
+ activity = sd_artifacts.read_trade_activity(trades_path)
+ assert activity is not None
+ exit_dates, max_concurrent = activity
+ # 18 physical rows but exactly 9 round trips — one count per exit row.
+ assert exit_dates == sorted(ALL_TRADE_DAYS)
+ assert len(exit_dates) == 9
+ assert max_concurrent == 1
+
+ rows = _compute_with_fixture_windows(_write_run_fixture(tmp_path / "again"))
+ assert sum(row.trades_in_regime for row in rows) == 9
+
+ def test_benchmark_is_read_from_benchmark_equity(self, tmp_path) -> None:
+ run_dir = _write_run_fixture(tmp_path)
+ equity_frame = pd.read_csv(run_dir / "artifacts" / "equity.csv")
+ assert "benchmark_equity" in equity_frame.columns
+ assert "benchmark" not in equity_frame.columns
+
+ rows = _compute_with_fixture_windows(run_dir)
+ assert rows
+ for row in rows:
+ assert row.benchmark_in_regime is not None, (
+ f"{row.regime}: benchmark must be read from the benchmark_equity "
+ f"column"
+ )
+ assert row.excess_in_regime is not None
+
+ def test_date_ranges_format(self, tmp_path) -> None:
+ run_dir = _write_run_fixture(tmp_path)
+ rows = _compute_with_fixture_windows(run_dir)
+ pattern = re.compile(r"^\d{4}-\d{2} to \d{4}-\d{2}$")
+ for row in rows:
+ assert isinstance(row.date_ranges, tuple)
+ assert row.date_ranges, f"{row.regime}: date_ranges must not be empty"
+ for entry in row.date_ranges:
+ assert pattern.match(entry), f"bad date_range format: {entry!r}"
+
+ def test_quality_classification_applied(self, tmp_path) -> None:
+ run_dir = _write_run_fixture(tmp_path)
+ rows = _compute_with_fixture_windows(run_dir)
+ for row in rows:
+ coverage = sd_models.coverage_days_from_ranges(list(row.date_ranges))
+ expected_quality = sd_models.classify_quality(
+ row.trades_in_regime, coverage
+ )
+ assert row.evidence_quality == expected_quality, (
+ f"{row.regime}: quality {row.evidence_quality!r} != "
+ f"classify_quality({row.trades_in_regime}, {coverage}) = {expected_quality!r}"
+ )
+ # Every fixture regime has < MIN_TRADES trades → insufficient plus
+ # the stable insufficient-trades: warning prefix.
+ assert row.evidence_quality == "insufficient"
+ assert any(w.startswith("insufficient-trades:") for w in row.warnings)
+
+ def test_breakeven_uses_position_size(self, tmp_path) -> None:
+ full_rows = _call_compute(
+ "sdm:fixture_run",
+ _write_run_fixture(tmp_path / "full"),
+ benchmark_window=5,
+ bear_threshold=-0.05,
+ bull_threshold=0.05,
+ position_size=1.0,
+ today="2026-08-01",
+ )
+ half_rows = _call_compute(
+ "sdm:fixture_run",
+ _write_run_fixture(tmp_path / "half"),
+ benchmark_window=5,
+ bear_threshold=-0.05,
+ bull_threshold=0.05,
+ position_size=0.5,
+ today="2026-08-01",
+ )
+ full_by_regime = {r.regime: r.breakeven_fee_bps for r in full_rows}
+ half_by_regime = {r.regime: r.breakeven_fee_bps for r in half_rows}
+ for regime, full in full_by_regime.items():
+ half = half_by_regime[regime]
+ assert full is not None and half is not None, f"{regime}: breakeven missing"
+ assert full > 0, f"{regime}: expected positive gross edge in fixture"
+ assert half == pytest.approx(2.0 * full, rel=1e-9), (
+ f"{regime}: position_size=0.5 must double breakeven "
+ f"(full={full}, half={half})"
+ )
+
+ def test_single_position_run_carries_no_concurrency_caveat(self, tmp_path) -> None:
+ run_dir = _write_run_fixture(tmp_path)
+ rows = _compute_with_fixture_windows(run_dir)
+ assert rows
+ for row in rows:
+ assert not any(
+ w.startswith(sd_harness.MULTI_POSITION_WARNING_PREFIX)
+ for w in row.warnings
+ ), f"{row.regime}: single-position runs need no concurrency caveat"
+ assert (
+ row.breakeven_fee_bps is not None
+ ), f"{row.regime}: single-position runs keep the exact breakeven"
+
+ def test_rows_carry_stage_provenance_and_regime_definition(self, tmp_path) -> None:
+ # initial-d (#969): every row names its evidence stage, the run it
+ # came from, and the regime-labeling parameters used.
+ run_dir = _write_run_fixture(tmp_path)
+ rows = _compute_with_fixture_windows(run_dir)
+ assert rows
+ definition = json.loads(rows[0].regime_definition)
+ for row in rows:
+ assert row.evidence_stage == "backtest"
+ assert row.provenance == str(run_dir)
+ assert json.loads(row.regime_definition) == definition
+ assert definition["benchmark_window"] == 5
+ assert definition["bear_threshold"] == -0.05
+ assert definition["bull_threshold"] == 0.05
+ assert definition["sharpe_annualization_bars"] == 252
+
+ def test_unparseable_trade_dates_are_rejected_not_fatal(self, tmp_path) -> None:
+ run_dir = _write_run_fixture(tmp_path)
+ trades_path = run_dir / "artifacts" / "trades.csv"
+ trades = pd.read_csv(trades_path)
+ junk_row = {column: "" for column in trades.columns}
+ junk_row.update(
+ {"timestamp": "not-a-date", "code": "TEST.SH", "side": "sell", "pnl": 50.0}
+ )
+ pd.concat([trades, pd.DataFrame([junk_row])], ignore_index=True).to_csv(
+ trades_path, index=False
+ )
+
+ rows = _compute_with_fixture_windows(run_dir)
+ counts = {row.regime: row.trades_in_regime for row in rows}
+ assert (
+ counts == EXPECTED_COUNTS
+ ), "unparseable-date rows must be skipped without changing counts"
+
+ def test_missing_csvs_or_artifacts_returns_empty_list_no_crash(
+ self, tmp_path
+ ) -> None:
+ empty_run = tmp_path / "empty_run"
+ empty_run.mkdir()
+ assert (
+ _call_compute(
+ "sdm:empty",
+ empty_run,
+ benchmark_window=5,
+ bear_threshold=-0.05,
+ bull_threshold=0.05,
+ today="2026-08-01",
+ )
+ == []
+ )
+
+ no_artifacts = tmp_path / "no_artifacts"
+ no_artifacts.mkdir()
+ assert (
+ _call_compute(
+ "sdm:empty",
+ no_artifacts,
+ benchmark_window=5,
+ bear_threshold=-0.05,
+ bull_threshold=0.05,
+ today="2026-08-01",
+ )
+ == []
+ )
+
+ def test_binary_garbage_trades_returns_empty_without_raising(
+ self, tmp_path
+ ) -> None:
+ run_dir = _write_run_fixture(tmp_path)
+ trades_path = run_dir / "artifacts" / "trades.csv"
+ trades_path.write_bytes(b"\xff\xfe\x00\x81garbage\x93\xfd")
+
+ assert sd_artifacts.read_trade_activity(trades_path) is None
+ assert _compute_with_fixture_windows(run_dir) == []
+
+ def test_binary_garbage_equity_returns_empty_without_raising(
+ self, tmp_path
+ ) -> None:
+ run_dir = _write_run_fixture(tmp_path)
+ equity_path = run_dir / "artifacts" / "equity.csv"
+ equity_path.write_bytes(b"\x93\xfd\x00binary\xff\xfe")
+
+ assert sd_artifacts.read_equity_series(equity_path) is None
+ assert _compute_with_fixture_windows(run_dir) == []
+
+
+# ---------------------------------------------------------------------------
+# Legacy one-row-per-trade artifacts still parse via aliases
+# ---------------------------------------------------------------------------
+
+
+@requires_harness
+class TestLegacyAliasSupport:
+ def test_legacy_date_benchmark_artifacts_still_parse(self, tmp_path) -> None:
+ run_dir = _write_legacy_fixture(tmp_path)
+ equity = pd.read_csv(run_dir / "artifacts" / "equity.csv")
+ assert {"date", "equity", "benchmark"} <= set(equity.columns)
+ assert "timestamp" not in equity.columns
+
+ rows = _compute_with_fixture_windows(run_dir)
+ counts = {r.regime: r.trades_in_regime for r in rows}
+ assert (
+ counts == EXPECTED_COUNTS
+ ), "legacy one-row-per-trade artifacts must keep counting every row"
+ for row in rows:
+ assert row.benchmark_in_regime is not None
+ # No zero-pnl marker → concurrency undetectable → fail-closed:
+ # generic caveat and a null breakeven, never a silent aggregate.
+ assert row.breakeven_fee_bps is None
+ assert any(
+ w.startswith(sd_harness.MULTI_POSITION_WARNING_PREFIX)
+ and "concurrency is unknown" in w
+ for w in row.warnings
+ ), f"{row.regime}: marker-less artifacts must carry the generic caveat"
+
+ def test_legacy_reader_counts_every_row_without_concurrency(self, tmp_path) -> None:
+ trades_path = _write_legacy_fixture(tmp_path) / "artifacts" / "trades.csv"
+ activity = sd_artifacts.read_trade_activity(trades_path)
+ assert activity is not None
+ trade_dates, max_concurrent = activity
+ assert trade_dates == sorted(ALL_TRADE_DAYS)
+ assert max_concurrent is None
+
+
+# ---------------------------------------------------------------------------
+# Multi-position runs carry the aggregate-breakeven caveat
+# ---------------------------------------------------------------------------
+
+
+@requires_harness
+class TestMultiPositionCaveat:
+ def test_overlapping_positions_null_the_breakeven(self, tmp_path) -> None:
+ # sergio12S (#969): the aggregate breakeven is structurally invalid
+ # for multi-position runs, so the row stores null instead of a number
+ # wrong by 1.1-6.5x — never a silent aggregate figure.
+ run_dir = _write_multi_position_fixture(tmp_path)
+ activity = sd_artifacts.read_trade_activity(
+ run_dir / "artifacts" / "trades.csv"
+ )
+ assert activity is not None
+ assert activity[1] == 2, "AAA (Jan 14-16) and BBB (Jan 15-21) overlap"
+
+ rows = _compute_with_fixture_windows(run_dir)
+ counts = {r.regime: r.trades_in_regime for r in rows}
+ assert counts == {"bear_market": 1, "bull_market": 1}
+ for row in rows:
+ assert row.breakeven_fee_bps is None, (
+ f"{row.regime}: multi-position breakeven must be null, got "
+ f"{row.breakeven_fee_bps!r}"
+ )
+ assert (
+ row.cost_sensitive is False
+ ), f"{row.regime}: sensitivity is unverifiable, not assertable"
+ caveats = [
+ w
+ for w in row.warnings
+ if w.startswith(sd_harness.MULTI_POSITION_WARNING_PREFIX)
+ ]
+ assert len(caveats) == 1, f"{row.regime}: exactly one caveat expected"
+ assert "2 concurrent positions" in caveats[0]
+ assert "breakeven_fee_bps is null" in caveats[0]
+
+
+# ---------------------------------------------------------------------------
+# rebuild_evidence
+# ---------------------------------------------------------------------------
+
+
+def _make_store(tmp_path):
+ from src.strategy_discovery.evidence_store import EvidenceStore
+
+ return EvidenceStore(tmp_path / "evidence.db")
+
+
+@requires_harness
+class TestRebuildEvidence:
+ def test_rebuild_clears_then_upserts_and_reports_skipped_dirs(
+ self, tmp_path
+ ) -> None:
+ store = _make_store(tmp_path)
+ junk = sd_models.EvidenceRow(
+ strategy_id="junk:row", regime="bear_market", trades_in_regime=1
+ )
+ store.upsert_rows([junk])
+
+ good_run = _write_run_fixture(tmp_path / "good")
+ bad_run = tmp_path / "bad_run"
+ bad_run.mkdir()
+
+ envelope = sd_harness.rebuild_evidence(
+ [
+ {"strategy_id": "sdm:fixture_run", "run_dir": str(good_run)},
+ {"strategy_id": "sdm:bad_run", "run_dir": str(bad_run)},
+ ],
+ store,
+ )
+
+ assert (
+ store.get_rows(strategy_id="junk:row") == []
+ ), "rebuild_evidence must clear the store before repopulating"
+ store_rows = store.get_rows()
+ assert store_rows, "good run_dir must have produced evidence rows"
+ assert {r.strategy_id for r in store_rows} == {"sdm:fixture_run"}
+ # Rebuild runs compute_evidence_for_run with its documented defaults;
+ # whatever regime windows those defaults find, no fixture round trip
+ # may be lost or double-counted (9 round trips, exit rows only).
+ assert sum(r.trades_in_regime for r in store_rows) == 9
+
+ assert isinstance(
+ envelope, dict
+ ), f"rebuild envelope must be a dict, got {type(envelope)}"
+ assert envelope.get("status") == "ok"
+ skipped = envelope.get("skipped")
+ assert (
+ skipped
+ ), f"envelope must carry a 'skipped' entry for bad dirs: {envelope!r}"
+ assert len(skipped) == 1
+ skipped_entry = skipped[0]
+ assert str(bad_run) in str(
+ skipped_entry.get("run_dir", "")
+ ), f"skipped entry must name the bad run_dir: {skipped_entry!r}"
+ assert skipped_entry.get(
+ "reason"
+ ), f"skipped entry must carry a reason: {skipped_entry!r}"
+
+ def test_rebuild_with_no_runs_leaves_store_empty(self, tmp_path) -> None:
+ store = _make_store(tmp_path)
+ junk = sd_models.EvidenceRow(
+ strategy_id="junk:row", regime="bull_market", trades_in_regime=2
+ )
+ store.upsert_rows([junk])
+ envelope = sd_harness.rebuild_evidence([], store)
+ assert store.row_count() == 0
+ assert envelope.get("status") == "ok"
+ assert envelope.get("rows") == 0
diff --git a/agent/tests/test_strategy_discovery_mcp.py b/agent/tests/test_strategy_discovery_mcp.py
new file mode 100644
index 000000000..c4788ea5d
--- /dev/null
+++ b/agent/tests/test_strategy_discovery_mcp.py
@@ -0,0 +1,155 @@
+"""Frozen-contract tests for Strategy Discovery tools over MCP — issue #969.
+
+AC1 (no phantom tools): ``list_strategies`` / ``query_strategies`` /
+``get_strategy_evidence`` must be registered on the FastMCP server and each
+wrapper must delegate to ``registry.execute(<own name>, <args>)`` — never the
+generic "Tool not found" path when the facade layer can answer, and never a
+crash when the registry is missing or broken (actionable JSON instead).
+
+Follows the ``test_qveris_mcp.py`` fixture pattern: a fresh/monkeypatched
+``mcp_server._registry`` per test. No network: delegation is verified against
+recording fake registries; the real store/facade are never constructed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+import pytest
+
+import mcp_server
+from src.agent.tools import ToolRegistry
+
+SD_TOOLS = ("list_strategies", "query_strategies", "get_strategy_evidence")
+
+
+def _unwrapped(name: str):
+ """Return the raw callable behind a fastmcp-registered tool, or None."""
+ obj = getattr(mcp_server, name, None)
+ if obj is None:
+ return None
+ return getattr(obj, "fn", None) or getattr(obj, "__wrapped__", None) or obj
+
+
+def _sd_tools_landed() -> bool:
+ return all(getattr(mcp_server, name, None) is not None for name in SD_TOOLS)
+
+
+requires_sd_mcp = pytest.mark.skipif(
+ not _sd_tools_landed(),
+ reason="waiting on sibling B: mcp_server Strategy Discovery tools not landed yet (issue #969)",
+)
+
+
[email protected](autouse=True)
+def fresh_mcp_registry():
+ """Reset the cached registry so each test rebuilds under its own patch."""
+ mcp_server._registry = None
+ yield
+ mcp_server._registry = None
+
+
+class _RecordingRegistry:
+ """Records execute() calls and returns canned envelopes."""
+
+ def __init__(self, canned='{"status": "ok", "recorded": true}'):
+ self.calls = []
+ self.canned = canned
+
+ def execute(self, name, params):
+ self.calls.append((name, dict(params)))
+ return self.canned
+
+
+@requires_sd_mcp
+class TestRegistration:
+ def test_all_three_tools_registered_with_descriptions(self) -> None:
+ tools = asyncio.run(mcp_server.mcp.list_tools())
+ registered = {t.name for t in tools}
+ missing = set(SD_TOOLS) - registered
+ assert not missing, (
+ f"MCP server is missing Strategy Discovery tools: {missing}. "
+ "Issue #969 requires all three registered AND callable (AC1)."
+ )
+ by_name = {t.name: t for t in tools}
+ for name in SD_TOOLS:
+ description = getattr(by_name[name], "description", "") or ""
+ assert description.strip(), f"{name} must carry an MCP description"
+ assert callable(_unwrapped(name)), f"mcp_server.{name} is not callable"
+
+
+@requires_sd_mcp
+class TestDelegation:
+ @pytest.mark.parametrize(
+ "tool_name,args",
+ [
+ ("list_strategies", {"limit": 7, "offset": 2, "source": "alpha_zoo"}),
+ (
+ "query_strategies",
+ {"regime": "bear_market", "min_trades": 12, "cost_feasible": True},
+ ),
+ ("get_strategy_evidence", {"strategy_id": "alpha_zoo:a1", "regime": None}),
+ ],
+ )
+ def test_wrapper_delegates_to_registry_execute_with_own_name(
+ self, monkeypatch, tool_name, args
+ ) -> None:
+ recording = _RecordingRegistry()
+ monkeypatch.setattr(mcp_server, "_get_registry", lambda: recording)
+
+ fn = _unwrapped(tool_name)
+ result = fn(**args)
+
+ assert recording.calls, f"{tool_name} did not call registry.execute"
+ called_name, called_params = recording.calls[-1]
+ assert (
+ called_name == tool_name
+ ), f"{tool_name} must delegate under its own name, got {called_name!r}"
+ for key, value in args.items():
+ if value is None:
+ continue
+ assert key in called_params and called_params[key] == value, (
+ f"{tool_name}: argument {key}={value!r} not forwarded "
+ f"(params={called_params!r})"
+ )
+ assert result == recording.canned
+
+ def test_missing_tool_in_registry_surfaces_json_error_not_crash(
+ self, monkeypatch
+ ) -> None:
+ # A registry that lacks the tool (e.g. facade import failed) must
+ # still answer with a parseable error envelope.
+ monkeypatch.setattr(mcp_server, "_get_registry", lambda: ToolRegistry())
+ fn = _unwrapped("list_strategies")
+ result = fn()
+ payload = json.loads(result)
+ assert payload.get("status") == "error"
+ assert payload.get("error")
+
+ def test_broken_registry_yields_actionable_error_not_exception(
+ self, monkeypatch
+ ) -> None:
+ # The exception message is a leak canary: the envelope must be a
+ # generic error, never echoing raw exception text (internal paths).
+ canary = "internal-detail /etc/shards/leak canary 7f3d"
+
+ def _exploding_registry():
+ raise RuntimeError(canary)
+
+ monkeypatch.setattr(mcp_server, "_get_registry", _exploding_registry)
+ for name in SD_TOOLS:
+ fn = _unwrapped(name)
+ if name == "get_strategy_evidence":
+ result = fn(strategy_id="alpha_zoo:a1")
+ else:
+ result = fn()
+ payload = json.loads(result)
+ assert (
+ payload.get("status") == "error" or payload.get("ok") is False
+ ), f"{name}: broken registry must produce an error envelope, got {payload!r}"
+ error = payload.get("error")
+ assert error, f"{name}: error envelope must carry a message"
+ assert (
+ canary not in error
+ ), f"{name}: raw exception text leaked into the envelope: {error!r}"
diff --git a/agent/tests/test_strategy_discovery_models.py b/agent/tests/test_strategy_discovery_models.py
new file mode 100644
index 000000000..144cae885
--- /dev/null
+++ b/agent/tests/test_strategy_discovery_models.py
@@ -0,0 +1,396 @@
+"""Frozen-contract tests for ``src.strategy_discovery.models`` — issue #969.
+
+The core-package contract (REGIMES, quality ladder, evidence thresholds,
+``EvidenceRow`` / ``StrategySummary`` shapes, ``coverage_days_from_ranges``,
+``classify_quality``, ``breakeven_fee_bps``, ``build_warnings``) is pinned
+here verbatim. Pure logic: no network, no real stores, no wall-clock
+dependence. AC5 (<10 trades insufficient), AC6 (sizing-corrected breakeven),
+and part of AC7 (no bundled YAML next to the models) are covered here.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import inspect
+import math
+import pathlib
+
+import pytest
+
+try:
+ from src.strategy_discovery import models as sd_models
+
+ MODELS_AVAILABLE = True
+except ImportError:
+ sd_models = None
+ MODELS_AVAILABLE = False
+
+requires_models = pytest.mark.skipif(
+ not MODELS_AVAILABLE,
+ reason="waiting on sibling A: src.strategy_discovery.models not landed yet (issue #969)",
+)
+
+
+@requires_models
+class TestConstants:
+ def test_regimes_tuple_exact(self) -> None:
+ assert sd_models.REGIMES == ("bear_market", "bull_market", "structural")
+
+ def test_evidence_stages_vocabulary_exact(self) -> None:
+ assert sd_models.EVIDENCE_STAGES == (
+ "hypothesis",
+ "backtest",
+ "holdout",
+ "shadow",
+ "live_canary",
+ "retired",
+ )
+
+ def test_quality_ladder_constants_and_order(self) -> None:
+ assert sd_models.QUALITY_ADEQUATE == "adequate"
+ assert sd_models.QUALITY_MARGINAL == "marginal"
+ assert sd_models.QUALITY_INSUFFICIENT == "insufficient"
+ order = sd_models.QUALITY_ORDER
+ assert set(order) >= {"adequate", "marginal", "insufficient"}
+ assert order["adequate"] > order["marginal"] > order["insufficient"]
+
+ def test_evidence_threshold_and_borderline_constants(self) -> None:
+ assert sd_models.MIN_TRADES == 10
+ assert sd_models.MIN_COVERAGE_DAYS == 730
+ assert sd_models.COST_SENSITIVE_BREAKEVEN_BPS == 5.0
+ assert sd_models.BORDERLINE_TRADE_BUFFER == 5
+ assert sd_models.BORDERLINE_BREAKEVEN_BPS == 10.0
+ assert sd_models.BORDERLINE_COVERAGE_BUFFER_DAYS == 365
+
+
+@requires_models
+class TestEvidenceRow:
+ def test_defaults_and_frozen(self) -> None:
+ row = sd_models.EvidenceRow(
+ strategy_id="alpha_zoo:x", regime="bear_market", trades_in_regime=12
+ )
+ assert row.position_size is None
+ assert row.return_in_regime is None
+ assert row.benchmark_in_regime is None
+ assert row.excess_in_regime is None
+ assert row.sharpe_in_regime is None
+ assert row.max_drawdown_in_regime is None
+ assert row.date_ranges == ()
+ assert isinstance(row.date_ranges, tuple)
+ assert row.breakeven_fee_bps is None
+ assert row.cost_sensitive is False
+ assert row.evidence_quality == "insufficient"
+ assert row.warnings == ()
+ assert row.last_verified == ""
+ assert row.evidence_stage == "backtest"
+ assert row.provenance == ""
+ assert row.regime_definition == ""
+ with pytest.raises(dataclasses.FrozenInstanceError):
+ row.trades_in_regime = 99
+
+ def test_invalid_regime_raises_value_error(self) -> None:
+ with pytest.raises(ValueError):
+ sd_models.EvidenceRow(
+ strategy_id="s", regime="sideways", trades_in_regime=12
+ )
+
+ def test_invalid_evidence_stage_raises_value_error(self) -> None:
+ with pytest.raises(ValueError):
+ sd_models.EvidenceRow(
+ strategy_id="s",
+ regime="bear_market",
+ trades_in_regime=12,
+ evidence_stage="rumor",
+ )
+
+ def test_every_evidence_stage_is_accepted(self) -> None:
+ for stage in sd_models.EVIDENCE_STAGES:
+ row = sd_models.EvidenceRow(
+ strategy_id="s",
+ regime="bear_market",
+ trades_in_regime=12,
+ evidence_stage=stage,
+ )
+ assert row.evidence_stage == stage
+
+ def test_full_construction_roundtrip(self) -> None:
+ row = sd_models.EvidenceRow(
+ strategy_id="sdm:abc",
+ regime="bull_market",
+ trades_in_regime=15,
+ position_size=0.5,
+ return_in_regime=0.12,
+ benchmark_in_regime=-0.03,
+ excess_in_regime=0.15,
+ sharpe_in_regime=0.9,
+ max_drawdown_in_regime=-0.08,
+ date_ranges=("2019-03 to 2020-01",),
+ breakeven_fee_bps=33.0,
+ cost_sensitive=False,
+ evidence_quality="adequate",
+ warnings=("w1",),
+ last_verified="2026-08-01",
+ )
+ assert row.sharpe_in_regime == 0.9
+ assert row.date_ranges == ("2019-03 to 2020-01",)
+ assert row.warnings == ("w1",)
+
+
+@requires_models
+class TestStrategySummary:
+ def test_defaults_and_frozen(self) -> None:
+ s = sd_models.StrategySummary(
+ strategy_id="alpha_zoo:a", name="A", source="alpha_zoo"
+ )
+ assert s.description is None
+ assert s.status is None
+ assert s.universe is None
+ assert s.has_evidence is False
+ assert s.regimes_with_evidence == ()
+ full = sd_models.StrategySummary(
+ strategy_id="sdm:b",
+ name="B",
+ source="sdm",
+ description="d",
+ status="active",
+ universe="csi300",
+ has_evidence=True,
+ regimes_with_evidence=("bear_market",),
+ )
+ assert full.regimes_with_evidence == ("bear_market",)
+ with pytest.raises(dataclasses.FrozenInstanceError):
+ full.has_evidence = False
+
+
+@requires_models
+class TestCoverageDays:
+ def test_two_disjoint_windows_span(self) -> None:
+ # 2018-01-01 .. 2022-12-31 = 1825 days.
+ assert (
+ sd_models.coverage_days_from_ranges(
+ ["2018-01 to 2018-12", "2022-01 to 2022-12"]
+ )
+ == 1825
+ )
+
+ def test_single_year_malformed_entries_and_empty(self) -> None:
+ assert sd_models.coverage_days_from_ranges(["2018-01 to 2018-12"]) == 364
+ assert (
+ sd_models.coverage_days_from_ranges(
+ ["garbage", "2018-01 to 2018-12", "2018-99 to nope"]
+ )
+ == 364
+ )
+ assert sd_models.coverage_days_from_ranges([]) == 0
+
+
+@requires_models
+class TestClassifyQuality:
+ def test_few_trades_is_insufficient_even_with_long_coverage(self) -> None:
+ # AC5: <10 trades is insufficient regardless of coverage.
+ assert sd_models.classify_quality(9, 9999) == "insufficient"
+ assert (
+ sd_models.classify_quality(
+ sd_models.MIN_TRADES - 1, sd_models.MIN_COVERAGE_DAYS
+ )
+ == "insufficient"
+ )
+
+ def test_short_coverage_is_marginal(self) -> None:
+ assert sd_models.classify_quality(12, 400) == "marginal"
+ assert (
+ sd_models.classify_quality(
+ sd_models.MIN_TRADES, sd_models.MIN_COVERAGE_DAYS - 1
+ )
+ == "marginal"
+ )
+
+ def test_adequate_when_both_thresholds_met(self) -> None:
+ assert sd_models.classify_quality(12, 800) == "adequate"
+ # Issue #969 flags "trades < 10" and "span < 2 years", so exactly
+ # MIN_TRADES and exactly MIN_COVERAGE_DAYS must pass.
+ assert (
+ sd_models.classify_quality(
+ sd_models.MIN_TRADES, sd_models.MIN_COVERAGE_DAYS
+ )
+ == "adequate"
+ )
+
+
+@requires_models
+class TestBreakevenFeeBps:
+ def test_formula_exact(self) -> None:
+ # breakeven_fee_bps == ln(1+g) / (2*n*s) * 10_000, s defaulting to 1.0
+ expected = math.log(1 + 0.20) / (2 * 10 * 1.0) * 10_000
+ assert sd_models.breakeven_fee_bps(0.20, 10) == pytest.approx(
+ expected, rel=1e-12
+ )
+ assert sd_models.breakeven_fee_bps(0.20, 10, 1.0) == pytest.approx(
+ expected, rel=1e-12
+ )
+
+ def test_half_position_size_doubles_breakeven(self) -> None:
+ # Reviewer-pinned AC6 sizing correction: at s=0.5 the breakeven fee is
+ # exactly 2x the full-position value.
+ full = sd_models.breakeven_fee_bps(0.20, 10, 1.0)
+ half = sd_models.breakeven_fee_bps(0.20, 10, 0.5)
+ assert full > 0
+ assert half == pytest.approx(2.0 * full, rel=1e-12)
+
+ def test_none_for_unusable_return_or_trade_count(self) -> None:
+ assert sd_models.breakeven_fee_bps(0.20, 0) is None
+ assert sd_models.breakeven_fee_bps(0.20, -3) is None
+ assert sd_models.breakeven_fee_bps(-1.0, 10) is None
+ assert sd_models.breakeven_fee_bps(-1.5, 10) is None
+
+ def test_none_for_nonpositive_size_and_non_finite_inputs(self) -> None:
+ assert sd_models.breakeven_fee_bps(0.20, 10, 0.0) is None
+ assert sd_models.breakeven_fee_bps(0.20, 10, -0.5) is None
+ assert sd_models.breakeven_fee_bps(float("nan"), 10) is None
+ assert sd_models.breakeven_fee_bps(float("inf"), 10) is None
+ assert sd_models.breakeven_fee_bps(0.20, 10, float("nan")) is None
+
+
+def _call_build_warnings(scenario: dict) -> tuple:
+ """Call ``build_warnings`` tolerantly across plausible signatures.
+
+ The contract pins behavior (tuple with stable prefixes), not the exact
+ parameter list; this helper tries keyword mapping by known aliases first,
+ then positional shapes. A signature that beats every shape fails loudly.
+ """
+ assert MODELS_AVAILABLE, "src.strategy_discovery.models not importable"
+ bw = sd_models.build_warnings
+ aliases = {
+ "trades": ("trades", "trades_in_regime", "n_trades", "trade_count"),
+ "coverage_days": ("coverage_days", "coverage", "total_coverage_days"),
+ "breakeven_fee_bps": ("breakeven_fee_bps", "breakeven", "breakeven_bps"),
+ "quality": ("quality", "evidence_quality"),
+ "cost_sensitive": ("cost_sensitive",),
+ }
+ try:
+ sig = inspect.signature(bw)
+ except (TypeError, ValueError):
+ sig = None
+
+ if sig is not None:
+ kwargs = {}
+ for param in sig.parameters.values():
+ if param.kind in (param.VAR_POSITIONAL, param.VAR_KEYWORD):
+ continue
+ for key, names in aliases.items():
+ if param.name in names and key in scenario:
+ kwargs[param.name] = scenario[key]
+ required = [
+ p
+ for p in sig.parameters.values()
+ if p.default is p.empty and p.kind not in (p.VAR_POSITIONAL, p.VAR_KEYWORD)
+ ]
+ if len(kwargs) >= len(required):
+ try:
+ out = bw(**kwargs)
+ if isinstance(out, tuple):
+ return out
+ except TypeError:
+ pass
+
+ fallbacks = [
+ lambda: bw(
+ scenario["trades"],
+ scenario["coverage_days"],
+ scenario["breakeven_fee_bps"],
+ scenario["quality"],
+ scenario["cost_sensitive"],
+ ),
+ lambda: bw(
+ scenario["trades"], scenario["coverage_days"], scenario["breakeven_fee_bps"]
+ ),
+ lambda: bw(
+ scenario["trades"],
+ scenario["coverage_days"],
+ scenario["breakeven_fee_bps"],
+ scenario["cost_sensitive"],
+ ),
+ ]
+ for shape in fallbacks:
+ try:
+ out = shape()
+ except TypeError:
+ continue
+ if isinstance(out, tuple):
+ return out
+
+ pytest.fail(
+ "contract drift: build_warnings could not be called with "
+ f"{{trades, coverage_days, breakeven_fee_bps, quality, cost_sensitive}} — scenario={scenario}"
+ )
+
+
+@requires_models
+class TestBuildWarnings:
+ def test_insufficient_trades_prefix(self) -> None:
+ warns = _call_build_warnings(
+ {
+ "trades": 5,
+ "coverage_days": 2000,
+ "breakeven_fee_bps": 50.0,
+ "quality": "insufficient",
+ "cost_sensitive": False,
+ }
+ )
+ assert isinstance(warns, tuple)
+ assert any(
+ isinstance(w, str) and w.startswith("insufficient-trades:") for w in warns
+ ), f"expected an 'insufficient-trades:' warning for 5 trades, got {warns!r}"
+
+ def test_short_coverage_prefix(self) -> None:
+ warns = _call_build_warnings(
+ {
+ "trades": 50,
+ "coverage_days": 200,
+ "breakeven_fee_bps": 50.0,
+ "quality": "marginal",
+ "cost_sensitive": False,
+ }
+ )
+ assert any(
+ isinstance(w, str) and w.startswith("short-coverage:") for w in warns
+ ), f"expected a 'short-coverage:' warning for 200 days coverage, got {warns!r}"
+
+ def test_cost_sensitive_prefix(self) -> None:
+ warns = _call_build_warnings(
+ {
+ "trades": 50,
+ "coverage_days": 2000,
+ "breakeven_fee_bps": 2.0,
+ "quality": "adequate",
+ "cost_sensitive": True,
+ }
+ )
+ assert any(
+ isinstance(w, str) and w.startswith("cost-sensitive:") for w in warns
+ ), f"expected a 'cost-sensitive:' warning for breakeven 2.0 bps, got {warns!r}"
+
+ def test_clean_evidence_yields_empty_tuple(self) -> None:
+ warns = _call_build_warnings(
+ {
+ "trades": 200,
+ "coverage_days": 2200,
+ "breakeven_fee_bps": 120.0,
+ "quality": "adequate",
+ "cost_sensitive": False,
+ }
+ )
+ assert warns == ()
+
+
+@requires_models
+class TestNoSeedCorpusInModels:
+ def test_no_yaml_bundled_next_to_models(self) -> None:
+ # AC7: the core package ships no seed corpus.
+ pkg_dir = pathlib.Path(sd_models.__file__).resolve().parent
+ yaml_files = sorted(
+ p.name for pattern in ("*.yaml", "*.yml") for p in pkg_dir.glob(pattern)
+ )
+ assert (
+ yaml_files == []
+ ), f"AC7 violation: seed-corpus YAML files found in src/strategy_discovery: {yaml_files}"
diff --git a/agent/tests/test_strategy_discovery_routing.py b/agent/tests/test_strategy_discovery_routing.py
new file mode 100644
index 000000000..51bfa56a1
--- /dev/null
+++ b/agent/tests/test_strategy_discovery_routing.py
@@ -0,0 +1,170 @@
+"""Frozen-contract tests for Strategy Discovery prompt routing — issue #969.
+
+AC2 (routing validated at startup): ``ContextBuilder.build_system_prompt()``
+must include the Strategy Discovery routing block when — and only when — all
+three tools are present in the tool registry, and must degrade to a clean
+prompt (no block, no crash) when ``src.strategy_discovery`` cannot be
+imported. The expected block text is derived from
+``src.strategy_discovery.guard.routing_block`` so these tests stay decoupled
+from the block's exact wording.
+
+Registries are real ``ToolRegistry`` objects with minimal ``BaseTool``
+stubs; ``SkillsLoader`` points at empty tmp dirs so no bundled skill scan or
+network can affect the prompt. No wall-clock assertions.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import sys
+
+import pytest
+
+from src.agent.context import ContextBuilder
+from src.agent.memory import WorkspaceMemory
+from src.agent.skills import SkillsLoader
+from src.agent.tools import BaseTool, ToolRegistry
+
+try:
+ from src.strategy_discovery import guard as sd_guard
+
+ GUARD_AVAILABLE = True
+except ImportError:
+ sd_guard = None
+ GUARD_AVAILABLE = False
+
+SD_TOOLS = ("list_strategies", "query_strategies", "get_strategy_evidence")
+
+
+class _StubTool(BaseTool):
+ description = "strategy discovery stub"
+ parameters = {"type": "object", "properties": {}, "required": []}
+
+ def __init__(self, name: str) -> None:
+ self.name = name
+
+ def execute(self, **kwargs) -> str:
+ return json.dumps({"status": "ok"})
+
+
+def _registry_with(names) -> ToolRegistry:
+ registry = ToolRegistry()
+ for name in names:
+ registry.register(_StubTool(name))
+ return registry
+
+
+def _context_module():
+ from src.agent import context as context_mod
+
+ return context_mod
+
+
+def _wiring_landed() -> bool:
+ if not GUARD_AVAILABLE:
+ return False
+ try:
+ source = inspect.getsource(_context_module())
+ except OSError:
+ return False
+ return "strategy_discovery" in source
+
+
+requires_routing = pytest.mark.skipif(
+ not _wiring_landed(),
+ reason=(
+ "waiting on sibling A+B: src.strategy_discovery.guard and/or the "
+ "src.agent.context Strategy Discovery routing wiring not landed yet (issue #969)"
+ ),
+)
+
+
+def builder_factory(tmp_path):
+ """Build ContextBuilders over empty skill dirs (hermetic, offline)."""
+
+ def _build(registry: ToolRegistry) -> ContextBuilder:
+ empty_bundled = tmp_path / "bundled_skills"
+ empty_user = tmp_path / "user_skills"
+ empty_bundled.mkdir(exist_ok=True)
+ empty_user.mkdir(exist_ok=True)
+ return ContextBuilder(
+ registry=registry,
+ memory=WorkspaceMemory(),
+ skills_loader=SkillsLoader(
+ skills_dir=empty_bundled, user_skills_dir=empty_user
+ ),
+ )
+
+ return _build
+
+
+@requires_routing
+class TestRoutingBlockInPrompt:
+ def test_block_present_when_all_tools_registered(self, builder_factory) -> None:
+ registry = _registry_with(SD_TOOLS)
+ expected_block = sd_guard.routing_block(registry)
+ assert (
+ expected_block.strip()
+ ), "guard block must be non-empty for a full registry"
+
+ prompt = builder_factory(registry).build_system_prompt()
+ assert expected_block in prompt, (
+ "build_system_prompt() must embed the guard routing block when all "
+ "Strategy Discovery tools are registered"
+ )
+ for tool_name in SD_TOOLS:
+ assert tool_name in prompt
+
+ def test_block_absent_when_tools_missing(self, builder_factory) -> None:
+ partial = _registry_with(("list_strategies",))
+ full = _registry_with(SD_TOOLS)
+ full_block = sd_guard.routing_block(full)
+ assert full_block.strip()
+
+ prompt = builder_factory(partial).build_system_prompt()
+ assert (
+ full_block not in prompt
+ ), "routing block must be omitted when tools are missing (fail-safe, AC2)"
+ # Tools absent from the registry must not be advertised anywhere.
+ assert "query_strategies" not in prompt
+ assert "get_strategy_evidence" not in prompt
+
+ def test_prompt_still_builds_when_strategy_discovery_import_raises(
+ self, builder_factory, monkeypatch
+ ) -> None:
+ context_mod = _context_module()
+ registry = _registry_with(SD_TOOLS)
+ full_block = sd_guard.routing_block(registry)
+
+ def _raiser(*args, **kwargs):
+ raise RuntimeError("simulated strategy_discovery import failure")
+
+ class _BrokenModule:
+ def __getattr__(self, item):
+ raise RuntimeError("simulated strategy_discovery import failure")
+
+ # Break the package for any deferred import inside build_system_prompt
+ # (an entry set to None makes ``import`` raise ImportError).
+ monkeypatch.setitem(sys.modules, "src.strategy_discovery", None)
+ monkeypatch.setitem(sys.modules, "src.strategy_discovery.guard", None)
+ # Additionally poison any module-level binding the context may hold,
+ # covering top-level-import designs that call the guard at runtime.
+ for name in dir(context_mod):
+ obj = getattr(context_mod, name, None)
+ module_of = getattr(obj, "__module__", "")
+ if module_of.startswith("src.strategy_discovery"):
+ monkeypatch.setattr(context_mod, name, _raiser, raising=True)
+ elif inspect.ismodule(obj) and obj.__name__.startswith(
+ "src.strategy_discovery"
+ ):
+ monkeypatch.setattr(context_mod, name, _BrokenModule(), raising=True)
+
+ prompt = builder_factory(registry).build_system_prompt()
+ assert (
+ isinstance(prompt, str) and prompt.strip()
+ ), "prompt must still build when src.strategy_discovery import fails"
+ assert (
+ full_block not in prompt
+ ), "broken import must degrade to no routing block"
diff --git a/agent/tests/test_strategy_discovery_store.py b/agent/tests/test_strategy_discovery_store.py
new file mode 100644
index 000000000..699022b9c
--- /dev/null
+++ b/agent/tests/test_strategy_discovery_store.py
@@ -0,0 +1,370 @@
+"""Frozen-contract tests for ``src.strategy_discovery.store`` — issue #969.
+
+``EvidenceStore`` is the facade-owned SQLite cache keyed by
+``(strategy_id, regime)``. These tests pin: explicit tmp-path initialization,
+auto table creation, upsert-replace semantics, filtered+sorted reads,
+``clear()`` / ``row_count()``, NaN rejection, tuple→JSON→tuple
+round-tripping of ``date_ranges`` / ``warnings``, and skip-with-warning for
+rows carrying an unknown regime (externally tampered database). A fresh
+database MUST be empty (AC7: no seed corpus is baked into the package).
+
+No network, no wall clock: every row carries an explicit ``last_verified``.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+import pytest
+
+try:
+ from src.strategy_discovery import models as sd_models
+ from src.strategy_discovery.evidence_store import EvidenceStore
+
+ STORE_AVAILABLE = True
+except ImportError:
+ sd_models = None
+ EvidenceStore = None
+ STORE_AVAILABLE = False
+
+requires_store = pytest.mark.skipif(
+ not STORE_AVAILABLE,
+ reason="waiting on sibling A: src.strategy_discovery.evidence_store not landed yet (issue #969)",
+)
+
+
+def _make_store(db_file):
+ """Construct EvidenceStore tolerantly across positional/keyword db path."""
+ try:
+ return EvidenceStore(db_file)
+ except TypeError:
+ for kw in ("db_path", "path", "db_file", "database"):
+ try:
+ return EvidenceStore(**{kw: db_file})
+ except TypeError:
+ continue
+ raise
+
+
+def _row(strategy_id="alpha_zoo:a1", regime="bear_market", trades=12, **overrides):
+ fields = dict(
+ strategy_id=strategy_id,
+ regime=regime,
+ trades_in_regime=trades,
+ position_size=1.0,
+ return_in_regime=0.083,
+ benchmark_in_regime=-0.246,
+ excess_in_regime=0.329,
+ sharpe_in_regime=0.72,
+ max_drawdown_in_regime=-0.152,
+ date_ranges=("2018-01 to 2018-12", "2022-01 to 2022-12"),
+ breakeven_fee_bps=45.2,
+ cost_sensitive=False,
+ evidence_quality="adequate",
+ warnings=("insufficient-trades: sample", "short-coverage: sample"),
+ last_verified="2026-08-01",
+ evidence_stage="backtest",
+ provenance="/tmp/runs/fixture_run",
+ regime_definition='{"bear_threshold": -0.1, "benchmark_window": 252}',
+ )
+ fields.update(overrides)
+ return sd_models.EvidenceRow(**fields)
+
+
+@requires_store
+class TestInitialization:
+ def test_explicit_tmp_path_db_and_table_auto_created(self, tmp_path) -> None:
+ db_file = tmp_path / "evidence.db"
+ store = _make_store(db_file)
+ assert db_file.exists()
+ with sqlite3.connect(db_file) as conn:
+ tables = {
+ r[0]
+ for r in conn.execute(
+ "SELECT name FROM sqlite_master WHERE type='table'"
+ ).fetchall()
+ }
+ assert any(
+ "strategy_regime_evidence" in t for t in tables
+ ), f"expected the strategy_regime_evidence table to be auto-created, found {tables}"
+ assert store.row_count() == 0
+
+ def test_fresh_db_is_empty_no_seed_corpus(self, tmp_path) -> None:
+ # AC7: a brand-new store has no rows — evidence only comes from
+ # reproducible runs written through upsert_rows/rebuild_evidence.
+ store = _make_store(tmp_path / "fresh.db")
+ assert store.row_count() == 0
+ assert store.get_rows() == []
+
+
+@requires_store
+class TestUpsertAndRead:
+ def test_upsert_then_get_roundtrip_all_fields(self, tmp_path) -> None:
+ store = _make_store(tmp_path / "s.db")
+ store.upsert_rows([_row()])
+ rows = store.get_rows()
+ assert len(rows) == 1
+ got = rows[0]
+ src = _row()
+ for field in (
+ "strategy_id",
+ "regime",
+ "trades_in_regime",
+ "position_size",
+ "return_in_regime",
+ "benchmark_in_regime",
+ "excess_in_regime",
+ "sharpe_in_regime",
+ "max_drawdown_in_regime",
+ "date_ranges",
+ "breakeven_fee_bps",
+ "cost_sensitive",
+ "evidence_quality",
+ "warnings",
+ "last_verified",
+ "evidence_stage",
+ "provenance",
+ "regime_definition",
+ ):
+ assert getattr(got, field) == getattr(
+ src, field
+ ), f"field {field} did not round-trip"
+
+ def test_upsert_replaces_on_same_key(self, tmp_path) -> None:
+ store = _make_store(tmp_path / "s.db")
+ store.upsert_rows([_row(trades=12)])
+ store.upsert_rows([_row(trades=99, sharpe_in_regime=1.5)])
+ assert store.row_count() == 1
+ got = store.get_rows()[0]
+ assert got.trades_in_regime == 99
+ assert got.sharpe_in_regime == 1.5
+
+ def test_get_rows_filters_by_strategy_id_and_regime(self, tmp_path) -> None:
+ store = _make_store(tmp_path / "s.db")
+ store.upsert_rows(
+ [
+ _row(strategy_id="alpha_zoo:a1", regime="bear_market"),
+ _row(strategy_id="sdm:s1", regime="bull_market"),
+ ]
+ )
+ by_strategy = store.get_rows(strategy_id="alpha_zoo:a1")
+ assert len(by_strategy) == 1
+ assert by_strategy[0].strategy_id == "alpha_zoo:a1"
+ by_regime = store.get_rows(regime="bull_market")
+ assert len(by_regime) == 1
+ assert by_regime[0].regime == "bull_market"
+
+ def test_get_rows_sorted_by_strategy_then_regime(self, tmp_path) -> None:
+ store = _make_store(tmp_path / "s.db")
+ store.upsert_rows(
+ [
+ _row(strategy_id="sdm:z", regime="structural"),
+ _row(strategy_id="alpha_zoo:a", regime="bull_market"),
+ _row(strategy_id="alpha_zoo:a", regime="bear_market"),
+ ]
+ )
+ rows = store.get_rows()
+ keys = [(r.strategy_id, r.regime) for r in rows]
+ assert keys == sorted(keys)
+
+ def test_clear_empties_store(self, tmp_path) -> None:
+ store = _make_store(tmp_path / "s.db")
+ store.upsert_rows([_row(), _row(strategy_id="sdm:s1")])
+ assert store.row_count() == 2
+ store.clear()
+ assert store.row_count() == 0
+ assert store.get_rows() == []
+
+
+@requires_store
+class TestValidationAndSerialization:
+ def test_nan_in_row_raises_value_error(self, tmp_path) -> None:
+ store = _make_store(tmp_path / "s.db")
+ bad = _row(sharpe_in_regime=float("nan"))
+ with pytest.raises(ValueError):
+ store.upsert_rows([bad])
+ assert store.row_count() == 0
+
+ def test_date_ranges_and_warnings_roundtrip_tuple_json_tuple(
+ self, tmp_path
+ ) -> None:
+ store = _make_store(tmp_path / "s.db")
+ date_ranges = ("2018-01 to 2018-12", "2022-01 to 2022-12")
+ warnings = (
+ "insufficient-trades: only 7 trades",
+ "cost-sensitive: breakeven 3.1 bps",
+ )
+ store.upsert_rows([_row(date_ranges=date_ranges, warnings=warnings)])
+ got = store.get_rows()[0]
+ assert got.date_ranges == date_ranges
+ assert isinstance(got.date_ranges, tuple)
+ assert got.warnings == warnings
+ assert isinstance(got.warnings, tuple)
+
+ store.upsert_rows([_row(strategy_id="sdm:empty", date_ranges=(), warnings=())])
+ empty = store.get_rows(strategy_id="sdm:empty")[0]
+ assert empty.date_ranges == ()
+ assert empty.warnings == ()
+
+
+@requires_store
+class TestUnknownRegimeSkip:
+ """Rows with an off-vocabulary regime can only reach the SQLite file via
+ external tampering (``EvidenceRow`` rejects unknown regimes on the write
+ path). The never-invent contract drops them from reads with a warning —
+ never remaps them onto a documented regime."""
+
+ _TAMPERED_INSERT = (
+ "INSERT INTO strategy_regime_evidence ("
+ "strategy_id, regime, trades_in_regime, date_ranges, "
+ "breakeven_fee_bps, cost_sensitive, evidence_quality, warnings, "
+ "last_verified"
+ ") VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)"
+ )
+
+ def _tamper_row(self, store, strategy_id, regime) -> None:
+ """Bypass the validated write path exactly like an external editor."""
+ with sqlite3.connect(store.db_path) as conn:
+ conn.execute(
+ self._TAMPERED_INSERT,
+ (strategy_id, regime, 42, "[]", None, 0, "adequate", "[]", ""),
+ )
+ conn.commit()
+
+ def test_unknown_regime_row_is_skipped_not_remapped(self, tmp_path, caplog) -> None:
+ store = _make_store(tmp_path / "s.db")
+ self._tamper_row(store, "sdm:tampered", "sideways")
+ with caplog.at_level("WARNING"):
+ rows = store.get_rows()
+ assert rows == [], (
+ "unknown-regime rows must be dropped from reads, never remapped "
+ f"onto a documented regime: {rows!r}"
+ )
+ assert any(
+ "sideways" in record.message for record in caplog.records
+ ), "skipping a tampered row must log a warning naming the regime"
+
+ def test_valid_rows_survive_alongside_tampered_row(self, tmp_path, caplog) -> None:
+ store = _make_store(tmp_path / "s.db")
+ store.upsert_rows([_row(strategy_id="alpha_zoo:ok", regime="bear_market")])
+ self._tamper_row(store, "sdm:tampered", "monsoon")
+ with caplog.at_level("WARNING"):
+ rows = store.get_rows()
+ assert [(r.strategy_id, r.regime) for r in rows] == [
+ ("alpha_zoo:ok", "bear_market")
+ ]
+ assert rows[0].regime == "bear_market"
+ assert any("monsoon" in record.message for record in caplog.records)
+
+ def test_row_count_still_counts_physical_rows(self, tmp_path) -> None:
+ # row_count() is a raw COUNT(*) over the file — the skip happens in
+ # row hydration, so it reflects physical rows including tampered ones.
+ store = _make_store(tmp_path / "s.db")
+ store.upsert_rows([_row(strategy_id="alpha_zoo:ok")])
+ self._tamper_row(store, "sdm:tampered", "sideways")
+ assert store.row_count() == 2
+ assert store.get_rows() != []
+ assert store.get_rows()[0].strategy_id == "alpha_zoo:ok"
+
+ def test_unknown_evidence_stage_row_is_skipped(self, tmp_path, caplog) -> None:
+ store = _make_store(tmp_path / "s.db")
+ with sqlite3.connect(store.db_path) as conn:
+ conn.execute(
+ "INSERT INTO strategy_regime_evidence ("
+ "strategy_id, regime, trades_in_regime, date_ranges, "
+ "cost_sensitive, evidence_quality, warnings, last_verified, "
+ "evidence_stage"
+ ") VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+ (
+ "sdm:tampered",
+ "bear_market",
+ 42,
+ "[]",
+ 0,
+ "adequate",
+ "[]",
+ "",
+ "rumor",
+ ),
+ )
+ conn.commit()
+ with caplog.at_level("WARNING"):
+ rows = store.get_rows()
+ assert rows == []
+ assert any(
+ "rumor" in record.message for record in caplog.records
+ ), "skipping an unknown-stage row must log a warning naming the stage"
+
+
+@requires_store
+class TestSchemaMigration:
+ """A cache DB written before the provenance/stage columns existed is
+ disposable: opening it drops and recreates the table rather than serving
+ rows that cannot carry the #969 contract."""
+
+ _LEGACY_SCHEMA = """
+ CREATE TABLE strategy_regime_evidence (
+ strategy_id TEXT NOT NULL,
+ regime TEXT NOT NULL,
+ trades_in_regime INTEGER NOT NULL,
+ position_size REAL,
+ return_in_regime REAL,
+ benchmark_in_regime REAL,
+ excess_in_regime REAL,
+ sharpe_in_regime REAL,
+ max_drawdown_in_regime REAL,
+ date_ranges TEXT NOT NULL,
+ breakeven_fee_bps REAL,
+ cost_sensitive INTEGER NOT NULL DEFAULT 0,
+ evidence_quality TEXT NOT NULL,
+ warnings TEXT NOT NULL,
+ last_verified TEXT NOT NULL DEFAULT '',
+ PRIMARY KEY (strategy_id, regime)
+ )
+ """
+
+ def test_stale_cache_is_dropped_and_recreated_empty(self, tmp_path, caplog) -> None:
+ db_file = tmp_path / "stale.db"
+ with sqlite3.connect(db_file) as conn:
+ conn.execute(self._LEGACY_SCHEMA)
+ conn.execute(
+ "INSERT INTO strategy_regime_evidence ("
+ "strategy_id, regime, trades_in_regime, date_ranges, "
+ "cost_sensitive, evidence_quality, warnings"
+ ") VALUES ('sdm:legacy', 'bear_market', 12, '[]', 0, "
+ "'adequate', '[]')"
+ )
+ conn.commit()
+
+ with caplog.at_level("WARNING"):
+ store = _make_store(db_file)
+ assert (
+ store.row_count() == 0
+ ), "a pre-provenance cache must be dropped, not served"
+ with sqlite3.connect(db_file) as conn:
+ columns = {
+ r[1]
+ for r in conn.execute(
+ "PRAGMA table_info(strategy_regime_evidence)"
+ ).fetchall()
+ }
+ for column in ("evidence_stage", "provenance", "regime_definition"):
+ assert column in columns, f"recreated table missing {column}"
+ assert any(
+ "predates columns" in record.message for record in caplog.records
+ ), "dropping a stale cache must log a warning"
+
+ store.upsert_rows([_row()])
+ assert store.row_count() == 1
+
+ def test_current_schema_is_not_dropped(self, tmp_path, caplog) -> None:
+ store = _make_store(tmp_path / "s.db")
+ store.upsert_rows([_row()])
+ with caplog.at_level("WARNING"):
+ reopened = _make_store(tmp_path / "s.db")
+ assert (
+ reopened.row_count() == 1
+ ), "a current-schema cache must survive re-open untouched"
+ assert not any(
+ "predates columns" in record.message for record in caplog.records
+ )
diff --git a/agent/tests/test_strategy_discovery_tools.py b/agent/tests/test_strategy_discovery_tools.py
new file mode 100644
index 000000000..e2f392283
--- /dev/null
+++ b/agent/tests/test_strategy_discovery_tools.py
@@ -0,0 +1,288 @@
+"""Frozen-contract tests for ``src.tools.strategy_discovery_tool`` — issue #969.
+
+AC1 (tools callable at runtime): the module must expose exactly three
+``BaseTool`` classes whose ``name`` attributes are ``list_strategies`` /
+``query_strategies`` / ``get_strategy_evidence``, all read-only, returning
+strict-JSON envelopes with ``status`` ok/error and never raising on invalid
+parameter types.
+
+The sibling-built ``StrategyDiscoveryFacade`` construction is intercepted at
+module level (patching ``sdt.StrategyDiscoveryFacade``) so a ``FakeFacade``
+records calls and canned envelopes — no real store, no filesystem state.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from src.agent.tools import BaseTool
+
+try:
+ from src.tools import strategy_discovery_tool as sdt
+
+ TOOLS_AVAILABLE = True
+except ImportError:
+ sdt = None
+ TOOLS_AVAILABLE = False
+
+requires_tools = pytest.mark.skipif(
+ not TOOLS_AVAILABLE,
+ reason="waiting on sibling B: src.tools.strategy_discovery_tool not landed yet (issue #969)",
+)
+
+EXPECTED_NAMES = {"list_strategies", "query_strategies", "get_strategy_evidence"}
+
+
+def _strict_json_loads(text: str) -> dict:
+ def _reject(constant):
+ raise ValueError(f"non-strict constant {constant!r} in tool output")
+
+ payload = json.loads(text, parse_constant=_reject)
+ assert isinstance(
+ payload, dict
+ ), f"tool output must be a JSON object, got {type(payload)}"
+ return payload
+
+
+class FakeFacade:
+ """Canned stand-in for StrategyDiscoveryFacade; records every call."""
+
+ instances: list = []
+
+ def __init__(self, *args, **kwargs):
+ self.init_args = args
+ self.init_kwargs = kwargs
+ self.calls = []
+ FakeFacade.instances.append(self)
+
+ def list_strategies(self, *args, **kwargs):
+ self.calls.append(("list_strategies", args, kwargs))
+ return {"status": "ok", "total": 0, "returned": 0, "offset": 0, "items": []}
+
+ def query_strategies(self, *args, **kwargs):
+ self.calls.append(("query_strategies", args, kwargs))
+ return {"status": "ok", "regime": None, "returned": 0, "items": []}
+
+ def get_strategy_evidence(self, *args, **kwargs):
+ self.calls.append(("get_strategy_evidence", args, kwargs))
+ strategy_id = kwargs.get("strategy_id") or (args[0] if args else "")
+ return {
+ "status": "ok",
+ "strategy_id": strategy_id,
+ "regime": kwargs.get("regime"),
+ "found": False,
+ "rows": [],
+ "note": "no evidence computed for this strategy yet",
+ }
+
+
+def fake_facade(monkeypatch):
+ """Intercept StrategyDiscoveryFacade construction.
+
+ The tool module imports the facade lazily inside execute() via
+ ``from src.strategy_discovery import StrategyDiscoveryFacade``, which is a
+ module-attribute lookup at call time — patching the package attribute (and
+ a module-level binding if present) keeps every real store untouched.
+ """
+ import src.strategy_discovery as sd_package
+
+ FakeFacade.instances.clear()
+ monkeypatch.setattr(sd_package, "StrategyDiscoveryFacade", FakeFacade, raising=True)
+ if getattr(sdt, "StrategyDiscoveryFacade", None) is not None:
+ monkeypatch.setattr(sdt, "StrategyDiscoveryFacade", FakeFacade, raising=True)
+ return FakeFacade
+
+
+def _discover_tool_classes():
+ return [
+ value
+ for value in vars(sdt).values()
+ if isinstance(value, type)
+ and issubclass(value, BaseTool)
+ and value is not BaseTool
+ and getattr(value, "__module__", "") == sdt.__name__
+ ]
+
+
+def _instantiate_tools() -> dict:
+ classes = _discover_tool_classes()
+ assert len(classes) == 3, (
+ f"expected exactly 3 BaseTool classes in strategy_discovery_tool, found "
+ f"{[c.__name__ for c in classes]}"
+ )
+ tools = {cls().name: cls() for cls in classes}
+ assert (
+ set(tools) == EXPECTED_NAMES
+ ), f"tool .name attributes must be {sorted(EXPECTED_NAMES)}, got {sorted(tools)}"
+ return tools
+
+
+@requires_tools
+class TestToolClasses:
+ def test_three_tools_with_exact_names_all_read_only(self, fake_facade) -> None:
+ tools = _instantiate_tools()
+ for name in EXPECTED_NAMES:
+ tool = tools[name]
+ assert isinstance(tool, BaseTool)
+ assert (
+ tool.parameters
+ ), f"{name} must declare a JSON-schema parameters block"
+ assert tool.is_readonly is True, f"{name} must be read-only"
+
+
+@requires_tools
+class TestExecuteEnvelopes:
+ def test_list_strategies_returns_canned_ok_envelope(self, fake_facade) -> None:
+ tool = _instantiate_tools()["list_strategies"]
+ payload = _strict_json_loads(tool.execute(limit=5, offset=0))
+ assert payload["status"] == "ok"
+ assert payload["items"] == []
+ facade = fake_facade.instances[-1]
+ assert facade.calls and facade.calls[-1][0] == "list_strategies"
+ _, args, kwargs = facade.calls[-1]
+ forwarded = {**kwargs}
+ if args:
+ forwarded.setdefault("args", args)
+ assert ("limit" in forwarded and forwarded["limit"] == 5) or (
+ 5 in args
+ ), f"limit=5 was not forwarded to the facade: args={args} kwargs={kwargs}"
+
+ def test_query_strategies_forwards_arguments(self, fake_facade) -> None:
+ tool = _instantiate_tools()["query_strategies"]
+ payload = _strict_json_loads(
+ tool.execute(regime="bear_market", min_evidence_quality="marginal", limit=3)
+ )
+ assert payload["status"] == "ok"
+ _, args, kwargs = fake_facade.instances[-1].calls[-1]
+ combined = json.dumps({"args": list(args), "kwargs": kwargs})
+ assert "bear_market" in combined
+ assert "marginal" in combined
+
+ def test_get_strategy_evidence_forwards_strategy_id(self, fake_facade) -> None:
+ tool = _instantiate_tools()["get_strategy_evidence"]
+ payload = _strict_json_loads(tool.execute(strategy_id="alpha_zoo:a1"))
+ assert payload["status"] == "ok"
+ assert payload["strategy_id"] == "alpha_zoo:a1"
+
+
+@requires_tools
+class TestInvalidParameters:
+ """Invalid types must yield an error envelope — never an exception."""
+
+ def test_list_strategies_rejects_string_limit(self, fake_facade) -> None:
+ tool = _instantiate_tools()["list_strategies"]
+ payload = _strict_json_loads(tool.execute(limit="ten"))
+ assert payload["status"] == "error"
+ assert payload.get("error")
+
+ def test_query_strategies_rejects_string_min_trades(self, fake_facade) -> None:
+ tool = _instantiate_tools()["query_strategies"]
+ payload = _strict_json_loads(tool.execute(min_trades="many"))
+ assert payload["status"] == "error"
+ assert payload.get("error")
+
+ def test_query_strategies_rejects_unparseable_cost_feasible(
+ self, fake_facade
+ ) -> None:
+ # "yes"/"no" are documented LLM-tolerant boolean forms; "maybe" is not.
+ tool = _instantiate_tools()["query_strategies"]
+ payload = _strict_json_loads(tool.execute(cost_feasible="maybe"))
+ assert payload["status"] == "error"
+ assert payload.get("error")
+
+ def test_get_strategy_evidence_rejects_non_string_strategy_id(
+ self, fake_facade
+ ) -> None:
+ tool = _instantiate_tools()["get_strategy_evidence"]
+ payload = _strict_json_loads(tool.execute(strategy_id=12345))
+ assert payload["status"] == "error"
+ assert payload.get("error")
+
+
+@requires_tools
+class TestStringLengthCap:
+ """Free-text params are identifiers; over-long values are rejected at the
+ tool boundary via the standard error envelope, before any facade call."""
+
+ def test_overlong_strategy_id_is_rejected_with_clear_message(
+ self, fake_facade
+ ) -> None:
+ tool = _instantiate_tools()["get_strategy_evidence"]
+ payload = _strict_json_loads(tool.execute(strategy_id="a" * 501))
+ assert payload["status"] == "error"
+ error = payload.get("error", "")
+ assert error, "cap rejection must carry a message"
+ assert "too long" in error.lower(), f"expected a length message: {error!r}"
+ assert (
+ not fake_facade.instances or not fake_facade.instances[-1].calls
+ ), "an over-long parameter must not reach the facade"
+
+ def test_exactly_500_chars_is_accepted(self, fake_facade) -> None:
+ tool = _instantiate_tools()["get_strategy_evidence"]
+ payload = _strict_json_loads(tool.execute(strategy_id="a" * 500))
+ assert payload["status"] == "ok"
+ assert payload["strategy_id"] == "a" * 500
+
+ def test_overlong_regime_and_source_are_rejected(self, fake_facade) -> None:
+ query = _instantiate_tools()["query_strategies"]
+ listed = _instantiate_tools()["list_strategies"]
+ bad = "r" * 700
+ for payload in (
+ _strict_json_loads(query.execute(regime=bad)),
+ _strict_json_loads(listed.execute(source=bad)),
+ ):
+ assert payload["status"] == "error"
+ assert "too long" in payload.get("error", "").lower()
+
+
+@requires_tools
+class TestGenericErrorEnvelope:
+ """Unexpected facade failures must surface as a generic error envelope —
+ raw exception text (file paths, internals) belongs to server logs only."""
+
+ class ExplodingFacade:
+ _SECRET = "traceback-canary /Users/x/.vibe-trading/secrets/token"
+
+ def __init__(self, *args, **kwargs):
+ pass
+
+ def list_strategies(self, *args, **kwargs):
+ raise RuntimeError(self._SECRET)
+
+ def query_strategies(self, *args, **kwargs):
+ raise RuntimeError(self._SECRET)
+
+ def get_strategy_evidence(self, *args, **kwargs):
+ raise RuntimeError(self._SECRET)
+
+ def test_facade_exception_yields_generic_message_without_leak(
+ self, monkeypatch
+ ) -> None:
+ import src.strategy_discovery as sd_package
+
+ monkeypatch.setattr(
+ sd_package, "StrategyDiscoveryFacade", self.ExplodingFacade, raising=True
+ )
+ if getattr(sdt, "StrategyDiscoveryFacade", None) is not None:
+ monkeypatch.setattr(
+ sdt, "StrategyDiscoveryFacade", self.ExplodingFacade, raising=True
+ )
+ tools = _instantiate_tools()
+ for name, call in (
+ ("list_strategies", lambda t: t.execute(limit=1)),
+ ("query_strategies", lambda t: t.execute()),
+ ("get_strategy_evidence", lambda t: t.execute(strategy_id="alpha_zoo:a1")),
+ ):
+ payload = _strict_json_loads(call(tools[name]))
+ assert payload["status"] == "error", f"{name}: expected error envelope"
+ error = payload.get("error", "")
+ assert error, f"{name}: error envelope must carry a message"
+ assert (
+ self.ExplodingFacade._SECRET not in error
+ ), f"{name}: raw exception text leaked into the envelope: {error!r}"
+ assert (
+ "failed internally" in error
+ ), f"{name}: expected the generic 'failed internally' wording: {error!r}"