fix(console): separate catalog gates from runtime facts (#288)

Co-authored-by: Codex <noreply@openai.com>

Author: Pigbibi

.github/workflows/deploy-strategy-switch-console.yml

@@ -7,6 +7,7 @@ on:
       - ".github/workflows/deploy-strategy-switch-console.yml"
       - "platform-config.json"
       - "python/scripts/build_config.py"
+      - "python/scripts/build_platform_config.py"
       - "python/scripts/sync_strategy_switch_page_asset.py"
       - "web/strategy-switch-console/**"
   workflow_dispatch:
@@ -58,6 +59,7 @@ jobs:
         run: |
           set -euo pipefail
           python3 python/scripts/build_platform_config.py
+          python3 python/scripts/build_platform_config.py --check
           python3 python/scripts/inject_platform_config.py
           python3 python/scripts/sync_strategy_switch_page_asset.py
 

.github/workflows/platform-health-monitor.yml

@@ -57,12 +57,14 @@ jobs:
         run: |
           set -euo pipefail
           python3 python/scripts/build_config.py
+          python3 python/scripts/build_platform_config.py --check
           python3 python/scripts/sync_strategy_switch_page_asset.py
           git diff --exit-code -- \
             web/strategy-switch-console/config.js \
             web/strategy-switch-console/index.html \
             web/strategy-switch-console/page_asset.js \
             web/strategy-switch-console/strategy_profiles_asset.js \
+            web/strategy-switch-console/runtime-catalog-projection.json \
             web/strategy-switch-console/app_css.js \
             web/strategy-switch-console/app_js.js
           jq empty web/strategy-switch-console/strategy-profiles.example.json

.github/workflows/validate.yml

@@ -91,8 +91,9 @@ jobs:
           set -euo pipefail
           python3 python/scripts/build_config.py --check
           python3 python/scripts/build_config.py
+          python3 python/scripts/build_platform_config.py --check
           python3 python/scripts/sync_strategy_switch_page_asset.py
-          git diff --exit-code -- web/strategy-switch-console/config.js web/strategy-switch-console/index.html web/strategy-switch-console/page_asset.js web/strategy-switch-console/strategy_profiles_asset.js web/strategy-switch-console/app_css.js web/strategy-switch-console/app_js.js
+          git diff --exit-code -- web/strategy-switch-console/config.js web/strategy-switch-console/index.html web/strategy-switch-console/page_asset.js web/strategy-switch-console/strategy_profiles_asset.js web/strategy-switch-console/runtime-catalog-projection.json web/strategy-switch-console/app_css.js web/strategy-switch-console/app_js.js
           jq empty web/strategy-switch-console/strategy-profiles.example.json
           node --experimental-default-type=module tests/strategy_switch_worker_validation.mjs
           sed -n '/<script>/,/<\/script>/p' web/strategy-switch-console/index.html | sed '1d;$d' | node --check --input-type=commonjs

docs/qsl_lifecycle_truth_v1.zh-CN.md

@@ -35,6 +35,24 @@ blocked_live_reason is empty
 缺少任意字段时都 fail closed。设置网站、Worker、配置生成器和后端验证不得从
 catalog 名称、默认值或 inventory 状态推导 live 权限。
 
+## 控制台读取优先级与陈旧资料保护
+
+`web/strategy-switch-console/runtime-catalog-projection.json` 由
+`platform-config.json` 生成，并带来源内容 SHA-256。它只显示目录门禁（例如策略是否
+可被切换流程考虑），`data_status=catalog_only`；它不观察 Cloud Run、Gateway、账户、
+订单、资金或 P4–P6 收据，因此不能用作“正在运行”或“已可升级”的事实。
+
+控制台必须按用途读取独立来源：
+
+1. 候选 P1–P3 生命周期与新鲜度：`GET /api/control-plane`；
+2. 精确策略 × 平台 × 通道的执行证据：`GET /api/execution-evidence`；
+3. 配置目录门禁：登录后的 `GET /api/runtime-catalog`。
+
+`web/strategy-switch-console/lifecycle-matrix.json` 只保留为 2026-08-23 的历史参考，
+已标记 `historical_reference_only`。任何界面、自动化或人工审阅都不得把它作为当前
+运行、升级或下单依据；缺少新鲜快照时应显示 `unavailable` / `stale`，不能回退到该
+历史矩阵填充“正常”状态。
+
 ## 一次性迁移规则
 
 - `platform-config.json`、设置网站 fallback 和生成的 profile asset 只写规范状态。

python/scripts/build_platform_config.py

@@ -11,6 +11,8 @@
 
 from __future__ import annotations
 
+import argparse
+import hashlib
 import json
 from pathlib import Path
 
@@ -19,6 +21,8 @@
 TARGET = ROOT / "web" / "strategy-switch-console" / "config.js"
 STRATEGY_TARGET = ROOT / "web" / "strategy-switch-console" / "strategy_profiles_asset.js"
 STRATEGY_EXAMPLE_TARGET = ROOT / "web" / "strategy-switch-console" / "strategy-profiles.example.json"
+RUNTIME_CATALOG_PROJECTION_TARGET = ROOT / "web" / "strategy-switch-console" / "runtime-catalog-projection.json"
+RUNTIME_CATALOG_PROJECTION_SCHEMA_VERSION = "qsl.runtime_catalog_projection.v1"
 
 
 def build_config_module(config: dict) -> str:
@@ -27,6 +31,7 @@ def build_config_module(config: dict) -> str:
     domains = config.get("domains", {})
     meta = config.get("meta", {})
     runtime_authority = meta.get("runtime_authority", {}) if isinstance(meta, dict) else {}
+    runtime_catalog_projection = build_runtime_catalog_projection(config)
 
     # ── platformConfig (replaces hardcoded in index.html) ──
     platform_config = {}
@@ -172,6 +177,8 @@ def build_config_module(config: dict) -> str:
         "",
         f"export const RUNTIME_AUTHORITY_STATUS = {json.dumps(runtime_authority, indent=2, ensure_ascii=False)};",
         "",
+        f"export const RUNTIME_CATALOG_PROJECTION = {json.dumps(runtime_catalog_projection, indent=2, ensure_ascii=False)};",
+        "",
         f"export const DEFAULT_ACCOUNT_OPTIONS = {json.dumps(default_accounts, indent=2, ensure_ascii=False)};",
         "",
         f"export const PLATFORM_REPOSITORIES = {json.dumps(repositories, indent=2, ensure_ascii=False)};",
@@ -293,28 +300,118 @@ def _strategy_profile_gate_fields(sdata: dict) -> dict[str, object]:
     }
 
 
