refactor: centralize numeric normalization

tests/preservation_helpers.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import ast
 import hashlib
 import re
 from pathlib import Path
@@ -33,6 +34,41 @@ def sha256(path: Path) -> str:
     return hashlib.sha256(path.read_bytes()).hexdigest()
 
 
+def function_contract(path: Path, name: str) -> tuple[str, str]:
+    tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+    function = next(
+        node for node in tree.body if isinstance(node, ast.FunctionDef) and node.name == name
+    )
+    body = ast.Module(body=function.body, type_ignores=[])
+    return (
+        ast.dump(function.args, include_attributes=False),
+        ast.dump(body, include_attributes=False),
+    )
+
+
+def module_contract(
+    path: Path,
+    *,
+    excluded_definitions: set[str] | None = None,
+    excluded_import_modules: set[str] | None = None,
+    exclude_imports: bool = False,
+) -> str:
+    excluded_definitions = excluded_definitions or set()
+    excluded_import_modules = excluded_import_modules or set()
+    tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+    tree.body = [
+        node
+        for node in tree.body
+        if not (exclude_imports and isinstance(node, (ast.Import, ast.ImportFrom)))
+        and not (
+            isinstance(node, ast.ImportFrom)
+            and node.module in excluded_import_modules
+        )
+        and getattr(node, "name", None) not in excluded_definitions
+    ]
+    return ast.dump(tree, include_attributes=False)
+
+
 def reassembled_frontend_runtime() -> str:
     chunks: dict[tuple[int, int], str] = {}
     for path in FRONTEND_ROOT.rglob("*.js"):

tests/test_numeric_normalization.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import math
+import unittest
+
+from backend.data.numbers import finite_number, non_nan_number
+from backend.data.providers import tushare_client
+from backend.features.market import insights
+from backend.features.screener import engine as screener_engine
+from backend.features.sentiment import engine as sentiment_engine
+
+
+class NumericNormalizationTests(unittest.TestCase):
+    def test_consumers_use_their_declared_shared_policy(self) -> None:
+        self.assertIs(tushare_client._number, finite_number)
+        self.assertIs(screener_engine._number, finite_number)
+        self.assertIs(insights._number, non_nan_number)
+        self.assertIs(sentiment_engine._number, non_nan_number)
+
+    def test_finite_policy_preserves_existing_results(self) -> None:
+        self.assertEqual(finite_number("12.5"), 12.5)
+        self.assertEqual(finite_number(None), 0.0)
+        self.assertEqual(finite_number("invalid", 7.0), 7.0)
+        self.assertEqual(finite_number(math.nan, 7.0), 7.0)
+        self.assertEqual(finite_number(math.inf, 7.0), 7.0)
+        self.assertEqual(finite_number(-math.inf, 7.0), 7.0)
+
+    def test_non_nan_policy_keeps_infinity_but_rejects_nan(self) -> None:
+        self.assertEqual(non_nan_number("12.5"), 12.5)
+        self.assertEqual(non_nan_number(None), 0.0)
+        self.assertEqual(non_nan_number("invalid", 7.0), 7.0)
+        self.assertEqual(non_nan_number(math.nan, 7.0), 7.0)
+        self.assertEqual(non_nan_number(math.inf, 7.0), math.inf)
+        self.assertEqual(non_nan_number(-math.inf, 7.0), -math.inf)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_preservation_slice_market.py

@@ -11,12 +11,14 @@ import realtime_aggregator
 import tushare_client
 from backend.bootstrap import config as bootstrap_config
 from backend.data import realtime
+from backend.data.numbers import finite_number
 from backend.data.providers import ifind_client as canonical_ifind
 from backend.data.providers import tushare_client as canonical_tushare
 from backend.features.market import charts
 from tests.preservation_helpers import (
     assert_frontend_runtime_matches_audited_baseline,
     assert_moved_asset_matches,
+    function_contract,
 )
 
 
@@ -102,18 +104,6 @@ def top_level_definitions(path: Path) -> dict[str, str]:
     }
 
 
-def function_contract(path: Path, name: str) -> tuple[str, str]:
-    tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
-    function = next(
-        node for node in tree.body if isinstance(node, ast.FunctionDef) and node.name == name
-    )
-    body = ast.Module(body=function.body, type_ignores=[])
-    return (
-        ast.dump(function.args, include_attributes=False),
-        ast.dump(body, include_attributes=False),
-    )
-
-
 class MarketSliceSourceEquivalenceTests(unittest.TestCase):
     def test_market_service_methods_are_exact_original_ast(self) -> None:
         original = class_methods(ORIGINAL_ROOT / "server.py", "DashboardService")
@@ -154,10 +144,17 @@ class MarketSliceSourceEquivalenceTests(unittest.TestCase):
         )
         for original, migrated in exact_moves:
             self.assertEqual(sha256(ORIGINAL_ROOT / original), sha256(APP_ROOT / migrated))
+        original_tushare = top_level_definitions(ORIGINAL_ROOT / "tushare_client.py")
+        original_tushare.pop("_number")
         self.assertEqual(
-            top_level_definitions(ORIGINAL_ROOT / "tushare_client.py"),
+            original_tushare,
             top_level_definitions(APP_ROOT / "backend/data/providers/tushare_client.py"),
         )
