docs(b12): consumer adoption matrix; prefer semantics+display in tests

docs/b06_execution_presentation_facade.zh-CN.md

@@ -24,3 +24,6 @@
 
 ## 验证
 `pytest tests/test_strategy_contracts.py tests/test_value_target_presentation_facade.py`
+
+## B12
+见 `docs/b12_consumer_adoption.zh-CN.md`（消费者采用矩阵；LB/Firstrade 剩余）。

docs/b12_consumer_adoption.zh-CN.md

@@ -0,0 +1,38 @@
+# B12：value-target 消费者采用矩阵（2026-10-09）
+
+依据：本地 clone `rg`（gh code search 本会话 rate-limit；Alpaca 等未 clone 仓标 incomplete）。  
+策略：batch-upgrade-then-remove-compat；**保留** `build_value_target_runtime_plan` 与混合 `ValueTargetExecutionAnnotations` facade，直至剩余生产消费者清零。
+
+## 1. 已迁到 `semantics` + `display` / execution API
+
+| 仓 | 路径 | 证据 |
+| --- | --- | --- |
+| CharlesSchwabPlatform | `decision_mapper.py` | [#501](https://github.com/QuantStrategyLab/CharlesSchwabPlatform/pull/501) → `build_value_target_execution_runtime_plan` + `ValueTargetPlanPresentation`；[#504](https://github.com/QuantStrategyLab/CharlesSchwabPlatform/pull/504) → `semantics=` + `display=`（pin QPK #655） |
+| QuantPlatformKit | `tests/test_value_target_presentation_facade.py` + `tests/test_strategy_contracts.py` | #654/#655；本 PR 将 contracts 单测改为 modern 优先 + legacy 等价 |
+
+## 2. 无 `ValueTargetExecutionAnnotations` / `build_value_target_runtime_plan` 生产调用（本批本地）
+
+| 仓 | 说明 |
+| --- | --- |
+| InteractiveBrokersPlatform | `decision_mapper` 用 `translate_decision_to_target_mode`；annotations 为 dict metadata，非 ValueTarget 类型 |
+| BinancePlatform | `decision_mapper` 无 value-target plan builder |
+| QmtPlatform（本地） | 无上述符号 |
+| UsEquityStrategies | 无上述符号（dashboard 走 diagnostics dict） |
+| QuantRuntimeSettings | JS Worker；不消费该 Python API |
+
+## 3. 剩余生产消费者（**本侧不迁**）
+
+| 仓 | 符号 | 原因 |
+| --- | --- | --- |
+| LongBridgePlatform | `build_value_target_runtime_plan` + `ValueTargetExecutionAnnotations(...)` | LB-HK 禁区；归 quant |
+| FirstradePlatform | 同上 | Firstrade Environment/ingress 禁区；归 quant |
+
+## 4. Facade 保留条件
+
+- 新代码：`build_value_target_execution_runtime_plan(semantics=, display=, presentation=)`  
+- 旧代码：`build_value_target_runtime_plan` / `annotations=ValueTargetExecutionAnnotations(...)`  
+- **删除混合字段 / 撤 facade**：仅当 §3 清零且 B12 矩阵绿灯（N14）
+
+## 5. incomplete
+
+- gh `search/code` org 查询本会话 **0 / rate-limit**；未对 AlpacaPlatform / 未 clone 仓做全文确认。限流恢复后补扫：`org:QuantStrategyLab build_value_target_runtime_plan`。

tests/test_strategy_contracts.py

@@ -21,6 +21,7 @@
 )
 from quant_platform_kit.common.execution_translation import (
     ValueTargetPortfolioInputs,
+    build_value_target_execution_runtime_plan,
     build_value_target_portfolio_inputs_from_account_state,
     build_value_target_portfolio_inputs_from_snapshot,
     build_value_target_runtime_plan,
@@ -29,6 +30,12 @@
     translate_value_decision_to_weight_targets,
     translate_weight_decision_to_value_targets,
 )
+from quant_platform_kit.common.presentation import (
+    ValueTargetDisplayAnnotations,
+    ValueTargetExecutionSemantics,
+    ValueTargetPlanPresentation,
+    split_value_target_annotation_parts,
+)
 from quant_platform_kit.common.runtime_inputs import (
     build_account_state_from_portfolio_snapshot,
     build_portfolio_snapshot_from_account_state,
@@ -973,7 +980,25 @@ def test_build_value_target_runtime_plan_translates_decision_with_shared_helper(
             }
         )
 
-        payload = build_value_target_runtime_plan(
+        semantics, display = split_value_target_annotation_parts(decision)
+        modern = build_value_target_execution_runtime_plan(
+            decision,
+            strategy_profile="soxl_soxx_trend_income",
+            portfolio_inputs=inputs,
+            semantics=semantics,
+            display=display,
+            presentation=ValueTargetPlanPresentation(
+                portfolio_rows_layout=("risk", "safe"),
+                execution_fields=(
+                    "trade_threshold_value",
+                    "signal_display",
+                    "investable_cash",
+                ),
+                execution_defaults={"investable_cash": 12000.0},
+            ),
+        )
+        # Compat facade must remain behavior-equivalent (B12 keeps facade).
+        legacy = build_value_target_runtime_plan(
             decision,
             strategy_profile="soxl_soxx_trend_income",
             portfolio_inputs=inputs,
@@ -986,9 +1011,12 @@ def test_build_value_target_runtime_plan_translates_decision_with_shared_helper(
             execution_defaults={"investable_cash": 12000.0},
         )
 
-        self.assertEqual(payload["allocation"]["target_mode"], "value")
-        self.assertEqual(payload["allocation"]["targets"]["SOXL"], 30000.0)
-        self.assertEqual(payload["portfolio"]["sellable_quantities"]["BOXX"], 5)
-        self.assertEqual(payload["execution"]["trade_threshold_value"], 250.0)
-        self.assertEqual(payload["execution"]["signal_display"], "risk-on")
-        self.assertEqual(payload["execution"]["investable_cash"], 12000.0)
+        self.assertEqual(modern, legacy)
+        self.assertEqual(modern["allocation"]["target_mode"], "value")
+        self.assertEqual(modern["allocation"]["targets"]["SOXL"], 30000.0)
+        self.assertEqual(modern["portfolio"]["sellable_quantities"]["BOXX"], 5)
+        self.assertEqual(modern["execution"]["trade_threshold_value"], 250.0)
+        self.assertEqual(modern["execution"]["signal_display"], "risk-on")
+        self.assertEqual(modern["execution"]["investable_cash"], 12000.0)
+        self.assertIsInstance(semantics, ValueTargetExecutionSemantics)
+        self.assertIsInstance(display, ValueTargetDisplayAnnotations)