-def main() -> int:
-    config = json.loads(SOURCE.read_text(encoding="utf-8"))
+def _config_content_sha256(config: dict) -> str:
+    canonical = json.dumps(config, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    return "sha256:" + hashlib.sha256(canonical.encode("utf-8")).hexdigest()
 
-    # Generate config.js
-    module = build_config_module(config)
-    TARGET.write_text(module, encoding="utf-8")
 
-    # Generate strategy_profiles_asset.js and keep strategy-profiles.example.json aligned.
+def build_runtime_catalog_projection(config: dict) -> dict[str, object]:
+    """Project catalog gates without claiming an observed runtime state.
+
+    This is deliberately separate from control-plane and execution-evidence
+    snapshots.  A checked-in strategy catalog can describe which modes a
+    workflow may consider, but cannot prove that a target is deployed, healthy,
+    funded, or permitted to trade.
+    """
     profiles = build_strategy_profile_entries(config)
-    STRATEGY_TARGET.write_text(
-        "// Generated by python/scripts/build_platform_config.py from platform-config.json\n"
-        f"export const DEFAULT_STRATEGY_PROFILES = {json.dumps(profiles, indent=2, ensure_ascii=False)};\n",
-        encoding="utf-8",
-    )
-    STRATEGY_EXAMPLE_TARGET.write_text(
-        json.dumps(profiles, ensure_ascii=False, separators=(",", ":")) + "\n",
-        encoding="utf-8",
+    status_profiles = [
+        {
+            field: profile[field]
+            for field in (
+                "profile",
+                "label",
+                "label_en",
+                "label_zh",
+                "domain",
+                "lifecycle_stage",
+                "runtime_enabled",
+                "can_switch_live",
+                "allowed_execution_modes",
+                "blocked_live_reason",
+            )
+        }
+        for profile in profiles
+    ]
+    lifecycle_stage_counts: dict[str, int] = {}
+    for profile in status_profiles:
+        stage = str(profile["lifecycle_stage"])
+        lifecycle_stage_counts[stage] = lifecycle_stage_counts.get(stage, 0) + 1
+
+    meta = config.get("meta", {})
+    return {
+        "schema_version": RUNTIME_CATALOG_PROJECTION_SCHEMA_VERSION,
+        "data_status": "catalog_only",
+        "source": {
+            "path": "platform-config.json",
+            "content_sha256": _config_content_sha256(config),
+            "catalog_as_of": meta.get("last_updated") if isinstance(meta, dict) else None,
+        },
+        "policy": {
+            "catalog_is_runtime_observation": False,
+            "catalog_can_authorize_promotion_or_trading": False,
+            "historical_lifecycle_inventory_is_authoritative": False,
+            "observed_state_sources": [
+                "qsl_control_plane_dashboard.v1",
+                "qsl_execution_evidence_dashboard.v1",
+            ],
+        },
+        "runtime_authority": meta.get("runtime_authority", {}) if isinstance(meta, dict) else {},
+        "summary": {
+            "strategy_profile_count": len(status_profiles),
+            "runtime_enabled_count": sum(1 for profile in status_profiles if profile["runtime_enabled"]),
+            "live_switchable_count": sum(1 for profile in status_profiles if profile["can_switch_live"]),
+            "lifecycle_stage_counts": dict(sorted(lifecycle_stage_counts.items())),
+        },
+        "strategies": status_profiles,
+    }
+
+
+def _generated_outputs(config: dict) -> dict[Path, str]:
+    profiles = build_strategy_profile_entries(config)
+    projection = build_runtime_catalog_projection(config)
+    return {
+        TARGET: build_config_module(config),
+        STRATEGY_TARGET: (
+            "// Generated by python/scripts/build_platform_config.py from platform-config.json\n"
+            f"export const DEFAULT_STRATEGY_PROFILES = {json.dumps(profiles, indent=2, ensure_ascii=False)};\n"
+        ),
+        STRATEGY_EXAMPLE_TARGET: json.dumps(profiles, ensure_ascii=False, separators=(",", ":")) + "\n",
+        RUNTIME_CATALOG_PROJECTION_TARGET: json.dumps(projection, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate strategy-switch console assets from platform-config.json")
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Fail when the generated runtime catalog projection does not match platform-config.json",
     )
+    args = parser.parse_args()
+    config = json.loads(SOURCE.read_text(encoding="utf-8"))
+    outputs = _generated_outputs(config)
+
+    if args.check:
+        # sync_strategy_switch_page_asset.py intentionally renders the strategy
+        # JS asset with a different (but semantically equivalent) formatter.
+        # The projection has one generator, so it is safe to use as a strict
+        # source-freshness guard even after the full console build pipeline.
+        checkable = {RUNTIME_CATALOG_PROJECTION_TARGET: outputs[RUNTIME_CATALOG_PROJECTION_TARGET]}
+        stale = [path for path, expected in checkable.items() if not path.exists() or path.read_text(encoding="utf-8") != expected]
+        if stale:
+            for path in stale:
+                print(f"Generated asset is stale: {path.relative_to(ROOT)}")
+            return 1
+        print("Generated runtime catalog projection matches platform-config.json")
+        return 0
+
+    for path, content in outputs.items():
+        path.write_text(content, encoding="utf-8")
 
     print(f"Generated: {TARGET}")
     print(f"Generated: {STRATEGY_TARGET}")
     print(f"Generated: {STRATEGY_EXAMPLE_TARGET}")
+    print(f"Generated: {RUNTIME_CATALOG_PROJECTION_TARGET}")
     return 0
 
 

python/tests/test_runtime_settings.py

@@ -714,6 +714,38 @@ def test_build_config_strategy_to_json_compat_includes_strategy_gate_fields(self
         self.assertEqual(profile["allowed_execution_modes"], ["paper", "dry_run"])
         self.assertEqual(profile["blocked_live_reason"], "manual-review")
 
+    def test_runtime_catalog_projection_is_exact_and_never_claims_observed_runtime(self):
+        config = build_config.load_config()
+        projection_path = ROOT / "web" / "strategy-switch-console" / "runtime-catalog-projection.json"
+        projection = json.loads(projection_path.read_text(encoding="utf-8"))
+
+        self.assertEqual(projection, build_platform_config.build_runtime_catalog_projection(config))
+        self.assertEqual(projection["schema_version"], "qsl.runtime_catalog_projection.v1")
+        self.assertEqual(projection["data_status"], "catalog_only")
+        self.assertFalse(projection["policy"]["catalog_is_runtime_observation"])
+        self.assertFalse(projection["policy"]["catalog_can_authorize_promotion_or_trading"])
+        self.assertFalse(projection["policy"]["historical_lifecycle_inventory_is_authoritative"])
+        self.assertEqual(
+            projection["summary"]["strategy_profile_count"],
+            len(config["strategies"]),
+        )
+        self.assertEqual(projection["summary"]["live_switchable_count"], 0)
+        self.assertEqual(
+            projection["source"]["content_sha256"],
+            build_platform_config._config_content_sha256(config),
+        )
+
+    def test_historical_lifecycle_inventory_is_explicitly_non_authoritative(self):
+        matrix = json.loads(
+            (ROOT / "web" / "strategy-switch-console" / "lifecycle-matrix.json").read_text(encoding="utf-8")
+        )
+
+        self.assertEqual(matrix["schema_version"], "qsl.historical_lifecycle_inventory.v1")
+        self.assertEqual(matrix["record_status"], "historical_reference_only")
+        self.assertEqual(matrix["superseded_by"]["catalog_gates"], "runtime-catalog-projection.json")
+        self.assertEqual(matrix["superseded_by"]["candidate_lifecycle"], "GET /api/control-plane")
+        self.assertEqual(matrix["superseded_by"]["target_execution_evidence"], "GET /api/execution-evidence")
+
     def test_global_and_hk_global_etf_rotation_profiles_are_research_only(self):
         expected = {
             "lifecycle_stage": "research_active",

tests/strategy_switch_worker_validation.mjs

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
 
 import worker, { __test } from "../web/strategy-switch-console/worker.js";
-import { DEFAULT_ACCOUNT_OPTIONS } from "../web/strategy-switch-console/config.js";
+import { DEFAULT_ACCOUNT_OPTIONS, RUNTIME_CATALOG_PROJECTION } from "../web/strategy-switch-console/config.js";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const indexHtml = [
@@ -1890,6 +1890,21 @@ const noKvPayload = await noKvHealthRead.json();
 assert.equal(noKvPayload.data_status, "unavailable");
 assert.equal(noKvPayload.summary.strategy_count, 0);
 
+const unauthorizedRuntimeCatalogRead = await worker.fetch(
+  new Request("https://switch.example/api/runtime-catalog"),
+  healthEnv,
+);
+assert.equal(unauthorizedRuntimeCatalogRead.status, 401);
+const runtimeCatalogRead = await worker.fetch(
+  new Request("https://switch.example/api/runtime-catalog", { headers: healthCookieHeaders }),
+  healthEnv,
+);
+assert.equal(runtimeCatalogRead.status, 200);
+assert.deepEqual(await runtimeCatalogRead.json(), RUNTIME_CATALOG_PROJECTION);
+assert.equal(RUNTIME_CATALOG_PROJECTION.data_status, "catalog_only");
+assert.equal(RUNTIME_CATALOG_PROJECTION.policy.catalog_is_runtime_observation, false);
+assert.equal(RUNTIME_CATALOG_PROJECTION.policy.catalog_can_authorize_promotion_or_trading, false);
+
 const controlStore = new Map();
 const controlKv = {
   async get(key) { return controlStore.get(key) || null; },

web/strategy-switch-console/README.zh-CN.md

@@ -101,6 +101,11 @@ python3 scripts/sync_strategy_switch_page_asset.py
 
 这会重新生成 `web/strategy-switch-console/page_asset.js` 和 `web/strategy-switch-console/strategy_profiles_asset.js`。部署 Worker 时需要同时带上 `worker.js`、`page_asset.js` 和 `strategy_profiles_asset.js`。
 
+`runtime-catalog-projection.json` 同样由 `platform-config.json` 生成，并用来源 SHA-256
+防止已提交的目录资产陈旧。登录后的 `GET /api/runtime-catalog` 只返回这个**配置门禁**
+投影；它不代表真实部署或交易状态。页面显示候选状态和目标执行状态时，必须分别使用
+`/api/control-plane` 与 `/api/execution-evidence`，不得回退到历史 `lifecycle-matrix.json`。
+
 ## 账号下拉配置
 
 Worker 页面内置示例 target 作为兜底。登录后如果没有加载账号配置，“一键切换”仍会保持禁用，Worker 后端也会拒绝 dispatch，避免账号不匹配。复制示例文件后填入你的真实 target/account route：