"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
feat(agent): add evidence-gated strategy discovery facade
shadowinlifebbfd82c87d64
diff --git a/README.md b/README.mdindex 1922f2a90..a51455a64 100644--- a/README.md+++ b/README.md@@ -428,9 +428,9 @@ Beyond OHLCV, **22 read-only data tools** reach into fundamentals & flow — funDetailed 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 searchdiff --git a/README_ar.md b/README_ar.mdindex 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 searchdiff --git a/README_ja.md b/README_ja.mdindex 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.mdindex 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 searchdiff --git a/README_zh.md b/README_zh.mdindex 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.mdindex 414c5f5af..d90707083 100644--- a/agent/SKILL.md+++ b/agent/SKILL.md@@ -1,7 +1,7 @@---name: vibe-tradingversion: 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 fivEach 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 Serversdiff --git a/agent/mcp_server.py b/agent/mcp_server.pyindex 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 theselected 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/patternanalysis, 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.pyindex 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 RoutingDecide 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 contract2. `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.pyindex 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.mdnew file mode 100644index 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__.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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 Falsediff --git a/agent/src/strategy_discovery/guard.py b/agent/src/strategy_discovery/guard.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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, exposuresdiff --git a/agent/src/tools/strategy_discovery_tool.py b/agent/src/tools/strategy_discovery_tool.pynew file mode 100644index 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.pyindex 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 resultassert "{skill_count}" not in resultassert "{data_source_count}" not in result+ assert "{strategy_discovery_routing}" not in resultdef 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.pynew file mode 100644index 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 injecteddiff --git a/agent/tests/test_strategy_discovery_guard.py b/agent/tests/test_strategy_discovery_guard.pynew file mode 100644index 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.pynew file mode 100644index 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") == 0diff --git a/agent/tests/test_strategy_discovery_mcp.py b/agent/tests/test_strategy_discovery_mcp.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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}"