+        self.assertEqual(
+            function_contract(ORIGINAL_ROOT / "tushare_client.py", "_number"),
+            function_contract(APP_ROOT / "backend/data/numbers.py", "finite_number"),
+        )
+        self.assertIs(canonical_tushare._number, finite_number)
         original_charts = top_level_definitions(ORIGINAL_ROOT / "chart_data_provider.py")
         original_charts.pop("_stock_market_code")
         self.assertEqual(

tests/test_preservation_slice_market_insights.py

@@ -6,11 +6,13 @@ import unittest
 from pathlib import Path
 
 import market_insights
+from backend.data.numbers import non_nan_number
 from backend.features.market import insights as canonical_insights
 from tests.preservation_helpers import (
     assert_frontend_runtime_matches_audited_baseline,
     assert_moved_asset_matches,
     assert_page_prefix_matches,
+    function_contract,
 )
 
 
@@ -106,6 +108,11 @@ class MarketInsightsSliceSourceEquivalenceTests(unittest.TestCase):
             MARKET_INSIGHT_METHODS,
         )
         self.assertIs(market_insights.MarketInsightsService, canonical_insights.MarketInsightsService)
+        self.assertEqual(
+            function_contract(ORIGINAL_ROOT / "market_insights.py", "_number"),
+            function_contract(APP_ROOT / "backend/data/numbers.py", "non_nan_number"),
+        )
+        self.assertIs(canonical_insights._number, non_nan_number)
 
     def test_dashboard_service_methods_are_exact_original_ast(self) -> None:
         original = ORIGINAL_ROOT / "server.py"

tests/test_preservation_slice_screener.py

@@ -9,12 +9,15 @@ import advanced_strategies
 import llm_strategy
 import screener
 import strategy_tracking
+from backend.data.numbers import finite_number
 from backend.features.screener import compiler, engine, strategies, tracking
 from backend.features.screener import service as screener_service
 from tests.preservation_helpers import (
     assert_frontend_runtime_matches_audited_baseline,
     assert_moved_asset_matches,
     assert_page_prefix_matches,
+    function_contract,
+    module_contract,
 )
 
 
@@ -91,14 +94,6 @@ def top_level_definition(path: Path, name: str) -> str:
     return ast.dump(node, include_attributes=False)
 
 
-def module_without_imports(path: Path) -> str:
-    tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
-    tree.body = [
-        node for node in tree.body if not isinstance(node, (ast.Import, ast.ImportFrom))
-    ]
-    return ast.dump(tree, include_attributes=False)
-
-
 def sha256(path: Path) -> str:
     return hashlib.sha256(path.read_bytes()).hexdigest()
 
@@ -154,11 +149,22 @@ class ScreenerSliceSourceEquivalenceTests(unittest.TestCase):
 
     def test_engine_and_tracking_logic_match_the_original(self) -> None:
         self.assertEqual(
-            module_without_imports(ORIGINAL_ROOT / "screener.py"),
-            module_without_imports(
-                APP_ROOT / "backend" / "features" / "screener" / "engine.py"
+            module_contract(
+                ORIGINAL_ROOT / "screener.py",
+                excluded_definitions={"_number"},
+                exclude_imports=True,
+            ),
+            module_contract(
+                APP_ROOT / "backend" / "features" / "screener" / "engine.py",
+                excluded_definitions={"_number"},
+                exclude_imports=True,
             ),
         )
+        self.assertEqual(
+            function_contract(ORIGINAL_ROOT / "screener.py", "_number"),
+            function_contract(APP_ROOT / "backend/data/numbers.py", "finite_number"),
+        )
+        self.assertIs(engine._number, finite_number)
         self.assertEqual(
             class_methods(
                 ORIGINAL_ROOT / "backend" / "features" / "screener" / "tracking.py",

tests/test_preservation_slice_sentiment_pools.py

@@ -6,11 +6,14 @@ import unittest
 from pathlib import Path
 
 import sentiment_engine
+from backend.data.numbers import non_nan_number
 from backend.features.sentiment import engine as canonical_engine
 from tests.preservation_helpers import (
     assert_frontend_runtime_matches_audited_baseline,
     assert_moved_asset_matches,
     assert_page_prefix_matches,
+    function_contract,
+    module_contract,
 )
 
 
@@ -94,10 +97,22 @@ class SentimentPoolSliceSourceEquivalenceTests(unittest.TestCase):
 
     def test_sentiment_engine_is_exact_original_with_legacy_alias(self) -> None:
         self.assertEqual(
-            sha256(ORIGINAL_ROOT / "sentiment_engine.py"),
-            sha256(APP_ROOT / "backend" / "features" / "sentiment" / "engine.py"),
+            module_contract(
+                ORIGINAL_ROOT / "sentiment_engine.py",
+                excluded_definitions={"_number"},
+            ),
+            module_contract(
+                APP_ROOT / "backend" / "features" / "sentiment" / "engine.py",
+                excluded_definitions={"_number"},
+                excluded_import_modules={"backend.data.numbers"},
+            ),
+        )
+        self.assertEqual(
+            function_contract(ORIGINAL_ROOT / "sentiment_engine.py", "_number"),
+            function_contract(APP_ROOT / "backend/data/numbers.py", "non_nan_number"),
         )
         self.assertIs(sentiment_engine, canonical_engine)
+        self.assertIs(canonical_engine._number, non_nan_number)
 
     def test_api_and_frontend_assets_are_unchanged(self) -> None:
         self.assertEqual(