"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
refactor(grounding): split the gate into a package (no behaviour change)
Haozhe Wueb3b927daedf
diff --git a/agent/src/agent/grounding.py b/agent/src/agent/grounding.pydeleted file mode 100644index 7504285c6..000000000--- a/agent/src/agent/grounding.py+++ /dev/null@@ -1,5183 +0,0 @@-"""Run-scoped identity and numeric evidence gates for the main agent loop.--The language model remains responsible for research and explanation, but three-facts are structural rather than advisory:--* a market-data consumer may only use an identity that was locked before the- current assistant tool-call batch started;-* a final price claim may not contradict the full, untruncated tool result; and-* a figure may not be attached to an instrument that no tool call in this run- ever passed in or returned.--Those are the mechanically decidable parts of the agent's output principles.-The rest of that contract — "state the as-of", "analysis, not advice", "refuse-out loud" — stays in the system prompt on purpose: see ``_validate_price_claims``-and the module tests for why a regex gate on them rejects correct answers.--This module deliberately contains no provider or tool-registry dependencies so-its state machine and final-answer checks remain deterministic and testable.-"""--from __future__ import annotations--import ast-import csv-import hashlib-import json-import math-import re-from dataclasses import asdict, dataclass, field, replace-from datetime import datetime, timezone-from pathlib import Path-from typing import Any, Iterable, Mapping, Sequence-from src.market_data import canonical_fx_pair--from src.agent.resolution_context import (- IdentityConstraint,- ResolutionContext,- candidate_market,-)---GROUNDING_ARTIFACT = "grounding_evidence.json"--_RESOLVER_TOOL = "search_symbol"--# Tools whose successful completion can ground backtest/analysis metric claims-# (#1336). Success alone is not authority: only results that actually carried-# metric output (parsed from the result or its run-dir artifacts) raise-# ``analysis_claim_unavailable``. A deduplicated ("skipped") call is never a-# completion.-_ANALYSIS_TOOLS = frozenset(- {"backtest", "factor_analysis", "run_shadow_backtest", "quantlib_call"}-)-# Tools whose run produces the equity/regime windows behind a categorical-# "all N-month windows were profitable" statement.-_ANALYSIS_WINDOW_TOOLS = frozenset({"backtest", "run_shadow_backtest"})-_PRIVATE_COMPANY_SKILL_NAMES = {- "private-company",- "private-company-analysis",- "private-company-research",- "private_company",- "private_company_analysis",- "private_company_research",-}-_SYMBOL_ARGUMENT_KEYS = {- "code",- "codes",- "symbol",- "symbols",- "ticker",- "tickers",- "underlying",- "underlyings",-}-# Workflow selection must not race an in-flight resolution or proceed on-# contradicted identity. It may proceed once the resolver has answered — and-# ``ambiguous`` is an answer: a screening request ("推荐低价高增长股票") resolves to-# many candidates by design. Requiring a locked identity there stalls every-# discovery task before it can load a screening skill, which is #955.-_RESOLUTION_INCOMPLETE_STATUSES = {"unresolved", "conflicting", "invalidated"}-# Bounded read-only recovery (#1081): a missing instrument identity or price-# evidence is often recoverable deterministically, so the loop should keep-# driving the original task through `search_symbol` and `get_market_data`-# instead of handing the user a terminal "confirm and continue" fallback.-# These budgets are separate from the rejected-draft count so real recovery-# progress is never cut off at the three-draft retry cap.-MAX_GROUNDING_RECOVERY_ROUNDS = 6-# Issue codes whose figure can be cut out of its clause and the draft released-# (see ``redacted_release``), and the provenance codes a data note repairs.-_REDACTABLE_CODES = frozenset(- {- "numeric_claim_conflict",- "numeric_claim_unavailable",- "unsourced_symbol_figures",- "analysis_claim_unavailable",- }-)-# The provenance codes a data note may fill in deterministically. The source-# and the currency are metadata ABOUT a figure. ``canonical_symbol_not_surfaced``-# is deliberately absent: the symbol is the figure's SUBJECT, and appending-# "562500.SH: source yahoo" under a draft that calls the instrument 贵州茅台-# footnotes a misattribution instead of repairing it — so the identity binding-# keeps its model-correction round.-_REPAIRABLE_PROVENANCE_CODES = frozenset(- {"data_source_not_surfaced", "currency_not_surfaced"}-)-_MAX_REDACTION_PASSES = 3-# The in-text mark for an omitted figure. It replaces the number AND the unit-# glued to it ("0.95 元" → "(略※)", "$1.10" → "(omitted※)") so the sentence-# still reads as prose, and the ※ points at the one footnote that says how-# many figures were omitted and why. A bracketed "[value removed]" left the-# unit dangling and read like a redaction stamp.-_REDACTION_MARKER_ZH = "(略※)"-_REDACTION_MARKER_EN = "(omitted※)"-# Unit / currency tokens glued to a price, swallowed with the figure.-# The single-character 元 additionally guards against CJK: without it the-# swallow ate the 元 of 元宵/元旦/元件 and left an orphan "宵节后关注" in the-# released text. The multi-character units cannot start a longer word the-# same way, so they keep the Latin-only guard (it is there for USD/USDT).-# Both guards also refuse a following slash: 元/股 and USD/share are ONE-# compound unit, and swallowing only its first half rewrote-# "建议买入价 0.95 元/股" into "建议买入价(略※)/股" — a denominator with-# nothing left above it.-_CURRENCY_UNIT_WORDS = (- r"人民币|美元|美金|港元|港币|日元|欧元|英镑|"- r"CNY|RMB|USD|HKD|JPY|EUR|GBP|CAD|AUD|SGD|USDT"-)-_UNIT_AFTER_RE = re.compile(- r"\s*(?:(?:" + _CURRENCY_UNIT_WORDS + r")(?![A-Za-z//])"- r"|元(?![A-Za-z//\u3400-\u9fff]))"-)-# The same tokens without the swallow guards. Those guards decide how much-# text the marker may EAT; this one only asks whether a figure is written as a-# price, and there "1.180 元已回撤" is as much a quote as "1.180 元。" is.-_UNIT_TOKEN_AFTER_RE = re.compile(- r"\s*(?:" + _CURRENCY_UNIT_WORDS + r"|元)", re.IGNORECASE-)-_CURRENCY_BEFORE_RE = re.compile(r"(?:US\$|HK\$|C\$|A\$|S\$|\$|¥|¥|€|£)\s*$")-MAX_SYMBOL_RESOLUTION_ATTEMPTS = 2-MAX_PRICE_EVIDENCE_ATTEMPTS = 3-_PRICE_FIELDS = {"open", "high", "low", "close", "adj_close", "price"}-_TIMESTAMP_FIELDS = ("trade_date", "date", "datetime", "timestamp", "time", "index")-_MAX_GENERIC_EVIDENCE = 2_000-_MAX_TRACKED_SYMBOLS = 5_000--# CSV columns (case-insensitive) accepted from OHLC files the run wrote via-# bash+yfinance, and their canonical price-field names. Everything else in the-# file (Volume, Adj Close, etc.) is deliberately ignored so the contradiction-# check does not gain values it would be willing to accept.-_CSV_PRICE_COLUMNS = {- "open": "open",- "high": "high",- "low": "low",- "close": "close",- "price": "price",-}-_CSV_DATE_COLUMNS = {"date", "datetime", "trade_date", "timestamp", "index"}-# Filename -> symbol mapping for run-dir CSVs. The bash workaround writes each-# series with a filesystem-safe stem: ``BYN_V.csv`` for ``BYN.V``, ``PDI_TO.csv``-# for ``PDI.TO``, ``GC_F.csv`` for ``GC=F``.-_CSV_FILENAME_SUFFIX_MAP = (- ("_V", ".V"),- ("_TO", ".TO"),- ("_F", "=F"),- # A US name is written ``INTC_US.csv`` by the same workaround, and- # ``.US`` is the venue suffix the rest of the project resolves on. Without- # this row the CSV was ingested as no evidence at all, so every price the- # run had actually fetched came back "numeric_claim_unavailable".- ("_US", ".US"),-)--# Only ``get_market_data`` returns bars whose columns are already the canonical-# OHLC field names. Every other market-sensitive tool nests its quote somewhere,-# and ``_ingest_generic_numeric`` stores that JSON path verbatim — "data.last",-# "quote[0].close_price". Without this map those observations never reach the-# final-answer check, so a price the run genuinely retrieved is rejected as-# "no matching observed tool evidence": measured against the live validator, an-# answer quoting a ``get_stock_profile`` price failed with-# ``numeric_claim_unavailable`` while the identical claim backed by-# ``get_market_data`` passed. Only unambiguous quote fields are mapped; ratios,-# volumes, strikes, and analyst targets stay out so the contradiction check does-# not gain a wider set of values it is willing to accept.-_GENERIC_PRICE_FIELD_ALIASES = {- "open": "open",- "open_price": "open",- "openprice": "open",- "开盘": "open",- "开盘价": "open",- "high": "high",- "high_price": "high",- "最高": "high",- "最高价": "high",- "low": "low",- "low_price": "low",- "最低": "low",- "最低价": "low",- "close": "close",- "close_price": "close",- "closeprice": "close",- "prev_close": "close",- "pre_close": "close",- "preclose": "close",- "previous_close": "close",- "收盘": "close",- "收盘价": "close",- "昨收": "close",- "adj_close": "adj_close",- "adjclose": "adj_close",- "adjusted_close": "adj_close",- "price": "price",- "last": "price",- "last_price": "price",- "lastprice": "price",- "latest_price": "price",- "current_price": "price",- "market_price": "price",- "settle": "price",- "settlement": "price",- "settle_price": "price",- "vwap": "price",- "现价": "price",- "最新价": "price",-}--# Project-style canonical symbols. A bare model-generated ticker is still-# checked when it appears under a symbol argument key, but it is not accepted-# as user-provided identity because it lacks venue information.-#-# A joined crypto pair (``BTCUSDT``, ``ETHUSDT`` …) is recognized alongside-# the dashed/slashed form so a user message like ``Get BTCUSDT spot price``-# seeds an asserted identity and the asserted-symbol conflict check at-# ``_ingest_resolution`` runs against it. The base is restricted to alpha-# so a numeric prefix cannot masquerade as a joined pair, and the suffix-# list is the unambiguous stablecoin set (``USDT`` / ``USDC`` / ``BUSD`` /-# ``TUSD``) — ``USD`` is excluded because too many non-crypto strings end-# in those three letters and over-matching would lock the wrong identity.-_JOINED_CRYPTO_QUOTE_SUFFIXES = ("USDT", "USDC", "BUSD", "TUSD")-# A dashed / slashed pair is crypto when its quote leg is unambiguously a-# crypto quote asset, or when a USD quote sits on one of these bases. Both-# sets MUST agree with ``_CRYPTO_QUOTE_ASSETS`` / ``_CRYPTO_USD_BASES`` in-# ``src.tools.symbol_search_tool`` — that module is the resolver, and a venue-# inferred here that disagrees with the identity it locks is a contradictory-# identity, which outranks every later lock and blocks all market tools. The-# tool imports this module, so the sets are duplicated rather than imported;-# ``test_crypto_pair_tables_match_the_resolver`` fails if they drift. ``USD``-# is the one quote the resolver accepts that is NOT unambiguous, so it is-# excluded here and decided by the base whitelist below instead.-_CRYPTO_QUOTE_ASSETS = frozenset(- {"USDT", "USDC", "BUSD", "TUSD", "FDUSD", "BTC", "ETH", "BNB"}-)-_CRYPTO_USD_BASES = frozenset(- {- "BTC", "ETH", "BNB", "SOL", "ADA", "XRP", "DOGE", "TRX", "DOT",- "MATIC", "AVAX", "LINK", "LTC", "BCH", "ETC", "XLM", "ATOM",- "FIL", "APT", "NEAR", "ALGO", "SAND", "MANA", "AXS", "XAUT",- "PAXG",- }-)-# Spot precious metals quoted in USD collide with the TUSD suffix: XPTUSD is-# XPT + USD (platinum), but stripping "TUSD" leaves the alpha base "XP" and-# folds it to XP-TUSD — a crypto pair that does not exist, and the same class-# of misresolution the USD exclusion above exists to prevent. XAU/XAG/XPD do-# not collide today; they are listed together because they are the same kind-# of symbol and a future suffix would collide with them the same way.-_METAL_USD_PAIR_RE = re.compile(r"^(?:XAU|XAG|XPT|XPD)USD$", re.IGNORECASE)-_JOINED_CRYPTO_RE = re.compile(- r"(?<![A-Za-z0-9_])[A-Z]{2,15}(?:" + "|".join(_JOINED_CRYPTO_QUOTE_SUFFIXES) + r")(?![A-Za-z0-9_])",- re.IGNORECASE,-)-_CANONICAL_SYMBOL_RE = re.compile(- r"(?<![A-Za-z0-9_])(?:"- r"\d{3,6}\.(?:SH|SZ|BJ|SS|HK|KS|KQ)|"- # Futu writes the venue as a PREFIX (HK.00700 / SH.600519 / US.AAPL). The- # suffix branch above cannot see it, so a user who pasted a connector code- # got no identity lock at all and every market tool answered- # identity_required. Handled for the whole prefix set, not just HK: the- # connector emits all four, and one venue's fix leaves the same hole open- # in the next.- r"(?:HK|SH|SZ|BJ|SS)\.\d{3,6}|"- # Case-SENSITIVE (the connector writes it uppercase): a case-folded- # match turns any "…/us.reuters/…" host inside a source URL into the- # symbol REUTERS.US and fails the answer for an unsourced figure.- r"(?-i:US\.[A-Z][A-Z0-9&-]{0,19})|"- r"[A-Z][A-Z0-9&.-]{0,19}\.(?:US|NS|BO|FX|TO|V)|"- r"[A-Z0-9]{2,15}(?:-|/)(?:USDT|USDC|USD|BTC|ETH)|"- r"[A-Z]{2,15}(?:" + "|".join(_JOINED_CRYPTO_QUOTE_SUFFIXES) + r")|"- r"\^[A-Z0-9&.\-]{1,20}|"- r"[A-Z0-9]{2,15}=[FX]"- r")(?![A-Za-z0-9_])",- re.IGNORECASE,-)-_ACTIONABLE_MARKET_RE = re.compile(- r"(?:\bbuy\b|\bsell\b|\bentry\b|\btarget price\b|\bcurrent price\b|"- r"\blatest price\b|\bprice of\b|\btrade\b|"- r"\bvaluation of\b|\bwhat (?:is|are) .{1,80} worth\b|"- r"\bis .{1,80} (?:listed|publicly traded)\b|"- r"买入|卖出|入场|目标价|现价|最新价|股价|交易价格|估值|值多少钱|"- r".{1,40}(?:是否|有没有|已经|已)(?:在.{0,20})?上市)",- re.IGNORECASE,-)-_PRIVATE_ASSERTION_RE = re.compile(- r"(?:\b(?:is|remains|still)\s+(?:an?\s+)?(?:private company|privately held)\b|"- r"\bnot publicly traded\b|\bunlisted company\b|"- r"(?:是|仍是|属于)(?:一家)?(?:私人|私营|非上市)公司|未上市|没有上市)",- re.IGNORECASE,-)-# The bare verbs below are present tense only, which is not how an answer-# actually states an observed price: "closed at 412.35" and "last traded at-# 412.35" are the ordinary spellings and neither matches \bclose\b or-# \btrade\b. Chinese 收盘 / 现价 match, so the gate was strictly leakier in-# English than in Chinese — a fabricated USD price in the most natural-# phrasing walked straight through while its Chinese translation was caught.-# The past-tense forms are required to be followed by "at" so that reporting-# volume ("traded 1.2M shares") or a corporate event ("the deal closed at a-# 30% premium" — a percentage, already masked) is not read as a quote.-_PRICE_VERB_PAST_RE = r"\b(?:closed|opened|traded|quoted|priced|settled|fixed)\s+at\b"-_PRICE_CONTEXT_RE = re.compile(- r"(?:\b(?:opening|open|high|low|closing|close|price|quote)\b|"- + _PRICE_VERB_PAST_RE + r"|"- r"\b(?:entry|buy|target|support|resistance)\s+(?:price|level)\b|"- r"开盘价?|最高价?|最低价?|收盘价?|买入价|入场价|目标价|支撑位?|阻力位?|"- # Chinese had the mirror-image gap: these four are as ordinary as 收盘价- # and none of them matched, so a fabricated 成交价 / 股价 walked through- # exactly the way "closed at" did in English.- r"成交价|最新价|股价|收报|"- r"现价|报价|价格|价位)",- re.IGNORECASE,-)-# The vocabulary of a price LEVEL — a band, a moving average, a support or-# resistance line. It is the only shape for which an indicator reading is-# admissible evidence, and the rule is stated this way round on purpose.-#-# It used to be stated the other way: an indicator was admissible unless the-# clause named an OHLC field, against a hand-written list of field phrases.-# A hand-written denylist is only ever as complete as the day it was typed,-# and it was not complete for one day: with the session's sma_20 at 1.150 and-# the observed close at 1.171, "收盘价为 1.150 元" was caught while "收盘于"'s-# English twins "closed at 1.150" / "the close was 1.150" / "highest price was-# 1.150" were released, and every spot-quote spelling there is — 现价 / 最新价-# / 成交价 / 报价 / 股价 / current price / the quote is — leaked in both-# scripts, because a spot quote names the latest print and named no OHLC-# field. An allowlist fails the other way: a level word this list misses costs-# a correction round instead of releasing a fabricated print.-_PRICE_LEVEL_WORD_RE = re.compile(- r"(?:\b(?:support|resistance|pivot|moving[- ]average|"- r"(?:upper|lower|middle) band|band|channel|bollinger|keltner|donchian|"- r"ichimoku|supertrend|vwap|atr)\b|"- r"\b(?:SMA|EMA|WMA|DMA|MA|BOLL)\d{0,3}\b|"- r"支撑|阻力|压力|均线|上轨|下轨|中轨|轨道|通道|中枢|枢轴|布林)",- re.IGNORECASE,-)-# A table column whose header names a price. Wider than the OHLC aliases on-# purpose: 挂单价 / 目标价 / Entry Price are price columns that-# ``_validate_price_tables`` does not key on and the prose scan skips, so-# their cells are figures no validator ever reads.-_PRICE_HEADER_RE = re.compile(r"(?:价格?|价位|price)\s*$", re.IGNORECASE)-_ANALYSIS_METRIC_RE = re.compile(- r"(?:\breturn vol(?:atility)?\b|\bmax(?: |\.)?drawdown\b|\bmaxdd\b|"- r"\bsharpe(?: ratio)?\b|\bwin rate\b|\bhit rate\b|"- r"\bprob(?:ability)?\.?\s+of\b|\bvolatility\b|\bdrawdown\b|"- r"\bannualiz\w*\b|\bwindow(?:s)?\b|\bregime(?:s)?\b|"- r"\b(?:annual|cumulative|total)\s+return\b|"- r"夏普|回撤|波动率|胜率|命中率|概率|年化|回测|窗口|收益(?:率)?|回报(?:率)?)",- re.IGNORECASE,-)-# Phrases that indicate a figure is attributed to an external source rather-# than model memory (paper restatement, #1338 review). Attributing a number-# to a named source is the opposite of an unsourced claim. The subject list-# is deliberately restricted to sources that cannot be this run's own output-# (papers, studies, analysts, filings): "the backtest reports" / "the data-# shows" is exactly how a model dresses up its own numbers (#1336), so-# data/backtest/strategy/report subjects do NOT count.-_ATTRIBUTION_RE = re.compile(- r"(?:"- r"\b(?:the\s+(?:papers?|studies?|researchers?|analysts?|surveys?"- r"|regulators?|authorities|literature|authors?)"- r"|analysts?|researchers?|literature|sec\s+filings?\b|filings?"- r"|annual\s+filings?|quarterly\s+filings?|rating\s+agencies?)"- r"\s+(?:reports?|estimates?|shows?|indicates?|suggests?|states?|claims?"- r"|notes?|cites?|mentions?|reveals?|discloses?|publishes?|found"- r"|calculated|computed|derived)\b"- r"|"- r"(?:论文|文献|分析师|研究机构|学者)"- r"[^。,\n]{0,6}?(?:报告|显示|表明|指出|称|估计|发现)"- r")",- re.IGNORECASE,-)-# Measurement-shaped numbers for analysis claims: keeps the % sign and sign-# (unlike _numbers_without_dates_or_percent, which drops percentages on-# purpose). A bare integer is NOT a measurement — "252 个交易日年化" is the-# standard convention, not a claim about this run's analysis (#1032-style-# definitional prose must stay untouched). Dates can still look like-# measurements, so date masks run first.-_MEASURE_NUMBER_RE = re.compile(- r"[-+]?(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)\s*[%%]?" # decimal: 1.21, -8.1%- r"|[-+]?(?:\d{1,3}(?:,\d{3})+|\d+)\s*[%%]" # integer percent: 55%, 70%-)-# A forward-looking frame means the figure is a forecast, not a claim that a-# backtest/analysis measured it — the measurement gate only polices "measured-# facts" (#1336), forecasts stay under the "analysis, not advice" prompt rule.-_FORECAST_FRAME_RE = re.compile(- r"(?:\b(?:forecast|expected|projected|predicted)\b|预计|预期|预测|估计|展望)",- re.IGNORECASE,-)--# Metric family for a claim/evidence leaf, so a figure is only grounded by-# evidence of its own kind: an observed price must never stand in for an-# invented volatility (#1336).-_ANALYSIS_KIND_ALIASES = {- "annualized_vol": "vol",- "annualized_volatility": "vol",- "volatility": "vol",- "return_vol": "vol",- "return_volatility": "vol",- "vol": "vol",- "max_drawdown": "drawdown",- "maxdd": "drawdown",- "drawdown": "drawdown",- "sharpe": "sharpe",- "sharpe_ratio": "sharpe",- "win_rate": "win_rate",- "hit_rate": "win_rate",- "hitrate": "win_rate",- "probability": "probability",- "prob": "probability",- "total_return": "return",- "annual_return": "return",- "cumulative_return": "return",- "benchmark_return": "return",- "excess_return": "return",- "annualized_return": "return",- "return": "return",- "returns": "return",- "ic_positive_ratio": "win_rate",-}--# Order matters: 最大回撤 is drawdown before 收益/return, and 年化波动率 is vol-# before the generic return branch.-_ANALYSIS_KIND_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = (- (re.compile(r"(?:回撤|drawdown|maxdd|最大亏损)", re.IGNORECASE), "drawdown"),- (- re.compile(- r"(?:波动率|波动性|volatility|annualized\s*vol|return\s*vol|年化波动)",- re.IGNORECASE,- ),- "vol",- ),- (re.compile(r"(?:夏普|sharpe)", re.IGNORECASE), "sharpe"),- (re.compile(r"(?:胜率|命中率|win\s*rate|hit\s*rate)", re.IGNORECASE), "win_rate"),- (re.compile(r"(?:概率|probability|prob)", re.IGNORECASE), "probability"),- # 年化/annualized alone ("| 年化 | 18.2% |") resolves to return so a- # generic-header table cannot dodge the gate with the fragment the prose- # detector (_ANALYSIS_METRIC_RE) already treats as a metric word.- (re.compile(r"(?:收益|回报|收益率|回报率|年化|\breturns?\b|\bannualized\b)", re.IGNORECASE), "return"),-)--# Definitional prose ("夏普比率大于 1.0 通常被认为较好") states a convention,-# not a measurement this session produced (#1336: preserve explicitly labelled-# definitions). The bare 通常 alone is deliberately not enough — "通常实现-# 18.2% 年化" is a measured claim.-_DEFINITION_FRAME_RE = re.compile(- r"(?:通常(?:认为|被?认为|说来|指|用于)|一般认为|定义为|是指|惯例|"- r"conventionally|typically\s+(?:considered|regarded|seen)|"- r"generally\s+(?:accepted|considered|regarded)|by\s+convention)",- re.IGNORECASE,-)--# A categorical "all N-month windows were profitable" claim carries only an-# integer window length, which _MEASURE_NUMBER_RE deliberately ignores; it is a-# measured fact about the run and needs a window-producing analysis result.-_CATEGORICAL_WINDOW_RE = re.compile(- r"(?:所有|全部|每个|任何|each|every|all)[\s\S]{0,40}?"- r"(?:窗口|区间|windows?|periods?)[\s\S]{0,30}?"- r"(?:正收益|均为正|都为正|盈利|上涨|positive|profitable)",- re.IGNORECASE,-)-_DERIVATION_RE = re.compile(- r"(?:\bderived\b|\bcalculated\b|\bformula\b|\bbased on\b|计算|推导|公式|基于)",- re.IGNORECASE,-)-# The separator between a formula and its result. "=" is how the gate first-# accepted a derivation; "≈" / "≒" / "约" / "约等于" are how a model writes one-# whose result it rounded, and each was rejected with the multiplier read as a-# quoted price. The evaluation tolerance already absorbs the rounding.-# The English spellings are here for the same reason the Chinese ones are:-# ``test_derived_return_exemption_is_structural_not_phrasal`` is the repo's-# standing rule that identical arithmetic gets an identical verdict in both-# languages, and "1.171 * 0.97 approximately 1.136" was still burning a-# revision round while its ≈ twin passed.-_RESULT_SEPARATOR_RE = re.compile(- r"约等于|≈|≒|=|约|~|\b(?:approximately|approx\.?|about|around|roughly)\b",- re.IGNORECASE,-)-# The subject of a performance metric decides which evidence may ground it.-# A strategy's max drawdown is a property of an equity curve a backtest-# produced; two observed prints of the instrument are not that curve, and-# neither is any arithmetic on them. "回测显示该策略最大回撤 5.9%(从 1.180-# 跌至 1.110)" rode out of the session on the endpoint-arithmetic exemption-# with no backtest anywhere in it. A PRICE-subject drawdown ("股价较 5 月高点-# 1.053 元已回撤约 37%") is the arithmetic itself and keeps the exemption.-_STRATEGY_SUBJECT_RE = re.compile(- r"(?:\bstrateg(?:y|ies)\b|\bbacktest(?:ed|ing)?\b|\bportfolio\b|"- r"\bequity curve\b|\bNAV\b|\bholdings?\b|"- r"策略|回测|组合|持仓|净值)",- re.IGNORECASE,-)-_INDICATOR_IDENTIFIER_RE = re.compile(r"(?<![0-9.])[A-Za-z_]+\d+(?![0-9.])")-# "从 2026-08-03 的 100.0 涨到 2026-09-02 的 112.4" / "rose from 100.0 to-# 112.4": a return figure framed as growth between two endpoints is-# arithmetic on sourced inputs, not an invented backtest metric (#1338-# review). The frame alone never grounds anything — the values must also-# match an observed endpoint pair exactly (see _return_derived_from_observed).-_NUMBER_RE = re.compile(- r"(?<![A-Za-z0-9_])[-+]?(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?"- r"(?![A-Za-z0-9_])"-)-# A line-leading ordered-list marker ("1. **标题**") is prose structure, not a-# number. Without masking it, "1." is parsed as a float and rejected downstream-# as a numeric_claim_conflict against an observed OHLC range (#BUGS-1). The-# pattern only matches a digit run at the start of a line followed by "." or ")"-# and whitespace, so an in-text decimal like "1.5" (digit after the dot) is-# never affected.-_MD_LIST_ITEM_RE = re.compile(r"^\s*\d+[.)]\s+", re.MULTILINE)-# Unitless identity constants in a symbolic rate formula are not quoted prices.-# Without this mask, ``1 - 单边成本率`` in a position-sizing formula is read as-# a one-yuan price merely because the same clause also mentions a close price.-# Keep the relaxation narrow: only 0/1 directly participating in arithmetic-# with a token explicitly labelled as a rate is removed.-_RATE_FORMULA_IDENTITY_RE = re.compile(- r"\b[01](?=\s*[-+]\s*(?:[A-Za-z_][A-Za-z0-9_]*_?rate\b|[^\d\s()+*/=-]{0,12}(?:成本率|费率|税率|滑点率)))",- re.IGNORECASE,-)-# re.ASCII keeps ``\b`` a *byte* word boundary. Without it, ``\w`` is-# Unicode-aware and CJK letters count as word characters, so a date that runs-# straight into Chinese text -- "(2026-07-14最低)" -- has no boundary after-# "14" and is left unmasked, contributing 2026/7/14 as candidate prices that-# reject a correct report (#1122).-_DATE_RE = re.compile(r"\b(?:19|20)\d{2}[-/]\d{1,2}[-/]\d{1,2}\b", re.ASCII)-# A year-less "8/5" is how a trading day is written in running prose, and it-# contributed 8 and 5 as candidate prices (#983). The month and day ranges are-# bounded, and both sides are fenced off from a longer slash run, so the window-# enumeration "20/50/200-day" cannot be mistaken for a date. Reports also write-# the same day as "08-10(一)" or "08-10盘中"; that dash form is masked by-# ``_DASH_DATE_RE`` below, where a zero-padded month or a weekday/session-# marker is required so a quoted price range like "8-10 元" stays checkable.-_SHORT_DATE_RE = re.compile(- r"(?<![\d/])(?:0?[1-9]|1[0-2])/(?:0?[1-9]|[12]\d|3[01])(?![\d/])"-)-# A report writes a trading day as "08-10(一)" or "08-10盘中", and the dash form-# leaked 8 and 10 as candidate prices exactly as "8/5" once did. The dash is-# NOT symmetric with the slash, though: it also separates a range, and "目标价-# 10-20 元" must stay checkable. So the two halves are split -- a zero-padded-# month (01-09) is a formatting intent no price range imitates, while 10/11/12-# have to carry a weekday or session marker to read as a date.-_DASH_DATE_RE = re.compile(- r"(?<![\d/-])(?:"- r"0[1-9]-(?:0[1-9]|[12]\d|3[01])"- r"|1[0-2]-(?:0[1-9]|[12]\d|3[01])"- r"(?=\s*(?:[((]\s*(?:周|星期)?[一二三四五六日天]\s*[))]"- r"|盘中|盘后|盘前|收盘|开盘|最低|最高"- r"|\s*(?:close|open|intraday|low|high)\b))"- r")(?![\d/-])",- re.IGNORECASE,-)-# A level stated as a RANGE has the same shape: the separator touches the-# second number, so masking "目标价 10" left "-20" behind and a negative price-# matches no OHLC window at all -- a guaranteed rejection of a correct draft.-# The tail is optional, so a single-value level is unaffected.-_RANGE_TAIL = r"(?:\s*[-–—~~至到]\s*[-+]?\d[\d,]*(?:\.\d+)?)?"--# A percentage range masks only its upper bound through the "%" tail check-# below, because the sign touches the second number: "1–2%" left 1 behind-# (#983). Mask the span as a whole.-_PERCENT_RANGE_RE = re.compile(- r"\d[\d,]*(?:\.\d+)?\s*[-–—~至]\s*\d[\d,]*(?:\.\d+)?\s*[%%]"-)-# A percentage-POINT delta is not a quoted price. "~3.6pp below Penumbra"-# describes a margin gap; left unmasked the ".6" is consumed as a decimal-# and the number reaches the OHLC comparator, which then rejects an-# otherwise correct fundamentals answer and demands `get_market_data` to-# substantiate a claim that has nothing to do with price.-# The trailing "%" spellings are already handled above; this covers the-# percentage-point spellings, which the percent masks never matched.-# The Chinese units take an optional measure word ("3.6 个百分点" is the-# ordinary spelling; bare "3.6 百分点" is the rare one) and are matched-# without a trailing \b: after a CJK character \b requires a non-word-# character to follow, so "下降 3.6 个百分点后企稳" would not match. The-# ASCII units keep \b, which is what stops "3.6ppm" being read as pp.-_PERCENTAGE_POINT_RE = re.compile(- r"[-+~≈]?\s*\d[\d,]*(?:\.\d+)?\s*"- r"(?:(?:pp|ppt|ppts|bps|bp)\b|个?(?:百分点|基点))",- re.IGNORECASE,-)-# Localized calendar text carries digits that the ISO pattern above leaves-# behind: "8 月 3 日" otherwise contributes 8 and 3 as candidate prices.-_LOCALIZED_DATE_RE = re.compile(- r"(?:(?:19|20)\d{2}\s*年\s*)?\d{1,2}\s*月(?:\s*\d{1,2}\s*[日号])?|(?:19|20)\d{2}\s*年"-)-# An aggregate amount is not a quoted price. "100 股成本 820 CNY" states a-# position cost; comparing 820 against a per-share OHLC range is a category-# error. The tradeoff is that a per-share figure written only as "成本 8.20"-# goes unchecked — provenance still requires symbol, source, and currency.-_AGGREGATE_AMOUNT_RE = re.compile(- r"(?:成本|总额|总价|总市值|市值|合计|金额|cost|total|notional|market value)"- r"\s*(?:为|是|约)?\s*[::]?\s*[-+]?\d[\d,]*(?:\.\d+)?",- re.IGNORECASE,-)-# Quantities, horizons, lot sizes, and lookback windows are unit-bearing:-# "100 股", "1–4 周", "3 个月", "52-week", "20/50/200-day". None are prices.-# The hyphenated English compound needs its own branch: the range alternation-# consumes "-4" in "1-4 周" but stalls on "-week", which left 52 behind to be-# compared against an OHLC range (#1001). The slash enumeration shares a single-# trailing unit, so "20/50/200-day" has to be masked as one span or its first-# two window lengths survive. ASCII units carry a trailing word boundary so-# "120 more" is not read as a quantity; the CJK branch cannot, because 周 and-# 内 are both word characters and "1–4 周内" must still mask.-_QUANTITY_WITH_UNIT_RE = re.compile(- r"\d[\d,]*(?:\.\d+)?"- r"(?:\s*/\s*\d[\d,]*(?:\.\d+)?)*"- r"(?:\s*[-–—~至]\s*\d[\d,]*(?:\.\d+)?)?"- r"\s*[-–—]?\s*"- r"(?:"- r"(?:股|手|张|份|口|笔|倍|个月|周|天|日|年|次|个交易日|项|行)"- r"|(?:shares?|contracts?|lots?|units?|sessions?|bars?|periods?|"- r"wks?|weeks?|months?|days?|years?|yrs?)\b"- r")",- re.IGNORECASE,-)-# A conviction reading is on a labelled scale, not a price scale: the 6 in-# "CONFIDENCE: 6" is bounded by the label that introduces it. Only the value-# bound to the label is masked, so a genuine quote elsewhere in the same-# clause is still checked. The optional denominator covers "6/10" (#1001).-_LABELLED_SCORE_RE = re.compile(- r"(?:confidence|conviction|score|rating|probability|odds|weighting|"- r"置信度|信心|评分|得分|概率|胜率)"- r"\s*(?:is|of|=|为|是)?\s*[::]?\s*"- r"[-+]?\d[\d,]*(?:\.\d+)?(?:\s*/\s*\d[\d,]*(?:\.\d+)?)?",- re.IGNORECASE,-)-# A named indicator reads on its own scale — "RSI of 46.7" is bounded at 100,-# not quoted in the instrument's currency. The name must be adjacent to the-# value, so a bare number elsewhere in the clause stays checked. Only-# unambiguous indicator names are listed: generic words such as "momentum" or-# "volatility" sit too close to price prose to mask safely.-_INDICATOR_VALUE_RE = re.compile(- r"\b(?:rsi|macd|atr|adx|cci|obv|kdj|boll|dif|dea|vix|iv|"- r"sharpe|sortino|beta)\b"- r"(?:\s*\([^)]{0,20}\))?"- # #1354: "RSI below 30" / "sharpe above 1" — a directional connective is- # part of the indicator reading, so the reading's number stays masked.- # Only indicator NAMES get these connectives; a price word with- # "below/above" ("close above 2500") is an observed-value claim and- # matches none of these names, so it stays gated.- r"\s*(?:is|at|of|reads?|=|为|是|below|above|under|over)?\s*[::]?\s*"- r"[-+]?\d[\d,]*(?:\.\d+)?",- re.IGNORECASE,-)-# A currency token may sit between a level marker or comparison operator and-# the number: "收盘 <$2.86", "目标位 C$6.80", "trigger at $119.68". Without-# it, the number survives masking and is compared against observed OHLC as a-# price claim even though it is a prospective level, not an observed quote.-_CURRENCY_TOKEN = r"(?:\$|US\$|C\$|HK\$|CAD|USD|CNY|HKD|¥|¥)?"--# An order line is an instruction, not an observation. "100 @ $3.50" states-# where a limit sits and "100" is a share count that was never a price at all,-# yet both went to the OHLC check and rejected a weekly update whose quotes-# were correct. This is the same category as the target/stop levels below -- a-# level the report proposes, not one the data source reported.--# #1354: a signal value trailing an arrow or a signal word ("sinal +1",-# "-> +1", "触发 +1", "Sinal: +1") is the formula's output, not an observed-# price. Signal values are small integers (a +/-1 signal, a 1-10 score); a-# multi-digit price never follows these words, so the digit bound keeps-# "close -> 2500" (a price claim written in arrow notation) gated. The colon-# is optional ("Sinal: +1" — ASCII '.' is not a clause separator, so this can-# sit in the same clause as the price word), the sign may be spaced ("sinal-# - 1"), and the lookahead stops the bound from masking the first two digits-# of a longer number ("signal 2500" keeps the full 2500 gated).-_SIGNAL_VALUE_RE = re.compile(- r"(?:\b(?:signal|sinal|trigger|triggers|triggered|dispara|信号|触发)\b[::]?"- r"|->|→|=>)"- r"\s*[-+]?\s*\d{1,2}(?:\.\d+)?(?!\d)",- re.IGNORECASE,-)-_ORDER_LEVEL_RE = re.compile(- r"(?:"- # (a) "<qty> [股|shares] @ <price>" -- the whole clause, quantity included- r"\d[\d,]*(?:\.\d+)?\s*(?:股|shares?)?\s*@\s*"- + _CURRENCY_TOKEN + r"\s*[-+]?\d[\d,]*(?:\.\d+)?"- r"|"- # (b) an order label, optionally carrying its own "<qty> @", then the level.- # There is deliberately no bare "@ <price>" branch: dates are masked before- # this runs, so "收盘 2026-08-10 @ 8.20" would arrive here as "@ 8.20" and a- # genuinely observed close would stop being checked. 买入价 / 卖出价 are- # absent for the same reason -- in running prose they name a price the- # report says it observed, not an instruction it proposes.- r"(?:挂单|限价单|限价|委托价?|订单"- r"|limit\s+(?:order|price)|\bGTC\b|\bGTD\b|\bIOC\b|\bFOK\b)"- r"\s*(?:为|是|at|=)?\s*[::]?\s*"- r"(?:\d[\d,]*(?:\.\d+)?\s*(?:股|shares?)?\s*@\s*)?"- + _CURRENCY_TOKEN + r"\s*[-+]?\d[\d,]*(?:\.\d+)?"- r")" + _RANGE_TAIL,- re.IGNORECASE,-)-# A historical reference names a price the instrument once traded at — an-# all-time high, a 52-week extreme — and the answer is not claiming it as-# today's observed quote. "8/12 高 149.60 为 6/16 ATH 225.64 以来最高" was-# rejected because 225.64 (the June ATH) fell outside this session's observed-# OHLC range. The marker must be adjacent to the number, so a plain field-# reading such as "8/12 高 149.60" stays checked: its 高 carries no historical-# qualifier. "创历史新高" shares the 历史新高 marker and is masked with it; the-# relaxation follows the same trade-off as prospective levels — the historical-# extreme is a reference, not an assertion about the current bar.-_REFERENCE_LEVEL_RE = re.compile(- r"(?:"- r"\bATH\b|all[- ]?time\s+(?:high|low)|"- r"52\s*[- ]?W(?:EEK)?\s*(?:high|low)|52\s*[- ]?W(?:EEK)?\s*高(?:点|位)?|"- r"52\s*周(?:高|低)(?:点|位)?|"- r"历史(?:最高|最低|新高|新低|高|低)(?:点|位|价)?|"- r"上市以来(?:最高|最低)(?:点|位|价)?"- r")"- r"\s*(?:of|为|是|约|at)?\s*[::]?\s*\(?"- r"\s*" + _CURRENCY_TOKEN + r"\s*[-+]?\d[\d,]*(?:\.\d+)?" + _RANGE_TAIL,- re.IGNORECASE,-)-# A date-anchored reference puts the historical extreme after the number:-# "7/10(150.57)以来最高" and "highest since 7/10 (150.57)". The parenthesized-# value is the earlier high/low, not a current quote, and was rejected against-# the session's observed window (which does not reach back to July).-_SINCE_REFERENCE_RE = re.compile(- r"[-+]?\d[\d,]*(?:\.\d+)?\s*\)?\s*以来(?:最高|最低|高|低)(?:点|位)?"- # Dates are masked before this runs, so "since 7/10 (150.57)" has lost its- # date digits by the time the connector is matched.- r"|(?:highest|lowest)\s+since[^0-9\n]{0,16}"- r"[-+]?\d[\d,]*(?:\.\d+)?",- re.IGNORECASE,-)-# A validation report cites a plan file by line number — "~line 206",-# "第 206 行" — and the number is a document location, not a price. Before-# this mask, "**文档 ~line 206「…」不成立" contributed 206.0 as a candidate-# price claim and was rejected against the observed OHLC range.-_LINE_REFERENCE_RE = re.compile(- r"(?:~\s*)?\blines?\b\s*[:#]?\s*\d{1,5}(?:\s*[-–—至~]\s*\d{1,5})?"- r"|第\s*\d{1,5}(?:\s*[-–—至~]\s*\d{1,5})?\s*行"- r"|行\s*[::]?\s*\d{1,5}(?:\s*[-–—至~]\s*\d{1,5})?",- re.IGNORECASE,-)-# A numbered markdown heading ("### 6. 关键价位") names a section index, not-# a price. The ordered-list mask only covers line-leading "1." and stops at-# the "### " prefix, so the section number was extracted as a claim.-_NUMBERED_HEADING_RE = re.compile(r"(?m)^\s*#{1,6}\s*\d+(?:[.、.])?\s*")-# A ratio ("6:1 折算", "10:1") names a conversion basis, not a quote price.-_RATIO_RE = re.compile(r"\d+(?:\.\d+)?\s*[::]\s*\d+(?:\.\d+)?")-# A currency conversion cited inside a report ("USD/CAD≈1.36") is a basis, not-# an instrument quote. But `EUR/USD` IS this project's canonical forex symbol-# (``backtest/engines/forex.py``, and akshare_loader accepts the slash form), so-# masking every ``AAA/BBB <number>`` would stop checking real FX quotes on a-# first-class market — an invented rate would pass. The pair form therefore-# requires an approximation marker, which a conversion basis carries and a quote-# does not: "USD/CAD≈1.36" is masked, bare "USD/CAD 1.36" stays checked. The-# labelled 汇率 / "exchange rate" form is unambiguous and needs no marker.-_FX_RATE_RE = re.compile(- r"[A-Z]{3}\s*/\s*[A-Z]{3}\s*(?:≈|~|约)\s*\d+(?:\.\d+)?"- r"|(?:汇率|FX\s*rate|exchange\s+rate)\s*(?:≈|~|=|为|是)?\s*\d+(?:\.\d+)?",- re.IGNORECASE,-)-# A trading plan quotes levels it does not claim to have observed. In the-# committee report attached to #983, "收盘 ≥6.45 且量 ≥35M手" is an entry-# trigger, "年线 4.63 成目标区" is a target zone, and neither asserts anything-# about what the instrument traded at. Compared against observed OHLC evidence-# they were reported first as numeric_claim_unavailable (before the run fetched-# prices) and then as numeric_claim_conflict (after it did) — the same false-# positive under two codes.-#-# This is a real relaxation, so every branch is span-local and anchored to the-# token that makes the number prospective, never to a word elsewhere in the-# clause: "现价 5.97,目标位 6.45" masks 6.45 and still checks 5.97. An-# assertion carries no such token and stays checked.-#-# Branch (d) accepts a conditional opener. A number inside "若收盘 5.36" is a-# hypothesis, and a hypothesis does not misrepresent observed data the way a-# bare quote does — but it is the widest branch here, so it requires the opener-# to PRECEDE the number with no digits in between, which keeps it from reaching-# back over an assertion that was already made.-_PROSPECTIVE_LEVEL_RE = re.compile(- r"(?:"- # (a) comparison operator immediately before the number- r"(?:>=|<=|≥|≤|>|<|大于|小于|不低于|不高于|高于|低于)"- r"\s*" + _CURRENCY_TOKEN + r"\s*[-+]?\d[\d,]*(?:\.\d+)?" + _RANGE_TAIL- + r"|"- # (b) a level marker introducing the number- r"(?:目标位|目标区|目标价|均值目标(?:价)?|平均目标(?:价)?|止损位?|止盈位?|触发价|触发位|触发点|上看|下看|"- r"支撑(?:阶梯|位|线)?|阻力(?:位|线)?|压力位|压力线|support(?:\s+(?:level|line|zone))?|"- r"resistance(?:\s+(?:level|line|zone))?|target\s+(?:price|level|zone)|trigger|stop[-\s]?loss|take[-\s]?profit)"- r"\s*(?:为|是|至|到|on|at|of|=)?\s*[::]?\s*"- + _CURRENCY_TOKEN- + r"\s*[-+]?\d[\d,]*(?:\.\d+)?" + _RANGE_TAIL- + r"|"- # (c) the number followed by a level marker- r"" + _CURRENCY_TOKEN + r"[-+]?\d[\d,]*(?:\.\d+)?" + _RANGE_TAIL- + r"\s*(?:一线|附近)?\s*(?:成为?|作为|是)?\s*"- r"(?:目标区|目标位|止损位|止盈位)"- r"|"- # (d) a conditional opener before the number, digits fencing the reach- r"(?:若|如果|一旦|倘若|假如|\bif\b|\bwhen\b|\bshould\b)[^0-9\n]{0,12}"- r"[-+]?\d[\d,]*(?:\.\d+)?"- r")",- re.IGNORECASE,-)-# #1354: the closed structural rule for prose price claims. A number that-# follows a price-context word is an observed value only when nothing-# formula-like binds it instead. Two closed token classes decide that:-#-# * a formula marker sitting between the price word and the number — a-# comparison/division operator, or an indicator identifier followed by-# digits (SMA/EMA/…/VWAP + digits; MA for the Chinese MA20 convention) —-# turns the number into an operand of the formula, not a claimed value;-# * an observation binder after that marker ("was", "at", 报收/收于/收报/收在)-# re-attaches the number to the price word, so "close above SMA50 and was-# 2500" stays a claim while "close/SMA50 > 1" claims nothing.-#-# This replaces the per-phrasing denylist (a signal-value mask, an indicator--# connective mask, …) with one syntactic distinction; the catalogue of-# phrasings can never close, a closed marker set can.-_FORMULA_MARKER_RE = re.compile(- r"(?:>=|<=|≥|≤|>|<|/)"- r"|\b(?:SMA|EMA|WMA|DMA|MA|RSI|MACD|ATR|ADX|CCI|OBV|KDJ|BOLL|VWAP)\d+\b",- re.IGNORECASE | re.ASCII,-)-_OBSERVATION_BINDER_RE = re.compile(- r"\b(?:was|were|is|are|at)\b|(?:报收|收于|收报|收在)|==|=|≈",- re.IGNORECASE,-)-# The clause splitter does not split on the ASCII period, so "close was 210.-# In 2024 the market rallied" stays one clause and 2024 would be misread as-# the asserted price. A period/bang/question followed by whitespace and a-# sentence-start (capital, quote, or bracket) is a boundary here — but only-# in this price-claim scan, never in the global clause splitter, where it-# would tear apart "000543.SZ" and "1.5". The capital/open-bracket lookahead-# deliberately excludes abbreviations: "close approx. 2500" keeps 2500 gated.-_SENTENCE_BOUNDARY_RE = re.compile(r"[.!?]\s+(?=[A-Z((])")---# Full-width enumeration commas delimit prose clauses. Paired brackets (ASCII-# or full-width ()()[]) are deliberately not separators: an explicit-# derivation such as "(8.5 - 7.9) / 2" must stay in one segment for the-# formula check, and 公司名(代码)价格 must stay in one segment so the-# unsourced-symbol gate can see the symbol with its figure (#1260).-# The English sentence period is a clause separator too. Without it two-# English sentences sharing a line were ONE clause, so the header's "last-# close" labelled the whole line and a derivation in the first sentence-# exempted a fabricated price in the second: "Based on close 1.171 * 0.80 =-# 0.937. The last traded price is 0.937." validated, while the byte-identical-# text with a paragraph break between the sentences was rejected — and the-# Chinese translation was rejected either way, because 。 always split. A-# per-language split is a per-language verdict, which is exactly what-# ``test_grounding_language_parity`` exists to stop.-# The lookahead is what keeps a decimal point, a ticker suffix (562500.SS) and-# an abbreviation ("approx. 1.10") out: only a period followed by whitespace-# and the start of a new sentence separates.-_CLAUSE_SEPARATOR_RE = re.compile(- r"[,,;;。、\n]|[.!?](?=\s+[\"'(\[“‘]?[A-Z])"-)---# The ASCII comma both separates clauses and groups thousands, and the clause-# split ran first: "收盘价 ¥1,309.22" became a clause ending in "¥1", whose 1 was-# compared against the observed 1300.01–1363.35 range and rejected as a-# conflict. That is every price above 999 written the ordinary way, and it is-# self-contradictory — ``_NUMBER_RE`` and the float conversion below it both-# already understand grouped numbers. Only a real group is removed: a comma-# needs a digit before it and exactly three digits after.-_THOUSANDS_SEPARATOR_RE = re.compile(r"(?<=\d),(?=\d{3}(?!\d))")---def _matches_any(raw: Any, values: Sequence[float], *, rel: float = 0.005) -> bool:- """Whether a measurement-shaped figure equals one of ``values``.-- Args:- raw: A figure as ``_measure_numbers`` returns it ("1.136", "5.26%").- values: Numeric values to match against.- rel: Relative tolerance, absolute floor 1e-9.-- Returns:- True when the parsed figure matches any value.- """- try:- number = float(str(raw).strip().rstrip("%%").replace(",", ""))- except ValueError:- return False- return any(abs(number - value) <= max(abs(value) * rel, 1e-9) for value in values)---def _format_price(value: float) -> str:- """Render an observed price without scientific notation or lost digits.-- ``%g`` switches to scientific notation past six significant digits, so an- index level printed in the release footnote read "1.23457e+06".- """- return format(value, ".10g")---def _redaction_targets(values: Sequence[Any]) -> tuple[bool, list[float], list[str]]:- """Split issue values into cut-everything / numeric / percent-literal cuts.-- Args:- values: The ``value`` field of each issue flagged on one clause.-- Returns:- ``(cut_all, numeric targets, percent literals)``. ``cut_all`` is set by- a ``None`` value, which is how ``unsourced_symbol_figures`` says "every- figure in this clause belongs to an instrument no tool handled".- """- cut_all = False- targets: list[float] = []- literals: list[str] = []- for value in values:- if value is None:- cut_all = True- elif isinstance(value, bool):- continue- elif isinstance(value, (int, float)):- targets.append(float(value))- elif isinstance(value, str) and value.strip():- literal = value.strip().replace(" ", "").replace(",", "")- if literal.endswith(("%", "%")):- literals.append(literal)- else:- try:- targets.append(float(literal))- except ValueError:- continue- return cut_all, targets, literals---_RELEASE_NOTE_LINE_RE = re.compile(r"^[^\S\n]*※[^\n]*\n?", re.MULTILINE)---def _strip_release_markers(content: str) -> str:- """Remove any redaction marker or release note the MODEL wrote.-- The marker and the footnote are the gate's own statements about what it- cut. A draft carrying "※ 略去 0 处……" of its own shipped both notes, one- contradicting the other, and a "(略※)" pasted into the body read as a- redaction that never happened.-- Args:- content: The rejected draft.-- Returns:- The draft with every marker and note-shaped line removed.- """- stripped = content.replace(_REDACTION_MARKER_ZH, "").replace(- _REDACTION_MARKER_EN, ""- )- return _RELEASE_NOTE_LINE_RE.sub("", stripped)---def _figure_reads_as_a_price(text: str, figure: str) -> bool:- """Whether ``figure`` is written as a price somewhere in ``text``.-- A price word ahead of it in the clause, a currency symbol in front of it,- or a currency/unit token glued behind it. Any one of the three is the- ordinary way an answer quotes a price, and none of them is how a metric- figure is written.-- Args:- text: The clause or cell the figure appears in.- figure: The figure exactly as it was written.-- Returns:- True when at least one occurrence reads as a price.- """- for match in re.finditer(re.escape(figure), text):- if _UNIT_TOKEN_AFTER_RE.match(text, match.end()):- return True- if _CURRENCY_BEFORE_RE.search(text[: match.start()]):- return True- if _PRICE_CONTEXT_RE.search(text[: match.start()]):- return True- return False---def _labels_its_result_observed(text: str, formula_start: int) -> bool:- """Whether a market-print word to the left CLAIMS the formula's result.-- The distinguisher is a result separator between the price word and the- formula's first operand. "收盘价 = 1.171 × 0.80" reads "the close IS this- expression" — the equation's subject is an observation, so its result is- a fabricated print. "基于收盘价 1.171 × 0.97 = 1.136" reads "starting from- the observed close" — the word labels an OPERAND, and the result is the- entry price the answer proposes, which is the shape the correction prompt- asks the model to write.-- Args:- text: The clause the formula was found in.- formula_start: Where the formula's arithmetic run starts in it.-- Returns:- True when the formula's result is claimed to be an observed print.- """- last: re.Match[str] | None = None- for match in _OBSERVED_PRICE_WORD_RE.finditer(text[:formula_start]):- last = match- if last is None:- return False- return bool(_RESULT_SEPARATOR_RE.search(text[last.end() : formula_start]))---def _clause_spans(text: str, offset: int = 0) -> list[tuple[str, int, int]]:- """Split prose into clauses, keeping each clause's span in the source text.-- A grouping comma is not a separator and is stripped from the returned- segment text, but the span is into the ORIGINAL, un-stripped text. The- redaction path needs that: it used to locate a flagged clause with- ``text.find(claim)`` on the normalised string, which never matched once a- price carried a thousands separator ("1,450.50"), and which matched inside- an unrelated longer number when the claim was a bare table cell ("1.10"- found inside "21.10").-- Args:- text: One line of candidate answer text.- offset: Where ``text`` starts inside the document being validated.-- Returns:- ``(segment, start, end)`` per clause, with ``start``/``end`` measured- in the document (``offset`` already added).- """- bounds: list[tuple[int, int]] = []- cursor = 0- for match in _CLAUSE_SEPARATOR_RE.finditer(text):- if match.group(0) == "," and _THOUSANDS_SEPARATOR_RE.match(text, match.start()):- continue- bounds.append((cursor, match.start()))- cursor = match.end()- bounds.append((cursor, len(text)))- return [- (_THOUSANDS_SEPARATOR_RE.sub("", text[start:end]), start + offset, end + offset)- for start, end in bounds- ]---def _lines_with_offsets(content: str) -> list[tuple[str, int]]:- """Return each line of ``content`` with its character offset in it.-- ``str.splitlines`` discards the terminators, so an issue raised on a line- cannot say where in the document that line sits. Offsets are recovered by- scanning forward, which is exact because only line terminators separate- one line's end from the next line's start.- """- positions: list[tuple[str, int]] = []- cursor = 0- for line in content.splitlines():- start = content.find(line, cursor) if line else cursor- if start < 0:- start = cursor- positions.append((line, start))- cursor = start + len(line)- return positions---_TABLE_SEPARATOR_RE = re.compile(r"^:?-{3,}:?$")--_TABLE_FIELD_ALIASES = {- "open": "open",- "opening": "open",- "opening price": "open",- "开盘": "open",- "开盘价": "open",- "high": "high",- "highest": "high",- "最高": "high",- "最高价": "high",- "low": "low",- "lowest": "low",- "最低": "low",- "最低价": "low",- "close": "close",- "closing": "close",- "closing price": "close",- "收盘": "close",- "收盘价": "close",-}-_DATE_HEADERS = {"date", "datetime", "trade date", "timestamp", "日期", "交易日", "时间"}--# A price word that asserts the figure is a MARKET PRINT — an OHLC field or a-# spot quote. Such a figure is an observation, and an observation is never-# something a formula produces: "2026-06-23 收盘价 = 1.171 × 0.80 = 0.937"-# is arithmetic whose result is claimed to be a close the ledger holds as-# 1.137, and the bare-equation derivation exemption released it. Only the-# formula's OPERANDS stay exempt under such a label; see-# ``_labels_its_result_observed``.-#-# The OHLC half is DERIVED from ``_TABLE_FIELD_ALIASES``, which is the table-# path's own source of truth and already carries both scripts — the previous-# hand-written prose list held "closing price" but not "closed at", and-# "收盘价" but not "收盘为". The four bare English words are dropped: "open" is-# a verb, "high"/"low" are adjectives, and "close" only counts when it is not-# "close to". The spot half has no table equivalent and is written out.-_OHLC_PROSE_WORDS = sorted(- (alias for alias in _TABLE_FIELD_ALIASES if alias not in {"open", "high", "low", "close"}),- key=len,- reverse=True,-)-_OBSERVED_PRICE_WORD_RE = re.compile(- "(?:"- # ASCII aliases take word boundaries so "closing" does not match inside- # "disclosing"; the CJK ones are written without spaces and must not.- + "|".join(- (r"\b" + re.escape(word) + r"\b") if word.isascii() else re.escape(word)- for word in _OHLC_PROSE_WORDS- )- + r"|\b(?:closed|opened|settled|fixed|traded|quoted|last[- ]traded|changed hands)\s+at\b"- + r"|\bthe\s+(?:close|open|high|low)\s+(?:was|is)\b"- + r"|\b(?:last|previous|prior|session|intraday|day's|today's)\s+(?:close|open|high|low)\b"- + r"|\bclose\b(?!\s+to\b)"- + r"|\b(?:current|latest|market|spot|share|last(?: traded)?)\s+price\b"- + r"|\bthe\s+quote\b|\btrad(?:es|ing)\s+at\b|\bchanges?\s+hands\s+at\b"- + r"|收盘于|收盘为|收报|报收|收于|现价|最新价|最新成交价|成交价|市价|报价|现报|股价"- + ")",- re.IGNORECASE,-)--# A loader's id is ASCII, but the answer follows the user's language, so a-# Chinese report names the same provider in Chinese. Demanding the ASCII id-# verbatim rejected correct prose: an answer reading "数据来源:腾讯财经" was-# reported as ``data_source_not_surfaced`` against evidence sourced from-# ``tencent``, and no rewrite short of writing the English word could pass.-_SOURCE_ALIASES = {- "akshare": ("akshare", "ak share"),- "baostock": ("baostock",),- "binance": ("binance", "币安"),- "ccxt": ("ccxt",),- "eastmoney": ("eastmoney", "东方财富", "东财"),- "futu": ("futu", "富途"),- "mootdx": ("mootdx", "通达信"),- "okx": ("okx", "欧易"),- "pykrx": ("pykrx", "krx"),- "sina": ("sina", "新浪"),- "stooq": ("stooq",),- "tencent": ("tencent", "腾讯"),- "tushare": ("tushare",),- "yahoo": ("yahoo", "雅虎"),- "yfinance": ("yfinance", "yahoo", "雅虎"),-}-# "元" is how a Chinese answer writes a CNY quote, but it is also the tail of-# 港元/美元/日元, so accepting it unguarded would let an answer about a Hong Kong-# listing satisfy a CNY requirement. It counts only when no other currency's-# character owns it.-_BARE_YUAN_RE = re.compile(r"(?<![港美日欧韩台新加澳])元")-_CURRENCY_ALIASES = {- "USD": ("usd", "us$", "美元", "美金"),- # ¥ is how a model actually writes a CNY quote. It is the yen sign too, but- # ``_infer_currency`` maps no venue to JPY, so nothing in this system can- # mean yen by it; adding a JPY venue means revisiting this entry.- "CNY": ("cny", "cnh", "rmb", "人民币", "¥", "¥"),- "HKD": ("hkd", "hk$", "港元", "港币"),- "KRW": ("krw", "韩元", "韩圜"),- "INR": ("inr", "印度卢比", "卢比"),- "CAD": ("cad", "c$", "加元", "加拿大元"),-}-_SYMBOL_HEADERS = {"symbol", "ticker", "code", "标的", "代码", "证券代码"}---def _utc_now() -> str:- """Return an audit-friendly UTC timestamp."""- return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")---# Provider spellings that denote one instrument. Shanghai is quoted as ``.SH``-# by Eastmoney and ``.SS`` by Yahoo, A-share tools also accept an exchange-# prefix (``sh600519``), Hong Kong codes are zero-padded to five digits, and-# ccxt writes a crypto pair with a slash. Every one of these is a spelling, not-# an identity: ``_infer_venue`` and ``_infer_currency`` below already map ``.SS``-# and ``.SH`` to the same venue and the same currency. Treating them as-# different identities made ``search_symbol("600519")`` return two candidates-# for one listing, which no tie-break could resolve, so every Shanghai listing-# resolved ``ambiguous`` and no market tool could run for the rest of the run.-_EXCHANGE_PREFIXED_RE = re.compile(r"^(SH|SZ|BJ)(\d{6})$")-# The dotted form of the same idea, as the Futu connector spells it-# (``HK.00700`` / ``US.AAPL``). ``SS`` is Yahoo's Shanghai alias and folds-# onto ``SH`` exactly as the suffix spelling does.-_VENUE_PREFIXES = frozenset({"HK", "SH", "SZ", "BJ", "SS", "US"})-_US_TICKER_RE = re.compile(r"[A-Z][A-Z0-9&-]{0,19}")---def _normalize_symbol(value: Any) -> str:- """Normalize a symbol onto one canonical identity for exact comparison.-- Args:- value: Any provider- or model-supplied symbol spelling.-- Returns:- The canonical spelling — uppercased, with Shanghai's ``.SS`` alias- folded onto ``.SH``, an exchange prefix rewritten as a suffix, a Hong- Kong code zero-padded, and a crypto pair hyphenated. A joined crypto- pair with no separator (``BTCUSDT``) is rewritten as the dashed form- (``BTC-USDT``) so every downstream check sees one identity. Text that- is not a symbol is returned uppercased and otherwise untouched.- """- # A fiat/fiat pair is one FX instrument regardless of spelling: ``GBP/USD``- # and ``GBPUSD`` are both ``GBPUSD=X``. Checked BEFORE the slash is- # rewritten ("GBP/USD" -> "GBP-USD", the crypto-pair spelling), which- # disagreed with the resolver's ``GBPUSD=X`` answer — a contradictory- # identity that outranked every later lock and blocked all further tools.- raw = str(value or "").strip().upper()- fx = canonical_fx_pair(raw)- if fx is not None:- return fx- symbol = raw.replace("/", "-")- if not symbol:- return ""-- prefixed = _EXCHANGE_PREFIXED_RE.match(symbol)- if prefixed:- return f"{prefixed.group(2)}.{prefixed.group(1)}"- base, dot, suffix = symbol.rpartition(".")- if not dot:- # No separator at all: rewrite a joined crypto pair (``BTCUSDT``)- # as the dashed form so the dash/slash branch and the canonical- # regex both match. The base must be all-alpha so a numeric prefix- # cannot collide with another numeric-code branch downstream.- joined = _JOINED_CRYPTO_RE.fullmatch(symbol)- if joined and not _METAL_USD_PAIR_RE.fullmatch(symbol):- for quote in _JOINED_CRYPTO_QUOTE_SUFFIXES:- if symbol.endswith(quote) and len(symbol) > len(quote):- base_part = symbol[: -len(quote)]- if base_part.isalpha():- return f"{base_part}-{quote}"- return symbol- # Venue-prefixed listing (Futu connector format: HK.06693 / SH.600519 /- # SZ.000001 / US.AAPL): rewrite to the canonical suffix spelling so- # identity matching agrees with the market-data chain (06693.HK) that- # get_market_data uses. Shanghai's .SS alias is folded onto .SH here too,- # the same way the suffix branch below does it.- if base in _VENUE_PREFIXES and suffix:- venue = "SH" if base == "SS" else base- if venue == "US":- if _US_TICKER_RE.fullmatch(suffix):- return f"{suffix}.US"- elif suffix.isdigit():- digits = suffix.zfill(5) if venue == "HK" else suffix- return f"{digits}.{venue}"- if suffix == "SS":- suffix = "SH"- if suffix == "HK" and base.isdigit():- base = base.zfill(5)- return f"{base}.{suffix}"---def _symbol_from_csv_filename(stem: str) -> str | None:- """Map a run-dir CSV stem back to a canonical project symbol.-- The bash workaround writes filesystem-safe stems: ``BYN_V.csv`` -> ``BYN.V``,- ``PDI_TO.csv`` -> ``PDI.TO``, ``GC_F.csv`` -> ``GC=F``, ``INTC_US.csv`` ->- ``INTC.US``. A stem without a recognized suffix (e.g. a bare US name- ``AAPL``) maps to None because the project convention requires an explicit- venue suffix.-- Args:- stem: CSV filename without the ``.csv`` extension.-- Returns:- The canonical symbol, or ``None`` when the stem has no recognizable- venue suffix.- """- upper = (stem or "").strip().upper()- if not upper:- return None- for raw, canonical in _CSV_FILENAME_SUFFIX_MAP:- if upper.endswith(raw) and len(upper) > len(raw):- return upper[: -len(raw)] + canonical- return None---def _query_key(value: Any) -> str:- """Normalize resolver queries into stable state-machine keys."""- return " ".join(str(value or "").casefold().split())---def _json_object(value: Any) -> dict[str, Any] | None:- """Parse a JSON object from a tool result when possible."""- if isinstance(value, dict):- return value- if not isinstance(value, str):- return None- try:- parsed = json.loads(value)- except (json.JSONDecodeError, TypeError):- return None- return parsed if isinstance(parsed, dict) else None---def _is_number(value: Any) -> bool:- """Return whether a value is a finite JSON-style number, excluding bool."""- return (- isinstance(value, (int, float))- and not isinstance(value, bool)- and math.isfinite(float(value))- )---def _coerce_csv_number(value: Any) -> int | float | None:- """Coerce a CSV cell to a finite number, or return None.-- CSV readers return every cell as text (``"0.375"``), so a bare- ``_is_number`` check would discard them all. Values that do not parse as a- finite number (blank cells, ``-``, ``N/A``) return ``None``.- """- if _is_number(value):- return value- if isinstance(value, str):- try:- parsed = float(value.strip().replace(",", ""))- except (TypeError, ValueError):- return None- if math.isfinite(parsed):- return parsed- return None---# "." is deliberately not a separator: a decimal price such as 8.5 would parse-# as month 8 day 5 and match a real trading day.-# A report writes the day as a table cell -- "08-10(一)", "08-10(周一)盘中",-# "08-10盘中" -- and the weekday or session suffix made the cell match no-# evidence row at all, so every price in that row came back-# "numeric_claim_unavailable" even though the run had fetched the bar.-_TRADING_DAY_SUFFIX = (- r"(?:\s*[((]\s*(?:周|星期)?[一二三四五六日天]\s*[))])?"- r"\s*(?:盘中|盘后|盘前|收盘|开盘|早盘|尾盘)?"-)-_YEARLESS_CLAIM_DATE_RE = re.compile(- r"^(0?[1-9]|1[0-2])\s*[-/月]\s*(0?[1-9]|[12]\d|3[01])\s*[日号]?"- + _TRADING_DAY_SUFFIX- + r"$"-)-# Two-digit day alternatives are tried before a bare digit so an-# unanchored prefix match consumes the full day ("10" of "08-10(一)")-# instead of stopping at "1".-_ISO_CLAIM_DATE_PREFIX_RE = re.compile(- r"^\s*((?:19|20)\d{2})\s*[-/]\s*(0?[1-9]|1[0-2])\s*[-/]\s*([12]\d|3[01]|0?[1-9])"-)-_YEARLESS_CLAIM_DATE_PREFIX_RE = re.compile(- r"^\s*(0?[1-9]|1[0-2])\s*[-/月]\s*([12]\d|3[01]|0?[1-9])"-)-_ISO_TIMESTAMP_RE = re.compile(r"^(\d{4})-(\d{1,2})-(\d{1,2})")---def _claim_date_tuple(date_value: str) -> tuple[int, int] | None:- """Extract the (month, day) named by a report-style date cell.-- Reports routinely annotate a trading day: the date column reads- ``08-10(一)``, ``08-10(周一)盘中`` or ``08-10盘中`` rather than the bare- ``08-10`` the strict full-cell matchers accept. Any leading month-day (or- full ISO date) prefix is therefore accepted so such a claim still compares- against the matching evidence row instead of being reported as- unevidenced.-- Args:- date_value: Date cell as written in the answer.-- Returns:- The (month, day) tuple, or None when no date prefix is present.- """- claim = (date_value or "").strip()- match = _YEARLESS_CLAIM_DATE_RE.match(claim)- if match:- return (int(match.group(1)), int(match.group(2)))- match = _ISO_CLAIM_DATE_PREFIX_RE.match(claim)- if match:- return (int(match.group(2)), int(match.group(3)))- match = _YEARLESS_CLAIM_DATE_PREFIX_RE.match(claim)- if match:- return (int(match.group(1)), int(match.group(2)))- return None---def _timestamp_matches_claim_date(timestamp: str, date_value: str) -> bool:- """Match an evidence timestamp against the date cell of a claim.-- The comparison used to be ``timestamp.startswith(date_value)``, which can- only succeed when the answer repeats the year. A table whose date column- reads ``08-05`` — the ordinary way a report writes a trading day — matched- nothing, so every cell in the row was reported as having no supporting- evidence while that evidence sat right there (#983: 79 such rejections in- one run, every value inside the observed range).-- A year-less date is matched on month and day, and a date cell may carry- weekday or intraday annotations (``08-10(一)``, ``08-10盘中``) whose- leading month-day is still recognized. Matching the wrong year is a- smaller failure than matching nothing, but it is a real one, so the- caller still compares the value against every record that matched rather- than trusting the date.-- Args:- timestamp: Evidence timestamp, normally ISO ``YYYY-MM-DD``.- date_value: Date cell as written in the answer.-- Returns:- True when the timestamp denotes the day the claim names.- """- stamp = (timestamp or "").strip()- claim = (date_value or "").strip()- if not stamp or not claim:- return False- if stamp.startswith(claim):- return True- claim_tuple = _claim_date_tuple(claim)- iso = _ISO_TIMESTAMP_RE.match(stamp)- if claim_tuple is None or not iso:- return False- return (int(iso.group(2)), int(iso.group(3))) == claim_tuple---def _price_field_for_path(path: str) -> str | None:- """Map a generic evidence JSON path to a canonical price field.-- Args:- path: Recorded evidence field, e.g. ``"data.quote[0].last_price"``.-- Returns:- The matching member of ``_PRICE_FIELDS``, or ``None`` when the leaf is- not an unambiguous quote field.- """- leaf = str(path or "").rsplit(".", 1)[-1]- leaf = re.sub(r"\[\d+\]$", "", leaf).strip().casefold()- return _GENERIC_PRICE_FIELD_ALIASES.get(leaf)---# A price-denominated indicator the session fetched is observed evidence in-# the same sense an OHLC bar is: ``indicators.sma_20: 0.7158`` came out of-# ``technical_indicators`` for this symbol, and an answer that writes "MA20-# 0.7158" or derives an entry from it is quoting a tool, not inventing a-# number. Before this, the value was compared against OHLC bars only and-# rejected as a fabricated price (deriv2 probe, 2026-09-09). The family list is-# closed and price-denominated on purpose — a moving average, band, pivot,-# support/resistance level, VWAP or ATR is in the instrument's currency; RSI,-# MACD, volume, counts and row totals are not. Letting a quote match-# ``rows: 54`` or a volume average would gut the fabrication check, so any-# non-price token anywhere in the path disqualifies the leaf.-_PRICE_INDICATOR_TOKENS = frozenset(- {- "sma", "ema", "wma", "dma", "dema", "tema", "hma", "kama", "ma", "vwap", "vwma",- "bb", "bbands", "boll", "bollinger", "band", "bands", "keltner", "kc", "donchian",- "pivot", "pp", "support", "resistance",- "atr", "psar", "sar", "supertrend", "ichimoku", "tenkan", "kijun", "senkou",- "chikou", "highest", "lowest",- }-)-# Generic band leaves. "lower" is a price only under a band family, so these-# need a family token elsewhere in the path: ``bollinger.lower`` qualifies,-# a bare ``summary.lower`` does not.-_PRICE_BAND_LEAVES = frozenset({"upper", "lower", "middle", "mid", "top", "bottom", "basis"})-# Standard pivot-level spellings. They are matched before the trailing digits-# are stripped: ``r1`` would otherwise become ``r``, which is in no set, and-# the six literals ``r1 r2 r3 s1 s2 s3`` sat in the family list unreachable.-_PIVOT_LEVEL_RE = re.compile(r"^[rs][123]$")-_NON_PRICE_TOKENS = frozenset(- {- "volume", "vol", "turnover", "amount", "count", "rows", "returned", "signal",- "histogram", "rsi", "kdj", "k", "d", "j", "cci", "adx", "obv", "mfi", "roc",- "williams", "wr", "stoch", "pct", "percent", "ratio", "change", "chg", "width",- "position", "score", "z", "zscore", "slope", "angle", "days", "bars",- # Parameters and derived shapes, not levels: ``params.ma_period: 20``- # and ``entry_condition.ma_window: 20`` are settings, ``ma_diff`` and- # ``sma_cross`` are differences and booleans. The leaf test below- # already rejects those three, but a path that also carries a family- # token in another segment must not be readmitted by it.- "window", "period", "length", "span", "lookback", "n", "cross", "flag",- }-)---def _is_price_denominated_indicator(path: str) -> bool:- """Return whether a generic evidence path is a price-denominated indicator.-- The decision is made on the LEAF — the last dotted segment, with a- trailing index stripped — not on "some token anywhere in the path". Under- the old any-token rule ``indicators.ma_diff``, ``indicators.sma_cross``- and ``indicators.supertrend_direction`` were all admitted as observed- prices because they carry ``ma`` / ``sma`` / ``supertrend`` somewhere,- and a payload with any of them set to 1.30 let the answer print- "现价 1.30 元" (attack6 probe, 2026-09-09). A difference, a crossover- flag and a direction are not prices.-- Args:- path: Recorded evidence field, e.g. ``"indicators.bollinger.lower"``.-- Returns:- True when the leaf names a price-denominated indicator level and no- path token names a non-price quantity.- """- text = str(path or "")- tokens = [- re.sub(r"\d+$", "", token).casefold()- for token in re.split(r"[._\[\]\-\s]+", text)- if token- ]- tokens = [token for token in tokens if token]- if not tokens:- return False- if any(token in _NON_PRICE_TOKENS for token in tokens):- return False- segments = [segment for segment in re.split(r"[.\[\]]+", text) if segment]- if not segments:- return False- leaf = segments[-1].strip().casefold()- if _PIVOT_LEVEL_RE.match(leaf):- return True- leaf = re.sub(r"[_\-]?\d+$", "", leaf) or leaf- if leaf in _PRICE_INDICATOR_TOKENS:- return True- return leaf in _PRICE_BAND_LEAVES and any(- token in _PRICE_INDICATOR_TOKENS for token in tokens- )---def _metric_kind_for_path(path: str) -> str | None:- """Map an evidence JSON path to an analysis metric kind."""- leaf = re.sub(r"\[\d+\]$", "", str(path or "").rsplit(".", 1)[-1])- leaf = leaf.strip().casefold()- kind = _ANALYSIS_KIND_ALIASES.get(leaf)- if kind is not None:- return kind- # Compound leaves name the kind as a token ("reported_annualized_return",- # "strategy_max_drawdown"). #1338 review: matching only the verbatim alias- # table makes every other spelling silently ungroundable. Scan from the- # right — English compounds put the head noun last, so "return_vol"- # resolves to vol, never to return.- tokens = [token for token in re.split(r"[_.]", leaf) if token]- for size in (2, 1):- for start in range(len(tokens) - size, -1, -1):- kind = _ANALYSIS_KIND_ALIASES.get("_".join(tokens[start : start + size]))- if kind is not None:- return kind- return _metric_kind_for_text(path)---def _metric_kind_for_text(text: str) -> str | None:- """Return the analysis metric kind named in a claim or header."""- for pattern, kind in _ANALYSIS_KIND_PATTERNS:- if pattern.search(text):- return kind- return None---def _scan_symbols(text: str) -> set[str]:- """Return the canonical symbols written anywhere in a blob of text."""- return {- _normalize_symbol(match.group(0))- for match in _CANONICAL_SYMBOL_RE.finditer(text or "")- }---def _infer_venue(symbol: str) -> str | None:- """Infer a coarse venue from a project symbol."""- upper = _normalize_symbol(symbol)- suffixes = {- ".US": "us",- ".SH": "shanghai",- ".SZ": "shenzhen",- ".BJ": "beijing",- ".HK": "hong_kong",- ".KS": "kospi",- ".KQ": "kosdaq",- ".NS": "nse",- ".BO": "bse",- ".FX": "forex",- ".TO": "toronto",- ".V": "tsx_venture",- }- for suffix, venue in suffixes.items():- if upper.endswith(suffix):- return venue- # Yahoo's continuous-front-month futures notation (GC=F, CL=F, SI=F, ...).- # The exchange category is the venue class. The engine and the- # correlation helper mirror this pattern; this is the third copy.- if upper.endswith("=F"):- return "futures"- # Yahoo's forex notation (XAUUSD=X, EURUSD=X) is FX.- if re.match(r"^[A-Z]{6}=X$", upper):- return "forex"- # Bare 6-character precious-metal / FX symbols. The whitelist is- # ISO 4217 metals + G10 currencies; it intentionally does NOT include- # any US-equity prefix. Mirroring the engine ``_MARKET_PATTERNS``.- if re.match(- r"^(?:XAU|XAG|XPT|XPD|EUR|GBP|JPY|CHF|CAD|AUD|NZD|USD)[A-Z]{3}$",- upper,- ):- return "forex"- # Dashed / slashed symbols are NOT categorically crypto: a USD quote is- # crypto only on a whitelisted base (``_CRYPTO_USD_BASES``), so- # ``XAU-USD`` / ``EUR-USD`` / ``GBP-USD`` are forex. Without this guard a- # spot-gold pair surfaced as a crypto-or-fx hybrid in the runtime- # registry, contradicting the engine classifier that already routes it to- # ``forex`` (#1280).- if "-" in upper or "/" in upper:- base, _, quote = (- upper.partition("-") if "-" in upper else upper.partition("/")- )- if quote in _CRYPTO_QUOTE_ASSETS:- return "crypto_or_fx"- if quote == "USD" and base in _CRYPTO_USD_BASES:- return "crypto_or_fx"- # Any other dashed / slashed pair is forex-shaped (e.g. ``XAU-USD``,- # ``EUR-USD``, ``GBP-USD``); the per-pair engine classifier decides- # ``forex`` vs ``crypto`` vs ``futures`` downstream.- return "forex"- return None---def _infer_currency(symbol: str) -> str | None:- """Infer quote currency without performing an implicit conversion."""- upper = _normalize_symbol(symbol)- suffixes = {- ".US": "USD",- ".SH": "CNY",- ".SZ": "CNY",- ".BJ": "CNY",- ".HK": "HKD",- ".KS": "KRW",- ".KQ": "KRW",- ".NS": "INR",- ".BO": "INR",- ".TO": "CAD",- ".V": "CAD",- }- for suffix, currency in suffixes.items():- if upper.endswith(suffix):- return currency- for separator in ("-", "/"):- if separator in upper:- quote = upper.rsplit(separator, 1)[-1]- if 3 <= len(quote) <= 5:- return quote- if upper.endswith("=X"):- pair = upper[:-2]- if len(pair) == 6:- return pair[3:6]- return None---def _infer_instrument_type(symbol: str, candidate_type: Any = None) -> str:- """Normalize provider types into the identity contract."""- raw = str(candidate_type or "").strip().casefold()- if "fund" in raw or "etf" in raw or "trust" in raw:- return "fund"- if "crypto" in raw:- return "crypto"- if "future" in raw:- return "future"- if "option" in raw:- return "option"- if "forex" in raw or raw == "currency":- return "forex"- if "index" in raw:- return "index"- upper = _normalize_symbol(symbol)- if upper.endswith("=F"):- return "future"- if upper.endswith(".FX"):- return "forex"- # Yahoo's continuous-front-month futures notation (GC=F, CL=F, ...).- # Mirrors the engine ``_MARKET_PATTERNS`` and the correlation helper.- if re.match(r"^[A-Z]{2,5}=F$", upper):- return "future"- # Yahoo's forex notation (XAUUSD=X, EURUSD=X).- if re.match(r"^[A-Z]{6}=X$", upper):- return "forex"- # Bare 6-character precious-metal / FX symbols (whitelist).- if re.match(- r"^(?:XAU|XAG|XPT|XPD|EUR|GBP|JPY|CHF|CAD|AUD|NZD|USD)[A-Z]{3}$",- upper,- ):- return "forex"- # Dashed / slashed symbols: crypto only when the quote leg is a- # stablecoin OR the base is in the USD-whitelist. The whitelist- # mirrors ``_canonical_crypto_pair`` in- # ``src.tools.symbol_search_tool``. ``XAU-USD`` / ``EUR-USD`` /- # ``GBP-USD`` are NOT crypto and resolve as ``forex`` (the per-pair- # engine classifier decides the final market downstream).- if "-" in upper or "/" in upper:- base, _, quote = (- upper.partition("-") if "-" in upper else upper.partition("/")- )- if quote in _CRYPTO_QUOTE_ASSETS:- return "crypto"- if quote == "USD" and base in _CRYPTO_USD_BASES:- return "crypto"- return "forex"- if upper.startswith("^"):- return "index"- return "listed_security"---@dataclass(frozen=True)-class IdentityRecord:- """One versioned entity-to-instrument resolution result."""-- query: str- status: str- symbol: str | None = None- venue: str | None = None- instrument_type: str | None = None- currency: str | None = None- source_tool_call_id: str | None = None- source: list[str] = field(default_factory=list)- candidates: list[dict[str, Any]] = field(default_factory=list)- resolution_constraints: list[dict[str, Any]] = field(default_factory=list)- version: int = 1- updated_at: str = field(default_factory=_utc_now)---@dataclass(frozen=True)-class EvidenceRecord:- """One observed, unavailable, or derived numeric evidence item."""-- call_id: str- tool: str- symbol: str | None- source: str- timestamp: str | None- field: str- value: int | float | None- status: str- currency: str | None = None- venue: str | None = None- currency_conversion: str | None = None---@dataclass(frozen=True)-class ToolAuthorization:- """Deterministic decision made before a tool starts."""-- allowed: bool- error_code: str | None = None- message: str | None = None- symbols: tuple[str, ...] = ()-- def error_payload(self, tool_name: str, identity: Mapping[str, Any]) -> str:- """Render a blocked tool call as a normal structured error result."""- return json.dumps(- {- "status": "error",- "error_code": self.error_code or "identity_gate_blocked",- "tool": tool_name,- "message": self.message or "Tool call blocked by identity gate",- "symbols": list(self.symbols),- "identity": dict(identity),- "required_action": (- "Call search_symbol in a separate assistant tool turn, wait for "- "its result, then reuse the exact locked symbol and venue. If the "- "resolver answers with a shortlist rather than one instrument, "- "show the candidates and ask the user which one to use — narrowing "- "the query again will not turn a genuine dual listing into one."- ),- },- ensure_ascii=False,- )---@dataclass(frozen=True)-class ValidationResult:- """Final-answer grounding decision."""-- valid: bool- issues: list[dict[str, Any]] = field(default_factory=list)---class GroundingLedger:- """Run-scoped identity state machine and evidence ledger."""-- def __init__(- self,- *,- run_dir: Path,- user_message: str,- history: Sequence[Mapping[str, Any]] | None = None,- contextual_identity_constraints: bool = True,- ) -> None:- """Create a ledger and seed only authoritative prior identities.-- Args:- run_dir: Active run directory.- user_message: Current user request.- history: Optional prior message history. It remains available to- the model. Only explicit constraints whose clause names the- current resolver subject may carry forward; stale global- instructions cannot authorize a new subject.- contextual_identity_constraints: Whether explicit market words in- the original conversation may narrow resolver candidates.- """- self.run_dir = Path(run_dir)- self.user_message = user_message- self.resolution_context = ResolutionContext.from_messages(- user_message,- history,- enabled=contextual_identity_constraints,- )- self._identities: dict[str, IdentityRecord] = {}- self._evidence: list[EvidenceRecord] = []- self._tool_failures: list[dict[str, Any]] = []- self._analysis_completed: list[dict[str, Any]] = []- self._analysis_metrics: list[dict[str, Any]] = []- self._validations: list[dict[str, Any]] = []- # The one document that actually shipped through the release path, if- # any. Not a draft, so it stays out of ``validation_count``.- self._released: dict[str, Any] | None = None- self._recovery_rounds = 0- self._symbol_resolution_attempts = 0- self._price_evidence_attempts = 0- self._ingested_csvs: set[str] = set()- self._identity_required = bool(_ACTIONABLE_MARKET_RE.search(user_message))- self._buffer_output = self._identity_required- # Every instrument this run is entitled to write about: the ones the- # user named, plus the ones a succeeding tool call passed in or returned.- self._session_symbols: set[str] = _scan_symbols(user_message)- # Bare tickers a succeeding call passed in, e.g. "AAPL" for the nine- # tools whose contract is a bare US ticker. "AAPL.US" in the answer then- # names an instrument the run really handled.- self._session_symbol_roots: set[str] = set()-- self._seed_symbols(user_message, source="user_message")- self.persist()-- @property- def authorized_symbols(self) -> set[str]:- """Return exact symbols locked before the next tool batch."""- return {- record.symbol- for record in self._identities.values()- if record.status == "locked" and record.symbol- }-- @property- def identity_status(self) -> str:- """Return the aggregate first-class identity state.-- ``conflicting`` is the only state that outranks a successful lock: two- sources contradicting each other about one query is a fact about the- data, not a gap in it. Every other blocking state means "not known- yet", and a side query that failed, went unanswered, or returned a- shortlist must not retract an identity the run did lock — one flaky- resolver call otherwise poisons every remaining answer in the session,- with no path back. Per-symbol safety does not depend on this aggregate:- a consumer still has to match a locked symbol in- :meth:`_match_authorized_symbol` before it may run.- """- records = list(self._identities.values())- if not records:- return "unresolved" if self._identity_required else "not_required"- statuses = {record.status for record in records}- if "conflicting" in statuses:- return "conflicting"- if "locked" in statuses:- return "locked"- for blocking in ("ambiguous", "invalidated", "unresolved"):- if blocking in statuses:- return blocking- if "not_found" in statuses:- return "not_found"- return "unresolved"-- @property- def should_buffer_output(self) -> bool:- """Return whether unverified model prose must be hidden from live sinks."""- return self._buffer_output or bool(self._evidence)-- @property- def validation_count(self) -> int:- """Return the number of final drafts checked so far."""- return len(self._validations)-- def identity_summary(self) -> dict[str, Any]:- """Return compact identity state for traces and tool errors."""- return {- "status": self.identity_status,- "authorized_symbols": sorted(self.authorized_symbols),- "records": [asdict(record) for record in self._identities.values()],- "recovery": self.recovery_summary(),- }-- def recovery_summary(self) -> dict[str, Any]:- """Return bounded-recovery budget state for traces and the artifact."""- return {- "rounds": self._recovery_rounds,- "max_rounds": MAX_GROUNDING_RECOVERY_ROUNDS,- "symbol_resolution_attempts": self._symbol_resolution_attempts,- "max_symbol_resolution_attempts": MAX_SYMBOL_RESOLUTION_ATTEMPTS,- "price_evidence_attempts": self._price_evidence_attempts,- "max_price_evidence_attempts": MAX_PRICE_EVIDENCE_ATTEMPTS,- }-- def authorize_tool_call(- self,- tool_name: str,- arguments: Mapping[str, Any],- *,- batch_authorized_symbols: Iterable[str],- call_id: str,- batch_identity_status: str | None = None,- ) -> ToolAuthorization:- """Authorize against identity state frozen before the whole LLM batch.-- Args:- tool_name: Requested tool.- arguments: Model-supplied arguments.- batch_authorized_symbols: Snapshot taken before processing any call- from this assistant response.- call_id: Provider tool-call identity.- batch_identity_status: Aggregate identity status from the same- pre-batch snapshot. Defaults to the current state for direct- callers outside the Agent loop.-- Returns:- An allow/block decision. Resolver calls are allowed but their result- cannot affect another call in this same batch.- """- if tool_name == _RESOLVER_TOOL:- self._identity_required = True- self._buffer_output = True- self._begin_resolution(str(arguments.get("query") or ""), call_id)- return ToolAuthorization(allowed=True)-- if self._is_private_company_skill(tool_name, arguments):- return self._authorize_private_company_skill()-- if tool_name == "load_skill" and self._identity_required:- frozen_status = batch_identity_status or self.identity_status- if frozen_status in _RESOLUTION_INCOMPLETE_STATUSES:- return ToolAuthorization(- allowed=False,- error_code="identity_required",- message=(- "Market-sensitive workflow selection is blocked while instrument "- "resolution is in flight or contradicted; a resolver result from "- "this same batch cannot be consumed."- ),- )- return ToolAuthorization(allowed=True)-- symbols = tuple(self._extract_symbol_arguments(arguments))- if not symbols:- return ToolAuthorization(allowed=True)-- self._identity_required = True- self._buffer_output = True- authorized = {_normalize_symbol(item) for item in batch_authorized_symbols}- frozen_status = batch_identity_status or self.identity_status- if frozen_status != "locked" or not authorized:- return ToolAuthorization(- allowed=False,- error_code=(- "identity_conflict"- if frozen_status in {"ambiguous", "conflicting", "invalidated"}- else "identity_required"- ),- message=(- "A canonical, non-conflicting identity was not locked before this "- "assistant tool-call batch started. A resolver result from this same "- "batch cannot be consumed."- ),- symbols=symbols,- )-- mismatched = tuple(- symbol- for symbol in symbols- if self._match_authorized_symbol(symbol, authorized) is None- )- if mismatched:- message = (- "Consumer symbol/venue differs from the locked resolver identity; "- "silent suffix or exchange rewrites are forbidden."- )- hints = [- hint- for symbol in mismatched- for hint in self._venue_mismatch_hints(symbol, authorized)- ]- if hints:- message += " " + " ".join(hints)- return ToolAuthorization(- allowed=False,- error_code="identity_mismatch",- message=message,- symbols=mismatched,- )- return ToolAuthorization(allowed=True, symbols=symbols)-- @staticmethod- def _venue_mismatch_hints(- requested_symbol: str,- authorized_symbols: Iterable[str],- ) -> list[str]:- """Turn a same-issuer venue mismatch into an actionable resolver hint.-- ``BLDP.US`` against a locked ``BLDP.TO`` is not a typo of one identity;- it is a second listing of the same company that was never resolved.- Naming the exact ``search_symbol`` query keeps the model from retrying- the identical unauthorized call. A bare ticker that collides with- several locked venues gets a "use the full suffix" hint instead.- """- requested = _normalize_symbol(requested_symbol)- authorized = {_normalize_symbol(item) for item in authorized_symbols}- if "." in requested:- base = requested.rsplit(".", 1)[0]- same_issuer = sorted(- item- for item in authorized- if "." in item and item.rsplit(".", 1)[0] == base- )- if same_issuer:- return [- f"[{requested_symbol} is a second venue of {', '.join(same_issuer)}; "- f"call search_symbol('{requested_symbol}') in a separate turn "- f"before querying it.]"- ]- return []- matches = sorted(- item- for item in authorized- if "." in item and item.rsplit(".", 1)[0] == requested- )- if len(matches) > 1:- return [- f"[{requested_symbol} matches multiple locked identities "- f"({', '.join(matches)}); use the full venue-suffixed symbol.]"- ]- return []-- @staticmethod- def _match_authorized_symbol(- requested_symbol: str,- authorized_symbols: Iterable[str],- ) -> str | None:- """Map a consumer argument to one unique locked canonical symbol.-- Both sides are canonicalized first, so a provider alias (``600519.SS``),- an exchange prefix (``sh600519``), an unpadded Hong Kong code- (``700.HK``) or a slashed pair (``BTC/USDT``) addresses the instrument- it names rather than being read as a silent venue rewrite.-- A bare code carries no venue, so it is accepted only when exactly one- locked identity has it as its base. That uniqueness — not a list of- which tools are allowed to use one — is what makes a bare ticker safe.- The list this replaced named nine tools while eleven documented- argument spellings across the registry were bare or prefixed, so the- tools' own schema examples were being rejected.-- Args:- requested_symbol: Model-supplied symbol argument.- authorized_symbols: Symbols locked before the tool batch.-- Returns:- The unique canonical identity consumed by the argument, or ``None``.- """- requested = _normalize_symbol(requested_symbol)- authorized = {_normalize_symbol(item) for item in authorized_symbols}- if requested in authorized:- return requested- if "." in requested:- return None- matches = [- symbol- for symbol in authorized- if "." in symbol and symbol.rsplit(".", 1)[0] == requested- ]- return matches[0] if len(matches) == 1 else None-- def ingest_tool_result(- self,- *,- tool_name: str,- arguments: Mapping[str, Any],- result: str,- call_id: str,- success: bool,- ) -> None:- """Consume the full untruncated tool result and persist its evidence.-- Args:- tool_name: Executed tool name.- arguments: Exact normalized tool arguments.- result: Full raw result, before model-context truncation.- call_id: Provider tool-call identity.- success: Result-envelope success classification.- """- payload = _json_object(result)- if not success:- self._record_tool_failure(tool_name, call_id, result)- if tool_name == _RESOLVER_TOOL:- self._finish_failed_resolution(arguments, call_id)- self.persist()- return-- self._track_session_symbols(arguments, result)- if tool_name in _ANALYSIS_TOOLS:- self._ingest_analysis_result(tool_name, arguments, payload, call_id)- if tool_name == _RESOLVER_TOOL:- self._ingest_resolution(arguments, payload, call_id)- elif tool_name == "get_market_data":- self._ingest_market_data(arguments, payload, call_id)- elif payload is not None:- self._ingest_generic_numeric(tool_name, arguments, payload, call_id)- self.persist()-- def _ingest_analysis_result(- self,- tool_name: str,- arguments: Mapping[str, Any],- payload: dict[str, Any] | None,- call_id: str,- ) -> None:- """Record metric numbers a completed analysis result actually produced.-- Success of the call envelope is not enough: ``backtest`` reports ok for- any runner exit, and a deduplicated ("skipped") call carries no new- result at all (#1336). Only results that yielded at least one- recognisable metric figure count as completed analysis.- """- if payload is None or payload.get("skipped"):- return- if tool_name == "backtest":- if str(payload.get("status") or "").casefold() != "ok" and payload.get(- "exit_code"- ) not in (0, "0"):- return- recorded = self._record_backtest_metrics(arguments, payload, call_id)- elif tool_name == "factor_analysis":- if str(payload.get("status") or "").casefold() != "ok":- return- recorded = self._record_leaf_metrics(payload, call_id, tool_name, "")- elif tool_name == "run_shadow_backtest":- if str(payload.get("status") or "").casefold() != "ok":- return- combined = payload.get("combined")- if not isinstance(combined, dict):- # A combined dict containing only {"error": ...} is no analysis.- return- recorded = self._record_leaf_metrics(combined, call_id, tool_name, "combined")- elif tool_name == "quantlib_call":- if payload.get("ok") is not True or str(- arguments.get("action") or ""- ).casefold() != "call":- return- function = str(arguments.get("function") or "")- recorded = self._record_leaf_metrics(- payload.get("result"), call_id, tool_name, function- )- else:- return- if recorded:- self._analysis_completed.append(- {"call_id": call_id, "tool": tool_name, "recorded_at": _utc_now()}- )-- def _record_leaf_metrics(- self,- value: Any,- call_id: str,- tool_name: str,- field_prefix: str,- ) -> int:- """Record nested numeric leaves whose key names a metric kind."""- recorded = 0-- def visit(item: Any, path: str) -> None:- nonlocal recorded- if _is_number(item):- kind = _metric_kind_for_path(path)- if kind is None:- return- self._analysis_metrics.append(- {- "metric": kind,- "value": float(item),- "tool": tool_name,- "call_id": call_id,- "field": path,- }- )- recorded += 1- return- if isinstance(item, dict):- for key, child in item.items():- visit(child, f"{path}.{key}" if path else str(key))- elif isinstance(item, list):- for index, child in enumerate(item):- visit(child, f"{path}[{index}]")-- visit(value, field_prefix or "")- return recorded-- def _record_backtest_metrics(- self,- arguments: Mapping[str, Any],- payload: dict[str, Any],- call_id: str,- ) -> int:- """Parse metric figures from a successful backtest's run-dir artifacts."""- root = self.run_dir.resolve()- candidates: list[Path] = []- raw_dir = arguments.get("run_dir") or payload.get("run_dir")- if raw_dir:- candidate = Path(str(raw_dir))- if not candidate.is_absolute():- candidate = self.run_dir / candidate- try:- resolved = candidate.resolve()- if resolved == root or resolved.is_relative_to(root):- candidates.append(resolved)- except OSError:- pass- # The loop archives a detached backtest's artifacts into the active run- # dir right after it succeeds, so that copy is the second candidate.- candidates.append(root)- artifacts = payload.get("artifacts")- if isinstance(artifacts, dict):- for path_value in artifacts.values():- if not isinstance(path_value, str):- continue- try:- resolved = Path(path_value).resolve()- if resolved.is_relative_to(root):- candidates.append(resolved)- except OSError:- continue- files: list[Path] = []- seen_dirs: set[Path] = set()- for candidate in candidates:- if candidate.is_file():- files.append(candidate)- continue- if candidate in seen_dirs:- continue- seen_dirs.add(candidate)- for dir_path in (candidate, candidate / "artifacts"):- for name in ("metrics.csv", "metrics.json"):- target = dir_path / name- if target.is_file():- files.append(target)- recorded = 0- seen_files: set[Path] = set()- for file_path in files:- if file_path in seen_files:- continue- seen_files.add(file_path)- recorded += self._record_metrics_file(file_path, call_id)- return recorded-- def _record_metrics_file(self, path: Path, call_id: str) -> int:- """Record metric figures from one metrics.csv/metrics.json artifact."""- try:- text = path.read_text(encoding="utf-8")- except (OSError, UnicodeDecodeError):- return 0- if path.suffix == ".json":- try:- data = json.loads(text)- except json.JSONDecodeError:- return 0- if not isinstance(data, dict):- return 0- return self._record_leaf_metrics(data, call_id, "backtest", "")- try:- rows = list(csv.reader(text.splitlines()))- except csv.Error:- return 0- if len(rows) < 2:- return 0- header = [cell.strip().casefold() for cell in rows[0]]- recorded = 0- for index, raw in enumerate(rows[1]):- if index >= len(header):- break- kind = _ANALYSIS_KIND_ALIASES.get(header[index])- value = _coerce_csv_number(raw)- if kind is not None and value is not None:- self._analysis_metrics.append(- {- "metric": kind,- "value": float(value),- "tool": "backtest",- "call_id": call_id,- "field": header[index],- }- )- recorded += 1- return recorded-- def validate_final_answer(self, content: str) -> ValidationResult:- """Validate identity assertions and numeric price claims.-- Args:- content: Candidate assistant answer.-- Returns:- A deterministic validation result. A record containing only the- answer hash and structured issues is appended to the artifact.- """- return self._validate(content, record=True)-- def revalidate(self, content: str) -> ValidationResult:- """Validate text WITHOUT counting it as a rejected draft.-- For the recheck that follows a deterministic repair or redaction. No- model round produced that text, so recording it would spend one unit- of the revision budget (``loop.py``) and add an attempt to the- artifact that no draft stands behind.-- Args:- content: The repaired or redacted answer.-- Returns:- A deterministic validation result.- """- return self._validate(content, record=False)-- def _validate(self, content: str, *, record: bool) -> ValidationResult:- """Run the gate, optionally without recording the attempt.-- ``validation_count`` is the run's rejected-DRAFT count: it caps the- revision budget (``loop.py``) and is printed to the user as the number- of rejected drafts in the degraded-run reason. The release path's own- rechecks are not drafts — one successful ``redacted_release`` inflated- the count from 1 to 4 with no model round in between, shrinking the- budget and overstating the audit number — so they pass ``record=False``.-- Args:- content: Candidate assistant answer.- record: Whether to append the attempt to the persisted ledger.-- Returns:- A deterministic validation result.- """- self._ingest_run_dir_ohlc_csvs()- issues: list[dict[str, Any]] = []- issues.extend(self._validate_identity(content))- issues.extend(self._validate_unsourced_symbols(content))- issues.extend(self._validate_price_claims(content))- issues.extend(self._validate_analysis_claims(content))- result = ValidationResult(valid=not issues, issues=issues)- if not record:- return result- self._validations.append(- {- "attempt": len(self._validations) + 1,- "checked_at": _utc_now(),- "content_sha256": hashlib.sha256(content.encode("utf-8")).hexdigest(),- "valid": result.valid,- "issues": issues,- }- )- self.persist()- return result-- def correction_prompt(self, validation: ValidationResult) -> str:- """Build bounded feedback for one rejected model draft."""- lines = [- "[GROUNDING GATE] The previous draft was rejected and was not released to the user.",- "Correct every issue using the existing structured identity and tool evidence:",- ]- for issue in validation.issues[:12]:- lines.append(f"- {issue.get('message', issue.get('code', 'grounding error'))}")- # Name the exact values that must be REMOVED, not rephrased. The model- # tends to restate a rejected figure in a new format; the gate then- # rejects it again and the run burns iterations until the fallback.- banned: list[str] = []- for issue in validation.issues:- code = issue.get("code")- value = issue.get("value")- if code in {"numeric_claim_conflict", "numeric_claim_unavailable", "unsourced_symbol_figures", "analysis_claim_unavailable"} and value is not None:- symbol = issue.get("symbol") or ""- label = f"{value:g}" if isinstance(value, (int, float)) else str(value)- banned.append(f"{label} ({symbol})" if symbol else label)- if banned:- deduped = list(dict.fromkeys(banned))- lines.append(- "REMOVE these rejected value(s) entirely - do NOT restate, rephrase, "- "or recompute them in any other format: " + ", ".join(deduped) + "."- )- repeated: list[str] = []- for prior in self._validations:- for prior_issue in prior.get("issues", []):- prior_value = prior_issue.get("value")- if isinstance(prior_value, (int, float)):- mark = f"{prior_value:g}"- if any(entry.startswith(mark) for entry in deduped):- repeated.append(mark)- if repeated:- lines.append(- "These value(s) have now been rejected repeatedly across drafts: "- + ", ".join(dict.fromkeys(repeated))- + ". Repeating them in any form keeps failing; drop them, or show "- "the full derivation from the observed inputs."- )- lines.extend(- [- "If a value is a derived or prospective level (stop, target, entry, etc.), "- "you must EITHER show the full derivation with the observed inputs and the "- "formula, OR omit it from the draft.",- "Reuse the exact locked symbol and venue.",- "Do not attach figures to a symbol no tool call in this session handled; "- "report it as not retrieved instead.",- ]- )- recovery = self.recovery_action(validation)- if recovery == _RESOLVER_TOOL:- lines.extend(- [- "Instrument identity is unresolved. Call `search_symbol` for the "- "candidate name in a separate tool-call turn, lock the exact canonical "- "symbol and venue it returns, then call `get_market_data` before finalizing.",- "Do NOT ask the user to confirm or continue while this read-only recovery "- "remains available.",- ]- )- elif recovery == "get_market_data":- lines.extend(- [- "Identity is locked but price evidence is missing. Call `get_market_data` "- "for the locked canonical symbol and venue in a separate tool-call turn, "- "then regenerate and re-validate the final answer.",- "Do NOT ask the user to confirm or continue while this read-only recovery "- "remains available.",- ]- )- else:- lines.append(- "If evidence is genuinely unavailable or conflicting and recovery is "- "exhausted, say so and ask for clarification; do not guess."- )- return "\n".join(lines)-- def recovery_action(self, validation: ValidationResult) -> str | None:- """Decide the next safe read-only recovery step for a rejected draft.-- Returns ``search_symbol`` when instrument identity is unresolved and- resolution attempts remain; ``get_market_data`` when identity is locked- but a price claim has no observed evidence and fetch attempts remain;- otherwise ``None`` (genuinely ambiguous, conflicting, or exhausted —- the loop must then ask the user or fail closed).-- This is the deterministic half of #1081: recoverable missing evidence is- often obtainable through read-only tools, so a rejected draft should- drive the original task forward instead of stopping.- """- if self._recovery_rounds >= MAX_GROUNDING_RECOVERY_ROUNDS:- return None- if self._identity_required and self.identity_status == "unresolved":- if self._symbol_resolution_attempts < MAX_SYMBOL_RESOLUTION_ATTEMPTS:- return _RESOLVER_TOOL- return None- if self.identity_status == "locked" and any(- issue.get("code") in {"numeric_claim_unavailable", "unsourced_symbol_figures"}- for issue in validation.issues- ):- if self._price_evidence_attempts < MAX_PRICE_EVIDENCE_ATTEMPTS:- return "get_market_data"- return None-- def record_recovery(self, action: str) -> None:- """Account one bounded recovery attempt against its budget."""- self._recovery_rounds += 1- if action == _RESOLVER_TOOL:- self._symbol_resolution_attempts += 1- elif action == "get_market_data":- self._price_evidence_attempts += 1-- def recovery_prompt(self, action: str, validation: ValidationResult) -> str:- """Build an executable next-step message for one bounded recovery turn."""- if action == _RESOLVER_TOOL:- return (- "[GROUNDING RECOVERY] Instrument identity is not yet locked and is "- "recoverable with read-only tools. Call `search_symbol` for the candidate "- "name in a separate assistant tool-call turn, lock and reuse the exact "- "canonical symbol and venue it returns, then call `get_market_data`. "- "Do NOT ask the user to confirm or continue while this read-only recovery "- "remains available, and do NOT finalize yet."- )- if action == "get_market_data":- return (- "[GROUNDING RECOVERY] Identity is locked but price evidence is missing. "- "Call `get_market_data` for the locked canonical symbol and venue in a "- "separate tool-call turn and use its existing bounded provider fallback, "- "then regenerate and re-validate the final answer. Do NOT ask the user to "- "confirm or continue while this read-only recovery remains available, and "- "do NOT finalize yet."- )- return self.correction_prompt(validation)-- def safe_fallback(self) -> str:- """Return a deterministic fail-closed answer after repeated rejection."""- is_zh = self._user_writes_chinese()- joined = self._observed_range_summary(is_zh)- if joined is not None:- if is_zh:- return (- "为避免输出与工具证据冲突的价格,我已拒绝上一版答案。"- f"当前可验证的已观测 OHLC 范围是:{joined}。"- "在重新核对标的或明确展示推导公式前,我不会生成买入价。"- )- return (- "I rejected the previous draft because its prices conflicted with tool evidence. "- f"The verified observed OHLC range is: {joined}. "- "I will not invent an entry price without a visible derivation or refreshed evidence."- )- # No observed price evidence: distinguish "identity unresolved" from- # "the draft cited prices this session never observed". Reporting the- # identity message for the latter is misleading (the run may not even- # have touched the market tools).- issue_codes = {- code- for validation in self._validations- for code in (issue.get("code") for issue in validation.get("issues", []))- }- if issue_codes & {- "numeric_claim_unavailable", "numeric_claim_conflict", "unsourced_symbol_figures"- }:- if is_zh:- return (- "我的回答被安全门槛拒绝:草稿引用了本会话未通过工具获取的价格数字,无法核验。"- "请重新发起任务,让模型先调用行情工具获取数据,或要求它去掉这些价格引用后重试。"- )- return (- "My previous answer was rejected by the verification gate: it cited price "- "figures that this session never obtained through a tool, so they could not "- "be verified. Re-run the task and let the agent fetch the market data first, "- "or ask it to answer without the unverified prices."- )- if is_zh:- return (- "当前无法安全确认标的身份或价格证据,因此没有生成交易结论。"- "请确认候选证券代码和交易所后再继续。"- )- return (- "I could not safely lock the instrument identity or price evidence, so I did not "- "produce a trading conclusion. Please confirm the candidate symbol and venue."- )-- def _user_writes_chinese(self) -> bool:- """Return whether user-facing gate text should be Chinese."""- return bool(re.search(r"[\u3400-\u9fff]", self.user_message))-- def _observed_range_summary(self, is_zh: bool, content: str | None = None) -> str | None:- """Summarise the observed OHLC range per symbol, or None without prices.-- Args:- is_zh: Whether to join the facts with Chinese punctuation.- content: The answer the summary is attached to, when there is one.- The symbol is then printed the way that answer spells it — a- footnote on an answer written throughout in ``562500.SS`` used- to name ``562500.SH``, because the evidence record is- canonicalised.-- Returns:- One fact per symbol, or None when the run observed no price.- """- price_records = self._price_records()- if not price_records:- return None- by_symbol: dict[str, list[EvidenceRecord]] = {}- for record in price_records:- by_symbol.setdefault(record.symbol or "unknown", []).append(record)- facts = []- for symbol, records in sorted(by_symbol.items()):- values = [float(record.value) for record in records if record.value is not None]- currency = next((record.currency for record in records if record.currency), None)- sources = sorted({record.source for record in records if record.source})- source_label = "/".join(sources) if sources else "unknown"- unit = f" {currency}" if currency else ""- facts.append(- f"{self._answer_symbol_spelling(symbol, content)}: "- f"{_format_price(min(values))}–{_format_price(max(values))}{unit} "- f"(source: {source_label}; currency conversion: none)"- )- return ";".join(facts) if is_zh else "; ".join(facts)-- @staticmethod- def _answer_symbol_spelling(canonical: str, content: str | None) -> str:- """Return the spelling ``content`` uses for a canonical symbol."""- if not content:- return canonical- for match in _CANONICAL_SYMBOL_RE.finditer(content):- if _normalize_symbol(match.group(0)) == canonical:- return match.group(0)- return canonical-- def _provenance_note(self, content: str | None = None) -> str | None:- """Build the one-line data note that satisfies the provenance checks.-- Args:- content: The answer the note is appended to, so the symbol is- printed the way that answer spells it.-- Returns:- The note, or None when the run observed no price.- """- price_records = self._price_records()- if not price_records:- return None- is_zh = self._user_writes_chinese()- by_symbol: dict[str, list[EvidenceRecord]] = {}- for record in price_records:- by_symbol.setdefault(record.symbol or "unknown", []).append(record)- parts = []- for symbol, records in sorted(by_symbol.items()):- sources = sorted(- {- record.source- for record in records- if record.source and record.source.casefold() not in {"auto", "unknown"}- }- )- currency = next((record.currency for record in records if record.currency), None)- source_label = "/".join(sources) if sources else ("未知" if is_zh else "unknown")- currency_label = currency or ("未知" if is_zh else "unknown")- spelling = self._answer_symbol_spelling(symbol, content)- parts.append(- f"{spelling}:行情来源 {source_label},计价货币 {currency_label}"- if is_zh- else f"{spelling}: price source {source_label}, quote currency {currency_label}"- )- if is_zh:- return "数据说明:" + ";".join(parts) + "。"- return "Data note: " + "; ".join(parts) + "."-- def repair_provenance(- self,- content: str,- validation: ValidationResult,- *,- require_checked_figures: bool = True,- ) -> str | None:- """Append a data note when the only defects are missing provenance words.-- ``data_source_not_surfaced`` and ``currency_not_surfaced`` mean the- answer quoted a price without naming the source or the currency. Both- are known to the ledger, so the omission is deterministic — and- regenerating a multi-minute report to add the word "tencent" is a full- model round for one word. Nothing here touches a figure: a draft- carrying any other issue is returned as None so the numeric checks- keep their round.-- ``canonical_symbol_not_surfaced`` is deliberately NOT repaired. That- check's job is that a price claim surfaces the symbol it is about, and- appending "562500.SH: price source yahoo" under a draft that reads- "贵州茅台 最新收盘价 1.171 元" turns a misattribution into a released- answer with a footnote naming a different instrument. It keeps its- model round (base rate: 1 of 27 rejections in the local traces, so- nearly all of the saving survives).-- The repair is also declined when the draft carries a price COLUMN the- table validator does not key on ("| 档位 | 挂单价 |"): those cells are- outside every validator's reach, and the note says where this run's- prices came from. Attaching it to a draft holding an unchecked ladder- price attests to a figure the gate never saw, in zero model rounds —- the round it used to cost was the last chance to drop that figure.-- Args:- content: The rejected draft.- validation: Its validation result.- require_checked_figures: Decline when an unchecked price column is- present. ``redacted_release`` passes False: there the choice- is not "repair or one more model round" but "repair or the- canned refusal", the revision budget is already spent, and the- document it repairs carries the redaction footnote.-- Returns:- The draft with a provenance note appended, or None when the issues- are not provenance-only, an unchecked price column is present, or- there is no price evidence to cite.- """- codes = {issue.get("code") for issue in validation.issues}- if not codes or not codes <= _REPAIRABLE_PROVENANCE_CODES:- return None- if require_checked_figures and self._has_unchecked_price_column(content):- return None- note = self._provenance_note(content)- if note is None:- return None- return content.rstrip() + "\n\n" + note-- @staticmethod- def _has_unchecked_price_column(content: str) -> bool:- """Whether a Markdown table holds a price column no validator reads.-- ``_validate_price_tables`` keys on ``_TABLE_FIELD_ALIASES`` — the OHLC- headers — and the prose scan skips every line containing "|". A column- headed 挂单价 / 目标价 / Entry price is read by neither.-- Args:- content: The draft to inspect.-- Returns:- True when such a column carries at least one numeric cell.- """- lines = content.splitlines()- for header, rows, _ in GroundingLedger._pipe_tables(lines):- unchecked = [- position- for position, cell in enumerate(header)- if _PRICE_HEADER_RE.search(cell)- and cell.strip().casefold() not in _TABLE_FIELD_ALIASES- ]- if not unchecked:- continue- for row in rows:- for position in unchecked:- if position < len(row) and _NUMBER_RE.search(row[position]):- return True- return False-- def redacted_release(self, content: str, validation: ValidationResult) -> str | None:- """Release the last rejected draft with its unverified figures cut out.-- Once the revision budget is spent, the draft is still the analysis the- user waited through every revision for, and the gate objected to- specific figures in specific clauses — not to the trend read, the- indicator commentary, or the risk notes around them. Each rejected- figure is replaced by a visible marker AT THE SPAN the validator- flagged, every other occurrence of the same figure elsewhere in the- document is cut with it, the missing provenance words are appended if- that is all that remains, and the whole released document — footnote- included — is re-validated by the same gate: only text that passes is- returned, so nothing the gate rejected reaches the user.-- Fail-closed by construction. None — leave the canned fallback in place —- whenever the run never observed a price at all (the draft's numbers then- have no basis to stand next to), carries an issue that is not a- cut-out-able figure (an identity finding is one), has a flagged clause- that cannot be located, or still fails after the cut.-- Args:- content: The rejected draft.- validation: Its validation result.-- Returns:- The redacted, re-validated draft followed by a note stating how many- figures were removed and the observed range, or None.- """- if not self._price_records():- return None- text = _strip_release_markers(content)- removed = 0- # Stripping moves every offset after it, and the issue spans are the- # only anchor the cuts have, so the verdict is retaken on the text the- # cuts will actually be made in.- pending = list(- validation.issues- if text == content- else self._validate(text, record=False).issues- )- # A validator reports one figure per clause, so cutting it can reveal- # the next one on the recheck. Cut, recheck, repeat — bounded, and- # every cut is a figure the gate itself flagged.- for _ in range(_MAX_REDACTION_PASSES):- codes = {issue.get("code") for issue in pending}- if not codes or not codes <= (_REDACTABLE_CODES | _REPAIRABLE_PROVENANCE_CODES):- return None- # Two issues can point at one clause ("unsourced symbol" and the- # conflict on the same figure), so cuts are grouped per span:- # each clause is rewritten once with every value flagged for it.- by_span: dict[tuple[int, int], list[Any]] = {}- for issue in pending:- if issue.get("code") not in _REDACTABLE_CODES:- continue- span = self._issue_span(text, issue)- if span is None:- return None- by_span.setdefault(span, []).append(issue.get("value"))- text, count = self._redact_spans(text, by_span)- if count == 0:- return None- removed += count- check = self._validate(text, record=False)- if not check.valid:- repaired = self.repair_provenance(- text, check, require_checked_figures=False- )- if repaired is not None:- text = repaired- check = self._validate(text, record=False)- if check.valid:- break- pending = list(check.issues)- else:- return None- released = text.rstrip() + "\n\n" + self._release_note(removed, text)- # The note carries the observed range and the canonical symbols, so it- # is answer text too. Validating the body and shipping body+note left- # the released document as a whole unchecked, which contradicted the- # fail-closed promise in this docstring.- if not self._validate(released, record=False).valid:- return None- # Recorded beside the drafts but NOT as one: the artifact otherwise- # held no evidence for the fail-closed promise above, because every- # recheck on this path is deliberately unrecorded.- self._released = {- "released_at": _utc_now(),- "content_sha256": hashlib.sha256(released.encode("utf-8")).hexdigest(),- "figures_removed": removed,- "revalidated": True,- }- self.persist()- return released-- @staticmethod- def _issue_span(text: str, issue: dict[str, Any]) -> tuple[int, int] | None:- """Locate the flagged clause in ``text``.-- The validators record the clause's character span, which is the only- reliable anchor: the stored ``claim`` is normalised (thousands- separators stripped, table cells rendered as "label: value"), so- ``text.find(claim)`` missed every price above 999 and every metric- table outright, and for a bare numeric cell it matched INSIDE a longer- number — "1.10" found in "21.10 亿元", rewriting an untouched turnover- figure into "2(略※)".-- The substring fallback that used to sit here is gone. Every one of the- six redactable-issue construction sites carries a span, so it was- reachable only from a hand-built issue, and it carried a documented- digit-boundary rationale for a hazard the span had already settled —- which is worse than no code, because a reader trusts it.-- Args:- text: The document the issue was raised against.- issue: One validation issue.-- Returns:- ``(start, end)`` or None when the issue carries no usable span.- """- span = issue.get("span")- if not isinstance(span, (list, tuple)) or len(span) != 2:- return None- try:- start, end = int(span[0]), int(span[1])- except (TypeError, ValueError):- return None- if 0 <= start <= end <= len(text):- return start, end- return None-- def _release_note(self, removed: int, content: str | None = None) -> str:- """Explain the redaction to the user, with the observed range.-- ``redacted_release`` returns None before this is reached when the run- holds no price record, which is the only case in which the summary is- None — so it is read directly rather than behind an ``or ""`` that- described a state the caller cannot produce.- """- is_zh = self._user_writes_chinese()- joined = self._observed_range_summary(is_zh, content)- if is_zh:- return (- f"※ 略去 {removed} 处无法与本会话工具数据对上的数值。"- f"已观测 OHLC 范围:{joined}。"- "如需买入价,请让我基于已观测的收盘价或均线给出带公式的推导。"- )- return (- f"※ {removed} figure(s) that could not be matched to this session's tool data "- f"were omitted. Observed OHLC range: {joined}. "- "For an entry price, ask me to derive one with a visible formula from an "- "observed close or moving average."- )-- def _redact_spans(- self,- text: str,- by_span: dict[tuple[int, int], list[Any]],- ) -> tuple[str, int]:- """Cut the flagged figures at their spans, then everywhere else.-- Numbers are located on the masked clause (symbols, dates, prospective- levels blanked) so a ticker's digits are never cut. A numeric value is- matched numerically, a percent-shaped analysis value textually, and a- ``None`` value (a clause attributing figures to an unhandled symbol)- cuts every number in that clause.-- The second stage is why the footnote can be believed. Cutting only the- flagged clause left the same rejected figure standing in a Markdown- table under a non-OHLC header or in a bullet with no price word —- neither surface is scanned by the validators — while the footnote- asserted it had been removed.-- Two kinds of occurrence are never swept, because the gate has already- accepted them where they stand: a figure the ledger observed, and a- figure sitting inside a valid formula elsewhere in the document.- Without the second, the rejected entry price 0.95 was cut out of- "基于 MA20 0.7158 × 0.95 = 0.680", mangling the one derivation the- correction prompt asks the model to write (159516.SZ replay,- 2026-09-09).-- The formula protection is scoped to the formula's own character SPANS.- Scoped to the VALUE it protected the rejected figure document-wide:- with "基于收盘价 1.171 × 0.95 = 1.112" anywhere in the draft, the same- 0.95 survived in "| 第一档 | 0.95 |" under a footnote saying one figure- had been cut — the exact restatement this second stage exists to- remove, protected by the derivation the model wrote beside it.-- A percent literal is protected the same way. Cutting every occurrence- of a flagged literal took the accepted one with it: "从 1.110 涨到- 1.171,区间收益率约 5.5%" is endpoint arithmetic this gate validated,- and it was cut and footnoted as unmatched because an unrelated- "策略年化波动率 5.5%" was flagged in the next clause.-- Args:- text: The document to rewrite.- by_span: ``(start, end)`` → the values flagged inside that span.-- Returns:- The rewritten text and the number of figures replaced.- """- swept: list[float] = []- swept_literals: list[str] = []- pieces: list[str] = []- cursor = 0- total = 0- for (start, end), values in sorted(by_span.items()):- if start < cursor:- continue- cut_all, targets, literals = _redaction_targets(values)- swept.extend(targets)- swept_literals.extend(literals)- replaced, count = self._rewrite_segment(- text[start:end], cut_all, targets, literals- )- pieces.append(text[cursor:start])- pieces.append(replaced)- total += count- cursor = end- pieces.append(text[cursor:])- text = "".join(pieces)- if total == 0 or not (swept or swept_literals):- return text, total- observed = self._observed_price_values()- survivors = [- target for target in swept if not _matches_any(target, observed, rel=1e-9)- ]- if not survivors and not swept_literals:- return text, total- protected = self._derivation_spans(text)- if swept_literals:- protected += self._accepted_metric_spans(text)- # Line by line, so each replacement takes the marker from the script of- # its OWN line. Run over the whole document the second stage picked one- # marker for everything, and a Chinese report containing an English- # table released "| Entry |(略※) |".- extra = 0- out: list[str] = []- cursor = 0- for line, start in _lines_with_offsets(text):- out.append(text[cursor:start])- local = [- (span_start - start, span_end - start)- for span_start, span_end in protected- if span_start >= start and span_end <= start + len(line)- ]- rewritten, count = self._rewrite_segment(- line, False, survivors, swept_literals, protected=local- )- out.append(rewritten)- extra += count- cursor = start + len(line)- out.append(text[cursor:])- return "".join(out), total + extra-- def _observed_price_values(self) -> list[float]:- """Every observed price value the run holds, for redaction protection."""- return [- float(record.value)- for record in self._comparable_price_records()- if record.value is not None- ]-- def _derivation_spans(self, text: str) -> list[tuple[int, int]]:- """Where a valid derivation sits in ``text``, in document offsets.-- Args:- text: The document about to be swept.-- Returns:- The character span of every arithmetically valid,- observation-anchored formula in it.- """- records = self._comparable_price_records()- document_symbol = self._symbol_for_claim(text, records)- spans: list[tuple[int, int]] = []- for line, offset in _lines_with_offsets(text):- if not _NUMBER_RE.search(line):- continue- symbol = self._symbol_for_claim(line, records) or document_symbol- for start, end, _, _ in self._derivation_formulas(line, records, symbol):- spans.append((offset + start, offset + end))- return spans-- def _accepted_metric_spans(self, text: str) -> list[tuple[int, int]]:- """Where this gate ACCEPTED a metric figure in ``text``.-- A clause the analysis validator examined — it carries a metric word- and a measurement-shaped number — and did not flag is a clause whose- figures this gate grounded. Sweeping such a figure out because an- unrelated clause states the same percentage cut a validated derivation- and footnoted it as unmatched.-- The verdict comes from the validator itself rather than from a second- copy of its exemption rules: a clause with no metric word was never- examined (a bullet, an unclaimed table column) and is deliberately not- protected — that unscanned surface is what the sweep exists for.-- Args:- text: The document about to be swept.-- Returns:- The character span of every examined-and-accepted metric clause.- """- flagged = {- (int(issue["span"][0]), int(issue["span"][1]))- for issue in self._validate(text, record=False).issues- if isinstance(issue.get("span"), (list, tuple))- and len(issue["span"]) == 2- }- spans: list[tuple[int, int]] = []- for line, offset in _lines_with_offsets(text):- for segment, start, end in _clause_spans(line, offset):- if not _ANALYSIS_METRIC_RE.search(segment):- continue- if not self._measure_numbers(segment):- continue- if any(- span_start <= start and end <= span_end- for span_start, span_end in flagged- ):- continue- spans.append((start, end))- return spans-- def _rewrite_segment(- self,- segment: str,- cut_all: bool,- targets: Sequence[float],- literals: Sequence[str],- *,- protected: Sequence[tuple[int, int]] = (),- ) -> tuple[str, int]:- """Replace the wanted figures in one stretch of text with the marker.-- Args:- segment: The stretch of the answer to rewrite.- cut_all: Cut every number, not only the listed targets.- targets: Numeric values to cut.- literals: Percent-shaped figures to cut by their written text.- protected: Character ranges inside ``segment`` that must survive- whatever they contain — a valid formula, or a metric clause- this gate accepted. Protection is by POSITION, not by value:- the rejected entry price is usually also the multiplier of the- correct derivation, and protecting the value protected every- restatement of the rejected figure along with it.-- Returns:- The rewritten stretch and the number of figures replaced.- """- if not cut_all and not targets and not literals:- return segment, 0- # The marker follows the SCRIPT OF THE TEXT BEING CUT, not the user's- # message: a Chinese user asking about a US name gets English tables,- # and "Suggested entry price(略※) per share." was the result. A- # stretch with neither script — a numeric table row — falls back to- # the user's language, which is what the footnote is written in.- if re.search(r"[\u3400-\u9fff]", segment):- marker = _REDACTION_MARKER_ZH- elif re.search(r"[A-Za-z]", segment):- marker = _REDACTION_MARKER_EN- else:- marker = (- _REDACTION_MARKER_ZH- if self._user_writes_chinese()- else _REDACTION_MARKER_EN- )- spans: list[tuple[int, int]] = []- if literals:- for match in _MEASURE_NUMBER_RE.finditer(segment):- normalized = match.group(0).replace(" ", "").replace(",", "")- if normalized in literals:- spans.append((match.start(), match.end()))- masked = self._masked_candidate_text(segment)- for match in _NUMBER_RE.finditer(masked):- try:- number = float(match.group(0).replace(",", ""))- except ValueError:- continue- if cut_all or _matches_any(number, targets, rel=1e-9):- spans.append((match.start(), match.end()))- pieces: list[str] = []- cursor = 0- count = 0- for start, end in sorted(set(spans)):- if start < cursor:- continue- if any(- keep_start <= start and end <= keep_end- for keep_start, keep_end in protected- ):- continue- unit = _UNIT_AFTER_RE.match(segment, end)- if unit:- end = unit.end()- symbol = _CURRENCY_BEFORE_RE.search(segment[cursor:start])- if symbol:- start = cursor + symbol.start()- if marker is _REDACTION_MARKER_ZH:- # "建议买入价 0.95 元" → "建议买入价(略※)": a full-width- # bracket sits flush against the preceding word. Not against a- # table pipe, though — "| 第一档 |(略※) |" loses the column's- # padding and reads as a broken row.- while (- start > cursor- and segment[start - 1] == " "- and segment[: start - 1].rstrip(" ")[-1:] != "|"- ):- start -= 1- pieces.append(segment[cursor:start])- pieces.append(marker)- cursor = end- count += 1- pieces.append(segment[cursor:])- return "".join(pieces), count-- def persist(self) -> None:- """Atomically persist the current structured ledger."""- artifact_dir = self.run_dir / "artifacts"- try:- artifact_dir.mkdir(parents=True, exist_ok=True)- path = artifact_dir / GROUNDING_ARTIFACT- temp = path.with_suffix(path.suffix + ".tmp")- payload = {- "schema_version": 1,- "updated_at": _utc_now(),- "identity": self.identity_summary(),- "session_symbols": sorted(self._session_symbols),- "session_symbol_roots": sorted(self._session_symbol_roots),- "evidence": [asdict(record) for record in self._evidence],- "tool_failures": list(self._tool_failures),- "analysis_completed": list(self._analysis_completed),- "analysis_evidence": list(self._analysis_metrics),- "validations": list(self._validations),- "released": dict(self._released) if self._released else None,- }- temp.write_text(- json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n",- encoding="utf-8",- )- temp.replace(path)- except OSError:- # Grounding decisions remain in memory; a read-only/broken artifact- # directory must not crash the agent's error path.- return-- def _seed_symbols(self, text: str, *, source: str) -> None:- """Lock exact symbols explicitly supplied by a user."""- for match in _CANONICAL_SYMBOL_RE.finditer(text or ""):- symbol = _normalize_symbol(match.group(0))- key = f"explicit:{symbol}"- existing = self._identities.get(key)- version = existing.version + 1 if existing else 1- self._identities[key] = IdentityRecord(- query=symbol,- status="locked",- symbol=symbol,- venue=_infer_venue(symbol),- instrument_type=_infer_instrument_type(symbol),- currency=_infer_currency(symbol),- source_tool_call_id=source,- source=[source],- version=version,- )- self._identity_required = True- self._buffer_output = True-- def _begin_resolution(self, query: str, call_id: str) -> None:- """Enter unresolved state before the resolver executes."""- key = _query_key(query) or f"call:{call_id}"- existing = self._identities.get(key)- self._identities[key] = IdentityRecord(- query=query,- status="unresolved",- source_tool_call_id=call_id,- version=(existing.version + 1) if existing else 1,- )- self.persist()-- def _finish_failed_resolution(- self,- arguments: Mapping[str, Any],- call_id: str,- ) -> None:- """Mark transport/business failure as invalidated, never not-found."""- query = str(arguments.get("query") or "")- key = _query_key(query) or f"call:{call_id}"- existing = self._identities.get(key)- self._identities[key] = IdentityRecord(- query=query,- status="invalidated",- source_tool_call_id=call_id,- version=(existing.version + 1) if existing else 1,- )-- def _ingest_resolution(- self,- arguments: Mapping[str, Any],- payload: dict[str, Any] | None,- call_id: str,- ) -> None:- """Advance unresolved identity from a structured resolver result."""- data = payload.get("data") if isinstance(payload, dict) else None- data = data if isinstance(data, dict) else {}- query = str(data.get("query") or arguments.get("query") or "")- key = _query_key(query) or f"call:{call_id}"- existing = self._identities.get(key)- version = (existing.version + 1) if existing else 1-- if not isinstance(payload, dict) or payload.get("ok") is False:- self._identities[key] = IdentityRecord(- query=query,- status="invalidated",- source_tool_call_id=call_id,- version=version,- )- return-- raw_candidates = data.get("candidates")- candidates = [dict(item) for item in raw_candidates if isinstance(item, dict)] if isinstance(raw_candidates, list) else []- resolver_candidates = candidates- relevant_constraints = self.resolution_context.constraints_for(query)- constraint_audit = [item.audit_record() for item in relevant_constraints]- sources = data.get("sources") if isinstance(data.get("sources"), dict) else {}- if not candidates:- # "This entity does not exist" may only be concluded when every- # source that could answer did answer. Counting two clean sources- # instead was unreachable for a Chinese query — Yahoo cannot serve- # one at all — so an entity that simply is not listed came back as- # ``invalidated``, which blocks the run rather than answering it.- # A source that skipped an unsupported query shape is not an outage.- clean_sources = [- str(name)- for name, value in sources.items()- if str(value).casefold() == "ok"- ]- failed_sources = [- str(name)- for name, value in sources.items()- if str(value).casefold() != "ok"- and not str(value).casefold().startswith("skipped")- ]- self._identities[key] = IdentityRecord(- query=query,- status="not_found" if clean_sources and not failed_sources else "invalidated",- source_tool_call_id=call_id,- source=clean_sources,- candidates=[],- resolution_constraints=constraint_audit,- version=version,- )- return-- market_values = {- item.value- for item in relevant_constraints- if item.dimension == "market" and item.explicit- }- if market_values:- constrained = [- candidate- for candidate in candidates- if candidate_market(candidate) in market_values- ]- if constrained:- candidates = constrained- else:- # A mismatch with an explicit constraint must stay fail closed.- # The candidate list may be truncated, so this is ambiguity,- # not proof that the requested listing does not exist.- self._identities[key] = IdentityRecord(- query=query,- status="ambiguous",- source_tool_call_id=call_id,- candidates=resolver_candidates,- resolution_constraints=constraint_audit,- version=version,- )- return-- chosen = self._choose_candidate(query, candidates)- if chosen is None:- self._identities[key] = IdentityRecord(- query=query,- status="ambiguous",- source_tool_call_id=call_id,- candidates=resolver_candidates,- resolution_constraints=constraint_audit,- version=version,- )- return-- symbol = _normalize_symbol(chosen.get("symbol"))- if not symbol:- self._identities[key] = IdentityRecord(- query=query,- status="invalidated",- source_tool_call_id=call_id,- candidates=resolver_candidates,- resolution_constraints=constraint_audit,- version=version,- )- return-- # A query that already spells a canonical symbol is asserting one, so a- # resolver answering with a different instrument contradicts it rather- # than refining it. This generalizes the ``.SS``/``.SH`` alias check it- # replaces: that one fired on one exchange's two spellings and stayed- # silent on an actual cross-exchange swap, which is the case that- # matters.- asserted = _scan_symbols(query)- if asserted and symbol not in asserted:- conflicting = list(candidates)- conflicting.extend({"symbol": item, "source": ["query"]} for item in sorted(asserted))- self._identities[key] = IdentityRecord(- query=query,- status="conflicting",- source_tool_call_id=call_id,- candidates=conflicting,- resolution_constraints=constraint_audit,- version=version,- )- return-- if existing and existing.status == "locked" and existing.symbol != symbol:- conflicting = list(candidates)- conflicting.insert(0, {"symbol": existing.symbol, "source": existing.source})- self._identities[key] = IdentityRecord(- query=query,- status="conflicting",- source_tool_call_id=call_id,- candidates=conflicting,- resolution_constraints=constraint_audit,- version=version,- )- return-- source_names = []- for value in [chosen.get("source"), *(chosen.get("also_from") or [])]:- name = str(value or "").strip()- if name and name not in source_names:- source_names.append(name)- venue = str(chosen.get("exchange") or chosen.get("market") or "").strip() or _infer_venue(symbol)- self._identities[key] = IdentityRecord(- query=query,- status="locked",- symbol=symbol,- venue=venue,- instrument_type=_infer_instrument_type(symbol, chosen.get("type")),- currency=_infer_currency(symbol),- source_tool_call_id=call_id,- source=source_names,- candidates=resolver_candidates,- resolution_constraints=constraint_audit,- version=version,- )- self._supersede_shortlists(symbol)-- def _supersede_shortlists(self, symbol: str) -> None:- """Retire ambiguous shortlists that this lock has just answered.-- A screening query resolves to many candidates by design. Once one of- them is locked by a later, narrower resolution, the earlier shortlist is- answered rather than unresolved — leaving it ``ambiguous`` blocks every- final answer in the run for the rest of the session (#955).-- Args:- symbol: Canonical symbol locked by the current resolution.- """- for key, record in self._identities.items():- if record.status != "ambiguous":- continue- offered = {- _normalize_symbol(candidate.get("symbol")) for candidate in record.candidates- }- if symbol in offered:- self._identities[key] = replace(- record, status="superseded", updated_at=_utc_now()- )-- @staticmethod- def _choose_candidate(- query: str,- candidates: list[dict[str, Any]],- ) -> dict[str, Any] | None:- """Choose only a unique or strongly corroborated resolver candidate.-- Candidates are collapsed onto their canonical symbol first. Two rows- that differ only by a provider's suffix convention describe one listing,- and counting them as rival candidates is what left every Shanghai query- with two "exact" matches and therefore no choice at all.- """- by_symbol: dict[str, dict[str, Any]] = {}- for candidate in candidates:- by_symbol.setdefault(_normalize_symbol(candidate.get("symbol")), candidate)- candidates = list(by_symbol.values())- if len(candidates) == 1:- return candidates[0]- normalized_query = re.sub(r"[^a-z0-9\u3400-\u9fff]", "", query.casefold())- exact: list[dict[str, Any]] = []- strong: list[dict[str, Any]] = []- for candidate in candidates:- symbol = _normalize_symbol(candidate.get("symbol"))- base = symbol.split(".", 1)[0].split("-", 1)[0].split("/", 1)[0]- name = str(candidate.get("name") or "")- comparable = {- re.sub(r"[^a-z0-9\u3400-\u9fff]", "", base.casefold()),- re.sub(r"[^a-z0-9\u3400-\u9fff]", "", name.casefold()),- re.sub(r"[^a-z0-9\u3400-\u9fff]", "", symbol.casefold()),- }- if normalized_query and normalized_query in comparable:- exact.append(candidate)- if candidate.get("also_from") or candidate.get("cik"):- strong.append(candidate)- if len(exact) == 1:- return exact[0]- if len(strong) == 1:- return strong[0]- return None-- def _authorize_private_company_skill(self) -> ToolAuthorization:- """Keep private-company routing symmetric with locked listing evidence."""- locked_listings = [- record- for record in self._identities.values()- if record.status == "locked"- and record.instrument_type in {"listed_security", "fund"}- ]- if locked_listings:- return ToolAuthorization(- allowed=False,- error_code="identity_conflict",- message=(- "A resolver has locked this entity to a listed security. Model memory "- "cannot replace that evidence with a private-company workflow."- ),- symbols=tuple(- record.symbol for record in locked_listings if record.symbol- ),- )- if self.identity_status == "not_found" or not self._identity_required:- return ToolAuthorization(allowed=True)- return ToolAuthorization(- allowed=False,- error_code="identity_required",- message=(- "Private-company routing requires a completed resolver result with clean "- "not_found status; current identity is unresolved, ambiguous, or invalidated."- ),- )-- @staticmethod- def _is_private_company_skill(- tool_name: str,- arguments: Mapping[str, Any],- ) -> bool:- """Return whether this call selects a private-company skill."""- if tool_name != "load_skill":- return False- name = str(arguments.get("name") or "").strip().casefold()- return name in _PRIVATE_COMPANY_SKILL_NAMES or (- "private" in name and "company" in name- )-- @staticmethod- def _extract_symbol_arguments(arguments: Mapping[str, Any]) -> list[str]:- """Extract model-selected identities from well-known argument keys."""- symbols: list[str] = []- for key, value in arguments.items():- if str(key).casefold() not in _SYMBOL_ARGUMENT_KEYS:- continue- values = value if isinstance(value, (list, tuple, set, frozenset)) else [value]- for item in values:- if not isinstance(item, (str, int)):- continue- symbol = _normalize_symbol(item)- if symbol and symbol not in symbols:- symbols.append(symbol)- return symbols-- def _track_session_symbols(- self,- arguments: Mapping[str, Any],- result: str,- ) -> None:- """Widen the run's instrument surface from one succeeding tool call.-- Both sides of a successful call count. The result is the strong signal —- a resolver shortlist, an OHLC panel, a filing index. The arguments are- the weaker one, but a symbol the model handed to a tool that then- succeeded has at least been exercised against a real system, whereas a- symbol that surfaces for the first time in the final prose has been- exercised against nothing. Failed calls are deliberately excluded, so a- blocked or erroring call never launders an invented ticker.-- Bare symbol arguments are tracked separately as roots. Many tools take a- bare ticker by contract, so a run that legitimately fetched ``AAPL``- never writes ``AAPL.US`` into any argument or result. Without the root,- the canonical spelling the rest of this module demands — see- ``canonical_symbol_not_surfaced`` — would be the one spelling this gate- rejects.-- Args:- arguments: Exact normalized tool arguments.- result: Full raw result, before model-context truncation.- """- if len(self._session_symbols) >= _MAX_TRACKED_SYMBOLS:- return- try:- rendered_arguments = json.dumps(arguments, ensure_ascii=False, default=str)- except (TypeError, ValueError):- rendered_arguments = ""- found = _scan_symbols(rendered_arguments) | _scan_symbols(result)- room = _MAX_TRACKED_SYMBOLS - len(self._session_symbols)- self._session_symbols.update(sorted(found)[:room])- self._session_symbol_roots.update(- symbol- for symbol in self._extract_symbol_arguments(arguments)- if "." not in symbol- )-- def _record_tool_failure(self, tool_name: str, call_id: str, result: str) -> None:- """Store structured unavailable evidence for failed business envelopes."""- payload = _json_object(result) or {}- self._tool_failures.append(- {- "call_id": call_id,- "tool": tool_name,- "status": "unavailable",- "error_code": payload.get("error_code"),- "message": str(payload.get("error") or payload.get("message") or "tool failed")[:500],- "recorded_at": _utc_now(),- }- )-- def _ingest_market_data(- self,- arguments: Mapping[str, Any],- payload: dict[str, Any] | None,- call_id: str,- ) -> None:- """Convert full OHLCV payloads into source-linked evidence rows."""- if payload is None:- self._record_tool_failure("get_market_data", call_id, "malformed JSON result")- return- requested_source = str(arguments.get("source") or "auto")- provenance = payload.get("_provenance")- provenance = provenance if isinstance(provenance, dict) else {}- for raw_symbol, raw_rows in payload.items():- if str(raw_symbol).startswith("_"):- continue- symbol = _normalize_symbol(raw_symbol)- rows = raw_rows.get("data") if isinstance(raw_rows, dict) else raw_rows- if not isinstance(rows, list):- continue- symbol_provenance = provenance.get(raw_symbol)- actual_source = (- str(symbol_provenance.get("source"))- if isinstance(symbol_provenance, dict) and symbol_provenance.get("source")- else requested_source- )- currency_conversion = (- str(symbol_provenance.get("currency_conversion"))- if isinstance(symbol_provenance, dict)- and symbol_provenance.get("currency_conversion")- else None- )- for row in rows:- if not isinstance(row, dict):- continue- timestamp = next(- (str(row[key]) for key in _TIMESTAMP_FIELDS if row.get(key) is not None),- None,- )- for field_name, value in row.items():- normalized_field = str(field_name).casefold()- if normalized_field in _TIMESTAMP_FIELDS or not _is_number(value):- continue- self._evidence.append(- EvidenceRecord(- call_id=call_id,- tool="get_market_data",- symbol=symbol,- source=actual_source,- timestamp=timestamp,- field=normalized_field,- value=value,- status="observed",- currency=_infer_currency(symbol),- venue=_infer_venue(symbol),- currency_conversion=currency_conversion,- )- )- unresolved = payload.get("_unresolved")- if isinstance(unresolved, list):- for raw_symbol in unresolved:- symbol = _normalize_symbol(raw_symbol)- self._evidence.append(- EvidenceRecord(- call_id=call_id,- tool="get_market_data",- symbol=symbol,- source=requested_source,- timestamp=None,- field="availability",- value=None,- status="unavailable",- currency=_infer_currency(symbol),- venue=_infer_venue(symbol),- )- )-- def _ingest_generic_numeric(- self,- tool_name: str,- arguments: Mapping[str, Any],- payload: dict[str, Any],- call_id: str,- ) -> None:- """Flatten bounded numeric leaves from other market-sensitive tools."""- symbols = self._extract_symbol_arguments(arguments)- symbol = symbols[0] if len(symbols) == 1 else None- if symbol:- symbol = (- self._match_authorized_symbol(symbol, self.authorized_symbols) or symbol- )- source = str(payload.get("source") or tool_name)- remaining = _MAX_GENERIC_EVIDENCE- timestamp_fields = (*_TIMESTAMP_FIELDS, "as_of")-- def visit(value: Any, path: str, timestamp: str | None = None) -> None:- nonlocal remaining- if remaining <= 0:- return- if _is_number(value):- self._evidence.append(- EvidenceRecord(- call_id=call_id,- tool=tool_name,- symbol=symbol,- source=source,- timestamp=timestamp,- field=path or "value",- value=value,- status="observed",- currency=_infer_currency(symbol or ""),- venue=_infer_venue(symbol or ""),- )- )- remaining -= 1- return- if isinstance(value, dict):- local_timestamp = next(- (- str(value[key])- for key in timestamp_fields- if value.get(key) is not None- ),- timestamp,- )- for key, item in value.items():- if str(key).casefold() in timestamp_fields:- continue- visit(- item,- f"{path}.{key}" if path else str(key),- local_timestamp,- )- elif isinstance(value, list):- for index, item in enumerate(value):- visit(item, f"{path}[{index}]", timestamp)-- visit(payload, "")-- def _ingest_run_dir_ohlc_csvs(self) -> None:- """Register OHLC rows from CSVs the run wrote via the bash workaround.-- The bash+yfinance escape hatch writes per-symbol OHLC CSVs into the run- directory (e.g. ``data/raw/BYN_V.csv``) instead of returning them through- ``get_market_data``. Those prices were genuinely observed tool output,- but they never entered the ledger, so the final-answer gate rejected- every one of them as ``numeric_claim_unavailable``. Scan the run dir for- such CSVs and register their open/high/low/close/price rows as observed- evidence, keyed to the symbol derived from the filename.-- Only files whose filename maps to a symbol already tracked in this run- are accepted, so a stray CSV cannot mint new identity. Rows are bounded- by ``_MAX_GENERIC_EVIDENCE`` and each file is ingested at most once.- """- if not self.run_dir.is_dir():- return- entitled = self._session_symbols | self.authorized_symbols- if not entitled:- return- room = _MAX_GENERIC_EVIDENCE- for path in sorted(self.run_dir.rglob("*.csv")):- if room <= 0:- return- try:- identity_key = f"{path.resolve()}:{path.stat().st_mtime_ns}"- except (OSError, ValueError):- continue- if identity_key in self._ingested_csvs:- continue- self._ingested_csvs.add(identity_key)- symbol = _symbol_from_csv_filename(path.stem)- if not symbol or symbol not in entitled:- continue- try:- with path.open("r", encoding="utf-8", errors="replace", newline="") as handle:- rows = list(csv.DictReader(handle))- except (OSError, UnicodeDecodeError, csv.Error):- continue- for row in rows:- if room <= 0:- return- if not isinstance(row, dict):- continue- timestamp = next(- (- str(row[key]).strip()- for key in row- if str(key).strip().casefold() in _CSV_DATE_COLUMNS- and row[key] not in (None, "")- ),- None,- )- for key, value in row.items():- field_name = _CSV_PRICE_COLUMNS.get(- str(key).strip().casefold().replace(" ", "_")- )- if field_name is None:- continue- numeric = _coerce_csv_number(value)- if numeric is None:- continue- self._evidence.append(- EvidenceRecord(- call_id=f"csv:{path.name}",- tool="bash",- symbol=symbol,- source="yfinance",- timestamp=timestamp,- field=field_name,- value=numeric,- status="observed",- currency=_infer_currency(symbol),- venue=_infer_venue(symbol),- )- )- room -= 1-- def _validate_identity(self, content: str) -> list[dict[str, Any]]:- """Validate aggregate state and listed/private contradictions."""- issues: list[dict[str, Any]] = []- status = self.identity_status- # Two conditions, both load-bearing.- #- # ``self._identities`` — a run that never named an instrument has no- # identity to get wrong. The trigger phrase is matched against the user- # message, so "什么是市盈率估值法?" set identity_required and then failed- # every draft it could ever produce, including the honest answer. This- # relaxation invents no licence to guess: a figure still has to survive- # ``_validate_price_claims``, and a figure attached to a symbol no tool- # handled still has to survive ``_validate_unsourced_symbols``.- #- # ``ambiguous`` is deliberately absent. A shortlist is an answer, which- # is why ``_RESOLUTION_INCOMPLETE_STATUSES`` already lets workflow- # selection proceed on it (#955) — but the final answer stayed blocked,- # so a screening run loaded its skill and was then refused a conclusion.- # Consumers remain blocked on ambiguous in ``authorize_tool_call``, so- # such a run still cannot fetch a quote to misattribute.- if (- self._identity_required- and self._identities- and status in {"unresolved", "conflicting", "invalidated"}- ):- issues.append(- {- "code": "identity_not_locked",- "status": status,- "message": f"Instrument identity is {status}; a final market conclusion requires locked identity.",- }- )- listed = [- record- for record in self._identities.values()- if record.status == "locked"- and record.instrument_type in {"listed_security", "fund"}- ]- if listed and _PRIVATE_ASSERTION_RE.search(content):- symbols = sorted(record.symbol for record in listed if record.symbol)- issues.append(- {- "code": "listed_identity_relabelled_private",- "symbols": symbols,- "message": (- f"Locked listed identity {', '.join(symbols)} was relabelled as private/unlisted "- "without a conflicting resolver result."- ),- }- )- return issues-- def _validate_unsourced_symbols(self, content: str) -> list[dict[str, Any]]:- """Reject figures attached to an instrument no tool in this run handled.-- This is the mechanically decidable half of "what the tools did not- return, you do not supply" (#886/#887). Naming a symbol is left alone —- prose may legitimately mention an index or a peer — but the moment a- clause pairs an unhandled canonical symbol with a figure, the figure has- no possible origin other than model memory.-- Args:- content: Candidate assistant answer.-- Returns:- One issue per distinct unsourced symbol carrying figures.- """- issues: list[dict[str, Any]] = []- reported: set[str] = set()- for line, line_offset in _lines_with_offsets(content):- for segment, span_start, span_end in _clause_spans(line, line_offset):- unknown = sorted(- symbol- for symbol in _scan_symbols(segment) - self._session_symbols - reported- if symbol.rsplit(".", 1)[0] not in self._session_symbol_roots- )- if not unknown or not self._numbers_without_dates_or_percent(segment):- continue- # Accept figures that are attributed to an external source- # (e.g., "The paper reports a Sharpe ratio of 1.8.") rather- # than model memory. Scoped to the clause: a line-level check- # would let a citation in one clause launder an invented- # sibling metric in the next.- if _ATTRIBUTION_RE.search(segment):- continue- for symbol in unknown:- reported.add(symbol)- issues.append(- {- "code": "unsourced_symbol_figures",- "symbol": symbol,- "claim": segment.strip()[:200],- "span": [span_start, span_end],- "message": (- f"No tool call in this session passed in or returned {symbol}, "- "yet the answer attaches figures to it. Retrieve it, or report "- "it as not retrieved."- ),- }- )- return issues-- def _validate_analysis_claims(self, content: str) -> list[dict[str, Any]]:- """Reject backtest/analysis metrics with no kind-scoped evidence.-- #1336: after failed or deduplicated market-data calls the model may- still present return-volatility / drawdown / probability figures as- measured facts. A metric figure is legitimate only when the run's- evidence contains the same *kind* of figure — recorded from a- completed analysis result (backtest artifacts, factor/shadow/quantlib- output) or from any successful tool's numeric output (e.g.- ``portfolio_risk_xray``, flattened into ``_evidence``). Kind scoping- is what keeps an observed price from standing in for an invented- volatility figure. Definitional prose ("夏普比率大于 1.0 通常被认为- 较好"), explicitly forward-looking forecasts, and categorical- historical-window facts without any window-producing analysis are- handled separately here.-- Args:- content: Candidate assistant answer.-- Returns:- One issue per metric-bearing clause or table cell.- """- issues: list[dict[str, Any]] = []- positions = _lines_with_offsets(content)- lines = [line for line, _ in positions]- consumed: set[int] = set()- price_records = self._comparable_price_records()- for header, rows, row_indices in self._pipe_tables(lines):- consumed.update(row_indices)- columns = [- (cell, _metric_kind_for_text(cell), bool(_FORECAST_FRAME_RE.search(cell)))- for cell in header- ]- has_kind_header = any(kind for _, kind, _ in columns)- for row, row_line_index in zip(rows, row_indices):- row_start = positions[row_line_index][1]- row_span = (row_start, row_start + len(lines[row_line_index]))- cells = row + [""] * (len(columns) - len(row))- if not has_kind_header:- # Generic header ("指标 | 数值", "Metric | Value"): a cell- # naming a metric kind is a row LABEL and claims exactly- # one adjacent value cell (right first — "label, value"- # order — then left, for value-first layouts). Validating- # every cell after the label would grab annotation columns- # ("备注 | 较去年提升 2%") that prose never attributes to- # the label; parity with the prose verdict is the bar.- row_kinds = [- (index, _metric_kind_for_text(cell))- for index, cell in enumerate(cells)- if _metric_kind_for_text(cell) is not None- ]- claimed: set[int] = set()- for label_index, row_kind in row_kinds:- # A label cell that smuggles its own measurement- # ("| 年化收益率 18.2% | - |") is prose-identical to- # "年化收益率为 18.2%" — validate the label's own- # numbers against its kind too.- self._check_table_cell(- cells[label_index], row_kind, cells[label_index], issues,- row_span, price_records,- )- # A forecast frame in the LABEL ("| 预计夏普比率 | 1.2 |")- # frames the claimed value clause-wide, exactly as prose- # exempts the whole clause and the metric-header path- # skips a forecast-framed column. Without this the generic- # path is stricter than both of its siblings.- label_is_forecast = bool(- _FORECAST_FRAME_RE.search(cells[label_index])- )- for value_index in (label_index + 1, label_index - 1):- if (- 0 <= value_index < len(cells)- and value_index not in claimed- and _metric_kind_for_text(cells[value_index]) is None- ):- claimed.add(value_index)- if label_is_forecast:- continue- self._check_table_cell(- cells[label_index], row_kind, cells[value_index], issues,- row_span, price_records,- )- continue- for (cell_text, kind, header_forecast), cell in zip(columns, cells):- if kind is None or header_forecast:- continue- self._check_table_cell(- cell_text, kind, cell, issues, row_span, price_records- )- for index, (line, line_offset) in enumerate(positions):- if index in consumed:- continue- line_symbol = self._symbol_for_claim(line, price_records)- for segment, span_start, span_end in _clause_spans(line, line_offset):- if _CATEGORICAL_WINDOW_RE.search(segment) and _NUMBER_RE.search(segment):- if not any(- entry.get("tool") in _ANALYSIS_WINDOW_TOOLS- for entry in self._analysis_completed- ):- match = _NUMBER_RE.search(segment)- issues.append(- {- "code": "analysis_claim_unavailable",- "claim": segment.strip()[:200],- "span": [span_start, span_end],- "value": match.group(0) if match else None,- "message": (- "No backtest completed in this session, yet the "- "answer states a categorical historical-window "- "fact. Mark the analysis as incomplete and omit "- "this claim."- ),- }- )- continue- if _DEFINITION_FRAME_RE.search(segment):- continue- # Attributed figures ("The paper reports a Sharpe of 1.8",- # or the marker in a neighbouring clause: "据研究显示,策略- # 年化收益 18.2%") are citations, not invented measurements- # — skip the gate.- if _ATTRIBUTION_RE.search(segment):- continue- values = self._measure_numbers(segment)- if not values:- continue- if not _ANALYSIS_METRIC_RE.search(segment):- continue- if _FORECAST_FRAME_RE.search(segment):- continue- kind = _metric_kind_for_text(segment)- unsupported = [- value- for value in values- if not self._analysis_value_observed(value, kind)- and not self._is_observed_price_figure(- value, price_records, line_symbol, segment- )- ]- if not unsupported:- continue- # A return figure may be arithmetic on sourced inputs rather- # than an invented backtest metric (#1338 review): an explicit- # formula anchored to observed values, or growth between two- # observed endpoints stated in the same line.- # A drawdown stated against an observed high ("较 5 月高点- # 1.053 元已回撤约 37%") is the same arithmetic on the same- # sourced endpoints, and was rejected as an invented backtest- # metric because only the return branch carried the exemption- # (owner-forwarded 159516.SZ run, 2026-09-09). Drawdown is- # compared by magnitude, as ``_analysis_value_observed`` does.- # Neither exemption is available to a STRATEGY-subject- # metric. A strategy's max drawdown is a property of an- # equity curve, and no arithmetic on two observed prints of- # the instrument is that curve: "回测显示该策略最大回撤 5.9%- # (从 1.180 跌至 1.110)" was released as grounded with no- # backtest in the session at all. Such a figure keeps the- # unchanged backtest-evidence requirement above.- if kind in {"return", "drawdown"} and not _STRATEGY_SUBJECT_RE.search(- segment- ):- if _DERIVATION_RE.search(segment):- # As in the price path: only the values the formula- # justifies are exempt, not every figure beside them.- # Scoped to the CLAUSE, which is where the claim- # itself was measured — a line-scoped exemption let- # "基于 40 × 1.171 = 46.84 计算,策略最大回撤 40%"- # ground the metric in the next clause.- justified = self._derivation_justified_values(- segment, price_records, line_symbol- )- unsupported = [- value- for value in unsupported- if not _matches_any(value, justified)- ]- if not unsupported:- continue- # The operand scan stays LINE-scoped: the endpoints of a- # move are routinely written in two clauses ("当前 0.666- # 元,较 5 月高点 1.053 元已回撤约 37%").- operands = self._observed_operands_in_line(- line, price_records, line_symbol- )- if len(operands) >= 2:- derived = self._returns_derived_from_observed(- unsupported,- price_records,- line_symbol,- operands=operands,- magnitude=kind == "drawdown",- )- # The endpoints themselves are grounded by the same- # exemption: "较高点 1.180 元已回撤约 6%" states the- # observed high beside the ratio it derives.- unsupported = [- value- for value in unsupported- if value not in derived- and not (- not str(value).endswith(("%", "%"))- and _matches_any(value, operands, rel=1e-9)- )- ]- if not unsupported:- continue- issues.append(- {- "code": "analysis_claim_unavailable",- "claim": segment.strip()[:200],- "span": [span_start, span_end],- "value": unsupported[0],- "kind": kind,- "message": (- "No supporting analysis evidence (a completed "- "backtest result or observed risk metric) exists for "- "this figure. Mark the analysis as incomplete and omit "- "these figures."- ),- }- )- return issues-- def _check_table_cell(- self,- label: str,- kind: str | None,- cell: str,- issues: list[dict[str, Any]],- span: tuple[int, int] | None = None,- price_records: Sequence[EvidenceRecord] = (),- ) -> None:- """Reject one table cell whose numeric value is an unsupported metric.-- Shared by the metric-headed and generic-header (label, value) table- paths. A forecast or definitional annotation exempts only that cell.-- Args:- label: The metric label the value is attached to (header cell or- row's first cell), for the issue claim text.- kind: The resolved metric kind, already derived from ``label``.- cell: One value cell to validate.- issues: Accumulator for ``analysis_claim_unavailable`` issues.- span: ``(start, end)`` of the table ROW inside the validated- answer. The claim text is the human-readable ``label: cell``,- which is not a substring of the draft ("| 最大回撤 | 12% |"),- so without the span the release path could never locate a- metric table and every metrics report fell back to the canned- refusal.- price_records: Comparable observed price evidence, so a cell that- merely restates observed closes ("| 峰值→当前 | 0.997 → 0.605 |")- is not reported as an invented drawdown figure and then cut- out of the released answer. Same rule as the prose path.- """- if kind is None:- return- values = GroundingLedger._measure_numbers(cell)- if not values:- return- # A forecast annotation inside the cell ("预计 12.4%") exempts only- # that cell, never its neighbours.- if _FORECAST_FRAME_RE.search(cell) or _DEFINITION_FRAME_RE.search(cell):- return- # A cell RESTATING endpoints ("| 峰值→当前 | 1.180 → 1.110 |") is not- # a metric figure, and cutting it out of the released answer removed- # two correctly quoted closes. The restatement shape is what the- # exemption is for, so it needs the cell to hold a PAIR: a single- # number in a metric cell IS that metric's value, and exempting it on- # numeric equality alone released "| 夏普比率 | 1.171 |" as grounded- # because 1.171 happened to be an observed close. On a $12.50 stock- # the collision is "| 最大回撤 | 12.5 |".- unsupported = [- value- for value in values- if not self._analysis_value_observed(value, kind)- and not (- len(values) >= 2- and self._matches_observed_price(value, price_records, None)- )- ]- if not unsupported:- return- issues.append(- {- "code": "analysis_claim_unavailable",- "claim": f"{label}: {cell}"[:200],- "span": list(span) if span else None,- "value": unsupported[0],- "kind": kind,- "message": (- "No supporting analysis evidence (a completed "- "backtest result or observed risk metric) exists "- "for this figure. Mark the analysis as incomplete "- "and omit these figures."- ),- }- )-- @staticmethod- def _measure_numbers(text: str) -> list[str]:- """Extract measurement-shaped numbers (decimal or percent) from a claim."""- masked = _LOCALIZED_DATE_RE.sub(" ", text)- masked = _DATE_RE.sub(" ", masked)- masked = _SHORT_DATE_RE.sub(" ", masked)- masked = _DASH_DATE_RE.sub(" ", masked)- return [- match.group(0).replace(" ", "").replace(",", "")- for match in _MEASURE_NUMBER_RE.finditer(masked)- ]-- @staticmethod- def _pipe_tables(- lines: Sequence[str],- ) -> list[tuple[list[str], list[list[str]], list[int]]]:- """Yield (header cells, row cells, row line indices) per pipe table."""- tables: list[tuple[list[str], list[list[str]], list[int]]] = []- index = 0- while index < len(lines):- if lines[index].count("|") < 2:- index += 1- continue- block_start = index- block: list[str] = []- while index < len(lines) and lines[index].count("|") >= 2:- block.append(lines[index])- index += 1- rows: list[list[str]] = []- row_indices: list[int] = []- for offset, block_line in enumerate(block[1:], start=1):- cells = GroundingLedger._table_cells(block_line)- if not cells or all(- _TABLE_SEPARATOR_RE.fullmatch(cell.strip()) for cell in cells- ):- continue- rows.append(cells)- row_indices.append(block_start + offset)- tables.append((GroundingLedger._table_cells(block[0]), rows, row_indices))- return tables-- def _analysis_value_observed(self, raw: str, kind: str | None) -> bool:- """Return True when a claim measurement matches kind-scoped evidence.-- Tools disagree on scale: ``compute_risk_xray`` returns fractions- (annualized_vol 0.182, max_drawdown -0.094) while answers quote- percents (18.2%, -9.4%). Try both the value and its percent scaling- so an observed 0.182 grounds an 18.2% claim and vice versa. Drawdown- sign conventions disagree too (positive vs negative fraction), so- magnitude is compared for that kind. Only evidence of the claim's own- kind counts: an observed price never grounds a volatility figure.- """- try:- value = float(raw.replace("%", "").replace("%", "").replace(",", ""))- except ValueError:- return True- observed: list[float] = []- for record in self._analysis_metrics:- if record.get("metric") == kind and record.get("value") is not None:- observed.append(float(record["value"]))- for record in self._evidence:- if record.status != "observed" or record.value is None:- continue- if _metric_kind_for_path(record.field) != kind:- continue- observed.append(float(record.value))- candidates = {value, value / 100.0}- if kind == "drawdown":- candidates |= {abs(value), abs(value) / 100.0}-- def close(candidate: float, item: float) -> bool:- return abs(candidate - item) <= max(abs(item) * 0.005, 1e-9)-- return any(close(candidate, item) for candidate in candidates for item in observed)-- def _is_observed_price_figure(- self,- raw: str,- records: Sequence[EvidenceRecord],- symbol: str | None,- text: str,- ) -> bool:- """Whether a figure in an analysis clause is literally an observed price.-- ``_validate_analysis_claims`` reports the FIRST unmatched number in a- clause that mentions a metric, and an observed close sharing a clause- with an ungrounded metric was that number: "最新收盘 1.171 元且策略最大- 回撤 12%" reported 1.171, so the release path cut the correctly quoted- close and footnoted it as unverifiable. A value the ledger observed is- not an invented backtest metric — its own check is- ``_compare_price_claim``, which compares any price-word figure against- observed OHLC at the 0.5% band. A percent-written figure is never- exempted here, so every drawdown / return / volatility / win-rate- percentage keeps the full analysis check.-- Numeric equality is not enough on its own. A run holds hundreds of- observed OHLC values spanning the instrument's price range, so ANY- percent-free metric written in that range collides with one:- "策略夏普比率 1.171" and "策略最大回撤 1.171" were released as grounded- against an observed close, with no backtest in the session. The figure- must also be WRITTEN as a price — a price word ahead of it or a- currency unit glued to it — which is exactly the shape that has its- own check in ``_compare_price_claim``.-- Args:- raw: A figure as ``_measure_numbers`` returns it.- records: Comparable observed price evidence.- symbol: Symbol resolved for the line, if any.- text: The clause the figure was written in.-- Returns:- True when the figure is written without a percent sign, reads as a- price in its clause, and equals an observed price value for this- symbol.- """- figure = str(raw).strip()- if not _figure_reads_as_a_price(text, figure):- return False- return self._matches_observed_price(figure, records, symbol)-- def _matches_observed_price(- self,- raw: str,- records: Sequence[EvidenceRecord],- symbol: str | None,- ) -> bool:- """Whether a percent-free figure equals an observed price value.-- Args:- raw: A figure as ``_measure_numbers`` returns it.- records: Comparable observed price evidence.- symbol: Symbol resolved for the claim, if any.-- Returns:- True when the figure carries no percent sign and matches evidence.- """- figure = str(raw).strip()- if figure.endswith(("%", "%")):- return False- candidates = list(records)- if symbol:- candidates = [record for record in candidates if record.symbol == symbol]- observed = [- float(record.value) for record in candidates if record.value is not None- ]- return _matches_any(figure, observed, rel=1e-9)-- def _observed_operands_in_line(- self,- line: str,- records: Sequence[EvidenceRecord],- symbol: str | None,- ) -> list[float]:- """Observed values that literally appear as numbers in this clause.-- This is the structural half of the derivation exemption. Keying it on- a growth PHRASE ("从…到" / "from…to") made the gate stricter for every- wording the list happened to miss, which is the same per-language- drift that ``test_grounding_language_parity`` exists to stop: the- Chinese "第一日收盘 100.0 美元,第二日收盘 112.4 美元,收益率 12.4%"- states the identical derivation and was rejected. Requiring the- operands themselves to be present and sourced is language-independent- and strictly narrower than a phrase list, because a bare- "cumulative return of 12.4%" carries no operands at all.- """- candidates = [record for record in records if record.value is not None]- if symbol:- candidates = [record for record in candidates if record.symbol == symbol]- observed = {float(record.value) for record in candidates}- if not observed:- return []- present: set[float] = set()- for raw in self._numbers_without_dates_or_percent(line):- try:- value = float(raw)- except (TypeError, ValueError):- continue- for candidate in observed:- if abs(value - candidate) <= max(abs(candidate) * 1e-9, 1e-9):- present.add(candidate)- return sorted(present)-- def _returns_derived_from_observed(- self,- claimed: Sequence[str],- records: Sequence[EvidenceRecord],- symbol: str | None,- *,- operands: Sequence[float] | None = None,- magnitude: bool = False,- ) -> set[str]:- """Return the figures that equal growth between observed endpoints.-- #1338 review: "AAPL.US 从 2026-08-03 的 100.0 涨到 2026-09-02 的- 112.4,区间收益率为 12.4%" states arithmetic on sourced inputs. Only- a match against a pair of observed values grounds the figure; the- caller must already have verified the from/to frame, so a bare- unanchored return claim never reaches here.-- The match tolerates the precision the figure was WRITTEN at: "约 37%"- for a derived 36.75% asserts that the value rounds to 37, and the flat- ±0.5% relative band (±0.18 points there) rejected every integer-percent- rounding a model makes. Half a unit of the last written digit is the- bound, so "37%" accepts 36.5–37.5 and "36.8%" accepts 36.75–36.85; a- figure that is simply wrong ("40%") is as far away as before.-- Args:- claimed: Raw figures from the clause, as ``_measure_numbers`` returns them.- records: Observed evidence the operands may come from.- symbol: Symbol the clause names, if any.- operands: Observed values literally present in the clause.- magnitude: Compare absolute values (drawdown sign conventions differ).-- Returns:- The subset of ``claimed`` the endpoint arithmetic justifies. It- used to be one bool for the whole clause, and the caller skipped- every figure beside the justified one: "at 0.666 down about 37%- from the 1.053 May high with a max drawdown of 60%" released the- 60% because the 37% checked out.- """- if operands is not None:- observed = sorted(set(operands))- else:- candidates = [record for record in records if record.value is not None]- if symbol:- candidates = [- record for record in candidates if record.symbol == symbol- ]- observed = sorted({float(record.value) for record in candidates})- if len(observed) < 2:- return set()- values: list[tuple[str, float, float, bool]] = []- for raw in claimed:- raw_text = str(raw).strip()- text = raw_text.rstrip("%%")- try:- value = float(text)- except ValueError:- continue- decimals = len(text.split(".", 1)[1]) if "." in text else 0- values.append((str(raw), value, 0.5 * 10.0 ** (-decimals), raw_text != text))-- def close(value: float, derived: float, half_unit: float) -> bool:- if magnitude:- # A drawdown is a fall. Taking absolute values so "回撤 37%"- # can match a derived -36.75% also made the INVERSE- # derivation match: the same two endpoints read low→high give- # +58.11%, and "最大回撤约 58%" was released as grounded- # (attack2 probe, 2026-09-09). Only the falling direction may- # ground a drawdown.- if derived > 0:- return False- value, derived = abs(value), abs(derived)- return abs(value - derived) <= max(abs(derived) * 0.005, half_unit, 1e-9)-- justified: set[str] = set()- for base in observed:- for target in observed:- if target == base:- continue- derived = (target - base) / base- for raw, value, half_unit, is_percent in values:- # ``half_unit`` is half a unit of the last digit the figure- # was WRITTEN with, so it is only meaningful against the- # derivation expressed in those same units. A figure- # carrying "%" is percentage points and is compared only- # against ``derived * 100``; running it against the- # fraction too gave an integer percent a 0.5 band in- # FRACTION units — 50 percentage points — and "区间收益率- # 约 0%" validated against a real +58% move (attack4- # probe, 2026-09-09). A bare figure stays ambiguous and is- # tried both ways, each against its own consistent band.- # A bare figure always carries a decimal point —- # ``_MEASURE_NUMBER_RE`` extracts an integer only with a- # percent sign on it — so the fraction reading is never- # taken with a 0.5 half unit (which would be 50- # percentage points wide).- if not is_percent and close(value, derived, half_unit):- justified.add(raw)- if close(value, derived * 100.0, half_unit):- justified.add(raw)- return justified-- @staticmethod- def _occurrence_is_derived(- segment: str,- formulas: Sequence[tuple[int, int, list[float], float]],- value: float,- start: int,- end: int,- ) -> bool:- """Whether this figure, HERE, is part of a formula that justifies it.-- Two things are decided per occurrence rather than per value.-- The position: a number is exempt only where it sits inside the- formula. "建议买入价 0.95 元(0.95 × 1.171 = 1.11245 参考)" is arithmetic- that derives nothing, and under a value-scoped exemption the entry- price outside the bracket inherited the exemption its own copy inside- the bracket earned.-- The role: a formula's RESULT is a number the answer proposes, which is- legitimate for an entry price and never legitimate for a market print.- "2026-06-23 收盘价 = 1.171 × 0.80 = 0.937" claims a close the ledger- holds as 1.137, and the exemption released it. Under an observation- label the operands stay exempt and the result is compared.-- Args:- segment: The clause the figure was found in.- formulas: ``_derivation_formulas`` output for that clause.- value: The figure.- start: Where the figure starts in ``segment``.- end: Where it ends.-- Returns:- True when the occurrence may skip the price comparison.- """- for formula_start, formula_end, inputs, result in formulas:- if not (formula_start <= start and end <= formula_end):- continue- if _matches_any(value, inputs):- return True- if _matches_any(value, [result]) and not _labels_its_result_observed(- segment, formula_start- ):- return True- return False-- def _validate_price_claims(self, content: str) -> list[dict[str, Any]]:- """Check Markdown OHLC tables and price prose against observed records.-- Comparison runs against every observed quote in the run, whichever tool- produced it. The provenance demands below stay keyed on ``get_market_data``- evidence, whose ``source``/``currency``/venue fields are authoritative;- a generic tool's fallback source is its own name, and requiring the- answer to spell that out would reject correct prose.- """- issues, table_lines = self._validate_price_tables(content)- records = self._comparable_price_records()- # A report names its subject once and then writes prose about it. Both- # narrower scopes are tried first; this is the last resort, and it only- # resolves when the whole answer names exactly one evidence symbol.- document_symbol = self._symbol_for_claim(content, records)- has_price_claim = any(- self._numbers_without_dates_or_percent(line)- for index, line in enumerate(content.splitlines())- if index in table_lines- )- for index, (line, line_offset) in enumerate(_lines_with_offsets(content)):- if index in table_lines or "|" in line:- continue- line_symbol = self._symbol_for_claim(line, records)- for segment, span_start, span_end in _clause_spans(line, line_offset):- if not _PRICE_CONTEXT_RE.search(segment):- continue- values = self._direct_price_values(segment)- if not values:- continue- has_price_claim = True- symbol = (- self._symbol_for_claim(segment, records)- or line_symbol- or document_symbol- )- # Only the formula's own operands and result are exempt, at- # the position where they sit; a figure riding along in the- # same clause is still compared.- formulas = self._derivation_formulas(segment, records, symbol)- # NO attribution exemption here, deliberately. A paper's- # Sharpe is a figure this run could never have observed, so- # citing it is legitimate; a PRICE is exactly what this run- # does observe, so "analysts say TSLA.US last traded at- # 412.35" is the laundering shape this gate exists to catch —- # adding a citation subject must not buy a fabricated quote a- # way through. The exemption stays in the analysis gate only.- #- # An indicator reading is admissible evidence only for a- # LEVEL claim; a clause claiming a market print is answered by- # OHLC evidence alone.- indicator_admissible = bool(- _PRICE_LEVEL_WORD_RE.search(segment)- ) and not _OBSERVED_PRICE_WORD_RE.search(segment)- for value, value_start, value_end in values:- if self._occurrence_is_derived(- segment, formulas, value, value_start, value_end- ):- continue- issue = self._compare_price_claim(- value=value,- records=records,- field_name=None,- date_value=None,- symbol=symbol,- claim=segment.strip(),- span=(span_start, span_end),- indicator_admissible=indicator_admissible,- )- if issue:- issues.append(issue)- market_records = self._price_records()- if has_price_claim and market_records:- issues.extend(self._validate_price_provenance(content, market_records))- return self._dedupe_issues(issues)-- @staticmethod- def _symbol_for_claim(- content: str,- records: Sequence[EvidenceRecord],- ) -> str | None:- """Return one canonical evidence symbol explicitly named in a claim."""- known = {record.symbol for record in records if record.symbol}- matches = {- _normalize_symbol(match.group(0))- for match in _CANONICAL_SYMBOL_RE.finditer(content)- if _normalize_symbol(match.group(0)) in known- }- return next(iter(matches)) if len(matches) == 1 else None-- def _validate_price_provenance(- self,- content: str,- records: Sequence[EvidenceRecord],- ) -> list[dict[str, Any]]:- """Require canonical symbol, actual source, and quote currency in output."""- issues: list[dict[str, Any]] = []- folded = content.casefold()- symbols = sorted({record.symbol for record in records if record.symbol})- # ``_scan_symbols`` canonicalizes, so an answer that writes Shanghai as- # ``600519.SS`` still surfaces the ``600519.SH`` identity it names.- written = _scan_symbols(content)- mentioned = [- symbol- for symbol in symbols- if symbol in written or symbol.casefold() in folded- ]- if not mentioned:- issues.append(- {- "code": "canonical_symbol_not_surfaced",- "symbols": symbols,- "message": (- "A price claim must surface its locked canonical symbol and venue suffix."- ),- }- )- target_symbols = set(mentioned or (symbols if len(symbols) == 1 else []))- target_records = [- record- for record in records- if not target_symbols or record.symbol in target_symbols- ]-- sources = sorted(- {- record.source- for record in target_records- if record.source and record.source.casefold() not in {"auto", "unknown"}- }- )- missing_sources = [- source- for source in sources- if not any(- alias in folded- for alias in _SOURCE_ALIASES.get(- source.casefold(), (source.casefold(),)- )- )- ]- if missing_sources:- issues.append(- {- "code": "data_source_not_surfaced",- "sources": missing_sources,- "message": (- "Price claims must name the actual data source: "- + ", ".join(missing_sources)- + "."- ),- }- )-- currencies = sorted(- {record.currency for record in target_records if record.currency}- )- missing_currencies = [- currency- for currency in currencies- if not self._currency_is_surfaced(currency, content)- ]- if missing_currencies:- issues.append(- {- "code": "currency_not_surfaced",- "currencies": missing_currencies,- "message": (- "Price claims must name their quote currency: "- + ", ".join(missing_currencies)- + "."- ),- }- )- return issues-- @staticmethod- def _currency_is_surfaced(currency: str, content: str) -> bool:- """Return whether a quote currency or an unambiguous alias is visible."""- folded = content.casefold()- code = currency.upper()- tokens = _CURRENCY_ALIASES.get(code, (currency.casefold(),))- if any(token.casefold() in folded for token in tokens):- return True- return code == "CNY" and bool(_BARE_YUAN_RE.search(content))-- def _validate_price_tables(- self,- content: str,- ) -> tuple[list[dict[str, Any]], set[int]]:- """Validate field/date-specific claims in Markdown OHLC tables."""- positions = _lines_with_offsets(content)- lines = [line for line, _ in positions]- issues: list[dict[str, Any]] = []- consumed: set[int] = set()- index = 0- records = self._comparable_price_records()- while index + 1 < len(lines):- header = self._table_cells(lines[index])- separator = self._table_cells(lines[index + 1])- if not header or not separator or len(header) != len(separator):- index += 1- continue- if not all(_TABLE_SEPARATOR_RE.match(cell.replace(" ", "")) for cell in separator):- index += 1- continue- field_columns = {- position: _TABLE_FIELD_ALIASES[cell.strip().casefold()]- for position, cell in enumerate(header)- if cell.strip().casefold() in _TABLE_FIELD_ALIASES- }- if not field_columns:- index += 1- continue- date_column = next(- (position for position, cell in enumerate(header) if cell.strip().casefold() in _DATE_HEADERS),- None,- )- symbol_column = next(- (position for position, cell in enumerate(header) if cell.strip().casefold() in _SYMBOL_HEADERS),- None,- )- consumed.update({index, index + 1})- row_index = index + 2- while row_index < len(lines):- row = self._table_cells(lines[row_index])- if not row or len(row) != len(header):- break- consumed.add(row_index)- date_value = row[date_column].strip() if date_column is not None else None- symbol = _normalize_symbol(row[symbol_column]) if symbol_column is not None else None- for position, field_name in field_columns.items():- values = self._numbers_without_dates_or_percent(row[position])- if len(values) != 1:- continue- row_start = positions[row_index][1]- issue = self._compare_price_claim(- value=values[0],- records=records,- field_name=field_name,- date_value=date_value,- symbol=symbol,- claim=row[position].strip(),- # A table cell's claim text is a bare number, so it- # can never be located by substring search — "1.10"- # matched inside "21.10 亿元" and rewrote an untouched- # turnover figure into "2(略※)". The row's own span- # is the anchor; the value inside it is what is cut.- span=(row_start, row_start + len(lines[row_index])),- )- if issue:- issues.append(issue)- row_index += 1- index = max(row_index, index + 1)- return issues, consumed-- @staticmethod- def _table_cells(line: str) -> list[str]:- """Split one Markdown table row, or return an empty list."""- if "|" not in line:- return []- stripped = line.strip()- if stripped.startswith("|"):- stripped = stripped[1:]- if stripped.endswith("|"):- stripped = stripped[:-1]- return [cell.strip() for cell in stripped.split("|")]-- def _compare_price_claim(- self,- *,- value: float,- records: list[EvidenceRecord],- field_name: str | None,- date_value: str | None,- symbol: str | None,- claim: str,- span: tuple[int, int] | None = None,- indicator_admissible: bool = False,- ) -> dict[str, Any] | None:- """Compare one unlabelled observed claim to the closest evidence value.-- Args:- value: The figure the answer states.- records: Comparable observed price evidence.- field_name: OHLC field the claim is keyed to (table column), if any.- date_value: Trade date the claim is keyed to, if any.- symbol: Symbol explicitly resolved for the claim, if any.- claim: Clause or cell text, for the issue message.- span: ``(start, end)`` of the claim inside the validated answer.- indicator_admissible: The prose clause states a price LEVEL- (支撑位 / 均线 / bollinger band), the one claim an indicator- reading may answer. Every other price claim — a named OHLC- field, a spot quote, a proposed entry — is compared against- OHLC evidence only, which is the rule the table path already- applies by filtering on ``field_name``. The table path passes- a ``field_name`` for every cell it validates and so leaves- this at its default.- """- resolved_symbol = symbol- candidates = records- if symbol:- candidates = [record for record in candidates if record.symbol == symbol]- symbols = sorted({record.symbol for record in candidates if record.symbol})- # An indicator reading is symbol-bound in a way an OHLC bar's union is- # not. With evidence for two instruments and a clause naming neither,- # 562500's sma_20 grounded "600519.SH … 其均线在 1.150 元"; the union- # below was argued for OHLC quotes, not for a derived level attached- # to one symbol. Drop indicator records whenever the claim's symbol- # was not explicitly resolved and the run holds more than one.- if resolved_symbol is None and len({r.symbol for r in records if r.symbol}) > 1:- candidates = [record for record in candidates if record.field != "indicator"]- if not indicator_admissible:- candidates = [record for record in candidates if record.field != "indicator"]- if not symbol and len(symbols) == 1:- symbol = symbols[0]- # An unattributed claim used to be rejected outright once the run held- # evidence for more than one symbol. That is every comparison report:- # "Apple's closing price was 313.33 USD. Microsoft closed higher." names- # its subject by company name, and the clause was refused although the- # value was exactly the observed close sitting in evidence. Such a claim- # is now checked against the union of the observed quotes instead, so a- # number the run never observed is still caught below — it simply has to- # match nothing at all rather than nothing under one chosen symbol.- if field_name:- candidates = [record for record in candidates if record.field == field_name]- if date_value:- candidates = [- record- for record in candidates- if record.timestamp- and _timestamp_matches_claim_date(record.timestamp, date_value)- ]- if not candidates:- return {- "code": "numeric_claim_unavailable",- "claim": claim,- "span": list(span) if span else None,- "value": value,- "symbol": symbol,- "field": field_name,- "date": date_value,- "message": f"Price claim {value:g} has no matching observed tool evidence.",- }- observed = [float(record.value) for record in candidates if record.value is not None]- if any(abs(value - item) <= max(abs(item) * 0.005, 1e-9) for item in observed):- return None- return {- "code": "numeric_claim_conflict",- "claim": claim,- "span": list(span) if span else None,- "value": value,- "symbol": symbol,- "field": field_name,- "date": date_value,- "observed_min": min(observed),- "observed_max": max(observed),- "source_tool_call_ids": sorted({record.call_id for record in candidates}),- "message": (- f"Price claim {value:g} conflicts with observed {field_name or 'OHLC'} "- f"evidence {min(observed):g}–{max(observed):g}."- ),- }-- def _price_records(self) -> list[EvidenceRecord]:- """Return observed OHLC/price evidence only."""- return [- record- for record in self._evidence- if record.status == "observed"- and record.field in _PRICE_FIELDS- and record.value is not None- ]-- def _comparable_price_records(self) -> list[EvidenceRecord]:- """Return every observed quote a numeric claim may be checked against.-- ``_price_records`` only sees fields already named ``open``/``close``/…,- which in practice means ``get_market_data``. Quotes returned by the- other market-sensitive tools are re-keyed onto the same canonical field- so the contradiction check compares like with like instead of reporting- the claim as unevidenced.-- Returns:- Observed price evidence with canonical ``field`` values.- """- records = self._price_records()- already_counted = {id(record) for record in records}- for record in self._evidence:- if id(record) in already_counted:- continue- if record.status != "observed" or record.value is None:- continue- field_name = _price_field_for_path(record.field)- if field_name is None:- if _is_price_denominated_indicator(record.field):- records.append(replace(record, field="indicator"))- continue- records.append(replace(record, field=field_name))- return records-- @staticmethod- def _masked_candidate_text(text: str) -> str:- """Mask every non-price digit run, preserving string length and offset.-- Each mask match is replaced by an equal-length run of spaces, so a- number's offset in the returned string is its offset in ``text`` — the- structural price-claim scan needs that alignment.- """- masked = text- for pattern in (- _MD_LIST_ITEM_RE,- _RATE_FORMULA_IDENTITY_RE,- _CANONICAL_SYMBOL_RE,- _LOCALIZED_DATE_RE,- _DATE_RE,- _SHORT_DATE_RE,- _DASH_DATE_RE,- _PERCENT_RANGE_RE,- _PERCENTAGE_POINT_RE,- _ORDER_LEVEL_RE,- _AGGREGATE_AMOUNT_RE,- _LABELLED_SCORE_RE,- _INDICATOR_VALUE_RE,- _SIGNAL_VALUE_RE,- _PROSPECTIVE_LEVEL_RE,- _REFERENCE_LEVEL_RE,- _SINCE_REFERENCE_RE,- _LINE_REFERENCE_RE,- _NUMBERED_HEADING_RE,- _RATIO_RE,- _FX_RATE_RE,- _QUANTITY_WITH_UNIT_RE,- ):- masked = pattern.sub(lambda m: " " * (m.end() - m.start()), masked)- return masked-- @staticmethod- def _numbers_without_dates_or_percent(text: str) -> list[float]:- """Extract the numbers in a claim that could plausibly be prices.-- Digits that belong to a canonical symbol, a calendar date, an aggregate- amount, a labelled score, a named indicator reading, a unit-bearing- quantity, or a percentage are masked first. Left unmasked they are- compared against observed OHLC ranges and reject a correct draft:- ``000543.SZ`` alone contributes 543, and a well-formed verdict line- contributes its confidence score and every moving-average window it- names (#1001).-- Args:- text: One claim segment or table cell.-- Returns:- Candidate price values, in order of appearance.- """- masked = GroundingLedger._masked_candidate_text(text)- values: list[float] = []- for match in _NUMBER_RE.finditer(masked):- tail = masked[match.end() :].lstrip()- if tail.startswith(("%", "%")):- continue- try:- values.append(float(match.group(0).replace(",", "")))- except ValueError:- continue- return values-- @staticmethod- def _direct_price_values(text: str) -> list[tuple[float, int, int]]:- """Numbers in a price segment that read as asserted observed values.-- Returned as ``(value, start, end)``: the masking that decides which- digits are candidates preserves length, so each offset is the number's- offset in ``text``. The caller needs the position, not only the value —- a derivation exempts the occurrence sitting inside it, not every copy- of the same number in the clause.-- ``_numbers_without_dates_or_percent`` returns every non-masked number;- this further drops numbers that are formula operands rather than claims- (#1354). For each surviving number, the span between the nearest- preceding price-context word and the number decides:-- * a sentence boundary (``. ``/``! ``/``? ``) in the span — the number- belongs to a later sentence the price word cannot reach ("close was- 210. In 2024 …" must not claim 2024);- * otherwise, a closed formula marker in the span turns the number into- an operand, unless an observation binder ("was", "at", 报收/收于/…) after- the last marker re-attaches it to the price word.-- "close/SMA50 > 1" and "close above SMA50 and was 2500" are decided in- opposite directions by the binder; "close was 2500" (no marker) stays- a claim either way.- """- price_words = list(_PRICE_CONTEXT_RE.finditer(text))- masked = GroundingLedger._masked_candidate_text(text)- values: list[tuple[float, int, int]] = []- for match in _NUMBER_RE.finditer(masked):- tail = masked[match.end() :].lstrip()- if tail.startswith(("%", "%")):- continue- try:- value = float(match.group(0).replace(",", ""))- except ValueError:- continue- preceding = [w for w in price_words if w.end() <= match.start()]- if preceding:- span = text[preceding[-1].end() : match.start()]- if _SENTENCE_BOUNDARY_RE.search(span):- continue- markers = list(_FORMULA_MARKER_RE.finditer(span))- if markers and not _OBSERVATION_BINDER_RE.search(- span[markers[-1].end() :]- ):- continue- values.append((value, match.start(), match.end()))- return values-- def _derivation_formulas(- self,- text: str,- records: Sequence[EvidenceRecord],- symbol: str | None,- ) -> list[tuple[int, int, list[float], float]]:- """Return every arithmetically valid, observation-anchored formula.-- Each entry is ``(start, end, operands, result)`` — the formula's own- character span inside ``text``, the operands it consumes and the result- it produces. The span is what makes the exemption safe. A value-scoped- exemption ("this number equals something a formula justifies") let a- figure be exempt EVERYWHERE in the clause once it appeared anywhere in- an equation, and a model told by the correction prompt to show its- arithmetic can satisfy that with arithmetic that derives nothing:- "建议买入价 0.95 元(0.95 × 1.171 = 1.11245 参考)" is true and released- an entry price 19% below every observed bar. The occurrence inside the- formula is exempt; the one beside it is compared like any other claim.-- There is no keyword or shape precondition. A `基于` / `based on` was- once required and an added `_ARITHMETIC_EQUATION_RE` relaxed it to- "any two-operand equation"; both are subsumed by what decides below —- a result separator, a parseable arithmetic run of at least two- operands (``_evaluate_formula``), an input matching observed evidence,- and a result that is correct. Deleting the regex changed no verdict in- the suite and removes one entry from the regex catalogue.-- Args:- text: The clause (or line) to inspect.- records: Comparable observed price evidence.- symbol: Symbol resolved for the claim, if any.-- Returns:- ``(start, end, operands, result)`` per valid formula, in order.- """- candidates = list(records)- if symbol:- candidates = [record for record in candidates if record.symbol == symbol]- candidate_symbols = {record.symbol for record in candidates if record.symbol}- if not symbol and len(candidate_symbols) > 1:- return []- observed = [- float(record.value) for record in candidates if record.value is not None- ]- if not observed:- return []-- formulas: list[tuple[int, int, list[float], float]] = []- for equals in _RESULT_SEPARATOR_RE.finditer(text):- # An indicator identifier carries digits ("SMA20", "MA5"); left in- # place they leak into the arithmetic run ("20 1.150 × 0.95") and- # the formula fails to parse, so a derivation from an observed- # moving average was never accepted. The blanking is- # LENGTH-PRESERVING because the offsets below are the exemption's- # anchor: collapsing "SMA20" to one space shifted every span after- # it and the formula was excluded from its own protection.- prefix = _INDICATOR_IDENTIFIER_RE.sub(- lambda match: " " * (match.end() - match.start()),- text[: equals.start()],- )- left = re.search(r"([0-9.,+\-*/×÷()\s]+)$", prefix)- right = re.match(- r"\s*([-+]?(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?)",- text[equals.end() :],- )- if not left or not right:- continue- evaluated = self._evaluate_formula(left.group(1))- if evaluated is None:- continue- computed, inputs = evaluated- try:- claimed = float(right.group(1).replace(",", ""))- except ValueError:- continue- if not any(- abs(item - value) <= max(abs(value) * 0.005, 1e-9)- for item in inputs- for value in observed- ):- continue- if abs(computed - claimed) <= max(abs(computed) * 0.005, 1e-9):- formulas.append(- (left.start(1), equals.end() + right.end(), inputs, claimed)- )- return formulas-- def _derivation_justified_values(- self,- text: str,- records: Sequence[EvidenceRecord],- symbol: str | None,- ) -> list[float]:- """Every operand and result of every valid formula in ``text``.-- The flat form, for the callers that only ask "is this figure one a- formula here justifies" without a position to check it at.- """- justified: list[float] = []- for _, _, inputs, result in self._derivation_formulas(text, records, symbol):- justified.extend(inputs)- justified.append(result)- return justified-- @staticmethod- def _evaluate_formula(expression: str) -> tuple[float, list[float]] | None:- """Evaluate a numeric ``+ - * /`` expression without executing code."""- normalized = expression.replace("×", "*").replace("÷", "/").replace(",", "").strip()- try:- tree = ast.parse(normalized, mode="eval")- except (SyntaxError, ValueError):- return None- inputs: list[float] = []-- def visit(node: ast.AST) -> float:- if isinstance(node, ast.Expression):- return visit(node.body)- if isinstance(node, ast.Constant) and _is_number(node.value):- value = float(node.value)- inputs.append(value)- return value- if isinstance(node, ast.UnaryOp) and isinstance(node.op, (ast.UAdd, ast.USub)):- value = visit(node.operand)- return value if isinstance(node.op, ast.UAdd) else -value- if isinstance(node, ast.BinOp) and isinstance(- node.op,- (ast.Add, ast.Sub, ast.Mult, ast.Div),- ):- left_value = visit(node.left)- right_value = visit(node.right)- if isinstance(node.op, ast.Add):- return left_value + right_value- if isinstance(node.op, ast.Sub):- return left_value - right_value- if isinstance(node.op, ast.Mult):- return left_value * right_value- if right_value == 0:- raise ValueError("division by zero")- return left_value / right_value- raise ValueError("unsupported formula")-- try:- value = visit(tree)- except (TypeError, ValueError, ZeroDivisionError, OverflowError):- return None- if len(inputs) < 2 or not math.isfinite(value):- return None- return value, inputs-- @staticmethod- def _dedupe_issues(issues: list[dict[str, Any]]) -> list[dict[str, Any]]:- """Remove duplicate validator findings while preserving order."""- unique: list[dict[str, Any]] = []- seen: set[str] = set()- for issue in issues:- key = json.dumps(issue, sort_keys=True, ensure_ascii=False, default=str)- if key in seen:- continue- seen.add(key)- unique.append(issue)- return unique---__all__ = [- "GROUNDING_ARTIFACT",- "GroundingLedger",- "IdentityConstraint",- "IdentityRecord",- "ResolutionContext",- "ToolAuthorization",- "ValidationResult",-]diff --git a/agent/src/agent/grounding/__init__.py b/agent/src/agent/grounding/__init__.pynew file mode 100644index 000000000..ca8922b88--- /dev/null+++ b/agent/src/agent/grounding/__init__.py@@ -0,0 +1,45 @@+"""Run-scoped identity and numeric evidence gates for the main agent loop.++The language model remains responsible for research and explanation, but three+facts are structural rather than advisory:++* a market-data consumer may only use an identity that was locked before the+ current assistant tool-call batch started;+* a final price claim may not contradict the full, untruncated tool result; and+* a figure may not be attached to an instrument that no tool call in this run+ ever passed in or returned.++Those are the mechanically decidable parts of the agent's output principles.+The rest of that contract — "state the as-of", "analysis, not advice", "refuse+out loud" — stays in the system prompt on purpose: see+``policies._validate_price_claims`` and the package tests for why a regex gate+on them rejects correct answers.++The package deliberately contains no provider or tool-registry dependencies so+its state machine and final-answer checks remain deterministic and testable.+The split follows the data flow: :mod:`identity` locks what a number is about,+:mod:`evidence` records what the run actually observed, :mod:`figures` finds+the numbers in a draft, :mod:`policies` decides whether each one is grounded,+:mod:`release` turns a rejection into a correction or a discounted release, and+:mod:`ledger` is the facade the agent loop drives.+"""++from __future__ import annotations++from src.agent.resolution_context import IdentityConstraint, ResolutionContext++from src.agent.grounding.identity import IdentityRecord, ToolAuthorization+from src.agent.grounding.evidence import EvidenceRecord+from src.agent.grounding.policies import ValidationResult+from src.agent.grounding.ledger import GROUNDING_ARTIFACT, GroundingLedger++__all__ = [+ "GROUNDING_ARTIFACT",+ "EvidenceRecord",+ "GroundingLedger",+ "IdentityConstraint",+ "IdentityRecord",+ "ResolutionContext",+ "ToolAuthorization",+ "ValidationResult",+]diff --git a/agent/src/agent/grounding/evidence.py b/agent/src/agent/grounding/evidence.pynew file mode 100644index 000000000..656b2a62e--- /dev/null+++ b/agent/src/agent/grounding/evidence.py@@ -0,0 +1,956 @@+"""Evidence intake: what a tool result is allowed to ground.++Every observed number the gate can validate against enters through this module+— market-data rows, registered indicator leaves, backtest metrics, run-dir CSVs+and generic numeric leaves. The kind map is keyed on TOOL FIELD NAMES, not on+natural language.+"""++from __future__ import annotations++import csv+import json+import math+import re+from dataclasses import dataclass, replace+from pathlib import Path+from typing import Any, Mapping++from src.agent.grounding.identity import (+ _infer_currency,+ _infer_venue,+ _normalize_symbol,+ _utc_now,+)++_PRICE_FIELDS = {"open", "high", "low", "close", "adj_close", "price"}+++_TIMESTAMP_FIELDS = ("trade_date", "date", "datetime", "timestamp", "time", "index")+++_MAX_GENERIC_EVIDENCE = 2_000+++# CSV columns (case-insensitive) accepted from OHLC files the run wrote via+# bash+yfinance, and their canonical price-field names. Everything else in the+# file (Volume, Adj Close, etc.) is deliberately ignored so the contradiction+# check does not gain values it would be willing to accept.+_CSV_PRICE_COLUMNS = {+ "open": "open",+ "high": "high",+ "low": "low",+ "close": "close",+ "price": "price",+}+++_CSV_DATE_COLUMNS = {"date", "datetime", "trade_date", "timestamp", "index"}+++# Filename -> symbol mapping for run-dir CSVs. The bash workaround writes each+# series with a filesystem-safe stem: ``BYN_V.csv`` for ``BYN.V``, ``PDI_TO.csv``+# for ``PDI.TO``, ``GC_F.csv`` for ``GC=F``.+_CSV_FILENAME_SUFFIX_MAP = (+ ("_V", ".V"),+ ("_TO", ".TO"),+ ("_F", "=F"),+ # A US name is written ``INTC_US.csv`` by the same workaround, and+ # ``.US`` is the venue suffix the rest of the project resolves on. Without+ # this row the CSV was ingested as no evidence at all, so every price the+ # run had actually fetched came back "numeric_claim_unavailable".+ ("_US", ".US"),+)+++# Only ``get_market_data`` returns bars whose columns are already the canonical+# OHLC field names. Every other market-sensitive tool nests its quote somewhere,+# and ``_ingest_generic_numeric`` stores that JSON path verbatim — "data.last",+# "quote[0].close_price". Without this map those observations never reach the+# final-answer check, so a price the run genuinely retrieved is rejected as+# "no matching observed tool evidence": measured against the live validator, an+# answer quoting a ``get_stock_profile`` price failed with+# ``numeric_claim_unavailable`` while the identical claim backed by+# ``get_market_data`` passed. Only unambiguous quote fields are mapped; ratios,+# volumes, strikes, and analyst targets stay out so the contradiction check does+# not gain a wider set of values it is willing to accept.+_GENERIC_PRICE_FIELD_ALIASES = {+ "open": "open",+ "open_price": "open",+ "openprice": "open",+ "开盘": "open",+ "开盘价": "open",+ "high": "high",+ "high_price": "high",+ "最高": "high",+ "最高价": "high",+ "low": "low",+ "low_price": "low",+ "最低": "low",+ "最低价": "low",+ "close": "close",+ "close_price": "close",+ "closeprice": "close",+ "prev_close": "close",+ "pre_close": "close",+ "preclose": "close",+ "previous_close": "close",+ "收盘": "close",+ "收盘价": "close",+ "昨收": "close",+ "adj_close": "adj_close",+ "adjclose": "adj_close",+ "adjusted_close": "adj_close",+ "price": "price",+ "last": "price",+ "last_price": "price",+ "lastprice": "price",+ "latest_price": "price",+ "current_price": "price",+ "market_price": "price",+ "settle": "price",+ "settlement": "price",+ "settle_price": "price",+ "vwap": "price",+ "现价": "price",+ "最新价": "price",+}+++# Metric family for a claim/evidence leaf, so a figure is only grounded by+# evidence of its own kind: an observed price must never stand in for an+# invented volatility (#1336).+_ANALYSIS_KIND_ALIASES = {+ "annualized_vol": "vol",+ "annualized_volatility": "vol",+ "volatility": "vol",+ "return_vol": "vol",+ "return_volatility": "vol",+ "vol": "vol",+ "max_drawdown": "drawdown",+ "maxdd": "drawdown",+ "drawdown": "drawdown",+ "sharpe": "sharpe",+ "sharpe_ratio": "sharpe",+ "win_rate": "win_rate",+ "hit_rate": "win_rate",+ "hitrate": "win_rate",+ "probability": "probability",+ "prob": "probability",+ "total_return": "return",+ "annual_return": "return",+ "cumulative_return": "return",+ "benchmark_return": "return",+ "excess_return": "return",+ "annualized_return": "return",+ "return": "return",+ "returns": "return",+ "ic_positive_ratio": "win_rate",+}+++# Order matters: 最大回撤 is drawdown before 收益/return, and 年化波动率 is vol+# before the generic return branch.+_ANALYSIS_KIND_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = (+ (re.compile(r"(?:回撤|drawdown|maxdd|最大亏损)", re.IGNORECASE), "drawdown"),+ (+ re.compile(+ r"(?:波动率|波动性|volatility|annualized\s*vol|return\s*vol|年化波动)",+ re.IGNORECASE,+ ),+ "vol",+ ),+ (re.compile(r"(?:夏普|sharpe)", re.IGNORECASE), "sharpe"),+ (re.compile(r"(?:胜率|命中率|win\s*rate|hit\s*rate)", re.IGNORECASE), "win_rate"),+ (re.compile(r"(?:概率|probability|prob)", re.IGNORECASE), "probability"),+ # 年化/annualized alone ("| 年化 | 18.2% |") resolves to return so a+ # generic-header table cannot dodge the gate with the fragment the prose+ # detector (_ANALYSIS_METRIC_RE) already treats as a metric word.+ (re.compile(r"(?:收益|回报|收益率|回报率|年化|\breturns?\b|\bannualized\b)", re.IGNORECASE), "return"),+)+++def _symbol_from_csv_filename(stem: str) -> str | None:+ """Map a run-dir CSV stem back to a canonical project symbol.++ The bash workaround writes filesystem-safe stems: ``BYN_V.csv`` -> ``BYN.V``,+ ``PDI_TO.csv`` -> ``PDI.TO``, ``GC_F.csv`` -> ``GC=F``, ``INTC_US.csv`` ->+ ``INTC.US``. A stem without a recognized suffix (e.g. a bare US name+ ``AAPL``) maps to None because the project convention requires an explicit+ venue suffix.++ Args:+ stem: CSV filename without the ``.csv`` extension.++ Returns:+ The canonical symbol, or ``None`` when the stem has no recognizable+ venue suffix.+ """+ upper = (stem or "").strip().upper()+ if not upper:+ return None+ for raw, canonical in _CSV_FILENAME_SUFFIX_MAP:+ if upper.endswith(raw) and len(upper) > len(raw):+ return upper[: -len(raw)] + canonical+ return None+++def _json_object(value: Any) -> dict[str, Any] | None:+ """Parse a JSON object from a tool result when possible."""+ if isinstance(value, dict):+ return value+ if not isinstance(value, str):+ return None+ try:+ parsed = json.loads(value)+ except (json.JSONDecodeError, TypeError):+ return None+ return parsed if isinstance(parsed, dict) else None+++def _is_number(value: Any) -> bool:+ """Return whether a value is a finite JSON-style number, excluding bool."""+ return (+ isinstance(value, (int, float))+ and not isinstance(value, bool)+ and math.isfinite(float(value))+ )+++def _coerce_csv_number(value: Any) -> int | float | None:+ """Coerce a CSV cell to a finite number, or return None.++ CSV readers return every cell as text (``"0.375"``), so a bare+ ``_is_number`` check would discard them all. Values that do not parse as a+ finite number (blank cells, ``-``, ``N/A``) return ``None``.+ """+ if _is_number(value):+ return value+ if isinstance(value, str):+ try:+ parsed = float(value.strip().replace(",", ""))+ except (TypeError, ValueError):+ return None+ if math.isfinite(parsed):+ return parsed+ return None+++# "." is deliberately not a separator: a decimal price such as 8.5 would parse+# as month 8 day 5 and match a real trading day.+# A report writes the day as a table cell -- "08-10(一)", "08-10(周一)盘中",+# "08-10盘中" -- and the weekday or session suffix made the cell match no+# evidence row at all, so every price in that row came back+# "numeric_claim_unavailable" even though the run had fetched the bar.+_TRADING_DAY_SUFFIX = (+ r"(?:\s*[((]\s*(?:周|星期)?[一二三四五六日天]\s*[))])?"+ r"\s*(?:盘中|盘后|盘前|收盘|开盘|早盘|尾盘)?"+)+++_YEARLESS_CLAIM_DATE_RE = re.compile(+ r"^(0?[1-9]|1[0-2])\s*[-/月]\s*(0?[1-9]|[12]\d|3[01])\s*[日号]?"+ + _TRADING_DAY_SUFFIX+ + r"$"+)+++# Two-digit day alternatives are tried before a bare digit so an+# unanchored prefix match consumes the full day ("10" of "08-10(一)")+# instead of stopping at "1".+_ISO_CLAIM_DATE_PREFIX_RE = re.compile(+ r"^\s*((?:19|20)\d{2})\s*[-/]\s*(0?[1-9]|1[0-2])\s*[-/]\s*([12]\d|3[01]|0?[1-9])"+)+++_YEARLESS_CLAIM_DATE_PREFIX_RE = re.compile(+ r"^\s*(0?[1-9]|1[0-2])\s*[-/月]\s*([12]\d|3[01]|0?[1-9])"+)+++_ISO_TIMESTAMP_RE = re.compile(r"^(\d{4})-(\d{1,2})-(\d{1,2})")+++def _claim_date_tuple(date_value: str) -> tuple[int, int] | None:+ """Extract the (month, day) named by a report-style date cell.++ Reports routinely annotate a trading day: the date column reads+ ``08-10(一)``, ``08-10(周一)盘中`` or ``08-10盘中`` rather than the bare+ ``08-10`` the strict full-cell matchers accept. Any leading month-day (or+ full ISO date) prefix is therefore accepted so such a claim still compares+ against the matching evidence row instead of being reported as+ unevidenced.++ Args:+ date_value: Date cell as written in the answer.++ Returns:+ The (month, day) tuple, or None when no date prefix is present.+ """+ claim = (date_value or "").strip()+ match = _YEARLESS_CLAIM_DATE_RE.match(claim)+ if match:+ return (int(match.group(1)), int(match.group(2)))+ match = _ISO_CLAIM_DATE_PREFIX_RE.match(claim)+ if match:+ return (int(match.group(2)), int(match.group(3)))+ match = _YEARLESS_CLAIM_DATE_PREFIX_RE.match(claim)+ if match:+ return (int(match.group(1)), int(match.group(2)))+ return None+++def _timestamp_matches_claim_date(timestamp: str, date_value: str) -> bool:+ """Match an evidence timestamp against the date cell of a claim.++ The comparison used to be ``timestamp.startswith(date_value)``, which can+ only succeed when the answer repeats the year. A table whose date column+ reads ``08-05`` — the ordinary way a report writes a trading day — matched+ nothing, so every cell in the row was reported as having no supporting+ evidence while that evidence sat right there (#983: 79 such rejections in+ one run, every value inside the observed range).++ A year-less date is matched on month and day, and a date cell may carry+ weekday or intraday annotations (``08-10(一)``, ``08-10盘中``) whose+ leading month-day is still recognized. Matching the wrong year is a+ smaller failure than matching nothing, but it is a real one, so the+ caller still compares the value against every record that matched rather+ than trusting the date.++ Args:+ timestamp: Evidence timestamp, normally ISO ``YYYY-MM-DD``.+ date_value: Date cell as written in the answer.++ Returns:+ True when the timestamp denotes the day the claim names.+ """+ stamp = (timestamp or "").strip()+ claim = (date_value or "").strip()+ if not stamp or not claim:+ return False+ if stamp.startswith(claim):+ return True+ claim_tuple = _claim_date_tuple(claim)+ iso = _ISO_TIMESTAMP_RE.match(stamp)+ if claim_tuple is None or not iso:+ return False+ return (int(iso.group(2)), int(iso.group(3))) == claim_tuple+++def _price_field_for_path(path: str) -> str | None:+ """Map a generic evidence JSON path to a canonical price field.++ Args:+ path: Recorded evidence field, e.g. ``"data.quote[0].last_price"``.++ Returns:+ The matching member of ``_PRICE_FIELDS``, or ``None`` when the leaf is+ not an unambiguous quote field.+ """+ leaf = str(path or "").rsplit(".", 1)[-1]+ leaf = re.sub(r"\[\d+\]$", "", leaf).strip().casefold()+ return _GENERIC_PRICE_FIELD_ALIASES.get(leaf)+++# A price-denominated indicator the session fetched is observed evidence in+# the same sense an OHLC bar is: ``indicators.sma_20: 0.7158`` came out of+# ``technical_indicators`` for this symbol, and an answer that writes "MA20+# 0.7158" or derives an entry from it is quoting a tool, not inventing a+# number. Before this, the value was compared against OHLC bars only and+# rejected as a fabricated price (deriv2 probe, 2026-09-09). The family list is+# closed and price-denominated on purpose — a moving average, band, pivot,+# support/resistance level, VWAP or ATR is in the instrument's currency; RSI,+# MACD, volume, counts and row totals are not. Letting a quote match+# ``rows: 54`` or a volume average would gut the fabrication check, so any+# non-price token anywhere in the path disqualifies the leaf.+_PRICE_INDICATOR_TOKENS = frozenset(+ {+ "sma", "ema", "wma", "dma", "dema", "tema", "hma", "kama", "ma", "vwap", "vwma",+ "bb", "bbands", "boll", "bollinger", "band", "bands", "keltner", "kc", "donchian",+ "pivot", "pp", "support", "resistance",+ "atr", "psar", "sar", "supertrend", "ichimoku", "tenkan", "kijun", "senkou",+ "chikou", "highest", "lowest",+ }+)+++# Generic band leaves. "lower" is a price only under a band family, so these+# need a family token elsewhere in the path: ``bollinger.lower`` qualifies,+# a bare ``summary.lower`` does not.+_PRICE_BAND_LEAVES = frozenset({"upper", "lower", "middle", "mid", "top", "bottom", "basis"})+++# Standard pivot-level spellings. They are matched before the trailing digits+# are stripped: ``r1`` would otherwise become ``r``, which is in no set, and+# the six literals ``r1 r2 r3 s1 s2 s3`` sat in the family list unreachable.+_PIVOT_LEVEL_RE = re.compile(r"^[rs][123]$")+++_NON_PRICE_TOKENS = frozenset(+ {+ "volume", "vol", "turnover", "amount", "count", "rows", "returned", "signal",+ "histogram", "rsi", "kdj", "k", "d", "j", "cci", "adx", "obv", "mfi", "roc",+ "williams", "wr", "stoch", "pct", "percent", "ratio", "change", "chg", "width",+ "position", "score", "z", "zscore", "slope", "angle", "days", "bars",+ # Parameters and derived shapes, not levels: ``params.ma_period: 20``+ # and ``entry_condition.ma_window: 20`` are settings, ``ma_diff`` and+ # ``sma_cross`` are differences and booleans. The leaf test below+ # already rejects those three, but a path that also carries a family+ # token in another segment must not be readmitted by it.+ "window", "period", "length", "span", "lookback", "n", "cross", "flag",+ }+)+++def _is_price_denominated_indicator(path: str) -> bool:+ """Return whether a generic evidence path is a price-denominated indicator.++ The decision is made on the LEAF — the last dotted segment, with a+ trailing index stripped — not on "some token anywhere in the path". Under+ the old any-token rule ``indicators.ma_diff``, ``indicators.sma_cross``+ and ``indicators.supertrend_direction`` were all admitted as observed+ prices because they carry ``ma`` / ``sma`` / ``supertrend`` somewhere,+ and a payload with any of them set to 1.30 let the answer print+ "现价 1.30 元" (attack6 probe, 2026-09-09). A difference, a crossover+ flag and a direction are not prices.++ Args:+ path: Recorded evidence field, e.g. ``"indicators.bollinger.lower"``.++ Returns:+ True when the leaf names a price-denominated indicator level and no+ path token names a non-price quantity.+ """+ text = str(path or "")+ tokens = [+ re.sub(r"\d+$", "", token).casefold()+ for token in re.split(r"[._\[\]\-\s]+", text)+ if token+ ]+ tokens = [token for token in tokens if token]+ if not tokens:+ return False+ if any(token in _NON_PRICE_TOKENS for token in tokens):+ return False+ segments = [segment for segment in re.split(r"[.\[\]]+", text) if segment]+ if not segments:+ return False+ leaf = segments[-1].strip().casefold()+ if _PIVOT_LEVEL_RE.match(leaf):+ return True+ leaf = re.sub(r"[_\-]?\d+$", "", leaf) or leaf+ if leaf in _PRICE_INDICATOR_TOKENS:+ return True+ return leaf in _PRICE_BAND_LEAVES and any(+ token in _PRICE_INDICATOR_TOKENS for token in tokens+ )+++def _metric_kind_for_path(path: str) -> str | None:+ """Map an evidence JSON path to an analysis metric kind."""+ leaf = re.sub(r"\[\d+\]$", "", str(path or "").rsplit(".", 1)[-1])+ leaf = leaf.strip().casefold()+ kind = _ANALYSIS_KIND_ALIASES.get(leaf)+ if kind is not None:+ return kind+ # Compound leaves name the kind as a token ("reported_annualized_return",+ # "strategy_max_drawdown"). #1338 review: matching only the verbatim alias+ # table makes every other spelling silently ungroundable. Scan from the+ # right — English compounds put the head noun last, so "return_vol"+ # resolves to vol, never to return.+ tokens = [token for token in re.split(r"[_.]", leaf) if token]+ for size in (2, 1):+ for start in range(len(tokens) - size, -1, -1):+ kind = _ANALYSIS_KIND_ALIASES.get("_".join(tokens[start : start + size]))+ if kind is not None:+ return kind+ return _metric_kind_for_text(path)+++def _metric_kind_for_text(text: str) -> str | None:+ """Return the analysis metric kind named in a claim or header."""+ for pattern, kind in _ANALYSIS_KIND_PATTERNS:+ if pattern.search(text):+ return kind+ return None+++@dataclass(frozen=True)+class EvidenceRecord:+ """One observed, unavailable, or derived numeric evidence item."""++ call_id: str+ tool: str+ symbol: str | None+ source: str+ timestamp: str | None+ field: str+ value: int | float | None+ status: str+ currency: str | None = None+ venue: str | None = None+ currency_conversion: str | None = None+++class _EvidenceMixin:+ """Evidence behaviour of :class:`GroundingLedger`."""++ def _ingest_analysis_result(+ self,+ tool_name: str,+ arguments: Mapping[str, Any],+ payload: dict[str, Any] | None,+ call_id: str,+ ) -> None:+ """Record metric numbers a completed analysis result actually produced.++ Success of the call envelope is not enough: ``backtest`` reports ok for+ any runner exit, and a deduplicated ("skipped") call carries no new+ result at all (#1336). Only results that yielded at least one+ recognisable metric figure count as completed analysis.+ """+ if payload is None or payload.get("skipped"):+ return+ if tool_name == "backtest":+ if str(payload.get("status") or "").casefold() != "ok" and payload.get(+ "exit_code"+ ) not in (0, "0"):+ return+ recorded = self._record_backtest_metrics(arguments, payload, call_id)+ elif tool_name == "factor_analysis":+ if str(payload.get("status") or "").casefold() != "ok":+ return+ recorded = self._record_leaf_metrics(payload, call_id, tool_name, "")+ elif tool_name == "run_shadow_backtest":+ if str(payload.get("status") or "").casefold() != "ok":+ return+ combined = payload.get("combined")+ if not isinstance(combined, dict):+ # A combined dict containing only {"error": ...} is no analysis.+ return+ recorded = self._record_leaf_metrics(combined, call_id, tool_name, "combined")+ elif tool_name == "quantlib_call":+ if payload.get("ok") is not True or str(+ arguments.get("action") or ""+ ).casefold() != "call":+ return+ function = str(arguments.get("function") or "")+ recorded = self._record_leaf_metrics(+ payload.get("result"), call_id, tool_name, function+ )+ else:+ return+ if recorded:+ self._analysis_completed.append(+ {"call_id": call_id, "tool": tool_name, "recorded_at": _utc_now()}+ )++ def _record_leaf_metrics(+ self,+ value: Any,+ call_id: str,+ tool_name: str,+ field_prefix: str,+ ) -> int:+ """Record nested numeric leaves whose key names a metric kind."""+ recorded = 0++ def visit(item: Any, path: str) -> None:+ nonlocal recorded+ if _is_number(item):+ kind = _metric_kind_for_path(path)+ if kind is None:+ return+ self._analysis_metrics.append(+ {+ "metric": kind,+ "value": float(item),+ "tool": tool_name,+ "call_id": call_id,+ "field": path,+ }+ )+ recorded += 1+ return+ if isinstance(item, dict):+ for key, child in item.items():+ visit(child, f"{path}.{key}" if path else str(key))+ elif isinstance(item, list):+ for index, child in enumerate(item):+ visit(child, f"{path}[{index}]")++ visit(value, field_prefix or "")+ return recorded++ def _record_backtest_metrics(+ self,+ arguments: Mapping[str, Any],+ payload: dict[str, Any],+ call_id: str,+ ) -> int:+ """Parse metric figures from a successful backtest's run-dir artifacts."""+ root = self.run_dir.resolve()+ candidates: list[Path] = []+ raw_dir = arguments.get("run_dir") or payload.get("run_dir")+ if raw_dir:+ candidate = Path(str(raw_dir))+ if not candidate.is_absolute():+ candidate = self.run_dir / candidate+ try:+ resolved = candidate.resolve()+ if resolved == root or resolved.is_relative_to(root):+ candidates.append(resolved)+ except OSError:+ pass+ # The loop archives a detached backtest's artifacts into the active run+ # dir right after it succeeds, so that copy is the second candidate.+ candidates.append(root)+ artifacts = payload.get("artifacts")+ if isinstance(artifacts, dict):+ for path_value in artifacts.values():+ if not isinstance(path_value, str):+ continue+ try:+ resolved = Path(path_value).resolve()+ if resolved.is_relative_to(root):+ candidates.append(resolved)+ except OSError:+ continue+ files: list[Path] = []+ seen_dirs: set[Path] = set()+ for candidate in candidates:+ if candidate.is_file():+ files.append(candidate)+ continue+ if candidate in seen_dirs:+ continue+ seen_dirs.add(candidate)+ for dir_path in (candidate, candidate / "artifacts"):+ for name in ("metrics.csv", "metrics.json"):+ target = dir_path / name+ if target.is_file():+ files.append(target)+ recorded = 0+ seen_files: set[Path] = set()+ for file_path in files:+ if file_path in seen_files:+ continue+ seen_files.add(file_path)+ recorded += self._record_metrics_file(file_path, call_id)+ return recorded++ def _record_metrics_file(self, path: Path, call_id: str) -> int:+ """Record metric figures from one metrics.csv/metrics.json artifact."""+ try:+ text = path.read_text(encoding="utf-8")+ except (OSError, UnicodeDecodeError):+ return 0+ if path.suffix == ".json":+ try:+ data = json.loads(text)+ except json.JSONDecodeError:+ return 0+ if not isinstance(data, dict):+ return 0+ return self._record_leaf_metrics(data, call_id, "backtest", "")+ try:+ rows = list(csv.reader(text.splitlines()))+ except csv.Error:+ return 0+ if len(rows) < 2:+ return 0+ header = [cell.strip().casefold() for cell in rows[0]]+ recorded = 0+ for index, raw in enumerate(rows[1]):+ if index >= len(header):+ break+ kind = _ANALYSIS_KIND_ALIASES.get(header[index])+ value = _coerce_csv_number(raw)+ if kind is not None and value is not None:+ self._analysis_metrics.append(+ {+ "metric": kind,+ "value": float(value),+ "tool": "backtest",+ "call_id": call_id,+ "field": header[index],+ }+ )+ recorded += 1+ return recorded++ def _observed_price_values(self) -> list[float]:+ """Every observed price value the run holds, for redaction protection."""+ return [+ float(record.value)+ for record in self._comparable_price_records()+ if record.value is not None+ ]++ def _record_tool_failure(self, tool_name: str, call_id: str, result: str) -> None:+ """Store structured unavailable evidence for failed business envelopes."""+ payload = _json_object(result) or {}+ self._tool_failures.append(+ {+ "call_id": call_id,+ "tool": tool_name,+ "status": "unavailable",+ "error_code": payload.get("error_code"),+ "message": str(payload.get("error") or payload.get("message") or "tool failed")[:500],+ "recorded_at": _utc_now(),+ }+ )++ def _ingest_market_data(+ self,+ arguments: Mapping[str, Any],+ payload: dict[str, Any] | None,+ call_id: str,+ ) -> None:+ """Convert full OHLCV payloads into source-linked evidence rows."""+ if payload is None:+ self._record_tool_failure("get_market_data", call_id, "malformed JSON result")+ return+ requested_source = str(arguments.get("source") or "auto")+ provenance = payload.get("_provenance")+ provenance = provenance if isinstance(provenance, dict) else {}+ for raw_symbol, raw_rows in payload.items():+ if str(raw_symbol).startswith("_"):+ continue+ symbol = _normalize_symbol(raw_symbol)+ rows = raw_rows.get("data") if isinstance(raw_rows, dict) else raw_rows+ if not isinstance(rows, list):+ continue+ symbol_provenance = provenance.get(raw_symbol)+ actual_source = (+ str(symbol_provenance.get("source"))+ if isinstance(symbol_provenance, dict) and symbol_provenance.get("source")+ else requested_source+ )+ currency_conversion = (+ str(symbol_provenance.get("currency_conversion"))+ if isinstance(symbol_provenance, dict)+ and symbol_provenance.get("currency_conversion")+ else None+ )+ for row in rows:+ if not isinstance(row, dict):+ continue+ timestamp = next(+ (str(row[key]) for key in _TIMESTAMP_FIELDS if row.get(key) is not None),+ None,+ )+ for field_name, value in row.items():+ normalized_field = str(field_name).casefold()+ if normalized_field in _TIMESTAMP_FIELDS or not _is_number(value):+ continue+ self._evidence.append(+ EvidenceRecord(+ call_id=call_id,+ tool="get_market_data",+ symbol=symbol,+ source=actual_source,+ timestamp=timestamp,+ field=normalized_field,+ value=value,+ status="observed",+ currency=_infer_currency(symbol),+ venue=_infer_venue(symbol),+ currency_conversion=currency_conversion,+ )+ )+ unresolved = payload.get("_unresolved")+ if isinstance(unresolved, list):+ for raw_symbol in unresolved:+ symbol = _normalize_symbol(raw_symbol)+ self._evidence.append(+ EvidenceRecord(+ call_id=call_id,+ tool="get_market_data",+ symbol=symbol,+ source=requested_source,+ timestamp=None,+ field="availability",+ value=None,+ status="unavailable",+ currency=_infer_currency(symbol),+ venue=_infer_venue(symbol),+ )+ )++ def _ingest_generic_numeric(+ self,+ tool_name: str,+ arguments: Mapping[str, Any],+ payload: dict[str, Any],+ call_id: str,+ ) -> None:+ """Flatten bounded numeric leaves from other market-sensitive tools."""+ symbols = self._extract_symbol_arguments(arguments)+ symbol = symbols[0] if len(symbols) == 1 else None+ if symbol:+ symbol = (+ self._match_authorized_symbol(symbol, self.authorized_symbols) or symbol+ )+ source = str(payload.get("source") or tool_name)+ remaining = _MAX_GENERIC_EVIDENCE+ timestamp_fields = (*_TIMESTAMP_FIELDS, "as_of")++ def visit(value: Any, path: str, timestamp: str | None = None) -> None:+ nonlocal remaining+ if remaining <= 0:+ return+ if _is_number(value):+ self._evidence.append(+ EvidenceRecord(+ call_id=call_id,+ tool=tool_name,+ symbol=symbol,+ source=source,+ timestamp=timestamp,+ field=path or "value",+ value=value,+ status="observed",+ currency=_infer_currency(symbol or ""),+ venue=_infer_venue(symbol or ""),+ )+ )+ remaining -= 1+ return+ if isinstance(value, dict):+ local_timestamp = next(+ (+ str(value[key])+ for key in timestamp_fields+ if value.get(key) is not None+ ),+ timestamp,+ )+ for key, item in value.items():+ if str(key).casefold() in timestamp_fields:+ continue+ visit(+ item,+ f"{path}.{key}" if path else str(key),+ local_timestamp,+ )+ elif isinstance(value, list):+ for index, item in enumerate(value):+ visit(item, f"{path}[{index}]", timestamp)++ visit(payload, "")++ def _ingest_run_dir_ohlc_csvs(self) -> None:+ """Register OHLC rows from CSVs the run wrote via the bash workaround.++ The bash+yfinance escape hatch writes per-symbol OHLC CSVs into the run+ directory (e.g. ``data/raw/BYN_V.csv``) instead of returning them through+ ``get_market_data``. Those prices were genuinely observed tool output,+ but they never entered the ledger, so the final-answer gate rejected+ every one of them as ``numeric_claim_unavailable``. Scan the run dir for+ such CSVs and register their open/high/low/close/price rows as observed+ evidence, keyed to the symbol derived from the filename.++ Only files whose filename maps to a symbol already tracked in this run+ are accepted, so a stray CSV cannot mint new identity. Rows are bounded+ by ``_MAX_GENERIC_EVIDENCE`` and each file is ingested at most once.+ """+ if not self.run_dir.is_dir():+ return+ entitled = self._session_symbols | self.authorized_symbols+ if not entitled:+ return+ room = _MAX_GENERIC_EVIDENCE+ for path in sorted(self.run_dir.rglob("*.csv")):+ if room <= 0:+ return+ try:+ identity_key = f"{path.resolve()}:{path.stat().st_mtime_ns}"+ except (OSError, ValueError):+ continue+ if identity_key in self._ingested_csvs:+ continue+ self._ingested_csvs.add(identity_key)+ symbol = _symbol_from_csv_filename(path.stem)+ if not symbol or symbol not in entitled:+ continue+ try:+ with path.open("r", encoding="utf-8", errors="replace", newline="") as handle:+ rows = list(csv.DictReader(handle))+ except (OSError, UnicodeDecodeError, csv.Error):+ continue+ for row in rows:+ if room <= 0:+ return+ if not isinstance(row, dict):+ continue+ timestamp = next(+ (+ str(row[key]).strip()+ for key in row+ if str(key).strip().casefold() in _CSV_DATE_COLUMNS+ and row[key] not in (None, "")+ ),+ None,+ )+ for key, value in row.items():+ field_name = _CSV_PRICE_COLUMNS.get(+ str(key).strip().casefold().replace(" ", "_")+ )+ if field_name is None:+ continue+ numeric = _coerce_csv_number(value)+ if numeric is None:+ continue+ self._evidence.append(+ EvidenceRecord(+ call_id=f"csv:{path.name}",+ tool="bash",+ symbol=symbol,+ source="yfinance",+ timestamp=timestamp,+ field=field_name,+ value=numeric,+ status="observed",+ currency=_infer_currency(symbol),+ venue=_infer_venue(symbol),+ )+ )+ room -= 1++ def _price_records(self) -> list[EvidenceRecord]:+ """Return observed OHLC/price evidence only."""+ return [+ record+ for record in self._evidence+ if record.status == "observed"+ and record.field in _PRICE_FIELDS+ and record.value is not None+ ]++ def _comparable_price_records(self) -> list[EvidenceRecord]:+ """Return every observed quote a numeric claim may be checked against.++ ``_price_records`` only sees fields already named ``open``/``close``/…,+ which in practice means ``get_market_data``. Quotes returned by the+ other market-sensitive tools are re-keyed onto the same canonical field+ so the contradiction check compares like with like instead of reporting+ the claim as unevidenced.++ Returns:+ Observed price evidence with canonical ``field`` values.+ """+ records = self._price_records()+ already_counted = {id(record) for record in records}+ for record in self._evidence:+ if id(record) in already_counted:+ continue+ if record.status != "observed" or record.value is None:+ continue+ field_name = _price_field_for_path(record.field)+ if field_name is None:+ if _is_price_denominated_indicator(record.field):+ records.append(replace(record, field="indicator"))+ continue+ records.append(replace(record, field=field_name))+ return recordsdiff --git a/agent/src/agent/grounding/figures.py b/agent/src/agent/grounding/figures.pynew file mode 100644index 000000000..408852ca4--- /dev/null+++ b/agent/src/agent/grounding/figures.py@@ -0,0 +1,176 @@+"""Shape primitives for locating numbers, dates and tables in answer text.++This module is deliberately language-agnostic: it answers "what shape is this+run of characters" and nothing about what the surrounding prose calls it.+"""++from __future__ import annotations++import re++# "从 2026-08-03 的 100.0 涨到 2026-09-02 的 112.4" / "rose from 100.0 to+# 112.4": a return figure framed as growth between two endpoints is+# arithmetic on sourced inputs, not an invented backtest metric (#1338+# review). The frame alone never grounds anything — the values must also+# match an observed endpoint pair exactly (see _return_derived_from_observed).+_NUMBER_RE = re.compile(+ r"(?<![A-Za-z0-9_])[-+]?(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?"+ r"(?![A-Za-z0-9_])"+)+++# A line-leading ordered-list marker ("1. **标题**") is prose structure, not a+# number. Without masking it, "1." is parsed as a float and rejected downstream+# as a numeric_claim_conflict against an observed OHLC range (#BUGS-1). The+# pattern only matches a digit run at the start of a line followed by "." or ")"+# and whitespace, so an in-text decimal like "1.5" (digit after the dot) is+# never affected.+_MD_LIST_ITEM_RE = re.compile(r"^\s*\d+[.)]\s+", re.MULTILINE)+++# re.ASCII keeps ``\b`` a *byte* word boundary. Without it, ``\w`` is+# Unicode-aware and CJK letters count as word characters, so a date that runs+# straight into Chinese text -- "(2026-07-14最低)" -- has no boundary after+# "14" and is left unmasked, contributing 2026/7/14 as candidate prices that+# reject a correct report (#1122).+_DATE_RE = re.compile(r"\b(?:19|20)\d{2}[-/]\d{1,2}[-/]\d{1,2}\b", re.ASCII)+++# A year-less "8/5" is how a trading day is written in running prose, and it+# contributed 8 and 5 as candidate prices (#983). The month and day ranges are+# bounded, and both sides are fenced off from a longer slash run, so the window+# enumeration "20/50/200-day" cannot be mistaken for a date. Reports also write+# the same day as "08-10(一)" or "08-10盘中"; that dash form is masked by+# ``_DASH_DATE_RE`` below, where a zero-padded month or a weekday/session+# marker is required so a quoted price range like "8-10 元" stays checkable.+_SHORT_DATE_RE = re.compile(+ r"(?<![\d/])(?:0?[1-9]|1[0-2])/(?:0?[1-9]|[12]\d|3[01])(?![\d/])"+)+++# A report writes a trading day as "08-10(一)" or "08-10盘中", and the dash form+# leaked 8 and 10 as candidate prices exactly as "8/5" once did. The dash is+# NOT symmetric with the slash, though: it also separates a range, and "目标价+# 10-20 元" must stay checkable. So the two halves are split -- a zero-padded+# month (01-09) is a formatting intent no price range imitates, while 10/11/12+# have to carry a weekday or session marker to read as a date.+_DASH_DATE_RE = re.compile(+ r"(?<![\d/-])(?:"+ r"0[1-9]-(?:0[1-9]|[12]\d|3[01])"+ r"|1[0-2]-(?:0[1-9]|[12]\d|3[01])"+ r"(?=\s*(?:[((]\s*(?:周|星期)?[一二三四五六日天]\s*[))]"+ r"|盘中|盘后|盘前|收盘|开盘|最低|最高"+ r"|\s*(?:close|open|intraday|low|high)\b))"+ r")(?![\d/-])",+ re.IGNORECASE,+)+++# Localized calendar text carries digits that the ISO pattern above leaves+# behind: "8 月 3 日" otherwise contributes 8 and 3 as candidate prices.+_LOCALIZED_DATE_RE = re.compile(+ r"(?:(?:19|20)\d{2}\s*年\s*)?\d{1,2}\s*月(?:\s*\d{1,2}\s*[日号])?|(?:19|20)\d{2}\s*年"+)+++# A numbered markdown heading ("### 6. 关键价位") names a section index, not+# a price. The ordered-list mask only covers line-leading "1." and stops at+# the "### " prefix, so the section number was extracted as a claim.+_NUMBERED_HEADING_RE = re.compile(r"(?m)^\s*#{1,6}\s*\d+(?:[.、.])?\s*")+++# The clause splitter does not split on the ASCII period, so "close was 210.+# In 2024 the market rallied" stays one clause and 2024 would be misread as+# the asserted price. A period/bang/question followed by whitespace and a+# sentence-start (capital, quote, or bracket) is a boundary here — but only+# in this price-claim scan, never in the global clause splitter, where it+# would tear apart "000543.SZ" and "1.5". The capital/open-bracket lookahead+# deliberately excludes abbreviations: "close approx. 2500" keeps 2500 gated.+_SENTENCE_BOUNDARY_RE = re.compile(r"[.!?]\s+(?=[A-Z((])")+++# Full-width enumeration commas delimit prose clauses. Paired brackets (ASCII+# or full-width ()()[]) are deliberately not separators: an explicit+# derivation such as "(8.5 - 7.9) / 2" must stay in one segment for the+# formula check, and 公司名(代码)价格 must stay in one segment so the+# unsourced-symbol gate can see the symbol with its figure (#1260).+# The English sentence period is a clause separator too. Without it two+# English sentences sharing a line were ONE clause, so the header's "last+# close" labelled the whole line and a derivation in the first sentence+# exempted a fabricated price in the second: "Based on close 1.171 * 0.80 =+# 0.937. The last traded price is 0.937." validated, while the byte-identical+# text with a paragraph break between the sentences was rejected — and the+# Chinese translation was rejected either way, because 。 always split. A+# per-language split is a per-language verdict, which is exactly what+# ``test_grounding_language_parity`` exists to stop.+# The lookahead is what keeps a decimal point, a ticker suffix (562500.SS) and+# an abbreviation ("approx. 1.10") out: only a period followed by whitespace+# and the start of a new sentence separates.+_CLAUSE_SEPARATOR_RE = re.compile(+ r"[,,;;。、\n]|[.!?](?=\s+[\"'(\[“‘]?[A-Z])"+)+++# The ASCII comma both separates clauses and groups thousands, and the clause+# split ran first: "收盘价 ¥1,309.22" became a clause ending in "¥1", whose 1 was+# compared against the observed 1300.01–1363.35 range and rejected as a+# conflict. That is every price above 999 written the ordinary way, and it is+# self-contradictory — ``_NUMBER_RE`` and the float conversion below it both+# already understand grouped numbers. Only a real group is removed: a comma+# needs a digit before it and exactly three digits after.+_THOUSANDS_SEPARATOR_RE = re.compile(r"(?<=\d),(?=\d{3}(?!\d))")+++def _clause_spans(text: str, offset: int = 0) -> list[tuple[str, int, int]]:+ """Split prose into clauses, keeping each clause's span in the source text.++ A grouping comma is not a separator and is stripped from the returned+ segment text, but the span is into the ORIGINAL, un-stripped text. The+ redaction path needs that: it used to locate a flagged clause with+ ``text.find(claim)`` on the normalised string, which never matched once a+ price carried a thousands separator ("1,450.50"), and which matched inside+ an unrelated longer number when the claim was a bare table cell ("1.10"+ found inside "21.10").++ Args:+ text: One line of candidate answer text.+ offset: Where ``text`` starts inside the document being validated.++ Returns:+ ``(segment, start, end)`` per clause, with ``start``/``end`` measured+ in the document (``offset`` already added).+ """+ bounds: list[tuple[int, int]] = []+ cursor = 0+ for match in _CLAUSE_SEPARATOR_RE.finditer(text):+ if match.group(0) == "," and _THOUSANDS_SEPARATOR_RE.match(text, match.start()):+ continue+ bounds.append((cursor, match.start()))+ cursor = match.end()+ bounds.append((cursor, len(text)))+ return [+ (_THOUSANDS_SEPARATOR_RE.sub("", text[start:end]), start + offset, end + offset)+ for start, end in bounds+ ]+++def _lines_with_offsets(content: str) -> list[tuple[str, int]]:+ """Return each line of ``content`` with its character offset in it.++ ``str.splitlines`` discards the terminators, so an issue raised on a line+ cannot say where in the document that line sits. Offsets are recovered by+ scanning forward, which is exact because only line terminators separate+ one line's end from the next line's start.+ """+ positions: list[tuple[str, int]] = []+ cursor = 0+ for line in content.splitlines():+ start = content.find(line, cursor) if line else cursor+ if start < 0:+ start = cursor+ positions.append((line, start))+ cursor = start + len(line)+ return positions+++_TABLE_SEPARATOR_RE = re.compile(r"^:?-{3,}:?$")diff --git a/agent/src/agent/grounding/identity.py b/agent/src/agent/grounding/identity.pynew file mode 100644index 000000000..6e3e1eae1--- /dev/null+++ b/agent/src/agent/grounding/identity.py@@ -0,0 +1,981 @@+"""Instrument identity: symbol shapes, resolution, and tool authorization.++The identity half of the gate. Symbol normalisation and venue/currency/type+inference live here as free functions because they are pure text-to-text; the+mixin holds the run-scoped state machine that locks an identity and decides+which tool call may use it.+"""++from __future__ import annotations++import json+import re+from dataclasses import dataclass, field, replace+from datetime import datetime, timezone+from typing import Any, Iterable, Mapping++from src.agent.resolution_context import candidate_market+from src.market_data import canonical_fx_pair++_RESOLVER_TOOL = "search_symbol"+++_PRIVATE_COMPANY_SKILL_NAMES = {+ "private-company",+ "private-company-analysis",+ "private-company-research",+ "private_company",+ "private_company_analysis",+ "private_company_research",+}+++_SYMBOL_ARGUMENT_KEYS = {+ "code",+ "codes",+ "symbol",+ "symbols",+ "ticker",+ "tickers",+ "underlying",+ "underlyings",+}+++# Workflow selection must not race an in-flight resolution or proceed on+# contradicted identity. It may proceed once the resolver has answered — and+# ``ambiguous`` is an answer: a screening request ("推荐低价高增长股票") resolves to+# many candidates by design. Requiring a locked identity there stalls every+# discovery task before it can load a screening skill, which is #955.+_RESOLUTION_INCOMPLETE_STATUSES = {"unresolved", "conflicting", "invalidated"}+++_MAX_TRACKED_SYMBOLS = 5_000+++# Project-style canonical symbols. A bare model-generated ticker is still+# checked when it appears under a symbol argument key, but it is not accepted+# as user-provided identity because it lacks venue information.+#+# A joined crypto pair (``BTCUSDT``, ``ETHUSDT`` …) is recognized alongside+# the dashed/slashed form so a user message like ``Get BTCUSDT spot price``+# seeds an asserted identity and the asserted-symbol conflict check at+# ``_ingest_resolution`` runs against it. The base is restricted to alpha+# so a numeric prefix cannot masquerade as a joined pair, and the suffix+# list is the unambiguous stablecoin set (``USDT`` / ``USDC`` / ``BUSD`` /+# ``TUSD``) — ``USD`` is excluded because too many non-crypto strings end+# in those three letters and over-matching would lock the wrong identity.+_JOINED_CRYPTO_QUOTE_SUFFIXES = ("USDT", "USDC", "BUSD", "TUSD")+++# A dashed / slashed pair is crypto when its quote leg is unambiguously a+# crypto quote asset, or when a USD quote sits on one of these bases. Both+# sets MUST agree with ``_CRYPTO_QUOTE_ASSETS`` / ``_CRYPTO_USD_BASES`` in+# ``src.tools.symbol_search_tool`` — that module is the resolver, and a venue+# inferred here that disagrees with the identity it locks is a contradictory+# identity, which outranks every later lock and blocks all market tools. The+# tool imports this module, so the sets are duplicated rather than imported;+# ``test_crypto_pair_tables_match_the_resolver`` fails if they drift. ``USD``+# is the one quote the resolver accepts that is NOT unambiguous, so it is+# excluded here and decided by the base whitelist below instead.+_CRYPTO_QUOTE_ASSETS = frozenset(+ {"USDT", "USDC", "BUSD", "TUSD", "FDUSD", "BTC", "ETH", "BNB"}+)+++_CRYPTO_USD_BASES = frozenset(+ {+ "BTC", "ETH", "BNB", "SOL", "ADA", "XRP", "DOGE", "TRX", "DOT",+ "MATIC", "AVAX", "LINK", "LTC", "BCH", "ETC", "XLM", "ATOM",+ "FIL", "APT", "NEAR", "ALGO", "SAND", "MANA", "AXS", "XAUT",+ "PAXG",+ }+)+++# Spot precious metals quoted in USD collide with the TUSD suffix: XPTUSD is+# XPT + USD (platinum), but stripping "TUSD" leaves the alpha base "XP" and+# folds it to XP-TUSD — a crypto pair that does not exist, and the same class+# of misresolution the USD exclusion above exists to prevent. XAU/XAG/XPD do+# not collide today; they are listed together because they are the same kind+# of symbol and a future suffix would collide with them the same way.+_METAL_USD_PAIR_RE = re.compile(r"^(?:XAU|XAG|XPT|XPD)USD$", re.IGNORECASE)+++_JOINED_CRYPTO_RE = re.compile(+ r"(?<![A-Za-z0-9_])[A-Z]{2,15}(?:" + "|".join(_JOINED_CRYPTO_QUOTE_SUFFIXES) + r")(?![A-Za-z0-9_])",+ re.IGNORECASE,+)+++_CANONICAL_SYMBOL_RE = re.compile(+ r"(?<![A-Za-z0-9_])(?:"+ r"\d{3,6}\.(?:SH|SZ|BJ|SS|HK|KS|KQ)|"+ # Futu writes the venue as a PREFIX (HK.00700 / SH.600519 / US.AAPL). The+ # suffix branch above cannot see it, so a user who pasted a connector code+ # got no identity lock at all and every market tool answered+ # identity_required. Handled for the whole prefix set, not just HK: the+ # connector emits all four, and one venue's fix leaves the same hole open+ # in the next.+ r"(?:HK|SH|SZ|BJ|SS)\.\d{3,6}|"+ # Case-SENSITIVE (the connector writes it uppercase): a case-folded+ # match turns any "…/us.reuters/…" host inside a source URL into the+ # symbol REUTERS.US and fails the answer for an unsourced figure.+ r"(?-i:US\.[A-Z][A-Z0-9&-]{0,19})|"+ r"[A-Z][A-Z0-9&.-]{0,19}\.(?:US|NS|BO|FX|TO|V)|"+ r"[A-Z0-9]{2,15}(?:-|/)(?:USDT|USDC|USD|BTC|ETH)|"+ r"[A-Z]{2,15}(?:" + "|".join(_JOINED_CRYPTO_QUOTE_SUFFIXES) + r")|"+ r"\^[A-Z0-9&.\-]{1,20}|"+ r"[A-Z0-9]{2,15}=[FX]"+ r")(?![A-Za-z0-9_])",+ re.IGNORECASE,+)+++def _utc_now() -> str:+ """Return an audit-friendly UTC timestamp."""+ return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")+++# Provider spellings that denote one instrument. Shanghai is quoted as ``.SH``+# by Eastmoney and ``.SS`` by Yahoo, A-share tools also accept an exchange+# prefix (``sh600519``), Hong Kong codes are zero-padded to five digits, and+# ccxt writes a crypto pair with a slash. Every one of these is a spelling, not+# an identity: ``_infer_venue`` and ``_infer_currency`` below already map ``.SS``+# and ``.SH`` to the same venue and the same currency. Treating them as+# different identities made ``search_symbol("600519")`` return two candidates+# for one listing, which no tie-break could resolve, so every Shanghai listing+# resolved ``ambiguous`` and no market tool could run for the rest of the run.+_EXCHANGE_PREFIXED_RE = re.compile(r"^(SH|SZ|BJ)(\d{6})$")+++# The dotted form of the same idea, as the Futu connector spells it+# (``HK.00700`` / ``US.AAPL``). ``SS`` is Yahoo's Shanghai alias and folds+# onto ``SH`` exactly as the suffix spelling does.+_VENUE_PREFIXES = frozenset({"HK", "SH", "SZ", "BJ", "SS", "US"})+++_US_TICKER_RE = re.compile(r"[A-Z][A-Z0-9&-]{0,19}")+++def _normalize_symbol(value: Any) -> str:+ """Normalize a symbol onto one canonical identity for exact comparison.++ Args:+ value: Any provider- or model-supplied symbol spelling.++ Returns:+ The canonical spelling — uppercased, with Shanghai's ``.SS`` alias+ folded onto ``.SH``, an exchange prefix rewritten as a suffix, a Hong+ Kong code zero-padded, and a crypto pair hyphenated. A joined crypto+ pair with no separator (``BTCUSDT``) is rewritten as the dashed form+ (``BTC-USDT``) so every downstream check sees one identity. Text that+ is not a symbol is returned uppercased and otherwise untouched.+ """+ # A fiat/fiat pair is one FX instrument regardless of spelling: ``GBP/USD``+ # and ``GBPUSD`` are both ``GBPUSD=X``. Checked BEFORE the slash is+ # rewritten ("GBP/USD" -> "GBP-USD", the crypto-pair spelling), which+ # disagreed with the resolver's ``GBPUSD=X`` answer — a contradictory+ # identity that outranked every later lock and blocked all further tools.+ raw = str(value or "").strip().upper()+ fx = canonical_fx_pair(raw)+ if fx is not None:+ return fx+ symbol = raw.replace("/", "-")+ if not symbol:+ return ""++ prefixed = _EXCHANGE_PREFIXED_RE.match(symbol)+ if prefixed:+ return f"{prefixed.group(2)}.{prefixed.group(1)}"+ base, dot, suffix = symbol.rpartition(".")+ if not dot:+ # No separator at all: rewrite a joined crypto pair (``BTCUSDT``)+ # as the dashed form so the dash/slash branch and the canonical+ # regex both match. The base must be all-alpha so a numeric prefix+ # cannot collide with another numeric-code branch downstream.+ joined = _JOINED_CRYPTO_RE.fullmatch(symbol)+ if joined and not _METAL_USD_PAIR_RE.fullmatch(symbol):+ for quote in _JOINED_CRYPTO_QUOTE_SUFFIXES:+ if symbol.endswith(quote) and len(symbol) > len(quote):+ base_part = symbol[: -len(quote)]+ if base_part.isalpha():+ return f"{base_part}-{quote}"+ return symbol+ # Venue-prefixed listing (Futu connector format: HK.06693 / SH.600519 /+ # SZ.000001 / US.AAPL): rewrite to the canonical suffix spelling so+ # identity matching agrees with the market-data chain (06693.HK) that+ # get_market_data uses. Shanghai's .SS alias is folded onto .SH here too,+ # the same way the suffix branch below does it.+ if base in _VENUE_PREFIXES and suffix:+ venue = "SH" if base == "SS" else base+ if venue == "US":+ if _US_TICKER_RE.fullmatch(suffix):+ return f"{suffix}.US"+ elif suffix.isdigit():+ digits = suffix.zfill(5) if venue == "HK" else suffix+ return f"{digits}.{venue}"+ if suffix == "SS":+ suffix = "SH"+ if suffix == "HK" and base.isdigit():+ base = base.zfill(5)+ return f"{base}.{suffix}"+++def _query_key(value: Any) -> str:+ """Normalize resolver queries into stable state-machine keys."""+ return " ".join(str(value or "").casefold().split())+++def _scan_symbols(text: str) -> set[str]:+ """Return the canonical symbols written anywhere in a blob of text."""+ return {+ _normalize_symbol(match.group(0))+ for match in _CANONICAL_SYMBOL_RE.finditer(text or "")+ }+++def _infer_venue(symbol: str) -> str | None:+ """Infer a coarse venue from a project symbol."""+ upper = _normalize_symbol(symbol)+ suffixes = {+ ".US": "us",+ ".SH": "shanghai",+ ".SZ": "shenzhen",+ ".BJ": "beijing",+ ".HK": "hong_kong",+ ".KS": "kospi",+ ".KQ": "kosdaq",+ ".NS": "nse",+ ".BO": "bse",+ ".FX": "forex",+ ".TO": "toronto",+ ".V": "tsx_venture",+ }+ for suffix, venue in suffixes.items():+ if upper.endswith(suffix):+ return venue+ # Yahoo's continuous-front-month futures notation (GC=F, CL=F, SI=F, ...).+ # The exchange category is the venue class. The engine and the+ # correlation helper mirror this pattern; this is the third copy.+ if upper.endswith("=F"):+ return "futures"+ # Yahoo's forex notation (XAUUSD=X, EURUSD=X) is FX.+ if re.match(r"^[A-Z]{6}=X$", upper):+ return "forex"+ # Bare 6-character precious-metal / FX symbols. The whitelist is+ # ISO 4217 metals + G10 currencies; it intentionally does NOT include+ # any US-equity prefix. Mirroring the engine ``_MARKET_PATTERNS``.+ if re.match(+ r"^(?:XAU|XAG|XPT|XPD|EUR|GBP|JPY|CHF|CAD|AUD|NZD|USD)[A-Z]{3}$",+ upper,+ ):+ return "forex"+ # Dashed / slashed symbols are NOT categorically crypto: a USD quote is+ # crypto only on a whitelisted base (``_CRYPTO_USD_BASES``), so+ # ``XAU-USD`` / ``EUR-USD`` / ``GBP-USD`` are forex. Without this guard a+ # spot-gold pair surfaced as a crypto-or-fx hybrid in the runtime+ # registry, contradicting the engine classifier that already routes it to+ # ``forex`` (#1280).+ if "-" in upper or "/" in upper:+ base, _, quote = (+ upper.partition("-") if "-" in upper else upper.partition("/")+ )+ if quote in _CRYPTO_QUOTE_ASSETS:+ return "crypto_or_fx"+ if quote == "USD" and base in _CRYPTO_USD_BASES:+ return "crypto_or_fx"+ # Any other dashed / slashed pair is forex-shaped (e.g. ``XAU-USD``,+ # ``EUR-USD``, ``GBP-USD``); the per-pair engine classifier decides+ # ``forex`` vs ``crypto`` vs ``futures`` downstream.+ return "forex"+ return None+++def _infer_currency(symbol: str) -> str | None:+ """Infer quote currency without performing an implicit conversion."""+ upper = _normalize_symbol(symbol)+ suffixes = {+ ".US": "USD",+ ".SH": "CNY",+ ".SZ": "CNY",+ ".BJ": "CNY",+ ".HK": "HKD",+ ".KS": "KRW",+ ".KQ": "KRW",+ ".NS": "INR",+ ".BO": "INR",+ ".TO": "CAD",+ ".V": "CAD",+ }+ for suffix, currency in suffixes.items():+ if upper.endswith(suffix):+ return currency+ for separator in ("-", "/"):+ if separator in upper:+ quote = upper.rsplit(separator, 1)[-1]+ if 3 <= len(quote) <= 5:+ return quote+ if upper.endswith("=X"):+ pair = upper[:-2]+ if len(pair) == 6:+ return pair[3:6]+ return None+++def _infer_instrument_type(symbol: str, candidate_type: Any = None) -> str:+ """Normalize provider types into the identity contract."""+ raw = str(candidate_type or "").strip().casefold()+ if "fund" in raw or "etf" in raw or "trust" in raw:+ return "fund"+ if "crypto" in raw:+ return "crypto"+ if "future" in raw:+ return "future"+ if "option" in raw:+ return "option"+ if "forex" in raw or raw == "currency":+ return "forex"+ if "index" in raw:+ return "index"+ upper = _normalize_symbol(symbol)+ if upper.endswith("=F"):+ return "future"+ if upper.endswith(".FX"):+ return "forex"+ # Yahoo's continuous-front-month futures notation (GC=F, CL=F, ...).+ # Mirrors the engine ``_MARKET_PATTERNS`` and the correlation helper.+ if re.match(r"^[A-Z]{2,5}=F$", upper):+ return "future"+ # Yahoo's forex notation (XAUUSD=X, EURUSD=X).+ if re.match(r"^[A-Z]{6}=X$", upper):+ return "forex"+ # Bare 6-character precious-metal / FX symbols (whitelist).+ if re.match(+ r"^(?:XAU|XAG|XPT|XPD|EUR|GBP|JPY|CHF|CAD|AUD|NZD|USD)[A-Z]{3}$",+ upper,+ ):+ return "forex"+ # Dashed / slashed symbols: crypto only when the quote leg is a+ # stablecoin OR the base is in the USD-whitelist. The whitelist+ # mirrors ``_canonical_crypto_pair`` in+ # ``src.tools.symbol_search_tool``. ``XAU-USD`` / ``EUR-USD`` /+ # ``GBP-USD`` are NOT crypto and resolve as ``forex`` (the per-pair+ # engine classifier decides the final market downstream).+ if "-" in upper or "/" in upper:+ base, _, quote = (+ upper.partition("-") if "-" in upper else upper.partition("/")+ )+ if quote in _CRYPTO_QUOTE_ASSETS:+ return "crypto"+ if quote == "USD" and base in _CRYPTO_USD_BASES:+ return "crypto"+ return "forex"+ if upper.startswith("^"):+ return "index"+ return "listed_security"+++@dataclass(frozen=True)+class IdentityRecord:+ """One versioned entity-to-instrument resolution result."""++ query: str+ status: str+ symbol: str | None = None+ venue: str | None = None+ instrument_type: str | None = None+ currency: str | None = None+ source_tool_call_id: str | None = None+ source: list[str] = field(default_factory=list)+ candidates: list[dict[str, Any]] = field(default_factory=list)+ resolution_constraints: list[dict[str, Any]] = field(default_factory=list)+ version: int = 1+ updated_at: str = field(default_factory=_utc_now)+++@dataclass(frozen=True)+class ToolAuthorization:+ """Deterministic decision made before a tool starts."""++ allowed: bool+ error_code: str | None = None+ message: str | None = None+ symbols: tuple[str, ...] = ()++ def error_payload(self, tool_name: str, identity: Mapping[str, Any]) -> str:+ """Render a blocked tool call as a normal structured error result."""+ return json.dumps(+ {+ "status": "error",+ "error_code": self.error_code or "identity_gate_blocked",+ "tool": tool_name,+ "message": self.message or "Tool call blocked by identity gate",+ "symbols": list(self.symbols),+ "identity": dict(identity),+ "required_action": (+ "Call search_symbol in a separate assistant tool turn, wait for "+ "its result, then reuse the exact locked symbol and venue. If the "+ "resolver answers with a shortlist rather than one instrument, "+ "show the candidates and ask the user which one to use — narrowing "+ "the query again will not turn a genuine dual listing into one."+ ),+ },+ ensure_ascii=False,+ )+++class _IdentityMixin:+ """Identity behaviour of :class:`GroundingLedger`."""++ def authorize_tool_call(+ self,+ tool_name: str,+ arguments: Mapping[str, Any],+ *,+ batch_authorized_symbols: Iterable[str],+ call_id: str,+ batch_identity_status: str | None = None,+ ) -> ToolAuthorization:+ """Authorize against identity state frozen before the whole LLM batch.++ Args:+ tool_name: Requested tool.+ arguments: Model-supplied arguments.+ batch_authorized_symbols: Snapshot taken before processing any call+ from this assistant response.+ call_id: Provider tool-call identity.+ batch_identity_status: Aggregate identity status from the same+ pre-batch snapshot. Defaults to the current state for direct+ callers outside the Agent loop.++ Returns:+ An allow/block decision. Resolver calls are allowed but their result+ cannot affect another call in this same batch.+ """+ if tool_name == _RESOLVER_TOOL:+ self._identity_required = True+ self._buffer_output = True+ self._begin_resolution(str(arguments.get("query") or ""), call_id)+ return ToolAuthorization(allowed=True)++ if self._is_private_company_skill(tool_name, arguments):+ return self._authorize_private_company_skill()++ if tool_name == "load_skill" and self._identity_required:+ frozen_status = batch_identity_status or self.identity_status+ if frozen_status in _RESOLUTION_INCOMPLETE_STATUSES:+ return ToolAuthorization(+ allowed=False,+ error_code="identity_required",+ message=(+ "Market-sensitive workflow selection is blocked while instrument "+ "resolution is in flight or contradicted; a resolver result from "+ "this same batch cannot be consumed."+ ),+ )+ return ToolAuthorization(allowed=True)++ symbols = tuple(self._extract_symbol_arguments(arguments))+ if not symbols:+ return ToolAuthorization(allowed=True)++ self._identity_required = True+ self._buffer_output = True+ authorized = {_normalize_symbol(item) for item in batch_authorized_symbols}+ frozen_status = batch_identity_status or self.identity_status+ if frozen_status != "locked" or not authorized:+ return ToolAuthorization(+ allowed=False,+ error_code=(+ "identity_conflict"+ if frozen_status in {"ambiguous", "conflicting", "invalidated"}+ else "identity_required"+ ),+ message=(+ "A canonical, non-conflicting identity was not locked before this "+ "assistant tool-call batch started. A resolver result from this same "+ "batch cannot be consumed."+ ),+ symbols=symbols,+ )++ mismatched = tuple(+ symbol+ for symbol in symbols+ if self._match_authorized_symbol(symbol, authorized) is None+ )+ if mismatched:+ message = (+ "Consumer symbol/venue differs from the locked resolver identity; "+ "silent suffix or exchange rewrites are forbidden."+ )+ hints = [+ hint+ for symbol in mismatched+ for hint in self._venue_mismatch_hints(symbol, authorized)+ ]+ if hints:+ message += " " + " ".join(hints)+ return ToolAuthorization(+ allowed=False,+ error_code="identity_mismatch",+ message=message,+ symbols=mismatched,+ )+ return ToolAuthorization(allowed=True, symbols=symbols)++ @staticmethod+ def _venue_mismatch_hints(+ requested_symbol: str,+ authorized_symbols: Iterable[str],+ ) -> list[str]:+ """Turn a same-issuer venue mismatch into an actionable resolver hint.++ ``BLDP.US`` against a locked ``BLDP.TO`` is not a typo of one identity;+ it is a second listing of the same company that was never resolved.+ Naming the exact ``search_symbol`` query keeps the model from retrying+ the identical unauthorized call. A bare ticker that collides with+ several locked venues gets a "use the full suffix" hint instead.+ """+ requested = _normalize_symbol(requested_symbol)+ authorized = {_normalize_symbol(item) for item in authorized_symbols}+ if "." in requested:+ base = requested.rsplit(".", 1)[0]+ same_issuer = sorted(+ item+ for item in authorized+ if "." in item and item.rsplit(".", 1)[0] == base+ )+ if same_issuer:+ return [+ f"[{requested_symbol} is a second venue of {', '.join(same_issuer)}; "+ f"call search_symbol('{requested_symbol}') in a separate turn "+ f"before querying it.]"+ ]+ return []+ matches = sorted(+ item+ for item in authorized+ if "." in item and item.rsplit(".", 1)[0] == requested+ )+ if len(matches) > 1:+ return [+ f"[{requested_symbol} matches multiple locked identities "+ f"({', '.join(matches)}); use the full venue-suffixed symbol.]"+ ]+ return []++ @staticmethod+ def _match_authorized_symbol(+ requested_symbol: str,+ authorized_symbols: Iterable[str],+ ) -> str | None:+ """Map a consumer argument to one unique locked canonical symbol.++ Both sides are canonicalized first, so a provider alias (``600519.SS``),+ an exchange prefix (``sh600519``), an unpadded Hong Kong code+ (``700.HK``) or a slashed pair (``BTC/USDT``) addresses the instrument+ it names rather than being read as a silent venue rewrite.++ A bare code carries no venue, so it is accepted only when exactly one+ locked identity has it as its base. That uniqueness — not a list of+ which tools are allowed to use one — is what makes a bare ticker safe.+ The list this replaced named nine tools while eleven documented+ argument spellings across the registry were bare or prefixed, so the+ tools' own schema examples were being rejected.++ Args:+ requested_symbol: Model-supplied symbol argument.+ authorized_symbols: Symbols locked before the tool batch.++ Returns:+ The unique canonical identity consumed by the argument, or ``None``.+ """+ requested = _normalize_symbol(requested_symbol)+ authorized = {_normalize_symbol(item) for item in authorized_symbols}+ if requested in authorized:+ return requested+ if "." in requested:+ return None+ matches = [+ symbol+ for symbol in authorized+ if "." in symbol and symbol.rsplit(".", 1)[0] == requested+ ]+ return matches[0] if len(matches) == 1 else None++ def _seed_symbols(self, text: str, *, source: str) -> None:+ """Lock exact symbols explicitly supplied by a user."""+ for match in _CANONICAL_SYMBOL_RE.finditer(text or ""):+ symbol = _normalize_symbol(match.group(0))+ key = f"explicit:{symbol}"+ existing = self._identities.get(key)+ version = existing.version + 1 if existing else 1+ self._identities[key] = IdentityRecord(+ query=symbol,+ status="locked",+ symbol=symbol,+ venue=_infer_venue(symbol),+ instrument_type=_infer_instrument_type(symbol),+ currency=_infer_currency(symbol),+ source_tool_call_id=source,+ source=[source],+ version=version,+ )+ self._identity_required = True+ self._buffer_output = True++ def _begin_resolution(self, query: str, call_id: str) -> None:+ """Enter unresolved state before the resolver executes."""+ key = _query_key(query) or f"call:{call_id}"+ existing = self._identities.get(key)+ self._identities[key] = IdentityRecord(+ query=query,+ status="unresolved",+ source_tool_call_id=call_id,+ version=(existing.version + 1) if existing else 1,+ )+ self.persist()++ def _finish_failed_resolution(+ self,+ arguments: Mapping[str, Any],+ call_id: str,+ ) -> None:+ """Mark transport/business failure as invalidated, never not-found."""+ query = str(arguments.get("query") or "")+ key = _query_key(query) or f"call:{call_id}"+ existing = self._identities.get(key)+ self._identities[key] = IdentityRecord(+ query=query,+ status="invalidated",+ source_tool_call_id=call_id,+ version=(existing.version + 1) if existing else 1,+ )++ def _ingest_resolution(+ self,+ arguments: Mapping[str, Any],+ payload: dict[str, Any] | None,+ call_id: str,+ ) -> None:+ """Advance unresolved identity from a structured resolver result."""+ data = payload.get("data") if isinstance(payload, dict) else None+ data = data if isinstance(data, dict) else {}+ query = str(data.get("query") or arguments.get("query") or "")+ key = _query_key(query) or f"call:{call_id}"+ existing = self._identities.get(key)+ version = (existing.version + 1) if existing else 1++ if not isinstance(payload, dict) or payload.get("ok") is False:+ self._identities[key] = IdentityRecord(+ query=query,+ status="invalidated",+ source_tool_call_id=call_id,+ version=version,+ )+ return++ raw_candidates = data.get("candidates")+ candidates = [dict(item) for item in raw_candidates if isinstance(item, dict)] if isinstance(raw_candidates, list) else []+ resolver_candidates = candidates+ relevant_constraints = self.resolution_context.constraints_for(query)+ constraint_audit = [item.audit_record() for item in relevant_constraints]+ sources = data.get("sources") if isinstance(data.get("sources"), dict) else {}+ if not candidates:+ # "This entity does not exist" may only be concluded when every+ # source that could answer did answer. Counting two clean sources+ # instead was unreachable for a Chinese query — Yahoo cannot serve+ # one at all — so an entity that simply is not listed came back as+ # ``invalidated``, which blocks the run rather than answering it.+ # A source that skipped an unsupported query shape is not an outage.+ clean_sources = [+ str(name)+ for name, value in sources.items()+ if str(value).casefold() == "ok"+ ]+ failed_sources = [+ str(name)+ for name, value in sources.items()+ if str(value).casefold() != "ok"+ and not str(value).casefold().startswith("skipped")+ ]+ self._identities[key] = IdentityRecord(+ query=query,+ status="not_found" if clean_sources and not failed_sources else "invalidated",+ source_tool_call_id=call_id,+ source=clean_sources,+ candidates=[],+ resolution_constraints=constraint_audit,+ version=version,+ )+ return++ market_values = {+ item.value+ for item in relevant_constraints+ if item.dimension == "market" and item.explicit+ }+ if market_values:+ constrained = [+ candidate+ for candidate in candidates+ if candidate_market(candidate) in market_values+ ]+ if constrained:+ candidates = constrained+ else:+ # A mismatch with an explicit constraint must stay fail closed.+ # The candidate list may be truncated, so this is ambiguity,+ # not proof that the requested listing does not exist.+ self._identities[key] = IdentityRecord(+ query=query,+ status="ambiguous",+ source_tool_call_id=call_id,+ candidates=resolver_candidates,+ resolution_constraints=constraint_audit,+ version=version,+ )+ return++ chosen = self._choose_candidate(query, candidates)+ if chosen is None:+ self._identities[key] = IdentityRecord(+ query=query,+ status="ambiguous",+ source_tool_call_id=call_id,+ candidates=resolver_candidates,+ resolution_constraints=constraint_audit,+ version=version,+ )+ return++ symbol = _normalize_symbol(chosen.get("symbol"))+ if not symbol:+ self._identities[key] = IdentityRecord(+ query=query,+ status="invalidated",+ source_tool_call_id=call_id,+ candidates=resolver_candidates,+ resolution_constraints=constraint_audit,+ version=version,+ )+ return++ # A query that already spells a canonical symbol is asserting one, so a+ # resolver answering with a different instrument contradicts it rather+ # than refining it. This generalizes the ``.SS``/``.SH`` alias check it+ # replaces: that one fired on one exchange's two spellings and stayed+ # silent on an actual cross-exchange swap, which is the case that+ # matters.+ asserted = _scan_symbols(query)+ if asserted and symbol not in asserted:+ conflicting = list(candidates)+ conflicting.extend({"symbol": item, "source": ["query"]} for item in sorted(asserted))+ self._identities[key] = IdentityRecord(+ query=query,+ status="conflicting",+ source_tool_call_id=call_id,+ candidates=conflicting,+ resolution_constraints=constraint_audit,+ version=version,+ )+ return++ if existing and existing.status == "locked" and existing.symbol != symbol:+ conflicting = list(candidates)+ conflicting.insert(0, {"symbol": existing.symbol, "source": existing.source})+ self._identities[key] = IdentityRecord(+ query=query,+ status="conflicting",+ source_tool_call_id=call_id,+ candidates=conflicting,+ resolution_constraints=constraint_audit,+ version=version,+ )+ return++ source_names = []+ for value in [chosen.get("source"), *(chosen.get("also_from") or [])]:+ name = str(value or "").strip()+ if name and name not in source_names:+ source_names.append(name)+ venue = str(chosen.get("exchange") or chosen.get("market") or "").strip() or _infer_venue(symbol)+ self._identities[key] = IdentityRecord(+ query=query,+ status="locked",+ symbol=symbol,+ venue=venue,+ instrument_type=_infer_instrument_type(symbol, chosen.get("type")),+ currency=_infer_currency(symbol),+ source_tool_call_id=call_id,+ source=source_names,+ candidates=resolver_candidates,+ resolution_constraints=constraint_audit,+ version=version,+ )+ self._supersede_shortlists(symbol)++ def _supersede_shortlists(self, symbol: str) -> None:+ """Retire ambiguous shortlists that this lock has just answered.++ A screening query resolves to many candidates by design. Once one of+ them is locked by a later, narrower resolution, the earlier shortlist is+ answered rather than unresolved — leaving it ``ambiguous`` blocks every+ final answer in the run for the rest of the session (#955).++ Args:+ symbol: Canonical symbol locked by the current resolution.+ """+ for key, record in self._identities.items():+ if record.status != "ambiguous":+ continue+ offered = {+ _normalize_symbol(candidate.get("symbol")) for candidate in record.candidates+ }+ if symbol in offered:+ self._identities[key] = replace(+ record, status="superseded", updated_at=_utc_now()+ )++ @staticmethod+ def _choose_candidate(+ query: str,+ candidates: list[dict[str, Any]],+ ) -> dict[str, Any] | None:+ """Choose only a unique or strongly corroborated resolver candidate.++ Candidates are collapsed onto their canonical symbol first. Two rows+ that differ only by a provider's suffix convention describe one listing,+ and counting them as rival candidates is what left every Shanghai query+ with two "exact" matches and therefore no choice at all.+ """+ by_symbol: dict[str, dict[str, Any]] = {}+ for candidate in candidates:+ by_symbol.setdefault(_normalize_symbol(candidate.get("symbol")), candidate)+ candidates = list(by_symbol.values())+ if len(candidates) == 1:+ return candidates[0]+ normalized_query = re.sub(r"[^a-z0-9\u3400-\u9fff]", "", query.casefold())+ exact: list[dict[str, Any]] = []+ strong: list[dict[str, Any]] = []+ for candidate in candidates:+ symbol = _normalize_symbol(candidate.get("symbol"))+ base = symbol.split(".", 1)[0].split("-", 1)[0].split("/", 1)[0]+ name = str(candidate.get("name") or "")+ comparable = {+ re.sub(r"[^a-z0-9\u3400-\u9fff]", "", base.casefold()),+ re.sub(r"[^a-z0-9\u3400-\u9fff]", "", name.casefold()),+ re.sub(r"[^a-z0-9\u3400-\u9fff]", "", symbol.casefold()),+ }+ if normalized_query and normalized_query in comparable:+ exact.append(candidate)+ if candidate.get("also_from") or candidate.get("cik"):+ strong.append(candidate)+ if len(exact) == 1:+ return exact[0]+ if len(strong) == 1:+ return strong[0]+ return None++ def _authorize_private_company_skill(self) -> ToolAuthorization:+ """Keep private-company routing symmetric with locked listing evidence."""+ locked_listings = [+ record+ for record in self._identities.values()+ if record.status == "locked"+ and record.instrument_type in {"listed_security", "fund"}+ ]+ if locked_listings:+ return ToolAuthorization(+ allowed=False,+ error_code="identity_conflict",+ message=(+ "A resolver has locked this entity to a listed security. Model memory "+ "cannot replace that evidence with a private-company workflow."+ ),+ symbols=tuple(+ record.symbol for record in locked_listings if record.symbol+ ),+ )+ if self.identity_status == "not_found" or not self._identity_required:+ return ToolAuthorization(allowed=True)+ return ToolAuthorization(+ allowed=False,+ error_code="identity_required",+ message=(+ "Private-company routing requires a completed resolver result with clean "+ "not_found status; current identity is unresolved, ambiguous, or invalidated."+ ),+ )++ @staticmethod+ def _is_private_company_skill(+ tool_name: str,+ arguments: Mapping[str, Any],+ ) -> bool:+ """Return whether this call selects a private-company skill."""+ if tool_name != "load_skill":+ return False+ name = str(arguments.get("name") or "").strip().casefold()+ return name in _PRIVATE_COMPANY_SKILL_NAMES or (+ "private" in name and "company" in name+ )++ @staticmethod+ def _extract_symbol_arguments(arguments: Mapping[str, Any]) -> list[str]:+ """Extract model-selected identities from well-known argument keys."""+ symbols: list[str] = []+ for key, value in arguments.items():+ if str(key).casefold() not in _SYMBOL_ARGUMENT_KEYS:+ continue+ values = value if isinstance(value, (list, tuple, set, frozenset)) else [value]+ for item in values:+ if not isinstance(item, (str, int)):+ continue+ symbol = _normalize_symbol(item)+ if symbol and symbol not in symbols:+ symbols.append(symbol)+ return symbols++ def _track_session_symbols(+ self,+ arguments: Mapping[str, Any],+ result: str,+ ) -> None:+ """Widen the run's instrument surface from one succeeding tool call.++ Both sides of a successful call count. The result is the strong signal —+ a resolver shortlist, an OHLC panel, a filing index. The arguments are+ the weaker one, but a symbol the model handed to a tool that then+ succeeded has at least been exercised against a real system, whereas a+ symbol that surfaces for the first time in the final prose has been+ exercised against nothing. Failed calls are deliberately excluded, so a+ blocked or erroring call never launders an invented ticker.++ Bare symbol arguments are tracked separately as roots. Many tools take a+ bare ticker by contract, so a run that legitimately fetched ``AAPL``+ never writes ``AAPL.US`` into any argument or result. Without the root,+ the canonical spelling the rest of this module demands — see+ ``canonical_symbol_not_surfaced`` — would be the one spelling this gate+ rejects.++ Args:+ arguments: Exact normalized tool arguments.+ result: Full raw result, before model-context truncation.+ """+ if len(self._session_symbols) >= _MAX_TRACKED_SYMBOLS:+ return+ try:+ rendered_arguments = json.dumps(arguments, ensure_ascii=False, default=str)+ except (TypeError, ValueError):+ rendered_arguments = ""+ found = _scan_symbols(rendered_arguments) | _scan_symbols(result)+ room = _MAX_TRACKED_SYMBOLS - len(self._session_symbols)+ self._session_symbols.update(sorted(found)[:room])+ self._session_symbol_roots.update(+ symbol+ for symbol in self._extract_symbol_arguments(arguments)+ if "." not in symbol+ )diff --git a/agent/src/agent/grounding/ledger.py b/agent/src/agent/grounding/ledger.pynew file mode 100644index 000000000..35a32153a--- /dev/null+++ b/agent/src/agent/grounding/ledger.py@@ -0,0 +1,314 @@+"""The :class:`GroundingLedger` facade the agent loop drives."""++from __future__ import annotations++import hashlib+import json+import re+from dataclasses import asdict+from pathlib import Path+from typing import Any, Mapping, Sequence++from src.agent.resolution_context import ResolutionContext++from src.agent.grounding.identity import (+ IdentityRecord,+ _IdentityMixin,+ _RESOLVER_TOOL,+ _scan_symbols,+ _utc_now,+)+from src.agent.grounding.evidence import EvidenceRecord, _EvidenceMixin, _json_object+from src.agent.grounding.policies import ValidationResult, _PolicyMixin+from src.agent.grounding.release import (+ MAX_GROUNDING_RECOVERY_ROUNDS,+ MAX_PRICE_EVIDENCE_ATTEMPTS,+ MAX_SYMBOL_RESOLUTION_ATTEMPTS,+ _ReleaseMixin,+)++GROUNDING_ARTIFACT = "grounding_evidence.json"+++# Tools whose successful completion can ground backtest/analysis metric claims+# (#1336). Success alone is not authority: only results that actually carried+# metric output (parsed from the result or its run-dir artifacts) raise+# ``analysis_claim_unavailable``. A deduplicated ("skipped") call is never a+# completion.+_ANALYSIS_TOOLS = frozenset(+ {"backtest", "factor_analysis", "run_shadow_backtest", "quantlib_call"}+)+++_ACTIONABLE_MARKET_RE = re.compile(+ r"(?:\bbuy\b|\bsell\b|\bentry\b|\btarget price\b|\bcurrent price\b|"+ r"\blatest price\b|\bprice of\b|\btrade\b|"+ r"\bvaluation of\b|\bwhat (?:is|are) .{1,80} worth\b|"+ r"\bis .{1,80} (?:listed|publicly traded)\b|"+ r"买入|卖出|入场|目标价|现价|最新价|股价|交易价格|估值|值多少钱|"+ r".{1,40}(?:是否|有没有|已经|已)(?:在.{0,20})?上市)",+ re.IGNORECASE,+)+++class GroundingLedger(+ _IdentityMixin,+ _EvidenceMixin,+ _PolicyMixin,+ _ReleaseMixin,+):+ """Run-scoped identity state machine and evidence ledger."""++ def __init__(+ self,+ *,+ run_dir: Path,+ user_message: str,+ history: Sequence[Mapping[str, Any]] | None = None,+ contextual_identity_constraints: bool = True,+ ) -> None:+ """Create a ledger and seed only authoritative prior identities.++ Args:+ run_dir: Active run directory.+ user_message: Current user request.+ history: Optional prior message history. It remains available to+ the model. Only explicit constraints whose clause names the+ current resolver subject may carry forward; stale global+ instructions cannot authorize a new subject.+ contextual_identity_constraints: Whether explicit market words in+ the original conversation may narrow resolver candidates.+ """+ self.run_dir = Path(run_dir)+ self.user_message = user_message+ self.resolution_context = ResolutionContext.from_messages(+ user_message,+ history,+ enabled=contextual_identity_constraints,+ )+ self._identities: dict[str, IdentityRecord] = {}+ self._evidence: list[EvidenceRecord] = []+ self._tool_failures: list[dict[str, Any]] = []+ self._analysis_completed: list[dict[str, Any]] = []+ self._analysis_metrics: list[dict[str, Any]] = []+ self._validations: list[dict[str, Any]] = []+ # The one document that actually shipped through the release path, if+ # any. Not a draft, so it stays out of ``validation_count``.+ self._released: dict[str, Any] | None = None+ self._recovery_rounds = 0+ self._symbol_resolution_attempts = 0+ self._price_evidence_attempts = 0+ self._ingested_csvs: set[str] = set()+ self._identity_required = bool(_ACTIONABLE_MARKET_RE.search(user_message))+ self._buffer_output = self._identity_required+ # Every instrument this run is entitled to write about: the ones the+ # user named, plus the ones a succeeding tool call passed in or returned.+ self._session_symbols: set[str] = _scan_symbols(user_message)+ # Bare tickers a succeeding call passed in, e.g. "AAPL" for the nine+ # tools whose contract is a bare US ticker. "AAPL.US" in the answer then+ # names an instrument the run really handled.+ self._session_symbol_roots: set[str] = set()++ self._seed_symbols(user_message, source="user_message")+ self.persist()++ @property+ def authorized_symbols(self) -> set[str]:+ """Return exact symbols locked before the next tool batch."""+ return {+ record.symbol+ for record in self._identities.values()+ if record.status == "locked" and record.symbol+ }++ @property+ def identity_status(self) -> str:+ """Return the aggregate first-class identity state.++ ``conflicting`` is the only state that outranks a successful lock: two+ sources contradicting each other about one query is a fact about the+ data, not a gap in it. Every other blocking state means "not known+ yet", and a side query that failed, went unanswered, or returned a+ shortlist must not retract an identity the run did lock — one flaky+ resolver call otherwise poisons every remaining answer in the session,+ with no path back. Per-symbol safety does not depend on this aggregate:+ a consumer still has to match a locked symbol in+ :meth:`_match_authorized_symbol` before it may run.+ """+ records = list(self._identities.values())+ if not records:+ return "unresolved" if self._identity_required else "not_required"+ statuses = {record.status for record in records}+ if "conflicting" in statuses:+ return "conflicting"+ if "locked" in statuses:+ return "locked"+ for blocking in ("ambiguous", "invalidated", "unresolved"):+ if blocking in statuses:+ return blocking+ if "not_found" in statuses:+ return "not_found"+ return "unresolved"++ @property+ def should_buffer_output(self) -> bool:+ """Return whether unverified model prose must be hidden from live sinks."""+ return self._buffer_output or bool(self._evidence)++ @property+ def validation_count(self) -> int:+ """Return the number of final drafts checked so far."""+ return len(self._validations)++ def identity_summary(self) -> dict[str, Any]:+ """Return compact identity state for traces and tool errors."""+ return {+ "status": self.identity_status,+ "authorized_symbols": sorted(self.authorized_symbols),+ "records": [asdict(record) for record in self._identities.values()],+ "recovery": self.recovery_summary(),+ }++ def recovery_summary(self) -> dict[str, Any]:+ """Return bounded-recovery budget state for traces and the artifact."""+ return {+ "rounds": self._recovery_rounds,+ "max_rounds": MAX_GROUNDING_RECOVERY_ROUNDS,+ "symbol_resolution_attempts": self._symbol_resolution_attempts,+ "max_symbol_resolution_attempts": MAX_SYMBOL_RESOLUTION_ATTEMPTS,+ "price_evidence_attempts": self._price_evidence_attempts,+ "max_price_evidence_attempts": MAX_PRICE_EVIDENCE_ATTEMPTS,+ }++ def ingest_tool_result(+ self,+ *,+ tool_name: str,+ arguments: Mapping[str, Any],+ result: str,+ call_id: str,+ success: bool,+ ) -> None:+ """Consume the full untruncated tool result and persist its evidence.++ Args:+ tool_name: Executed tool name.+ arguments: Exact normalized tool arguments.+ result: Full raw result, before model-context truncation.+ call_id: Provider tool-call identity.+ success: Result-envelope success classification.+ """+ payload = _json_object(result)+ if not success:+ self._record_tool_failure(tool_name, call_id, result)+ if tool_name == _RESOLVER_TOOL:+ self._finish_failed_resolution(arguments, call_id)+ self.persist()+ return++ self._track_session_symbols(arguments, result)+ if tool_name in _ANALYSIS_TOOLS:+ self._ingest_analysis_result(tool_name, arguments, payload, call_id)+ if tool_name == _RESOLVER_TOOL:+ self._ingest_resolution(arguments, payload, call_id)+ elif tool_name == "get_market_data":+ self._ingest_market_data(arguments, payload, call_id)+ elif payload is not None:+ self._ingest_generic_numeric(tool_name, arguments, payload, call_id)+ self.persist()++ def validate_final_answer(self, content: str) -> ValidationResult:+ """Validate identity assertions and numeric price claims.++ Args:+ content: Candidate assistant answer.++ Returns:+ A deterministic validation result. A record containing only the+ answer hash and structured issues is appended to the artifact.+ """+ return self._validate(content, record=True)++ def revalidate(self, content: str) -> ValidationResult:+ """Validate text WITHOUT counting it as a rejected draft.++ For the recheck that follows a deterministic repair or redaction. No+ model round produced that text, so recording it would spend one unit+ of the revision budget (``loop.py``) and add an attempt to the+ artifact that no draft stands behind.++ Args:+ content: The repaired or redacted answer.++ Returns:+ A deterministic validation result.+ """+ return self._validate(content, record=False)++ def _validate(self, content: str, *, record: bool) -> ValidationResult:+ """Run the gate, optionally without recording the attempt.++ ``validation_count`` is the run's rejected-DRAFT count: it caps the+ revision budget (``loop.py``) and is printed to the user as the number+ of rejected drafts in the degraded-run reason. The release path's own+ rechecks are not drafts — one successful ``redacted_release`` inflated+ the count from 1 to 4 with no model round in between, shrinking the+ budget and overstating the audit number — so they pass ``record=False``.++ Args:+ content: Candidate assistant answer.+ record: Whether to append the attempt to the persisted ledger.++ Returns:+ A deterministic validation result.+ """+ self._ingest_run_dir_ohlc_csvs()+ issues: list[dict[str, Any]] = []+ issues.extend(self._validate_identity(content))+ issues.extend(self._validate_unsourced_symbols(content))+ issues.extend(self._validate_price_claims(content))+ issues.extend(self._validate_analysis_claims(content))+ result = ValidationResult(valid=not issues, issues=issues)+ if not record:+ return result+ self._validations.append(+ {+ "attempt": len(self._validations) + 1,+ "checked_at": _utc_now(),+ "content_sha256": hashlib.sha256(content.encode("utf-8")).hexdigest(),+ "valid": result.valid,+ "issues": issues,+ }+ )+ self.persist()+ return result++ def persist(self) -> None:+ """Atomically persist the current structured ledger."""+ artifact_dir = self.run_dir / "artifacts"+ try:+ artifact_dir.mkdir(parents=True, exist_ok=True)+ path = artifact_dir / GROUNDING_ARTIFACT+ temp = path.with_suffix(path.suffix + ".tmp")+ payload = {+ "schema_version": 1,+ "updated_at": _utc_now(),+ "identity": self.identity_summary(),+ "session_symbols": sorted(self._session_symbols),+ "session_symbol_roots": sorted(self._session_symbol_roots),+ "evidence": [asdict(record) for record in self._evidence],+ "tool_failures": list(self._tool_failures),+ "analysis_completed": list(self._analysis_completed),+ "analysis_evidence": list(self._analysis_metrics),+ "validations": list(self._validations),+ "released": dict(self._released) if self._released else None,+ }+ temp.write_text(+ json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n",+ encoding="utf-8",+ )+ temp.replace(path)+ except OSError:+ # Grounding decisions remain in memory; a read-only/broken artifact+ # directory must not crash the agent's error path.+ returndiff --git a/agent/src/agent/grounding/policies.py b/agent/src/agent/grounding/policies.pynew file mode 100644index 000000000..13e79b9dc--- /dev/null+++ b/agent/src/agent/grounding/policies.py@@ -0,0 +1,2112 @@+"""Per-claim validation: the checks that turn evidence into issues."""++from __future__ import annotations++import ast+import json+import math+import re+from dataclasses import dataclass, field+from typing import Any, Sequence++from src.agent.grounding.identity import (+ _CANONICAL_SYMBOL_RE,+ _normalize_symbol,+ _scan_symbols,+)+from src.agent.grounding.evidence import (+ EvidenceRecord,+ _is_number,+ _metric_kind_for_path,+ _metric_kind_for_text,+ _timestamp_matches_claim_date,+)+from src.agent.grounding.figures import (+ _DASH_DATE_RE,+ _DATE_RE,+ _LOCALIZED_DATE_RE,+ _MD_LIST_ITEM_RE,+ _NUMBERED_HEADING_RE,+ _NUMBER_RE,+ _SENTENCE_BOUNDARY_RE,+ _SHORT_DATE_RE,+ _TABLE_SEPARATOR_RE,+ _clause_spans,+ _lines_with_offsets,+)++# Tools whose run produces the equity/regime windows behind a categorical+# "all N-month windows were profitable" statement.+_ANALYSIS_WINDOW_TOOLS = frozenset({"backtest", "run_shadow_backtest"})+++# Unit / currency tokens glued to a price, swallowed with the figure.+# The single-character 元 additionally guards against CJK: without it the+# swallow ate the 元 of 元宵/元旦/元件 and left an orphan "宵节后关注" in the+# released text. The multi-character units cannot start a longer word the+# same way, so they keep the Latin-only guard (it is there for USD/USDT).+# Both guards also refuse a following slash: 元/股 and USD/share are ONE+# compound unit, and swallowing only its first half rewrote+# "建议买入价 0.95 元/股" into "建议买入价(略※)/股" — a denominator with+# nothing left above it.+_CURRENCY_UNIT_WORDS = (+ r"人民币|美元|美金|港元|港币|日元|欧元|英镑|"+ r"CNY|RMB|USD|HKD|JPY|EUR|GBP|CAD|AUD|SGD|USDT"+)+++# The same tokens without the swallow guards. Those guards decide how much+# text the marker may EAT; this one only asks whether a figure is written as a+# price, and there "1.180 元已回撤" is as much a quote as "1.180 元。" is.+_UNIT_TOKEN_AFTER_RE = re.compile(+ r"\s*(?:" + _CURRENCY_UNIT_WORDS + r"|元)", re.IGNORECASE+)+++_CURRENCY_BEFORE_RE = re.compile(r"(?:US\$|HK\$|C\$|A\$|S\$|\$|¥|¥|€|£)\s*$")+++_PRIVATE_ASSERTION_RE = re.compile(+ r"(?:\b(?:is|remains|still)\s+(?:an?\s+)?(?:private company|privately held)\b|"+ r"\bnot publicly traded\b|\bunlisted company\b|"+ r"(?:是|仍是|属于)(?:一家)?(?:私人|私营|非上市)公司|未上市|没有上市)",+ re.IGNORECASE,+)+++# The bare verbs below are present tense only, which is not how an answer+# actually states an observed price: "closed at 412.35" and "last traded at+# 412.35" are the ordinary spellings and neither matches \bclose\b or+# \btrade\b. Chinese 收盘 / 现价 match, so the gate was strictly leakier in+# English than in Chinese — a fabricated USD price in the most natural+# phrasing walked straight through while its Chinese translation was caught.+# The past-tense forms are required to be followed by "at" so that reporting+# volume ("traded 1.2M shares") or a corporate event ("the deal closed at a+# 30% premium" — a percentage, already masked) is not read as a quote.+_PRICE_VERB_PAST_RE = r"\b(?:closed|opened|traded|quoted|priced|settled|fixed)\s+at\b"+++_PRICE_CONTEXT_RE = re.compile(+ r"(?:\b(?:opening|open|high|low|closing|close|price|quote)\b|"+ + _PRICE_VERB_PAST_RE + r"|"+ r"\b(?:entry|buy|target|support|resistance)\s+(?:price|level)\b|"+ r"开盘价?|最高价?|最低价?|收盘价?|买入价|入场价|目标价|支撑位?|阻力位?|"+ # Chinese had the mirror-image gap: these four are as ordinary as 收盘价+ # and none of them matched, so a fabricated 成交价 / 股价 walked through+ # exactly the way "closed at" did in English.+ r"成交价|最新价|股价|收报|"+ r"现价|报价|价格|价位)",+ re.IGNORECASE,+)+++# The vocabulary of a price LEVEL — a band, a moving average, a support or+# resistance line. It is the only shape for which an indicator reading is+# admissible evidence, and the rule is stated this way round on purpose.+#+# It used to be stated the other way: an indicator was admissible unless the+# clause named an OHLC field, against a hand-written list of field phrases.+# A hand-written denylist is only ever as complete as the day it was typed,+# and it was not complete for one day: with the session's sma_20 at 1.150 and+# the observed close at 1.171, "收盘价为 1.150 元" was caught while "收盘于"'s+# English twins "closed at 1.150" / "the close was 1.150" / "highest price was+# 1.150" were released, and every spot-quote spelling there is — 现价 / 最新价+# / 成交价 / 报价 / 股价 / current price / the quote is — leaked in both+# scripts, because a spot quote names the latest print and named no OHLC+# field. An allowlist fails the other way: a level word this list misses costs+# a correction round instead of releasing a fabricated print.+_PRICE_LEVEL_WORD_RE = re.compile(+ r"(?:\b(?:support|resistance|pivot|moving[- ]average|"+ r"(?:upper|lower|middle) band|band|channel|bollinger|keltner|donchian|"+ r"ichimoku|supertrend|vwap|atr)\b|"+ r"\b(?:SMA|EMA|WMA|DMA|MA|BOLL)\d{0,3}\b|"+ r"支撑|阻力|压力|均线|上轨|下轨|中轨|轨道|通道|中枢|枢轴|布林)",+ re.IGNORECASE,+)+++_ANALYSIS_METRIC_RE = re.compile(+ r"(?:\breturn vol(?:atility)?\b|\bmax(?: |\.)?drawdown\b|\bmaxdd\b|"+ r"\bsharpe(?: ratio)?\b|\bwin rate\b|\bhit rate\b|"+ r"\bprob(?:ability)?\.?\s+of\b|\bvolatility\b|\bdrawdown\b|"+ r"\bannualiz\w*\b|\bwindow(?:s)?\b|\bregime(?:s)?\b|"+ r"\b(?:annual|cumulative|total)\s+return\b|"+ r"夏普|回撤|波动率|胜率|命中率|概率|年化|回测|窗口|收益(?:率)?|回报(?:率)?)",+ re.IGNORECASE,+)+++# Phrases that indicate a figure is attributed to an external source rather+# than model memory (paper restatement, #1338 review). Attributing a number+# to a named source is the opposite of an unsourced claim. The subject list+# is deliberately restricted to sources that cannot be this run's own output+# (papers, studies, analysts, filings): "the backtest reports" / "the data+# shows" is exactly how a model dresses up its own numbers (#1336), so+# data/backtest/strategy/report subjects do NOT count.+_ATTRIBUTION_RE = re.compile(+ r"(?:"+ r"\b(?:the\s+(?:papers?|studies?|researchers?|analysts?|surveys?"+ r"|regulators?|authorities|literature|authors?)"+ r"|analysts?|researchers?|literature|sec\s+filings?\b|filings?"+ r"|annual\s+filings?|quarterly\s+filings?|rating\s+agencies?)"+ r"\s+(?:reports?|estimates?|shows?|indicates?|suggests?|states?|claims?"+ r"|notes?|cites?|mentions?|reveals?|discloses?|publishes?|found"+ r"|calculated|computed|derived)\b"+ r"|"+ r"(?:论文|文献|分析师|研究机构|学者)"+ r"[^。,\n]{0,6}?(?:报告|显示|表明|指出|称|估计|发现)"+ r")",+ re.IGNORECASE,+)+++# Measurement-shaped numbers for analysis claims: keeps the % sign and sign+# (unlike _numbers_without_dates_or_percent, which drops percentages on+# purpose). A bare integer is NOT a measurement — "252 个交易日年化" is the+# standard convention, not a claim about this run's analysis (#1032-style+# definitional prose must stay untouched). Dates can still look like+# measurements, so date masks run first.+_MEASURE_NUMBER_RE = re.compile(+ r"[-+]?(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)\s*[%%]?" # decimal: 1.21, -8.1%+ r"|[-+]?(?:\d{1,3}(?:,\d{3})+|\d+)\s*[%%]" # integer percent: 55%, 70%+)+++# A forward-looking frame means the figure is a forecast, not a claim that a+# backtest/analysis measured it — the measurement gate only polices "measured+# facts" (#1336), forecasts stay under the "analysis, not advice" prompt rule.+_FORECAST_FRAME_RE = re.compile(+ r"(?:\b(?:forecast|expected|projected|predicted)\b|预计|预期|预测|估计|展望)",+ re.IGNORECASE,+)+++# Definitional prose ("夏普比率大于 1.0 通常被认为较好") states a convention,+# not a measurement this session produced (#1336: preserve explicitly labelled+# definitions). The bare 通常 alone is deliberately not enough — "通常实现+# 18.2% 年化" is a measured claim.+_DEFINITION_FRAME_RE = re.compile(+ r"(?:通常(?:认为|被?认为|说来|指|用于)|一般认为|定义为|是指|惯例|"+ r"conventionally|typically\s+(?:considered|regarded|seen)|"+ r"generally\s+(?:accepted|considered|regarded)|by\s+convention)",+ re.IGNORECASE,+)+++# A categorical "all N-month windows were profitable" claim carries only an+# integer window length, which _MEASURE_NUMBER_RE deliberately ignores; it is a+# measured fact about the run and needs a window-producing analysis result.+_CATEGORICAL_WINDOW_RE = re.compile(+ r"(?:所有|全部|每个|任何|each|every|all)[\s\S]{0,40}?"+ r"(?:窗口|区间|windows?|periods?)[\s\S]{0,30}?"+ r"(?:正收益|均为正|都为正|盈利|上涨|positive|profitable)",+ re.IGNORECASE,+)+++_DERIVATION_RE = re.compile(+ r"(?:\bderived\b|\bcalculated\b|\bformula\b|\bbased on\b|计算|推导|公式|基于)",+ re.IGNORECASE,+)+++# The separator between a formula and its result. "=" is how the gate first+# accepted a derivation; "≈" / "≒" / "约" / "约等于" are how a model writes one+# whose result it rounded, and each was rejected with the multiplier read as a+# quoted price. The evaluation tolerance already absorbs the rounding.+# The English spellings are here for the same reason the Chinese ones are:+# ``test_derived_return_exemption_is_structural_not_phrasal`` is the repo's+# standing rule that identical arithmetic gets an identical verdict in both+# languages, and "1.171 * 0.97 approximately 1.136" was still burning a+# revision round while its ≈ twin passed.+_RESULT_SEPARATOR_RE = re.compile(+ r"约等于|≈|≒|=|约|~|\b(?:approximately|approx\.?|about|around|roughly)\b",+ re.IGNORECASE,+)+++# The subject of a performance metric decides which evidence may ground it.+# A strategy's max drawdown is a property of an equity curve a backtest+# produced; two observed prints of the instrument are not that curve, and+# neither is any arithmetic on them. "回测显示该策略最大回撤 5.9%(从 1.180+# 跌至 1.110)" rode out of the session on the endpoint-arithmetic exemption+# with no backtest anywhere in it. A PRICE-subject drawdown ("股价较 5 月高点+# 1.053 元已回撤约 37%") is the arithmetic itself and keeps the exemption.+_STRATEGY_SUBJECT_RE = re.compile(+ r"(?:\bstrateg(?:y|ies)\b|\bbacktest(?:ed|ing)?\b|\bportfolio\b|"+ r"\bequity curve\b|\bNAV\b|\bholdings?\b|"+ r"策略|回测|组合|持仓|净值)",+ re.IGNORECASE,+)+++_INDICATOR_IDENTIFIER_RE = re.compile(r"(?<![0-9.])[A-Za-z_]+\d+(?![0-9.])")+++# Unitless identity constants in a symbolic rate formula are not quoted prices.+# Without this mask, ``1 - 单边成本率`` in a position-sizing formula is read as+# a one-yuan price merely because the same clause also mentions a close price.+# Keep the relaxation narrow: only 0/1 directly participating in arithmetic+# with a token explicitly labelled as a rate is removed.+_RATE_FORMULA_IDENTITY_RE = re.compile(+ r"\b[01](?=\s*[-+]\s*(?:[A-Za-z_][A-Za-z0-9_]*_?rate\b|[^\d\s()+*/=-]{0,12}(?:成本率|费率|税率|滑点率)))",+ re.IGNORECASE,+)+++# A level stated as a RANGE has the same shape: the separator touches the+# second number, so masking "目标价 10" left "-20" behind and a negative price+# matches no OHLC window at all -- a guaranteed rejection of a correct draft.+# The tail is optional, so a single-value level is unaffected.+_RANGE_TAIL = r"(?:\s*[-–—~~至到]\s*[-+]?\d[\d,]*(?:\.\d+)?)?"+++# A percentage range masks only its upper bound through the "%" tail check+# below, because the sign touches the second number: "1–2%" left 1 behind+# (#983). Mask the span as a whole.+_PERCENT_RANGE_RE = re.compile(+ r"\d[\d,]*(?:\.\d+)?\s*[-–—~至]\s*\d[\d,]*(?:\.\d+)?\s*[%%]"+)+++# A percentage-POINT delta is not a quoted price. "~3.6pp below Penumbra"+# describes a margin gap; left unmasked the ".6" is consumed as a decimal+# and the number reaches the OHLC comparator, which then rejects an+# otherwise correct fundamentals answer and demands `get_market_data` to+# substantiate a claim that has nothing to do with price.+# The trailing "%" spellings are already handled above; this covers the+# percentage-point spellings, which the percent masks never matched.+# The Chinese units take an optional measure word ("3.6 个百分点" is the+# ordinary spelling; bare "3.6 百分点" is the rare one) and are matched+# without a trailing \b: after a CJK character \b requires a non-word+# character to follow, so "下降 3.6 个百分点后企稳" would not match. The+# ASCII units keep \b, which is what stops "3.6ppm" being read as pp.+_PERCENTAGE_POINT_RE = re.compile(+ r"[-+~≈]?\s*\d[\d,]*(?:\.\d+)?\s*"+ r"(?:(?:pp|ppt|ppts|bps|bp)\b|个?(?:百分点|基点))",+ re.IGNORECASE,+)+++# An aggregate amount is not a quoted price. "100 股成本 820 CNY" states a+# position cost; comparing 820 against a per-share OHLC range is a category+# error. The tradeoff is that a per-share figure written only as "成本 8.20"+# goes unchecked — provenance still requires symbol, source, and currency.+_AGGREGATE_AMOUNT_RE = re.compile(+ r"(?:成本|总额|总价|总市值|市值|合计|金额|cost|total|notional|market value)"+ r"\s*(?:为|是|约)?\s*[::]?\s*[-+]?\d[\d,]*(?:\.\d+)?",+ re.IGNORECASE,+)+++# Quantities, horizons, lot sizes, and lookback windows are unit-bearing:+# "100 股", "1–4 周", "3 个月", "52-week", "20/50/200-day". None are prices.+# The hyphenated English compound needs its own branch: the range alternation+# consumes "-4" in "1-4 周" but stalls on "-week", which left 52 behind to be+# compared against an OHLC range (#1001). The slash enumeration shares a single+# trailing unit, so "20/50/200-day" has to be masked as one span or its first+# two window lengths survive. ASCII units carry a trailing word boundary so+# "120 more" is not read as a quantity; the CJK branch cannot, because 周 and+# 内 are both word characters and "1–4 周内" must still mask.+_QUANTITY_WITH_UNIT_RE = re.compile(+ r"\d[\d,]*(?:\.\d+)?"+ r"(?:\s*/\s*\d[\d,]*(?:\.\d+)?)*"+ r"(?:\s*[-–—~至]\s*\d[\d,]*(?:\.\d+)?)?"+ r"\s*[-–—]?\s*"+ r"(?:"+ r"(?:股|手|张|份|口|笔|倍|个月|周|天|日|年|次|个交易日|项|行)"+ r"|(?:shares?|contracts?|lots?|units?|sessions?|bars?|periods?|"+ r"wks?|weeks?|months?|days?|years?|yrs?)\b"+ r")",+ re.IGNORECASE,+)+++# A conviction reading is on a labelled scale, not a price scale: the 6 in+# "CONFIDENCE: 6" is bounded by the label that introduces it. Only the value+# bound to the label is masked, so a genuine quote elsewhere in the same+# clause is still checked. The optional denominator covers "6/10" (#1001).+_LABELLED_SCORE_RE = re.compile(+ r"(?:confidence|conviction|score|rating|probability|odds|weighting|"+ r"置信度|信心|评分|得分|概率|胜率)"+ r"\s*(?:is|of|=|为|是)?\s*[::]?\s*"+ r"[-+]?\d[\d,]*(?:\.\d+)?(?:\s*/\s*\d[\d,]*(?:\.\d+)?)?",+ re.IGNORECASE,+)+++# A named indicator reads on its own scale — "RSI of 46.7" is bounded at 100,+# not quoted in the instrument's currency. The name must be adjacent to the+# value, so a bare number elsewhere in the clause stays checked. Only+# unambiguous indicator names are listed: generic words such as "momentum" or+# "volatility" sit too close to price prose to mask safely.+_INDICATOR_VALUE_RE = re.compile(+ r"\b(?:rsi|macd|atr|adx|cci|obv|kdj|boll|dif|dea|vix|iv|"+ r"sharpe|sortino|beta)\b"+ r"(?:\s*\([^)]{0,20}\))?"+ # #1354: "RSI below 30" / "sharpe above 1" — a directional connective is+ # part of the indicator reading, so the reading's number stays masked.+ # Only indicator NAMES get these connectives; a price word with+ # "below/above" ("close above 2500") is an observed-value claim and+ # matches none of these names, so it stays gated.+ r"\s*(?:is|at|of|reads?|=|为|是|below|above|under|over)?\s*[::]?\s*"+ r"[-+]?\d[\d,]*(?:\.\d+)?",+ re.IGNORECASE,+)+++# A currency token may sit between a level marker or comparison operator and+# the number: "收盘 <$2.86", "目标位 C$6.80", "trigger at $119.68". Without+# it, the number survives masking and is compared against observed OHLC as a+# price claim even though it is a prospective level, not an observed quote.+_CURRENCY_TOKEN = r"(?:\$|US\$|C\$|HK\$|CAD|USD|CNY|HKD|¥|¥)?"+++# An order line is an instruction, not an observation. "100 @ $3.50" states+# where a limit sits and "100" is a share count that was never a price at all,+# yet both went to the OHLC check and rejected a weekly update whose quotes+# were correct. This is the same category as the target/stop levels below -- a+# level the report proposes, not one the data source reported.++# #1354: a signal value trailing an arrow or a signal word ("sinal +1",+# "-> +1", "触发 +1", "Sinal: +1") is the formula's output, not an observed+# price. Signal values are small integers (a +/-1 signal, a 1-10 score); a+# multi-digit price never follows these words, so the digit bound keeps+# "close -> 2500" (a price claim written in arrow notation) gated. The colon+# is optional ("Sinal: +1" — ASCII '.' is not a clause separator, so this can+# sit in the same clause as the price word), the sign may be spaced ("sinal+# - 1"), and the lookahead stops the bound from masking the first two digits+# of a longer number ("signal 2500" keeps the full 2500 gated).+_SIGNAL_VALUE_RE = re.compile(+ r"(?:\b(?:signal|sinal|trigger|triggers|triggered|dispara|信号|触发)\b[::]?"+ r"|->|→|=>)"+ r"\s*[-+]?\s*\d{1,2}(?:\.\d+)?(?!\d)",+ re.IGNORECASE,+)+++_ORDER_LEVEL_RE = re.compile(+ r"(?:"+ # (a) "<qty> [股|shares] @ <price>" -- the whole clause, quantity included+ r"\d[\d,]*(?:\.\d+)?\s*(?:股|shares?)?\s*@\s*"+ + _CURRENCY_TOKEN + r"\s*[-+]?\d[\d,]*(?:\.\d+)?"+ r"|"+ # (b) an order label, optionally carrying its own "<qty> @", then the level.+ # There is deliberately no bare "@ <price>" branch: dates are masked before+ # this runs, so "收盘 2026-08-10 @ 8.20" would arrive here as "@ 8.20" and a+ # genuinely observed close would stop being checked. 买入价 / 卖出价 are+ # absent for the same reason -- in running prose they name a price the+ # report says it observed, not an instruction it proposes.+ r"(?:挂单|限价单|限价|委托价?|订单"+ r"|limit\s+(?:order|price)|\bGTC\b|\bGTD\b|\bIOC\b|\bFOK\b)"+ r"\s*(?:为|是|at|=)?\s*[::]?\s*"+ r"(?:\d[\d,]*(?:\.\d+)?\s*(?:股|shares?)?\s*@\s*)?"+ + _CURRENCY_TOKEN + r"\s*[-+]?\d[\d,]*(?:\.\d+)?"+ r")" + _RANGE_TAIL,+ re.IGNORECASE,+)+++# A historical reference names a price the instrument once traded at — an+# all-time high, a 52-week extreme — and the answer is not claiming it as+# today's observed quote. "8/12 高 149.60 为 6/16 ATH 225.64 以来最高" was+# rejected because 225.64 (the June ATH) fell outside this session's observed+# OHLC range. The marker must be adjacent to the number, so a plain field+# reading such as "8/12 高 149.60" stays checked: its 高 carries no historical+# qualifier. "创历史新高" shares the 历史新高 marker and is masked with it; the+# relaxation follows the same trade-off as prospective levels — the historical+# extreme is a reference, not an assertion about the current bar.+_REFERENCE_LEVEL_RE = re.compile(+ r"(?:"+ r"\bATH\b|all[- ]?time\s+(?:high|low)|"+ r"52\s*[- ]?W(?:EEK)?\s*(?:high|low)|52\s*[- ]?W(?:EEK)?\s*高(?:点|位)?|"+ r"52\s*周(?:高|低)(?:点|位)?|"+ r"历史(?:最高|最低|新高|新低|高|低)(?:点|位|价)?|"+ r"上市以来(?:最高|最低)(?:点|位|价)?"+ r")"+ r"\s*(?:of|为|是|约|at)?\s*[::]?\s*\(?"+ r"\s*" + _CURRENCY_TOKEN + r"\s*[-+]?\d[\d,]*(?:\.\d+)?" + _RANGE_TAIL,+ re.IGNORECASE,+)+++# A date-anchored reference puts the historical extreme after the number:+# "7/10(150.57)以来最高" and "highest since 7/10 (150.57)". The parenthesized+# value is the earlier high/low, not a current quote, and was rejected against+# the session's observed window (which does not reach back to July).+_SINCE_REFERENCE_RE = re.compile(+ r"[-+]?\d[\d,]*(?:\.\d+)?\s*\)?\s*以来(?:最高|最低|高|低)(?:点|位)?"+ # Dates are masked before this runs, so "since 7/10 (150.57)" has lost its+ # date digits by the time the connector is matched.+ r"|(?:highest|lowest)\s+since[^0-9\n]{0,16}"+ r"[-+]?\d[\d,]*(?:\.\d+)?",+ re.IGNORECASE,+)+++# A validation report cites a plan file by line number — "~line 206",+# "第 206 行" — and the number is a document location, not a price. Before+# this mask, "**文档 ~line 206「…」不成立" contributed 206.0 as a candidate+# price claim and was rejected against the observed OHLC range.+_LINE_REFERENCE_RE = re.compile(+ r"(?:~\s*)?\blines?\b\s*[:#]?\s*\d{1,5}(?:\s*[-–—至~]\s*\d{1,5})?"+ r"|第\s*\d{1,5}(?:\s*[-–—至~]\s*\d{1,5})?\s*行"+ r"|行\s*[::]?\s*\d{1,5}(?:\s*[-–—至~]\s*\d{1,5})?",+ re.IGNORECASE,+)+++# A ratio ("6:1 折算", "10:1") names a conversion basis, not a quote price.+_RATIO_RE = re.compile(r"\d+(?:\.\d+)?\s*[::]\s*\d+(?:\.\d+)?")+++# A currency conversion cited inside a report ("USD/CAD≈1.36") is a basis, not+# an instrument quote. But `EUR/USD` IS this project's canonical forex symbol+# (``backtest/engines/forex.py``, and akshare_loader accepts the slash form), so+# masking every ``AAA/BBB <number>`` would stop checking real FX quotes on a+# first-class market — an invented rate would pass. The pair form therefore+# requires an approximation marker, which a conversion basis carries and a quote+# does not: "USD/CAD≈1.36" is masked, bare "USD/CAD 1.36" stays checked. The+# labelled 汇率 / "exchange rate" form is unambiguous and needs no marker.+_FX_RATE_RE = re.compile(+ r"[A-Z]{3}\s*/\s*[A-Z]{3}\s*(?:≈|~|约)\s*\d+(?:\.\d+)?"+ r"|(?:汇率|FX\s*rate|exchange\s+rate)\s*(?:≈|~|=|为|是)?\s*\d+(?:\.\d+)?",+ re.IGNORECASE,+)+++# A trading plan quotes levels it does not claim to have observed. In the+# committee report attached to #983, "收盘 ≥6.45 且量 ≥35M手" is an entry+# trigger, "年线 4.63 成目标区" is a target zone, and neither asserts anything+# about what the instrument traded at. Compared against observed OHLC evidence+# they were reported first as numeric_claim_unavailable (before the run fetched+# prices) and then as numeric_claim_conflict (after it did) — the same false+# positive under two codes.+#+# This is a real relaxation, so every branch is span-local and anchored to the+# token that makes the number prospective, never to a word elsewhere in the+# clause: "现价 5.97,目标位 6.45" masks 6.45 and still checks 5.97. An+# assertion carries no such token and stays checked.+#+# Branch (d) accepts a conditional opener. A number inside "若收盘 5.36" is a+# hypothesis, and a hypothesis does not misrepresent observed data the way a+# bare quote does — but it is the widest branch here, so it requires the opener+# to PRECEDE the number with no digits in between, which keeps it from reaching+# back over an assertion that was already made.+_PROSPECTIVE_LEVEL_RE = re.compile(+ r"(?:"+ # (a) comparison operator immediately before the number+ r"(?:>=|<=|≥|≤|>|<|大于|小于|不低于|不高于|高于|低于)"+ r"\s*" + _CURRENCY_TOKEN + r"\s*[-+]?\d[\d,]*(?:\.\d+)?" + _RANGE_TAIL+ + r"|"+ # (b) a level marker introducing the number+ r"(?:目标位|目标区|目标价|均值目标(?:价)?|平均目标(?:价)?|止损位?|止盈位?|触发价|触发位|触发点|上看|下看|"+ r"支撑(?:阶梯|位|线)?|阻力(?:位|线)?|压力位|压力线|support(?:\s+(?:level|line|zone))?|"+ r"resistance(?:\s+(?:level|line|zone))?|target\s+(?:price|level|zone)|trigger|stop[-\s]?loss|take[-\s]?profit)"+ r"\s*(?:为|是|至|到|on|at|of|=)?\s*[::]?\s*"+ + _CURRENCY_TOKEN+ + r"\s*[-+]?\d[\d,]*(?:\.\d+)?" + _RANGE_TAIL+ + r"|"+ # (c) the number followed by a level marker+ r"" + _CURRENCY_TOKEN + r"[-+]?\d[\d,]*(?:\.\d+)?" + _RANGE_TAIL+ + r"\s*(?:一线|附近)?\s*(?:成为?|作为|是)?\s*"+ r"(?:目标区|目标位|止损位|止盈位)"+ r"|"+ # (d) a conditional opener before the number, digits fencing the reach+ r"(?:若|如果|一旦|倘若|假如|\bif\b|\bwhen\b|\bshould\b)[^0-9\n]{0,12}"+ r"[-+]?\d[\d,]*(?:\.\d+)?"+ r")",+ re.IGNORECASE,+)+++# #1354: the closed structural rule for prose price claims. A number that+# follows a price-context word is an observed value only when nothing+# formula-like binds it instead. Two closed token classes decide that:+#+# * a formula marker sitting between the price word and the number — a+# comparison/division operator, or an indicator identifier followed by+# digits (SMA/EMA/…/VWAP + digits; MA for the Chinese MA20 convention) —+# turns the number into an operand of the formula, not a claimed value;+# * an observation binder after that marker ("was", "at", 报收/收于/收报/收在)+# re-attaches the number to the price word, so "close above SMA50 and was+# 2500" stays a claim while "close/SMA50 > 1" claims nothing.+#+# This replaces the per-phrasing denylist (a signal-value mask, an indicator-+# connective mask, …) with one syntactic distinction; the catalogue of+# phrasings can never close, a closed marker set can.+_FORMULA_MARKER_RE = re.compile(+ r"(?:>=|<=|≥|≤|>|<|/)"+ r"|\b(?:SMA|EMA|WMA|DMA|MA|RSI|MACD|ATR|ADX|CCI|OBV|KDJ|BOLL|VWAP)\d+\b",+ re.IGNORECASE | re.ASCII,+)+++_OBSERVATION_BINDER_RE = re.compile(+ r"\b(?:was|were|is|are|at)\b|(?:报收|收于|收报|收在)|==|=|≈",+ re.IGNORECASE,+)+++def _matches_any(raw: Any, values: Sequence[float], *, rel: float = 0.005) -> bool:+ """Whether a measurement-shaped figure equals one of ``values``.++ Args:+ raw: A figure as ``_measure_numbers`` returns it ("1.136", "5.26%").+ values: Numeric values to match against.+ rel: Relative tolerance, absolute floor 1e-9.++ Returns:+ True when the parsed figure matches any value.+ """+ try:+ number = float(str(raw).strip().rstrip("%%").replace(",", ""))+ except ValueError:+ return False+ return any(abs(number - value) <= max(abs(value) * rel, 1e-9) for value in values)+++def _figure_reads_as_a_price(text: str, figure: str) -> bool:+ """Whether ``figure`` is written as a price somewhere in ``text``.++ A price word ahead of it in the clause, a currency symbol in front of it,+ or a currency/unit token glued behind it. Any one of the three is the+ ordinary way an answer quotes a price, and none of them is how a metric+ figure is written.++ Args:+ text: The clause or cell the figure appears in.+ figure: The figure exactly as it was written.++ Returns:+ True when at least one occurrence reads as a price.+ """+ for match in re.finditer(re.escape(figure), text):+ if _UNIT_TOKEN_AFTER_RE.match(text, match.end()):+ return True+ if _CURRENCY_BEFORE_RE.search(text[: match.start()]):+ return True+ if _PRICE_CONTEXT_RE.search(text[: match.start()]):+ return True+ return False+++def _labels_its_result_observed(text: str, formula_start: int) -> bool:+ """Whether a market-print word to the left CLAIMS the formula's result.++ The distinguisher is a result separator between the price word and the+ formula's first operand. "收盘价 = 1.171 × 0.80" reads "the close IS this+ expression" — the equation's subject is an observation, so its result is+ a fabricated print. "基于收盘价 1.171 × 0.97 = 1.136" reads "starting from+ the observed close" — the word labels an OPERAND, and the result is the+ entry price the answer proposes, which is the shape the correction prompt+ asks the model to write.++ Args:+ text: The clause the formula was found in.+ formula_start: Where the formula's arithmetic run starts in it.++ Returns:+ True when the formula's result is claimed to be an observed print.+ """+ last: re.Match[str] | None = None+ for match in _OBSERVED_PRICE_WORD_RE.finditer(text[:formula_start]):+ last = match+ if last is None:+ return False+ return bool(_RESULT_SEPARATOR_RE.search(text[last.end() : formula_start]))+++_TABLE_FIELD_ALIASES = {+ "open": "open",+ "opening": "open",+ "opening price": "open",+ "开盘": "open",+ "开盘价": "open",+ "high": "high",+ "highest": "high",+ "最高": "high",+ "最高价": "high",+ "low": "low",+ "lowest": "low",+ "最低": "low",+ "最低价": "low",+ "close": "close",+ "closing": "close",+ "closing price": "close",+ "收盘": "close",+ "收盘价": "close",+}+++_DATE_HEADERS = {"date", "datetime", "trade date", "timestamp", "日期", "交易日", "时间"}+++# A price word that asserts the figure is a MARKET PRINT — an OHLC field or a+# spot quote. Such a figure is an observation, and an observation is never+# something a formula produces: "2026-06-23 收盘价 = 1.171 × 0.80 = 0.937"+# is arithmetic whose result is claimed to be a close the ledger holds as+# 1.137, and the bare-equation derivation exemption released it. Only the+# formula's OPERANDS stay exempt under such a label; see+# ``_labels_its_result_observed``.+#+# The OHLC half is DERIVED from ``_TABLE_FIELD_ALIASES``, which is the table+# path's own source of truth and already carries both scripts — the previous+# hand-written prose list held "closing price" but not "closed at", and+# "收盘价" but not "收盘为". The four bare English words are dropped: "open" is+# a verb, "high"/"low" are adjectives, and "close" only counts when it is not+# "close to". The spot half has no table equivalent and is written out.+_OHLC_PROSE_WORDS = sorted(+ (alias for alias in _TABLE_FIELD_ALIASES if alias not in {"open", "high", "low", "close"}),+ key=len,+ reverse=True,+)+++_OBSERVED_PRICE_WORD_RE = re.compile(+ "(?:"+ # ASCII aliases take word boundaries so "closing" does not match inside+ # "disclosing"; the CJK ones are written without spaces and must not.+ + "|".join(+ (r"\b" + re.escape(word) + r"\b") if word.isascii() else re.escape(word)+ for word in _OHLC_PROSE_WORDS+ )+ + r"|\b(?:closed|opened|settled|fixed|traded|quoted|last[- ]traded|changed hands)\s+at\b"+ + r"|\bthe\s+(?:close|open|high|low)\s+(?:was|is)\b"+ + r"|\b(?:last|previous|prior|session|intraday|day's|today's)\s+(?:close|open|high|low)\b"+ + r"|\bclose\b(?!\s+to\b)"+ + r"|\b(?:current|latest|market|spot|share|last(?: traded)?)\s+price\b"+ + r"|\bthe\s+quote\b|\btrad(?:es|ing)\s+at\b|\bchanges?\s+hands\s+at\b"+ + r"|收盘于|收盘为|收报|报收|收于|现价|最新价|最新成交价|成交价|市价|报价|现报|股价"+ + ")",+ re.IGNORECASE,+)+++# A loader's id is ASCII, but the answer follows the user's language, so a+# Chinese report names the same provider in Chinese. Demanding the ASCII id+# verbatim rejected correct prose: an answer reading "数据来源:腾讯财经" was+# reported as ``data_source_not_surfaced`` against evidence sourced from+# ``tencent``, and no rewrite short of writing the English word could pass.+_SOURCE_ALIASES = {+ "akshare": ("akshare", "ak share"),+ "baostock": ("baostock",),+ "binance": ("binance", "币安"),+ "ccxt": ("ccxt",),+ "eastmoney": ("eastmoney", "东方财富", "东财"),+ "futu": ("futu", "富途"),+ "mootdx": ("mootdx", "通达信"),+ "okx": ("okx", "欧易"),+ "pykrx": ("pykrx", "krx"),+ "sina": ("sina", "新浪"),+ "stooq": ("stooq",),+ "tencent": ("tencent", "腾讯"),+ "tushare": ("tushare",),+ "yahoo": ("yahoo", "雅虎"),+ "yfinance": ("yfinance", "yahoo", "雅虎"),+}+++# "元" is how a Chinese answer writes a CNY quote, but it is also the tail of+# 港元/美元/日元, so accepting it unguarded would let an answer about a Hong Kong+# listing satisfy a CNY requirement. It counts only when no other currency's+# character owns it.+_BARE_YUAN_RE = re.compile(r"(?<![港美日欧韩台新加澳])元")+++_CURRENCY_ALIASES = {+ "USD": ("usd", "us$", "美元", "美金"),+ # ¥ is how a model actually writes a CNY quote. It is the yen sign too, but+ # ``_infer_currency`` maps no venue to JPY, so nothing in this system can+ # mean yen by it; adding a JPY venue means revisiting this entry.+ "CNY": ("cny", "cnh", "rmb", "人民币", "¥", "¥"),+ "HKD": ("hkd", "hk$", "港元", "港币"),+ "KRW": ("krw", "韩元", "韩圜"),+ "INR": ("inr", "印度卢比", "卢比"),+ "CAD": ("cad", "c$", "加元", "加拿大元"),+}+++_SYMBOL_HEADERS = {"symbol", "ticker", "code", "标的", "代码", "证券代码"}+++@dataclass(frozen=True)+class ValidationResult:+ """Final-answer grounding decision."""++ valid: bool+ issues: list[dict[str, Any]] = field(default_factory=list)+++class _PolicyMixin:+ """Policy behaviour of :class:`GroundingLedger`."""++ def _validate_identity(self, content: str) -> list[dict[str, Any]]:+ """Validate aggregate state and listed/private contradictions."""+ issues: list[dict[str, Any]] = []+ status = self.identity_status+ # Two conditions, both load-bearing.+ #+ # ``self._identities`` — a run that never named an instrument has no+ # identity to get wrong. The trigger phrase is matched against the user+ # message, so "什么是市盈率估值法?" set identity_required and then failed+ # every draft it could ever produce, including the honest answer. This+ # relaxation invents no licence to guess: a figure still has to survive+ # ``_validate_price_claims``, and a figure attached to a symbol no tool+ # handled still has to survive ``_validate_unsourced_symbols``.+ #+ # ``ambiguous`` is deliberately absent. A shortlist is an answer, which+ # is why ``_RESOLUTION_INCOMPLETE_STATUSES`` already lets workflow+ # selection proceed on it (#955) — but the final answer stayed blocked,+ # so a screening run loaded its skill and was then refused a conclusion.+ # Consumers remain blocked on ambiguous in ``authorize_tool_call``, so+ # such a run still cannot fetch a quote to misattribute.+ if (+ self._identity_required+ and self._identities+ and status in {"unresolved", "conflicting", "invalidated"}+ ):+ issues.append(+ {+ "code": "identity_not_locked",+ "status": status,+ "message": f"Instrument identity is {status}; a final market conclusion requires locked identity.",+ }+ )+ listed = [+ record+ for record in self._identities.values()+ if record.status == "locked"+ and record.instrument_type in {"listed_security", "fund"}+ ]+ if listed and _PRIVATE_ASSERTION_RE.search(content):+ symbols = sorted(record.symbol for record in listed if record.symbol)+ issues.append(+ {+ "code": "listed_identity_relabelled_private",+ "symbols": symbols,+ "message": (+ f"Locked listed identity {', '.join(symbols)} was relabelled as private/unlisted "+ "without a conflicting resolver result."+ ),+ }+ )+ return issues++ def _validate_unsourced_symbols(self, content: str) -> list[dict[str, Any]]:+ """Reject figures attached to an instrument no tool in this run handled.++ This is the mechanically decidable half of "what the tools did not+ return, you do not supply" (#886/#887). Naming a symbol is left alone —+ prose may legitimately mention an index or a peer — but the moment a+ clause pairs an unhandled canonical symbol with a figure, the figure has+ no possible origin other than model memory.++ Args:+ content: Candidate assistant answer.++ Returns:+ One issue per distinct unsourced symbol carrying figures.+ """+ issues: list[dict[str, Any]] = []+ reported: set[str] = set()+ for line, line_offset in _lines_with_offsets(content):+ for segment, span_start, span_end in _clause_spans(line, line_offset):+ unknown = sorted(+ symbol+ for symbol in _scan_symbols(segment) - self._session_symbols - reported+ if symbol.rsplit(".", 1)[0] not in self._session_symbol_roots+ )+ if not unknown or not self._numbers_without_dates_or_percent(segment):+ continue+ # Accept figures that are attributed to an external source+ # (e.g., "The paper reports a Sharpe ratio of 1.8.") rather+ # than model memory. Scoped to the clause: a line-level check+ # would let a citation in one clause launder an invented+ # sibling metric in the next.+ if _ATTRIBUTION_RE.search(segment):+ continue+ for symbol in unknown:+ reported.add(symbol)+ issues.append(+ {+ "code": "unsourced_symbol_figures",+ "symbol": symbol,+ "claim": segment.strip()[:200],+ "span": [span_start, span_end],+ "message": (+ f"No tool call in this session passed in or returned {symbol}, "+ "yet the answer attaches figures to it. Retrieve it, or report "+ "it as not retrieved."+ ),+ }+ )+ return issues++ def _validate_analysis_claims(self, content: str) -> list[dict[str, Any]]:+ """Reject backtest/analysis metrics with no kind-scoped evidence.++ #1336: after failed or deduplicated market-data calls the model may+ still present return-volatility / drawdown / probability figures as+ measured facts. A metric figure is legitimate only when the run's+ evidence contains the same *kind* of figure — recorded from a+ completed analysis result (backtest artifacts, factor/shadow/quantlib+ output) or from any successful tool's numeric output (e.g.+ ``portfolio_risk_xray``, flattened into ``_evidence``). Kind scoping+ is what keeps an observed price from standing in for an invented+ volatility figure. Definitional prose ("夏普比率大于 1.0 通常被认为+ 较好"), explicitly forward-looking forecasts, and categorical+ historical-window facts without any window-producing analysis are+ handled separately here.++ Args:+ content: Candidate assistant answer.++ Returns:+ One issue per metric-bearing clause or table cell.+ """+ issues: list[dict[str, Any]] = []+ positions = _lines_with_offsets(content)+ lines = [line for line, _ in positions]+ consumed: set[int] = set()+ price_records = self._comparable_price_records()+ for header, rows, row_indices in self._pipe_tables(lines):+ consumed.update(row_indices)+ columns = [+ (cell, _metric_kind_for_text(cell), bool(_FORECAST_FRAME_RE.search(cell)))+ for cell in header+ ]+ has_kind_header = any(kind for _, kind, _ in columns)+ for row, row_line_index in zip(rows, row_indices):+ row_start = positions[row_line_index][1]+ row_span = (row_start, row_start + len(lines[row_line_index]))+ cells = row + [""] * (len(columns) - len(row))+ if not has_kind_header:+ # Generic header ("指标 | 数值", "Metric | Value"): a cell+ # naming a metric kind is a row LABEL and claims exactly+ # one adjacent value cell (right first — "label, value"+ # order — then left, for value-first layouts). Validating+ # every cell after the label would grab annotation columns+ # ("备注 | 较去年提升 2%") that prose never attributes to+ # the label; parity with the prose verdict is the bar.+ row_kinds = [+ (index, _metric_kind_for_text(cell))+ for index, cell in enumerate(cells)+ if _metric_kind_for_text(cell) is not None+ ]+ claimed: set[int] = set()+ for label_index, row_kind in row_kinds:+ # A label cell that smuggles its own measurement+ # ("| 年化收益率 18.2% | - |") is prose-identical to+ # "年化收益率为 18.2%" — validate the label's own+ # numbers against its kind too.+ self._check_table_cell(+ cells[label_index], row_kind, cells[label_index], issues,+ row_span, price_records,+ )+ # A forecast frame in the LABEL ("| 预计夏普比率 | 1.2 |")+ # frames the claimed value clause-wide, exactly as prose+ # exempts the whole clause and the metric-header path+ # skips a forecast-framed column. Without this the generic+ # path is stricter than both of its siblings.+ label_is_forecast = bool(+ _FORECAST_FRAME_RE.search(cells[label_index])+ )+ for value_index in (label_index + 1, label_index - 1):+ if (+ 0 <= value_index < len(cells)+ and value_index not in claimed+ and _metric_kind_for_text(cells[value_index]) is None+ ):+ claimed.add(value_index)+ if label_is_forecast:+ continue+ self._check_table_cell(+ cells[label_index], row_kind, cells[value_index], issues,+ row_span, price_records,+ )+ continue+ for (cell_text, kind, header_forecast), cell in zip(columns, cells):+ if kind is None or header_forecast:+ continue+ self._check_table_cell(+ cell_text, kind, cell, issues, row_span, price_records+ )+ for index, (line, line_offset) in enumerate(positions):+ if index in consumed:+ continue+ line_symbol = self._symbol_for_claim(line, price_records)+ for segment, span_start, span_end in _clause_spans(line, line_offset):+ if _CATEGORICAL_WINDOW_RE.search(segment) and _NUMBER_RE.search(segment):+ if not any(+ entry.get("tool") in _ANALYSIS_WINDOW_TOOLS+ for entry in self._analysis_completed+ ):+ match = _NUMBER_RE.search(segment)+ issues.append(+ {+ "code": "analysis_claim_unavailable",+ "claim": segment.strip()[:200],+ "span": [span_start, span_end],+ "value": match.group(0) if match else None,+ "message": (+ "No backtest completed in this session, yet the "+ "answer states a categorical historical-window "+ "fact. Mark the analysis as incomplete and omit "+ "this claim."+ ),+ }+ )+ continue+ if _DEFINITION_FRAME_RE.search(segment):+ continue+ # Attributed figures ("The paper reports a Sharpe of 1.8",+ # or the marker in a neighbouring clause: "据研究显示,策略+ # 年化收益 18.2%") are citations, not invented measurements+ # — skip the gate.+ if _ATTRIBUTION_RE.search(segment):+ continue+ values = self._measure_numbers(segment)+ if not values:+ continue+ if not _ANALYSIS_METRIC_RE.search(segment):+ continue+ if _FORECAST_FRAME_RE.search(segment):+ continue+ kind = _metric_kind_for_text(segment)+ unsupported = [+ value+ for value in values+ if not self._analysis_value_observed(value, kind)+ and not self._is_observed_price_figure(+ value, price_records, line_symbol, segment+ )+ ]+ if not unsupported:+ continue+ # A return figure may be arithmetic on sourced inputs rather+ # than an invented backtest metric (#1338 review): an explicit+ # formula anchored to observed values, or growth between two+ # observed endpoints stated in the same line.+ # A drawdown stated against an observed high ("较 5 月高点+ # 1.053 元已回撤约 37%") is the same arithmetic on the same+ # sourced endpoints, and was rejected as an invented backtest+ # metric because only the return branch carried the exemption+ # (owner-forwarded 159516.SZ run, 2026-09-09). Drawdown is+ # compared by magnitude, as ``_analysis_value_observed`` does.+ # Neither exemption is available to a STRATEGY-subject+ # metric. A strategy's max drawdown is a property of an+ # equity curve, and no arithmetic on two observed prints of+ # the instrument is that curve: "回测显示该策略最大回撤 5.9%+ # (从 1.180 跌至 1.110)" was released as grounded with no+ # backtest in the session at all. Such a figure keeps the+ # unchanged backtest-evidence requirement above.+ if kind in {"return", "drawdown"} and not _STRATEGY_SUBJECT_RE.search(+ segment+ ):+ if _DERIVATION_RE.search(segment):+ # As in the price path: only the values the formula+ # justifies are exempt, not every figure beside them.+ # Scoped to the CLAUSE, which is where the claim+ # itself was measured — a line-scoped exemption let+ # "基于 40 × 1.171 = 46.84 计算,策略最大回撤 40%"+ # ground the metric in the next clause.+ justified = self._derivation_justified_values(+ segment, price_records, line_symbol+ )+ unsupported = [+ value+ for value in unsupported+ if not _matches_any(value, justified)+ ]+ if not unsupported:+ continue+ # The operand scan stays LINE-scoped: the endpoints of a+ # move are routinely written in two clauses ("当前 0.666+ # 元,较 5 月高点 1.053 元已回撤约 37%").+ operands = self._observed_operands_in_line(+ line, price_records, line_symbol+ )+ if len(operands) >= 2:+ derived = self._returns_derived_from_observed(+ unsupported,+ price_records,+ line_symbol,+ operands=operands,+ magnitude=kind == "drawdown",+ )+ # The endpoints themselves are grounded by the same+ # exemption: "较高点 1.180 元已回撤约 6%" states the+ # observed high beside the ratio it derives.+ unsupported = [+ value+ for value in unsupported+ if value not in derived+ and not (+ not str(value).endswith(("%", "%"))+ and _matches_any(value, operands, rel=1e-9)+ )+ ]+ if not unsupported:+ continue+ issues.append(+ {+ "code": "analysis_claim_unavailable",+ "claim": segment.strip()[:200],+ "span": [span_start, span_end],+ "value": unsupported[0],+ "kind": kind,+ "message": (+ "No supporting analysis evidence (a completed "+ "backtest result or observed risk metric) exists for "+ "this figure. Mark the analysis as incomplete and omit "+ "these figures."+ ),+ }+ )+ return issues++ def _check_table_cell(+ self,+ label: str,+ kind: str | None,+ cell: str,+ issues: list[dict[str, Any]],+ span: tuple[int, int] | None = None,+ price_records: Sequence[EvidenceRecord] = (),+ ) -> None:+ """Reject one table cell whose numeric value is an unsupported metric.++ Shared by the metric-headed and generic-header (label, value) table+ paths. A forecast or definitional annotation exempts only that cell.++ Args:+ label: The metric label the value is attached to (header cell or+ row's first cell), for the issue claim text.+ kind: The resolved metric kind, already derived from ``label``.+ cell: One value cell to validate.+ issues: Accumulator for ``analysis_claim_unavailable`` issues.+ span: ``(start, end)`` of the table ROW inside the validated+ answer. The claim text is the human-readable ``label: cell``,+ which is not a substring of the draft ("| 最大回撤 | 12% |"),+ so without the span the release path could never locate a+ metric table and every metrics report fell back to the canned+ refusal.+ price_records: Comparable observed price evidence, so a cell that+ merely restates observed closes ("| 峰值→当前 | 0.997 → 0.605 |")+ is not reported as an invented drawdown figure and then cut+ out of the released answer. Same rule as the prose path.+ """+ if kind is None:+ return+ values = _PolicyMixin._measure_numbers(cell)+ if not values:+ return+ # A forecast annotation inside the cell ("预计 12.4%") exempts only+ # that cell, never its neighbours.+ if _FORECAST_FRAME_RE.search(cell) or _DEFINITION_FRAME_RE.search(cell):+ return+ # A cell RESTATING endpoints ("| 峰值→当前 | 1.180 → 1.110 |") is not+ # a metric figure, and cutting it out of the released answer removed+ # two correctly quoted closes. The restatement shape is what the+ # exemption is for, so it needs the cell to hold a PAIR: a single+ # number in a metric cell IS that metric's value, and exempting it on+ # numeric equality alone released "| 夏普比率 | 1.171 |" as grounded+ # because 1.171 happened to be an observed close. On a $12.50 stock+ # the collision is "| 最大回撤 | 12.5 |".+ unsupported = [+ value+ for value in values+ if not self._analysis_value_observed(value, kind)+ and not (+ len(values) >= 2+ and self._matches_observed_price(value, price_records, None)+ )+ ]+ if not unsupported:+ return+ issues.append(+ {+ "code": "analysis_claim_unavailable",+ "claim": f"{label}: {cell}"[:200],+ "span": list(span) if span else None,+ "value": unsupported[0],+ "kind": kind,+ "message": (+ "No supporting analysis evidence (a completed "+ "backtest result or observed risk metric) exists "+ "for this figure. Mark the analysis as incomplete "+ "and omit these figures."+ ),+ }+ )++ @staticmethod+ def _measure_numbers(text: str) -> list[str]:+ """Extract measurement-shaped numbers (decimal or percent) from a claim."""+ masked = _LOCALIZED_DATE_RE.sub(" ", text)+ masked = _DATE_RE.sub(" ", masked)+ masked = _SHORT_DATE_RE.sub(" ", masked)+ masked = _DASH_DATE_RE.sub(" ", masked)+ return [+ match.group(0).replace(" ", "").replace(",", "")+ for match in _MEASURE_NUMBER_RE.finditer(masked)+ ]++ @staticmethod+ def _pipe_tables(+ lines: Sequence[str],+ ) -> list[tuple[list[str], list[list[str]], list[int]]]:+ """Yield (header cells, row cells, row line indices) per pipe table."""+ tables: list[tuple[list[str], list[list[str]], list[int]]] = []+ index = 0+ while index < len(lines):+ if lines[index].count("|") < 2:+ index += 1+ continue+ block_start = index+ block: list[str] = []+ while index < len(lines) and lines[index].count("|") >= 2:+ block.append(lines[index])+ index += 1+ rows: list[list[str]] = []+ row_indices: list[int] = []+ for offset, block_line in enumerate(block[1:], start=1):+ cells = _PolicyMixin._table_cells(block_line)+ if not cells or all(+ _TABLE_SEPARATOR_RE.fullmatch(cell.strip()) for cell in cells+ ):+ continue+ rows.append(cells)+ row_indices.append(block_start + offset)+ tables.append((_PolicyMixin._table_cells(block[0]), rows, row_indices))+ return tables++ def _analysis_value_observed(self, raw: str, kind: str | None) -> bool:+ """Return True when a claim measurement matches kind-scoped evidence.++ Tools disagree on scale: ``compute_risk_xray`` returns fractions+ (annualized_vol 0.182, max_drawdown -0.094) while answers quote+ percents (18.2%, -9.4%). Try both the value and its percent scaling+ so an observed 0.182 grounds an 18.2% claim and vice versa. Drawdown+ sign conventions disagree too (positive vs negative fraction), so+ magnitude is compared for that kind. Only evidence of the claim's own+ kind counts: an observed price never grounds a volatility figure.+ """+ try:+ value = float(raw.replace("%", "").replace("%", "").replace(",", ""))+ except ValueError:+ return True+ observed: list[float] = []+ for record in self._analysis_metrics:+ if record.get("metric") == kind and record.get("value") is not None:+ observed.append(float(record["value"]))+ for record in self._evidence:+ if record.status != "observed" or record.value is None:+ continue+ if _metric_kind_for_path(record.field) != kind:+ continue+ observed.append(float(record.value))+ candidates = {value, value / 100.0}+ if kind == "drawdown":+ candidates |= {abs(value), abs(value) / 100.0}++ def close(candidate: float, item: float) -> bool:+ return abs(candidate - item) <= max(abs(item) * 0.005, 1e-9)++ return any(close(candidate, item) for candidate in candidates for item in observed)++ def _is_observed_price_figure(+ self,+ raw: str,+ records: Sequence[EvidenceRecord],+ symbol: str | None,+ text: str,+ ) -> bool:+ """Whether a figure in an analysis clause is literally an observed price.++ ``_validate_analysis_claims`` reports the FIRST unmatched number in a+ clause that mentions a metric, and an observed close sharing a clause+ with an ungrounded metric was that number: "最新收盘 1.171 元且策略最大+ 回撤 12%" reported 1.171, so the release path cut the correctly quoted+ close and footnoted it as unverifiable. A value the ledger observed is+ not an invented backtest metric — its own check is+ ``_compare_price_claim``, which compares any price-word figure against+ observed OHLC at the 0.5% band. A percent-written figure is never+ exempted here, so every drawdown / return / volatility / win-rate+ percentage keeps the full analysis check.++ Numeric equality is not enough on its own. A run holds hundreds of+ observed OHLC values spanning the instrument's price range, so ANY+ percent-free metric written in that range collides with one:+ "策略夏普比率 1.171" and "策略最大回撤 1.171" were released as grounded+ against an observed close, with no backtest in the session. The figure+ must also be WRITTEN as a price — a price word ahead of it or a+ currency unit glued to it — which is exactly the shape that has its+ own check in ``_compare_price_claim``.++ Args:+ raw: A figure as ``_measure_numbers`` returns it.+ records: Comparable observed price evidence.+ symbol: Symbol resolved for the line, if any.+ text: The clause the figure was written in.++ Returns:+ True when the figure is written without a percent sign, reads as a+ price in its clause, and equals an observed price value for this+ symbol.+ """+ figure = str(raw).strip()+ if not _figure_reads_as_a_price(text, figure):+ return False+ return self._matches_observed_price(figure, records, symbol)++ def _matches_observed_price(+ self,+ raw: str,+ records: Sequence[EvidenceRecord],+ symbol: str | None,+ ) -> bool:+ """Whether a percent-free figure equals an observed price value.++ Args:+ raw: A figure as ``_measure_numbers`` returns it.+ records: Comparable observed price evidence.+ symbol: Symbol resolved for the claim, if any.++ Returns:+ True when the figure carries no percent sign and matches evidence.+ """+ figure = str(raw).strip()+ if figure.endswith(("%", "%")):+ return False+ candidates = list(records)+ if symbol:+ candidates = [record for record in candidates if record.symbol == symbol]+ observed = [+ float(record.value) for record in candidates if record.value is not None+ ]+ return _matches_any(figure, observed, rel=1e-9)++ def _observed_operands_in_line(+ self,+ line: str,+ records: Sequence[EvidenceRecord],+ symbol: str | None,+ ) -> list[float]:+ """Observed values that literally appear as numbers in this clause.++ This is the structural half of the derivation exemption. Keying it on+ a growth PHRASE ("从…到" / "from…to") made the gate stricter for every+ wording the list happened to miss, which is the same per-language+ drift that ``test_grounding_language_parity`` exists to stop: the+ Chinese "第一日收盘 100.0 美元,第二日收盘 112.4 美元,收益率 12.4%"+ states the identical derivation and was rejected. Requiring the+ operands themselves to be present and sourced is language-independent+ and strictly narrower than a phrase list, because a bare+ "cumulative return of 12.4%" carries no operands at all.+ """+ candidates = [record for record in records if record.value is not None]+ if symbol:+ candidates = [record for record in candidates if record.symbol == symbol]+ observed = {float(record.value) for record in candidates}+ if not observed:+ return []+ present: set[float] = set()+ for raw in self._numbers_without_dates_or_percent(line):+ try:+ value = float(raw)+ except (TypeError, ValueError):+ continue+ for candidate in observed:+ if abs(value - candidate) <= max(abs(candidate) * 1e-9, 1e-9):+ present.add(candidate)+ return sorted(present)++ def _returns_derived_from_observed(+ self,+ claimed: Sequence[str],+ records: Sequence[EvidenceRecord],+ symbol: str | None,+ *,+ operands: Sequence[float] | None = None,+ magnitude: bool = False,+ ) -> set[str]:+ """Return the figures that equal growth between observed endpoints.++ #1338 review: "AAPL.US 从 2026-08-03 的 100.0 涨到 2026-09-02 的+ 112.4,区间收益率为 12.4%" states arithmetic on sourced inputs. Only+ a match against a pair of observed values grounds the figure; the+ caller must already have verified the from/to frame, so a bare+ unanchored return claim never reaches here.++ The match tolerates the precision the figure was WRITTEN at: "约 37%"+ for a derived 36.75% asserts that the value rounds to 37, and the flat+ ±0.5% relative band (±0.18 points there) rejected every integer-percent+ rounding a model makes. Half a unit of the last written digit is the+ bound, so "37%" accepts 36.5–37.5 and "36.8%" accepts 36.75–36.85; a+ figure that is simply wrong ("40%") is as far away as before.++ Args:+ claimed: Raw figures from the clause, as ``_measure_numbers`` returns them.+ records: Observed evidence the operands may come from.+ symbol: Symbol the clause names, if any.+ operands: Observed values literally present in the clause.+ magnitude: Compare absolute values (drawdown sign conventions differ).++ Returns:+ The subset of ``claimed`` the endpoint arithmetic justifies. It+ used to be one bool for the whole clause, and the caller skipped+ every figure beside the justified one: "at 0.666 down about 37%+ from the 1.053 May high with a max drawdown of 60%" released the+ 60% because the 37% checked out.+ """+ if operands is not None:+ observed = sorted(set(operands))+ else:+ candidates = [record for record in records if record.value is not None]+ if symbol:+ candidates = [+ record for record in candidates if record.symbol == symbol+ ]+ observed = sorted({float(record.value) for record in candidates})+ if len(observed) < 2:+ return set()+ values: list[tuple[str, float, float, bool]] = []+ for raw in claimed:+ raw_text = str(raw).strip()+ text = raw_text.rstrip("%%")+ try:+ value = float(text)+ except ValueError:+ continue+ decimals = len(text.split(".", 1)[1]) if "." in text else 0+ values.append((str(raw), value, 0.5 * 10.0 ** (-decimals), raw_text != text))++ def close(value: float, derived: float, half_unit: float) -> bool:+ if magnitude:+ # A drawdown is a fall. Taking absolute values so "回撤 37%"+ # can match a derived -36.75% also made the INVERSE+ # derivation match: the same two endpoints read low→high give+ # +58.11%, and "最大回撤约 58%" was released as grounded+ # (attack2 probe, 2026-09-09). Only the falling direction may+ # ground a drawdown.+ if derived > 0:+ return False+ value, derived = abs(value), abs(derived)+ return abs(value - derived) <= max(abs(derived) * 0.005, half_unit, 1e-9)++ justified: set[str] = set()+ for base in observed:+ for target in observed:+ if target == base:+ continue+ derived = (target - base) / base+ for raw, value, half_unit, is_percent in values:+ # ``half_unit`` is half a unit of the last digit the figure+ # was WRITTEN with, so it is only meaningful against the+ # derivation expressed in those same units. A figure+ # carrying "%" is percentage points and is compared only+ # against ``derived * 100``; running it against the+ # fraction too gave an integer percent a 0.5 band in+ # FRACTION units — 50 percentage points — and "区间收益率+ # 约 0%" validated against a real +58% move (attack4+ # probe, 2026-09-09). A bare figure stays ambiguous and is+ # tried both ways, each against its own consistent band.+ # A bare figure always carries a decimal point —+ # ``_MEASURE_NUMBER_RE`` extracts an integer only with a+ # percent sign on it — so the fraction reading is never+ # taken with a 0.5 half unit (which would be 50+ # percentage points wide).+ if not is_percent and close(value, derived, half_unit):+ justified.add(raw)+ if close(value, derived * 100.0, half_unit):+ justified.add(raw)+ return justified++ @staticmethod+ def _occurrence_is_derived(+ segment: str,+ formulas: Sequence[tuple[int, int, list[float], float]],+ value: float,+ start: int,+ end: int,+ ) -> bool:+ """Whether this figure, HERE, is part of a formula that justifies it.++ Two things are decided per occurrence rather than per value.++ The position: a number is exempt only where it sits inside the+ formula. "建议买入价 0.95 元(0.95 × 1.171 = 1.11245 参考)" is arithmetic+ that derives nothing, and under a value-scoped exemption the entry+ price outside the bracket inherited the exemption its own copy inside+ the bracket earned.++ The role: a formula's RESULT is a number the answer proposes, which is+ legitimate for an entry price and never legitimate for a market print.+ "2026-06-23 收盘价 = 1.171 × 0.80 = 0.937" claims a close the ledger+ holds as 1.137, and the exemption released it. Under an observation+ label the operands stay exempt and the result is compared.++ Args:+ segment: The clause the figure was found in.+ formulas: ``_derivation_formulas`` output for that clause.+ value: The figure.+ start: Where the figure starts in ``segment``.+ end: Where it ends.++ Returns:+ True when the occurrence may skip the price comparison.+ """+ for formula_start, formula_end, inputs, result in formulas:+ if not (formula_start <= start and end <= formula_end):+ continue+ if _matches_any(value, inputs):+ return True+ if _matches_any(value, [result]) and not _labels_its_result_observed(+ segment, formula_start+ ):+ return True+ return False++ def _validate_price_claims(self, content: str) -> list[dict[str, Any]]:+ """Check Markdown OHLC tables and price prose against observed records.++ Comparison runs against every observed quote in the run, whichever tool+ produced it. The provenance demands below stay keyed on ``get_market_data``+ evidence, whose ``source``/``currency``/venue fields are authoritative;+ a generic tool's fallback source is its own name, and requiring the+ answer to spell that out would reject correct prose.+ """+ issues, table_lines = self._validate_price_tables(content)+ records = self._comparable_price_records()+ # A report names its subject once and then writes prose about it. Both+ # narrower scopes are tried first; this is the last resort, and it only+ # resolves when the whole answer names exactly one evidence symbol.+ document_symbol = self._symbol_for_claim(content, records)+ has_price_claim = any(+ self._numbers_without_dates_or_percent(line)+ for index, line in enumerate(content.splitlines())+ if index in table_lines+ )+ for index, (line, line_offset) in enumerate(_lines_with_offsets(content)):+ if index in table_lines or "|" in line:+ continue+ line_symbol = self._symbol_for_claim(line, records)+ for segment, span_start, span_end in _clause_spans(line, line_offset):+ if not _PRICE_CONTEXT_RE.search(segment):+ continue+ values = self._direct_price_values(segment)+ if not values:+ continue+ has_price_claim = True+ symbol = (+ self._symbol_for_claim(segment, records)+ or line_symbol+ or document_symbol+ )+ # Only the formula's own operands and result are exempt, at+ # the position where they sit; a figure riding along in the+ # same clause is still compared.+ formulas = self._derivation_formulas(segment, records, symbol)+ # NO attribution exemption here, deliberately. A paper's+ # Sharpe is a figure this run could never have observed, so+ # citing it is legitimate; a PRICE is exactly what this run+ # does observe, so "analysts say TSLA.US last traded at+ # 412.35" is the laundering shape this gate exists to catch —+ # adding a citation subject must not buy a fabricated quote a+ # way through. The exemption stays in the analysis gate only.+ #+ # An indicator reading is admissible evidence only for a+ # LEVEL claim; a clause claiming a market print is answered by+ # OHLC evidence alone.+ indicator_admissible = bool(+ _PRICE_LEVEL_WORD_RE.search(segment)+ ) and not _OBSERVED_PRICE_WORD_RE.search(segment)+ for value, value_start, value_end in values:+ if self._occurrence_is_derived(+ segment, formulas, value, value_start, value_end+ ):+ continue+ issue = self._compare_price_claim(+ value=value,+ records=records,+ field_name=None,+ date_value=None,+ symbol=symbol,+ claim=segment.strip(),+ span=(span_start, span_end),+ indicator_admissible=indicator_admissible,+ )+ if issue:+ issues.append(issue)+ market_records = self._price_records()+ if has_price_claim and market_records:+ issues.extend(self._validate_price_provenance(content, market_records))+ return self._dedupe_issues(issues)++ @staticmethod+ def _symbol_for_claim(+ content: str,+ records: Sequence[EvidenceRecord],+ ) -> str | None:+ """Return one canonical evidence symbol explicitly named in a claim."""+ known = {record.symbol for record in records if record.symbol}+ matches = {+ _normalize_symbol(match.group(0))+ for match in _CANONICAL_SYMBOL_RE.finditer(content)+ if _normalize_symbol(match.group(0)) in known+ }+ return next(iter(matches)) if len(matches) == 1 else None++ def _validate_price_provenance(+ self,+ content: str,+ records: Sequence[EvidenceRecord],+ ) -> list[dict[str, Any]]:+ """Require canonical symbol, actual source, and quote currency in output."""+ issues: list[dict[str, Any]] = []+ folded = content.casefold()+ symbols = sorted({record.symbol for record in records if record.symbol})+ # ``_scan_symbols`` canonicalizes, so an answer that writes Shanghai as+ # ``600519.SS`` still surfaces the ``600519.SH`` identity it names.+ written = _scan_symbols(content)+ mentioned = [+ symbol+ for symbol in symbols+ if symbol in written or symbol.casefold() in folded+ ]+ if not mentioned:+ issues.append(+ {+ "code": "canonical_symbol_not_surfaced",+ "symbols": symbols,+ "message": (+ "A price claim must surface its locked canonical symbol and venue suffix."+ ),+ }+ )+ target_symbols = set(mentioned or (symbols if len(symbols) == 1 else []))+ target_records = [+ record+ for record in records+ if not target_symbols or record.symbol in target_symbols+ ]++ sources = sorted(+ {+ record.source+ for record in target_records+ if record.source and record.source.casefold() not in {"auto", "unknown"}+ }+ )+ missing_sources = [+ source+ for source in sources+ if not any(+ alias in folded+ for alias in _SOURCE_ALIASES.get(+ source.casefold(), (source.casefold(),)+ )+ )+ ]+ if missing_sources:+ issues.append(+ {+ "code": "data_source_not_surfaced",+ "sources": missing_sources,+ "message": (+ "Price claims must name the actual data source: "+ + ", ".join(missing_sources)+ + "."+ ),+ }+ )++ currencies = sorted(+ {record.currency for record in target_records if record.currency}+ )+ missing_currencies = [+ currency+ for currency in currencies+ if not self._currency_is_surfaced(currency, content)+ ]+ if missing_currencies:+ issues.append(+ {+ "code": "currency_not_surfaced",+ "currencies": missing_currencies,+ "message": (+ "Price claims must name their quote currency: "+ + ", ".join(missing_currencies)+ + "."+ ),+ }+ )+ return issues++ @staticmethod+ def _currency_is_surfaced(currency: str, content: str) -> bool:+ """Return whether a quote currency or an unambiguous alias is visible."""+ folded = content.casefold()+ code = currency.upper()+ tokens = _CURRENCY_ALIASES.get(code, (currency.casefold(),))+ if any(token.casefold() in folded for token in tokens):+ return True+ return code == "CNY" and bool(_BARE_YUAN_RE.search(content))++ def _validate_price_tables(+ self,+ content: str,+ ) -> tuple[list[dict[str, Any]], set[int]]:+ """Validate field/date-specific claims in Markdown OHLC tables."""+ positions = _lines_with_offsets(content)+ lines = [line for line, _ in positions]+ issues: list[dict[str, Any]] = []+ consumed: set[int] = set()+ index = 0+ records = self._comparable_price_records()+ while index + 1 < len(lines):+ header = self._table_cells(lines[index])+ separator = self._table_cells(lines[index + 1])+ if not header or not separator or len(header) != len(separator):+ index += 1+ continue+ if not all(_TABLE_SEPARATOR_RE.match(cell.replace(" ", "")) for cell in separator):+ index += 1+ continue+ field_columns = {+ position: _TABLE_FIELD_ALIASES[cell.strip().casefold()]+ for position, cell in enumerate(header)+ if cell.strip().casefold() in _TABLE_FIELD_ALIASES+ }+ if not field_columns:+ index += 1+ continue+ date_column = next(+ (position for position, cell in enumerate(header) if cell.strip().casefold() in _DATE_HEADERS),+ None,+ )+ symbol_column = next(+ (position for position, cell in enumerate(header) if cell.strip().casefold() in _SYMBOL_HEADERS),+ None,+ )+ consumed.update({index, index + 1})+ row_index = index + 2+ while row_index < len(lines):+ row = self._table_cells(lines[row_index])+ if not row or len(row) != len(header):+ break+ consumed.add(row_index)+ date_value = row[date_column].strip() if date_column is not None else None+ symbol = _normalize_symbol(row[symbol_column]) if symbol_column is not None else None+ for position, field_name in field_columns.items():+ values = self._numbers_without_dates_or_percent(row[position])+ if len(values) != 1:+ continue+ row_start = positions[row_index][1]+ issue = self._compare_price_claim(+ value=values[0],+ records=records,+ field_name=field_name,+ date_value=date_value,+ symbol=symbol,+ claim=row[position].strip(),+ # A table cell's claim text is a bare number, so it+ # can never be located by substring search — "1.10"+ # matched inside "21.10 亿元" and rewrote an untouched+ # turnover figure into "2(略※)". The row's own span+ # is the anchor; the value inside it is what is cut.+ span=(row_start, row_start + len(lines[row_index])),+ )+ if issue:+ issues.append(issue)+ row_index += 1+ index = max(row_index, index + 1)+ return issues, consumed++ @staticmethod+ def _table_cells(line: str) -> list[str]:+ """Split one Markdown table row, or return an empty list."""+ if "|" not in line:+ return []+ stripped = line.strip()+ if stripped.startswith("|"):+ stripped = stripped[1:]+ if stripped.endswith("|"):+ stripped = stripped[:-1]+ return [cell.strip() for cell in stripped.split("|")]++ def _compare_price_claim(+ self,+ *,+ value: float,+ records: list[EvidenceRecord],+ field_name: str | None,+ date_value: str | None,+ symbol: str | None,+ claim: str,+ span: tuple[int, int] | None = None,+ indicator_admissible: bool = False,+ ) -> dict[str, Any] | None:+ """Compare one unlabelled observed claim to the closest evidence value.++ Args:+ value: The figure the answer states.+ records: Comparable observed price evidence.+ field_name: OHLC field the claim is keyed to (table column), if any.+ date_value: Trade date the claim is keyed to, if any.+ symbol: Symbol explicitly resolved for the claim, if any.+ claim: Clause or cell text, for the issue message.+ span: ``(start, end)`` of the claim inside the validated answer.+ indicator_admissible: The prose clause states a price LEVEL+ (支撑位 / 均线 / bollinger band), the one claim an indicator+ reading may answer. Every other price claim — a named OHLC+ field, a spot quote, a proposed entry — is compared against+ OHLC evidence only, which is the rule the table path already+ applies by filtering on ``field_name``. The table path passes+ a ``field_name`` for every cell it validates and so leaves+ this at its default.+ """+ resolved_symbol = symbol+ candidates = records+ if symbol:+ candidates = [record for record in candidates if record.symbol == symbol]+ symbols = sorted({record.symbol for record in candidates if record.symbol})+ # An indicator reading is symbol-bound in a way an OHLC bar's union is+ # not. With evidence for two instruments and a clause naming neither,+ # 562500's sma_20 grounded "600519.SH … 其均线在 1.150 元"; the union+ # below was argued for OHLC quotes, not for a derived level attached+ # to one symbol. Drop indicator records whenever the claim's symbol+ # was not explicitly resolved and the run holds more than one.+ if resolved_symbol is None and len({r.symbol for r in records if r.symbol}) > 1:+ candidates = [record for record in candidates if record.field != "indicator"]+ if not indicator_admissible:+ candidates = [record for record in candidates if record.field != "indicator"]+ if not symbol and len(symbols) == 1:+ symbol = symbols[0]+ # An unattributed claim used to be rejected outright once the run held+ # evidence for more than one symbol. That is every comparison report:+ # "Apple's closing price was 313.33 USD. Microsoft closed higher." names+ # its subject by company name, and the clause was refused although the+ # value was exactly the observed close sitting in evidence. Such a claim+ # is now checked against the union of the observed quotes instead, so a+ # number the run never observed is still caught below — it simply has to+ # match nothing at all rather than nothing under one chosen symbol.+ if field_name:+ candidates = [record for record in candidates if record.field == field_name]+ if date_value:+ candidates = [+ record+ for record in candidates+ if record.timestamp+ and _timestamp_matches_claim_date(record.timestamp, date_value)+ ]+ if not candidates:+ return {+ "code": "numeric_claim_unavailable",+ "claim": claim,+ "span": list(span) if span else None,+ "value": value,+ "symbol": symbol,+ "field": field_name,+ "date": date_value,+ "message": f"Price claim {value:g} has no matching observed tool evidence.",+ }+ observed = [float(record.value) for record in candidates if record.value is not None]+ if any(abs(value - item) <= max(abs(item) * 0.005, 1e-9) for item in observed):+ return None+ return {+ "code": "numeric_claim_conflict",+ "claim": claim,+ "span": list(span) if span else None,+ "value": value,+ "symbol": symbol,+ "field": field_name,+ "date": date_value,+ "observed_min": min(observed),+ "observed_max": max(observed),+ "source_tool_call_ids": sorted({record.call_id for record in candidates}),+ "message": (+ f"Price claim {value:g} conflicts with observed {field_name or 'OHLC'} "+ f"evidence {min(observed):g}–{max(observed):g}."+ ),+ }++ @staticmethod+ def _masked_candidate_text(text: str) -> str:+ """Mask every non-price digit run, preserving string length and offset.++ Each mask match is replaced by an equal-length run of spaces, so a+ number's offset in the returned string is its offset in ``text`` — the+ structural price-claim scan needs that alignment.+ """+ masked = text+ for pattern in (+ _MD_LIST_ITEM_RE,+ _RATE_FORMULA_IDENTITY_RE,+ _CANONICAL_SYMBOL_RE,+ _LOCALIZED_DATE_RE,+ _DATE_RE,+ _SHORT_DATE_RE,+ _DASH_DATE_RE,+ _PERCENT_RANGE_RE,+ _PERCENTAGE_POINT_RE,+ _ORDER_LEVEL_RE,+ _AGGREGATE_AMOUNT_RE,+ _LABELLED_SCORE_RE,+ _INDICATOR_VALUE_RE,+ _SIGNAL_VALUE_RE,+ _PROSPECTIVE_LEVEL_RE,+ _REFERENCE_LEVEL_RE,+ _SINCE_REFERENCE_RE,+ _LINE_REFERENCE_RE,+ _NUMBERED_HEADING_RE,+ _RATIO_RE,+ _FX_RATE_RE,+ _QUANTITY_WITH_UNIT_RE,+ ):+ masked = pattern.sub(lambda m: " " * (m.end() - m.start()), masked)+ return masked++ @staticmethod+ def _numbers_without_dates_or_percent(text: str) -> list[float]:+ """Extract the numbers in a claim that could plausibly be prices.++ Digits that belong to a canonical symbol, a calendar date, an aggregate+ amount, a labelled score, a named indicator reading, a unit-bearing+ quantity, or a percentage are masked first. Left unmasked they are+ compared against observed OHLC ranges and reject a correct draft:+ ``000543.SZ`` alone contributes 543, and a well-formed verdict line+ contributes its confidence score and every moving-average window it+ names (#1001).++ Args:+ text: One claim segment or table cell.++ Returns:+ Candidate price values, in order of appearance.+ """+ masked = _PolicyMixin._masked_candidate_text(text)+ values: list[float] = []+ for match in _NUMBER_RE.finditer(masked):+ tail = masked[match.end() :].lstrip()+ if tail.startswith(("%", "%")):+ continue+ try:+ values.append(float(match.group(0).replace(",", "")))+ except ValueError:+ continue+ return values++ @staticmethod+ def _direct_price_values(text: str) -> list[tuple[float, int, int]]:+ """Numbers in a price segment that read as asserted observed values.++ Returned as ``(value, start, end)``: the masking that decides which+ digits are candidates preserves length, so each offset is the number's+ offset in ``text``. The caller needs the position, not only the value —+ a derivation exempts the occurrence sitting inside it, not every copy+ of the same number in the clause.++ ``_numbers_without_dates_or_percent`` returns every non-masked number;+ this further drops numbers that are formula operands rather than claims+ (#1354). For each surviving number, the span between the nearest+ preceding price-context word and the number decides:++ * a sentence boundary (``. ``/``! ``/``? ``) in the span — the number+ belongs to a later sentence the price word cannot reach ("close was+ 210. In 2024 …" must not claim 2024);+ * otherwise, a closed formula marker in the span turns the number into+ an operand, unless an observation binder ("was", "at", 报收/收于/…) after+ the last marker re-attaches it to the price word.++ "close/SMA50 > 1" and "close above SMA50 and was 2500" are decided in+ opposite directions by the binder; "close was 2500" (no marker) stays+ a claim either way.+ """+ price_words = list(_PRICE_CONTEXT_RE.finditer(text))+ masked = _PolicyMixin._masked_candidate_text(text)+ values: list[tuple[float, int, int]] = []+ for match in _NUMBER_RE.finditer(masked):+ tail = masked[match.end() :].lstrip()+ if tail.startswith(("%", "%")):+ continue+ try:+ value = float(match.group(0).replace(",", ""))+ except ValueError:+ continue+ preceding = [w for w in price_words if w.end() <= match.start()]+ if preceding:+ span = text[preceding[-1].end() : match.start()]+ if _SENTENCE_BOUNDARY_RE.search(span):+ continue+ markers = list(_FORMULA_MARKER_RE.finditer(span))+ if markers and not _OBSERVATION_BINDER_RE.search(+ span[markers[-1].end() :]+ ):+ continue+ values.append((value, match.start(), match.end()))+ return values++ def _derivation_formulas(+ self,+ text: str,+ records: Sequence[EvidenceRecord],+ symbol: str | None,+ ) -> list[tuple[int, int, list[float], float]]:+ """Return every arithmetically valid, observation-anchored formula.++ Each entry is ``(start, end, operands, result)`` — the formula's own+ character span inside ``text``, the operands it consumes and the result+ it produces. The span is what makes the exemption safe. A value-scoped+ exemption ("this number equals something a formula justifies") let a+ figure be exempt EVERYWHERE in the clause once it appeared anywhere in+ an equation, and a model told by the correction prompt to show its+ arithmetic can satisfy that with arithmetic that derives nothing:+ "建议买入价 0.95 元(0.95 × 1.171 = 1.11245 参考)" is true and released+ an entry price 19% below every observed bar. The occurrence inside the+ formula is exempt; the one beside it is compared like any other claim.++ There is no keyword or shape precondition. A `基于` / `based on` was+ once required and an added `_ARITHMETIC_EQUATION_RE` relaxed it to+ "any two-operand equation"; both are subsumed by what decides below —+ a result separator, a parseable arithmetic run of at least two+ operands (``_evaluate_formula``), an input matching observed evidence,+ and a result that is correct. Deleting the regex changed no verdict in+ the suite and removes one entry from the regex catalogue.++ Args:+ text: The clause (or line) to inspect.+ records: Comparable observed price evidence.+ symbol: Symbol resolved for the claim, if any.++ Returns:+ ``(start, end, operands, result)`` per valid formula, in order.+ """+ candidates = list(records)+ if symbol:+ candidates = [record for record in candidates if record.symbol == symbol]+ candidate_symbols = {record.symbol for record in candidates if record.symbol}+ if not symbol and len(candidate_symbols) > 1:+ return []+ observed = [+ float(record.value) for record in candidates if record.value is not None+ ]+ if not observed:+ return []++ formulas: list[tuple[int, int, list[float], float]] = []+ for equals in _RESULT_SEPARATOR_RE.finditer(text):+ # An indicator identifier carries digits ("SMA20", "MA5"); left in+ # place they leak into the arithmetic run ("20 1.150 × 0.95") and+ # the formula fails to parse, so a derivation from an observed+ # moving average was never accepted. The blanking is+ # LENGTH-PRESERVING because the offsets below are the exemption's+ # anchor: collapsing "SMA20" to one space shifted every span after+ # it and the formula was excluded from its own protection.+ prefix = _INDICATOR_IDENTIFIER_RE.sub(+ lambda match: " " * (match.end() - match.start()),+ text[: equals.start()],+ )+ left = re.search(r"([0-9.,+\-*/×÷()\s]+)$", prefix)+ right = re.match(+ r"\s*([-+]?(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?)",+ text[equals.end() :],+ )+ if not left or not right:+ continue+ evaluated = self._evaluate_formula(left.group(1))+ if evaluated is None:+ continue+ computed, inputs = evaluated+ try:+ claimed = float(right.group(1).replace(",", ""))+ except ValueError:+ continue+ if not any(+ abs(item - value) <= max(abs(value) * 0.005, 1e-9)+ for item in inputs+ for value in observed+ ):+ continue+ if abs(computed - claimed) <= max(abs(computed) * 0.005, 1e-9):+ formulas.append(+ (left.start(1), equals.end() + right.end(), inputs, claimed)+ )+ return formulas++ def _derivation_justified_values(+ self,+ text: str,+ records: Sequence[EvidenceRecord],+ symbol: str | None,+ ) -> list[float]:+ """Every operand and result of every valid formula in ``text``.++ The flat form, for the callers that only ask "is this figure one a+ formula here justifies" without a position to check it at.+ """+ justified: list[float] = []+ for _, _, inputs, result in self._derivation_formulas(text, records, symbol):+ justified.extend(inputs)+ justified.append(result)+ return justified++ @staticmethod+ def _evaluate_formula(expression: str) -> tuple[float, list[float]] | None:+ """Evaluate a numeric ``+ - * /`` expression without executing code."""+ normalized = expression.replace("×", "*").replace("÷", "/").replace(",", "").strip()+ try:+ tree = ast.parse(normalized, mode="eval")+ except (SyntaxError, ValueError):+ return None+ inputs: list[float] = []++ def visit(node: ast.AST) -> float:+ if isinstance(node, ast.Expression):+ return visit(node.body)+ if isinstance(node, ast.Constant) and _is_number(node.value):+ value = float(node.value)+ inputs.append(value)+ return value+ if isinstance(node, ast.UnaryOp) and isinstance(node.op, (ast.UAdd, ast.USub)):+ value = visit(node.operand)+ return value if isinstance(node.op, ast.UAdd) else -value+ if isinstance(node, ast.BinOp) and isinstance(+ node.op,+ (ast.Add, ast.Sub, ast.Mult, ast.Div),+ ):+ left_value = visit(node.left)+ right_value = visit(node.right)+ if isinstance(node.op, ast.Add):+ return left_value + right_value+ if isinstance(node.op, ast.Sub):+ return left_value - right_value+ if isinstance(node.op, ast.Mult):+ return left_value * right_value+ if right_value == 0:+ raise ValueError("division by zero")+ return left_value / right_value+ raise ValueError("unsupported formula")++ try:+ value = visit(tree)+ except (TypeError, ValueError, ZeroDivisionError, OverflowError):+ return None+ if len(inputs) < 2 or not math.isfinite(value):+ return None+ return value, inputs++ @staticmethod+ def _dedupe_issues(issues: list[dict[str, Any]]) -> list[dict[str, Any]]:+ """Remove duplicate validator findings while preserving order."""+ unique: list[dict[str, Any]] = []+ seen: set[str] = set()+ for issue in issues:+ key = json.dumps(issue, sort_keys=True, ensure_ascii=False, default=str)+ if key in seen:+ continue+ seen.add(key)+ unique.append(issue)+ return uniquediff --git a/agent/src/agent/grounding/release.py b/agent/src/agent/grounding/release.pynew file mode 100644index 000000000..3983dc72e--- /dev/null+++ b/agent/src/agent/grounding/release.py@@ -0,0 +1,924 @@+"""What happens after a rejection: correction, recovery, repair, redaction."""++from __future__ import annotations++import hashlib+import re+from typing import Any, Sequence++from src.agent.grounding.identity import (+ _CANONICAL_SYMBOL_RE,+ _RESOLVER_TOOL,+ _normalize_symbol,+ _utc_now,+)+from src.agent.grounding.evidence import EvidenceRecord+from src.agent.grounding.figures import _NUMBER_RE, _clause_spans, _lines_with_offsets+from src.agent.grounding.policies import (+ ValidationResult,+ _ANALYSIS_METRIC_RE,+ _CURRENCY_BEFORE_RE,+ _CURRENCY_UNIT_WORDS,+ _MEASURE_NUMBER_RE,+ _PolicyMixin,+ _TABLE_FIELD_ALIASES,+ _matches_any,+)++# Bounded read-only recovery (#1081): a missing instrument identity or price+# evidence is often recoverable deterministically, so the loop should keep+# driving the original task through `search_symbol` and `get_market_data`+# instead of handing the user a terminal "confirm and continue" fallback.+# These budgets are separate from the rejected-draft count so real recovery+# progress is never cut off at the three-draft retry cap.+MAX_GROUNDING_RECOVERY_ROUNDS = 6+++# Issue codes whose figure can be cut out of its clause and the draft released+# (see ``redacted_release``), and the provenance codes a data note repairs.+_REDACTABLE_CODES = frozenset(+ {+ "numeric_claim_conflict",+ "numeric_claim_unavailable",+ "unsourced_symbol_figures",+ "analysis_claim_unavailable",+ }+)+++# The provenance codes a data note may fill in deterministically. The source+# and the currency are metadata ABOUT a figure. ``canonical_symbol_not_surfaced``+# is deliberately absent: the symbol is the figure's SUBJECT, and appending+# "562500.SH: source yahoo" under a draft that calls the instrument 贵州茅台+# footnotes a misattribution instead of repairing it — so the identity binding+# keeps its model-correction round.+_REPAIRABLE_PROVENANCE_CODES = frozenset(+ {"data_source_not_surfaced", "currency_not_surfaced"}+)+++_MAX_REDACTION_PASSES = 3+++# The in-text mark for an omitted figure. It replaces the number AND the unit+# glued to it ("0.95 元" → "(略※)", "$1.10" → "(omitted※)") so the sentence+# still reads as prose, and the ※ points at the one footnote that says how+# many figures were omitted and why. A bracketed "[value removed]" left the+# unit dangling and read like a redaction stamp.+_REDACTION_MARKER_ZH = "(略※)"+++_REDACTION_MARKER_EN = "(omitted※)"+++_UNIT_AFTER_RE = re.compile(+ r"\s*(?:(?:" + _CURRENCY_UNIT_WORDS + r")(?![A-Za-z//])"+ r"|元(?![A-Za-z//\u3400-\u9fff]))"+)+++MAX_SYMBOL_RESOLUTION_ATTEMPTS = 2+++MAX_PRICE_EVIDENCE_ATTEMPTS = 3+++# A table column whose header names a price. Wider than the OHLC aliases on+# purpose: 挂单价 / 目标价 / Entry Price are price columns that+# ``_validate_price_tables`` does not key on and the prose scan skips, so+# their cells are figures no validator ever reads.+_PRICE_HEADER_RE = re.compile(r"(?:价格?|价位|price)\s*$", re.IGNORECASE)+++def _format_price(value: float) -> str:+ """Render an observed price without scientific notation or lost digits.++ ``%g`` switches to scientific notation past six significant digits, so an+ index level printed in the release footnote read "1.23457e+06".+ """+ return format(value, ".10g")+++def _redaction_targets(values: Sequence[Any]) -> tuple[bool, list[float], list[str]]:+ """Split issue values into cut-everything / numeric / percent-literal cuts.++ Args:+ values: The ``value`` field of each issue flagged on one clause.++ Returns:+ ``(cut_all, numeric targets, percent literals)``. ``cut_all`` is set by+ a ``None`` value, which is how ``unsourced_symbol_figures`` says "every+ figure in this clause belongs to an instrument no tool handled".+ """+ cut_all = False+ targets: list[float] = []+ literals: list[str] = []+ for value in values:+ if value is None:+ cut_all = True+ elif isinstance(value, bool):+ continue+ elif isinstance(value, (int, float)):+ targets.append(float(value))+ elif isinstance(value, str) and value.strip():+ literal = value.strip().replace(" ", "").replace(",", "")+ if literal.endswith(("%", "%")):+ literals.append(literal)+ else:+ try:+ targets.append(float(literal))+ except ValueError:+ continue+ return cut_all, targets, literals+++_RELEASE_NOTE_LINE_RE = re.compile(r"^[^\S\n]*※[^\n]*\n?", re.MULTILINE)+++def _strip_release_markers(content: str) -> str:+ """Remove any redaction marker or release note the MODEL wrote.++ The marker and the footnote are the gate's own statements about what it+ cut. A draft carrying "※ 略去 0 处……" of its own shipped both notes, one+ contradicting the other, and a "(略※)" pasted into the body read as a+ redaction that never happened.++ Args:+ content: The rejected draft.++ Returns:+ The draft with every marker and note-shaped line removed.+ """+ stripped = content.replace(_REDACTION_MARKER_ZH, "").replace(+ _REDACTION_MARKER_EN, ""+ )+ return _RELEASE_NOTE_LINE_RE.sub("", stripped)+++class _ReleaseMixin:+ """Release behaviour of :class:`GroundingLedger`."""++ def correction_prompt(self, validation: ValidationResult) -> str:+ """Build bounded feedback for one rejected model draft."""+ lines = [+ "[GROUNDING GATE] The previous draft was rejected and was not released to the user.",+ "Correct every issue using the existing structured identity and tool evidence:",+ ]+ for issue in validation.issues[:12]:+ lines.append(f"- {issue.get('message', issue.get('code', 'grounding error'))}")+ # Name the exact values that must be REMOVED, not rephrased. The model+ # tends to restate a rejected figure in a new format; the gate then+ # rejects it again and the run burns iterations until the fallback.+ banned: list[str] = []+ for issue in validation.issues:+ code = issue.get("code")+ value = issue.get("value")+ if code in {"numeric_claim_conflict", "numeric_claim_unavailable", "unsourced_symbol_figures", "analysis_claim_unavailable"} and value is not None:+ symbol = issue.get("symbol") or ""+ label = f"{value:g}" if isinstance(value, (int, float)) else str(value)+ banned.append(f"{label} ({symbol})" if symbol else label)+ if banned:+ deduped = list(dict.fromkeys(banned))+ lines.append(+ "REMOVE these rejected value(s) entirely - do NOT restate, rephrase, "+ "or recompute them in any other format: " + ", ".join(deduped) + "."+ )+ repeated: list[str] = []+ for prior in self._validations:+ for prior_issue in prior.get("issues", []):+ prior_value = prior_issue.get("value")+ if isinstance(prior_value, (int, float)):+ mark = f"{prior_value:g}"+ if any(entry.startswith(mark) for entry in deduped):+ repeated.append(mark)+ if repeated:+ lines.append(+ "These value(s) have now been rejected repeatedly across drafts: "+ + ", ".join(dict.fromkeys(repeated))+ + ". Repeating them in any form keeps failing; drop them, or show "+ "the full derivation from the observed inputs."+ )+ lines.extend(+ [+ "If a value is a derived or prospective level (stop, target, entry, etc.), "+ "you must EITHER show the full derivation with the observed inputs and the "+ "formula, OR omit it from the draft.",+ "Reuse the exact locked symbol and venue.",+ "Do not attach figures to a symbol no tool call in this session handled; "+ "report it as not retrieved instead.",+ ]+ )+ recovery = self.recovery_action(validation)+ if recovery == _RESOLVER_TOOL:+ lines.extend(+ [+ "Instrument identity is unresolved. Call `search_symbol` for the "+ "candidate name in a separate tool-call turn, lock the exact canonical "+ "symbol and venue it returns, then call `get_market_data` before finalizing.",+ "Do NOT ask the user to confirm or continue while this read-only recovery "+ "remains available.",+ ]+ )+ elif recovery == "get_market_data":+ lines.extend(+ [+ "Identity is locked but price evidence is missing. Call `get_market_data` "+ "for the locked canonical symbol and venue in a separate tool-call turn, "+ "then regenerate and re-validate the final answer.",+ "Do NOT ask the user to confirm or continue while this read-only recovery "+ "remains available.",+ ]+ )+ else:+ lines.append(+ "If evidence is genuinely unavailable or conflicting and recovery is "+ "exhausted, say so and ask for clarification; do not guess."+ )+ return "\n".join(lines)++ def recovery_action(self, validation: ValidationResult) -> str | None:+ """Decide the next safe read-only recovery step for a rejected draft.++ Returns ``search_symbol`` when instrument identity is unresolved and+ resolution attempts remain; ``get_market_data`` when identity is locked+ but a price claim has no observed evidence and fetch attempts remain;+ otherwise ``None`` (genuinely ambiguous, conflicting, or exhausted —+ the loop must then ask the user or fail closed).++ This is the deterministic half of #1081: recoverable missing evidence is+ often obtainable through read-only tools, so a rejected draft should+ drive the original task forward instead of stopping.+ """+ if self._recovery_rounds >= MAX_GROUNDING_RECOVERY_ROUNDS:+ return None+ if self._identity_required and self.identity_status == "unresolved":+ if self._symbol_resolution_attempts < MAX_SYMBOL_RESOLUTION_ATTEMPTS:+ return _RESOLVER_TOOL+ return None+ if self.identity_status == "locked" and any(+ issue.get("code") in {"numeric_claim_unavailable", "unsourced_symbol_figures"}+ for issue in validation.issues+ ):+ if self._price_evidence_attempts < MAX_PRICE_EVIDENCE_ATTEMPTS:+ return "get_market_data"+ return None++ def record_recovery(self, action: str) -> None:+ """Account one bounded recovery attempt against its budget."""+ self._recovery_rounds += 1+ if action == _RESOLVER_TOOL:+ self._symbol_resolution_attempts += 1+ elif action == "get_market_data":+ self._price_evidence_attempts += 1++ def recovery_prompt(self, action: str, validation: ValidationResult) -> str:+ """Build an executable next-step message for one bounded recovery turn."""+ if action == _RESOLVER_TOOL:+ return (+ "[GROUNDING RECOVERY] Instrument identity is not yet locked and is "+ "recoverable with read-only tools. Call `search_symbol` for the candidate "+ "name in a separate assistant tool-call turn, lock and reuse the exact "+ "canonical symbol and venue it returns, then call `get_market_data`. "+ "Do NOT ask the user to confirm or continue while this read-only recovery "+ "remains available, and do NOT finalize yet."+ )+ if action == "get_market_data":+ return (+ "[GROUNDING RECOVERY] Identity is locked but price evidence is missing. "+ "Call `get_market_data` for the locked canonical symbol and venue in a "+ "separate tool-call turn and use its existing bounded provider fallback, "+ "then regenerate and re-validate the final answer. Do NOT ask the user to "+ "confirm or continue while this read-only recovery remains available, and "+ "do NOT finalize yet."+ )+ return self.correction_prompt(validation)++ def safe_fallback(self) -> str:+ """Return a deterministic fail-closed answer after repeated rejection."""+ is_zh = self._user_writes_chinese()+ joined = self._observed_range_summary(is_zh)+ if joined is not None:+ if is_zh:+ return (+ "为避免输出与工具证据冲突的价格,我已拒绝上一版答案。"+ f"当前可验证的已观测 OHLC 范围是:{joined}。"+ "在重新核对标的或明确展示推导公式前,我不会生成买入价。"+ )+ return (+ "I rejected the previous draft because its prices conflicted with tool evidence. "+ f"The verified observed OHLC range is: {joined}. "+ "I will not invent an entry price without a visible derivation or refreshed evidence."+ )+ # No observed price evidence: distinguish "identity unresolved" from+ # "the draft cited prices this session never observed". Reporting the+ # identity message for the latter is misleading (the run may not even+ # have touched the market tools).+ issue_codes = {+ code+ for validation in self._validations+ for code in (issue.get("code") for issue in validation.get("issues", []))+ }+ if issue_codes & {+ "numeric_claim_unavailable", "numeric_claim_conflict", "unsourced_symbol_figures"+ }:+ if is_zh:+ return (+ "我的回答被安全门槛拒绝:草稿引用了本会话未通过工具获取的价格数字,无法核验。"+ "请重新发起任务,让模型先调用行情工具获取数据,或要求它去掉这些价格引用后重试。"+ )+ return (+ "My previous answer was rejected by the verification gate: it cited price "+ "figures that this session never obtained through a tool, so they could not "+ "be verified. Re-run the task and let the agent fetch the market data first, "+ "or ask it to answer without the unverified prices."+ )+ if is_zh:+ return (+ "当前无法安全确认标的身份或价格证据,因此没有生成交易结论。"+ "请确认候选证券代码和交易所后再继续。"+ )+ return (+ "I could not safely lock the instrument identity or price evidence, so I did not "+ "produce a trading conclusion. Please confirm the candidate symbol and venue."+ )++ def _user_writes_chinese(self) -> bool:+ """Return whether user-facing gate text should be Chinese."""+ return bool(re.search(r"[\u3400-\u9fff]", self.user_message))++ def _observed_range_summary(self, is_zh: bool, content: str | None = None) -> str | None:+ """Summarise the observed OHLC range per symbol, or None without prices.++ Args:+ is_zh: Whether to join the facts with Chinese punctuation.+ content: The answer the summary is attached to, when there is one.+ The symbol is then printed the way that answer spells it — a+ footnote on an answer written throughout in ``562500.SS`` used+ to name ``562500.SH``, because the evidence record is+ canonicalised.++ Returns:+ One fact per symbol, or None when the run observed no price.+ """+ price_records = self._price_records()+ if not price_records:+ return None+ by_symbol: dict[str, list[EvidenceRecord]] = {}+ for record in price_records:+ by_symbol.setdefault(record.symbol or "unknown", []).append(record)+ facts = []+ for symbol, records in sorted(by_symbol.items()):+ values = [float(record.value) for record in records if record.value is not None]+ currency = next((record.currency for record in records if record.currency), None)+ sources = sorted({record.source for record in records if record.source})+ source_label = "/".join(sources) if sources else "unknown"+ unit = f" {currency}" if currency else ""+ facts.append(+ f"{self._answer_symbol_spelling(symbol, content)}: "+ f"{_format_price(min(values))}–{_format_price(max(values))}{unit} "+ f"(source: {source_label}; currency conversion: none)"+ )+ return ";".join(facts) if is_zh else "; ".join(facts)++ @staticmethod+ def _answer_symbol_spelling(canonical: str, content: str | None) -> str:+ """Return the spelling ``content`` uses for a canonical symbol."""+ if not content:+ return canonical+ for match in _CANONICAL_SYMBOL_RE.finditer(content):+ if _normalize_symbol(match.group(0)) == canonical:+ return match.group(0)+ return canonical++ def _provenance_note(self, content: str | None = None) -> str | None:+ """Build the one-line data note that satisfies the provenance checks.++ Args:+ content: The answer the note is appended to, so the symbol is+ printed the way that answer spells it.++ Returns:+ The note, or None when the run observed no price.+ """+ price_records = self._price_records()+ if not price_records:+ return None+ is_zh = self._user_writes_chinese()+ by_symbol: dict[str, list[EvidenceRecord]] = {}+ for record in price_records:+ by_symbol.setdefault(record.symbol or "unknown", []).append(record)+ parts = []+ for symbol, records in sorted(by_symbol.items()):+ sources = sorted(+ {+ record.source+ for record in records+ if record.source and record.source.casefold() not in {"auto", "unknown"}+ }+ )+ currency = next((record.currency for record in records if record.currency), None)+ source_label = "/".join(sources) if sources else ("未知" if is_zh else "unknown")+ currency_label = currency or ("未知" if is_zh else "unknown")+ spelling = self._answer_symbol_spelling(symbol, content)+ parts.append(+ f"{spelling}:行情来源 {source_label},计价货币 {currency_label}"+ if is_zh+ else f"{spelling}: price source {source_label}, quote currency {currency_label}"+ )+ if is_zh:+ return "数据说明:" + ";".join(parts) + "。"+ return "Data note: " + "; ".join(parts) + "."++ def repair_provenance(+ self,+ content: str,+ validation: ValidationResult,+ *,+ require_checked_figures: bool = True,+ ) -> str | None:+ """Append a data note when the only defects are missing provenance words.++ ``data_source_not_surfaced`` and ``currency_not_surfaced`` mean the+ answer quoted a price without naming the source or the currency. Both+ are known to the ledger, so the omission is deterministic — and+ regenerating a multi-minute report to add the word "tencent" is a full+ model round for one word. Nothing here touches a figure: a draft+ carrying any other issue is returned as None so the numeric checks+ keep their round.++ ``canonical_symbol_not_surfaced`` is deliberately NOT repaired. That+ check's job is that a price claim surfaces the symbol it is about, and+ appending "562500.SH: price source yahoo" under a draft that reads+ "贵州茅台 最新收盘价 1.171 元" turns a misattribution into a released+ answer with a footnote naming a different instrument. It keeps its+ model round (base rate: 1 of 27 rejections in the local traces, so+ nearly all of the saving survives).++ The repair is also declined when the draft carries a price COLUMN the+ table validator does not key on ("| 档位 | 挂单价 |"): those cells are+ outside every validator's reach, and the note says where this run's+ prices came from. Attaching it to a draft holding an unchecked ladder+ price attests to a figure the gate never saw, in zero model rounds —+ the round it used to cost was the last chance to drop that figure.++ Args:+ content: The rejected draft.+ validation: Its validation result.+ require_checked_figures: Decline when an unchecked price column is+ present. ``redacted_release`` passes False: there the choice+ is not "repair or one more model round" but "repair or the+ canned refusal", the revision budget is already spent, and the+ document it repairs carries the redaction footnote.++ Returns:+ The draft with a provenance note appended, or None when the issues+ are not provenance-only, an unchecked price column is present, or+ there is no price evidence to cite.+ """+ codes = {issue.get("code") for issue in validation.issues}+ if not codes or not codes <= _REPAIRABLE_PROVENANCE_CODES:+ return None+ if require_checked_figures and self._has_unchecked_price_column(content):+ return None+ note = self._provenance_note(content)+ if note is None:+ return None+ return content.rstrip() + "\n\n" + note++ @staticmethod+ def _has_unchecked_price_column(content: str) -> bool:+ """Whether a Markdown table holds a price column no validator reads.++ ``_validate_price_tables`` keys on ``_TABLE_FIELD_ALIASES`` — the OHLC+ headers — and the prose scan skips every line containing "|". A column+ headed 挂单价 / 目标价 / Entry price is read by neither.++ Args:+ content: The draft to inspect.++ Returns:+ True when such a column carries at least one numeric cell.+ """+ lines = content.splitlines()+ for header, rows, _ in _PolicyMixin._pipe_tables(lines):+ unchecked = [+ position+ for position, cell in enumerate(header)+ if _PRICE_HEADER_RE.search(cell)+ and cell.strip().casefold() not in _TABLE_FIELD_ALIASES+ ]+ if not unchecked:+ continue+ for row in rows:+ for position in unchecked:+ if position < len(row) and _NUMBER_RE.search(row[position]):+ return True+ return False++ def redacted_release(self, content: str, validation: ValidationResult) -> str | None:+ """Release the last rejected draft with its unverified figures cut out.++ Once the revision budget is spent, the draft is still the analysis the+ user waited through every revision for, and the gate objected to+ specific figures in specific clauses — not to the trend read, the+ indicator commentary, or the risk notes around them. Each rejected+ figure is replaced by a visible marker AT THE SPAN the validator+ flagged, every other occurrence of the same figure elsewhere in the+ document is cut with it, the missing provenance words are appended if+ that is all that remains, and the whole released document — footnote+ included — is re-validated by the same gate: only text that passes is+ returned, so nothing the gate rejected reaches the user.++ Fail-closed by construction. None — leave the canned fallback in place —+ whenever the run never observed a price at all (the draft's numbers then+ have no basis to stand next to), carries an issue that is not a+ cut-out-able figure (an identity finding is one), has a flagged clause+ that cannot be located, or still fails after the cut.++ Args:+ content: The rejected draft.+ validation: Its validation result.++ Returns:+ The redacted, re-validated draft followed by a note stating how many+ figures were removed and the observed range, or None.+ """+ if not self._price_records():+ return None+ text = _strip_release_markers(content)+ removed = 0+ # Stripping moves every offset after it, and the issue spans are the+ # only anchor the cuts have, so the verdict is retaken on the text the+ # cuts will actually be made in.+ pending = list(+ validation.issues+ if text == content+ else self._validate(text, record=False).issues+ )+ # A validator reports one figure per clause, so cutting it can reveal+ # the next one on the recheck. Cut, recheck, repeat — bounded, and+ # every cut is a figure the gate itself flagged.+ for _ in range(_MAX_REDACTION_PASSES):+ codes = {issue.get("code") for issue in pending}+ if not codes or not codes <= (_REDACTABLE_CODES | _REPAIRABLE_PROVENANCE_CODES):+ return None+ # Two issues can point at one clause ("unsourced symbol" and the+ # conflict on the same figure), so cuts are grouped per span:+ # each clause is rewritten once with every value flagged for it.+ by_span: dict[tuple[int, int], list[Any]] = {}+ for issue in pending:+ if issue.get("code") not in _REDACTABLE_CODES:+ continue+ span = self._issue_span(text, issue)+ if span is None:+ return None+ by_span.setdefault(span, []).append(issue.get("value"))+ text, count = self._redact_spans(text, by_span)+ if count == 0:+ return None+ removed += count+ check = self._validate(text, record=False)+ if not check.valid:+ repaired = self.repair_provenance(+ text, check, require_checked_figures=False+ )+ if repaired is not None:+ text = repaired+ check = self._validate(text, record=False)+ if check.valid:+ break+ pending = list(check.issues)+ else:+ return None+ released = text.rstrip() + "\n\n" + self._release_note(removed, text)+ # The note carries the observed range and the canonical symbols, so it+ # is answer text too. Validating the body and shipping body+note left+ # the released document as a whole unchecked, which contradicted the+ # fail-closed promise in this docstring.+ if not self._validate(released, record=False).valid:+ return None+ # Recorded beside the drafts but NOT as one: the artifact otherwise+ # held no evidence for the fail-closed promise above, because every+ # recheck on this path is deliberately unrecorded.+ self._released = {+ "released_at": _utc_now(),+ "content_sha256": hashlib.sha256(released.encode("utf-8")).hexdigest(),+ "figures_removed": removed,+ "revalidated": True,+ }+ self.persist()+ return released++ @staticmethod+ def _issue_span(text: str, issue: dict[str, Any]) -> tuple[int, int] | None:+ """Locate the flagged clause in ``text``.++ The validators record the clause's character span, which is the only+ reliable anchor: the stored ``claim`` is normalised (thousands+ separators stripped, table cells rendered as "label: value"), so+ ``text.find(claim)`` missed every price above 999 and every metric+ table outright, and for a bare numeric cell it matched INSIDE a longer+ number — "1.10" found in "21.10 亿元", rewriting an untouched turnover+ figure into "2(略※)".++ The substring fallback that used to sit here is gone. Every one of the+ six redactable-issue construction sites carries a span, so it was+ reachable only from a hand-built issue, and it carried a documented+ digit-boundary rationale for a hazard the span had already settled —+ which is worse than no code, because a reader trusts it.++ Args:+ text: The document the issue was raised against.+ issue: One validation issue.++ Returns:+ ``(start, end)`` or None when the issue carries no usable span.+ """+ span = issue.get("span")+ if not isinstance(span, (list, tuple)) or len(span) != 2:+ return None+ try:+ start, end = int(span[0]), int(span[1])+ except (TypeError, ValueError):+ return None+ if 0 <= start <= end <= len(text):+ return start, end+ return None++ def _release_note(self, removed: int, content: str | None = None) -> str:+ """Explain the redaction to the user, with the observed range.++ ``redacted_release`` returns None before this is reached when the run+ holds no price record, which is the only case in which the summary is+ None — so it is read directly rather than behind an ``or ""`` that+ described a state the caller cannot produce.+ """+ is_zh = self._user_writes_chinese()+ joined = self._observed_range_summary(is_zh, content)+ if is_zh:+ return (+ f"※ 略去 {removed} 处无法与本会话工具数据对上的数值。"+ f"已观测 OHLC 范围:{joined}。"+ "如需买入价,请让我基于已观测的收盘价或均线给出带公式的推导。"+ )+ return (+ f"※ {removed} figure(s) that could not be matched to this session's tool data "+ f"were omitted. Observed OHLC range: {joined}. "+ "For an entry price, ask me to derive one with a visible formula from an "+ "observed close or moving average."+ )++ def _redact_spans(+ self,+ text: str,+ by_span: dict[tuple[int, int], list[Any]],+ ) -> tuple[str, int]:+ """Cut the flagged figures at their spans, then everywhere else.++ Numbers are located on the masked clause (symbols, dates, prospective+ levels blanked) so a ticker's digits are never cut. A numeric value is+ matched numerically, a percent-shaped analysis value textually, and a+ ``None`` value (a clause attributing figures to an unhandled symbol)+ cuts every number in that clause.++ The second stage is why the footnote can be believed. Cutting only the+ flagged clause left the same rejected figure standing in a Markdown+ table under a non-OHLC header or in a bullet with no price word —+ neither surface is scanned by the validators — while the footnote+ asserted it had been removed.++ Two kinds of occurrence are never swept, because the gate has already+ accepted them where they stand: a figure the ledger observed, and a+ figure sitting inside a valid formula elsewhere in the document.+ Without the second, the rejected entry price 0.95 was cut out of+ "基于 MA20 0.7158 × 0.95 = 0.680", mangling the one derivation the+ correction prompt asks the model to write (159516.SZ replay,+ 2026-09-09).++ The formula protection is scoped to the formula's own character SPANS.+ Scoped to the VALUE it protected the rejected figure document-wide:+ with "基于收盘价 1.171 × 0.95 = 1.112" anywhere in the draft, the same+ 0.95 survived in "| 第一档 | 0.95 |" under a footnote saying one figure+ had been cut — the exact restatement this second stage exists to+ remove, protected by the derivation the model wrote beside it.++ A percent literal is protected the same way. Cutting every occurrence+ of a flagged literal took the accepted one with it: "从 1.110 涨到+ 1.171,区间收益率约 5.5%" is endpoint arithmetic this gate validated,+ and it was cut and footnoted as unmatched because an unrelated+ "策略年化波动率 5.5%" was flagged in the next clause.++ Args:+ text: The document to rewrite.+ by_span: ``(start, end)`` → the values flagged inside that span.++ Returns:+ The rewritten text and the number of figures replaced.+ """+ swept: list[float] = []+ swept_literals: list[str] = []+ pieces: list[str] = []+ cursor = 0+ total = 0+ for (start, end), values in sorted(by_span.items()):+ if start < cursor:+ continue+ cut_all, targets, literals = _redaction_targets(values)+ swept.extend(targets)+ swept_literals.extend(literals)+ replaced, count = self._rewrite_segment(+ text[start:end], cut_all, targets, literals+ )+ pieces.append(text[cursor:start])+ pieces.append(replaced)+ total += count+ cursor = end+ pieces.append(text[cursor:])+ text = "".join(pieces)+ if total == 0 or not (swept or swept_literals):+ return text, total+ observed = self._observed_price_values()+ survivors = [+ target for target in swept if not _matches_any(target, observed, rel=1e-9)+ ]+ if not survivors and not swept_literals:+ return text, total+ protected = self._derivation_spans(text)+ if swept_literals:+ protected += self._accepted_metric_spans(text)+ # Line by line, so each replacement takes the marker from the script of+ # its OWN line. Run over the whole document the second stage picked one+ # marker for everything, and a Chinese report containing an English+ # table released "| Entry |(略※) |".+ extra = 0+ out: list[str] = []+ cursor = 0+ for line, start in _lines_with_offsets(text):+ out.append(text[cursor:start])+ local = [+ (span_start - start, span_end - start)+ for span_start, span_end in protected+ if span_start >= start and span_end <= start + len(line)+ ]+ rewritten, count = self._rewrite_segment(+ line, False, survivors, swept_literals, protected=local+ )+ out.append(rewritten)+ extra += count+ cursor = start + len(line)+ out.append(text[cursor:])+ return "".join(out), total + extra++ def _derivation_spans(self, text: str) -> list[tuple[int, int]]:+ """Where a valid derivation sits in ``text``, in document offsets.++ Args:+ text: The document about to be swept.++ Returns:+ The character span of every arithmetically valid,+ observation-anchored formula in it.+ """+ records = self._comparable_price_records()+ document_symbol = self._symbol_for_claim(text, records)+ spans: list[tuple[int, int]] = []+ for line, offset in _lines_with_offsets(text):+ if not _NUMBER_RE.search(line):+ continue+ symbol = self._symbol_for_claim(line, records) or document_symbol+ for start, end, _, _ in self._derivation_formulas(line, records, symbol):+ spans.append((offset + start, offset + end))+ return spans++ def _accepted_metric_spans(self, text: str) -> list[tuple[int, int]]:+ """Where this gate ACCEPTED a metric figure in ``text``.++ A clause the analysis validator examined — it carries a metric word+ and a measurement-shaped number — and did not flag is a clause whose+ figures this gate grounded. Sweeping such a figure out because an+ unrelated clause states the same percentage cut a validated derivation+ and footnoted it as unmatched.++ The verdict comes from the validator itself rather than from a second+ copy of its exemption rules: a clause with no metric word was never+ examined (a bullet, an unclaimed table column) and is deliberately not+ protected — that unscanned surface is what the sweep exists for.++ Args:+ text: The document about to be swept.++ Returns:+ The character span of every examined-and-accepted metric clause.+ """+ flagged = {+ (int(issue["span"][0]), int(issue["span"][1]))+ for issue in self._validate(text, record=False).issues+ if isinstance(issue.get("span"), (list, tuple))+ and len(issue["span"]) == 2+ }+ spans: list[tuple[int, int]] = []+ for line, offset in _lines_with_offsets(text):+ for segment, start, end in _clause_spans(line, offset):+ if not _ANALYSIS_METRIC_RE.search(segment):+ continue+ if not self._measure_numbers(segment):+ continue+ if any(+ span_start <= start and end <= span_end+ for span_start, span_end in flagged+ ):+ continue+ spans.append((start, end))+ return spans++ def _rewrite_segment(+ self,+ segment: str,+ cut_all: bool,+ targets: Sequence[float],+ literals: Sequence[str],+ *,+ protected: Sequence[tuple[int, int]] = (),+ ) -> tuple[str, int]:+ """Replace the wanted figures in one stretch of text with the marker.++ Args:+ segment: The stretch of the answer to rewrite.+ cut_all: Cut every number, not only the listed targets.+ targets: Numeric values to cut.+ literals: Percent-shaped figures to cut by their written text.+ protected: Character ranges inside ``segment`` that must survive+ whatever they contain — a valid formula, or a metric clause+ this gate accepted. Protection is by POSITION, not by value:+ the rejected entry price is usually also the multiplier of the+ correct derivation, and protecting the value protected every+ restatement of the rejected figure along with it.++ Returns:+ The rewritten stretch and the number of figures replaced.+ """+ if not cut_all and not targets and not literals:+ return segment, 0+ # The marker follows the SCRIPT OF THE TEXT BEING CUT, not the user's+ # message: a Chinese user asking about a US name gets English tables,+ # and "Suggested entry price(略※) per share." was the result. A+ # stretch with neither script — a numeric table row — falls back to+ # the user's language, which is what the footnote is written in.+ if re.search(r"[\u3400-\u9fff]", segment):+ marker = _REDACTION_MARKER_ZH+ elif re.search(r"[A-Za-z]", segment):+ marker = _REDACTION_MARKER_EN+ else:+ marker = (+ _REDACTION_MARKER_ZH+ if self._user_writes_chinese()+ else _REDACTION_MARKER_EN+ )+ spans: list[tuple[int, int]] = []+ if literals:+ for match in _MEASURE_NUMBER_RE.finditer(segment):+ normalized = match.group(0).replace(" ", "").replace(",", "")+ if normalized in literals:+ spans.append((match.start(), match.end()))+ masked = self._masked_candidate_text(segment)+ for match in _NUMBER_RE.finditer(masked):+ try:+ number = float(match.group(0).replace(",", ""))+ except ValueError:+ continue+ if cut_all or _matches_any(number, targets, rel=1e-9):+ spans.append((match.start(), match.end()))+ pieces: list[str] = []+ cursor = 0+ count = 0+ for start, end in sorted(set(spans)):+ if start < cursor:+ continue+ if any(+ keep_start <= start and end <= keep_end+ for keep_start, keep_end in protected+ ):+ continue+ unit = _UNIT_AFTER_RE.match(segment, end)+ if unit:+ end = unit.end()+ symbol = _CURRENCY_BEFORE_RE.search(segment[cursor:start])+ if symbol:+ start = cursor + symbol.start()+ if marker is _REDACTION_MARKER_ZH:+ # "建议买入价 0.95 元" → "建议买入价(略※)": a full-width+ # bracket sits flush against the preceding word. Not against a+ # table pipe, though — "| 第一档 |(略※) |" loses the column's+ # padding and reads as a broken row.+ while (+ start > cursor+ and segment[start - 1] == " "+ and segment[: start - 1].rstrip(" ")[-1:] != "|"+ ):+ start -= 1+ pieces.append(segment[cursor:start])+ pieces.append(marker)+ cursor = end+ count += 1+ pieces.append(segment[cursor:])+ return "".join(pieces), countdiff --git a/agent/tests/test_agent_grounding.py b/agent/tests/test_agent_grounding.pyindex c4bfb4a07..4baf81c88 100644--- a/agent/tests/test_agent_grounding.py+++ b/agent/tests/test_agent_grounding.py@@ -10,14 +10,16 @@ from typing import Any, Callableimport pytestfrom src.agent.context import ContextBuilder-from src.agent.grounding import (- GroundingLedger,+from src.agent.grounding import GroundingLedger+from src.agent.grounding.identity import (+ _JOINED_CRYPTO_RE,_infer_currency,_infer_instrument_type,_infer_venue,- _JOINED_CRYPTO_RE,_normalize_symbol,_scan_symbols,+)+from src.agent.grounding.evidence import (_symbol_from_csv_filename,_timestamp_matches_claim_date,)@@ -2052,7 +2054,7 @@ def test_shanghai_lock_depends_on_symbol_canonicalization() -> None:"""Mutation guard: drop canonicalization and Shanghai dead-ends again."""monkeypatch.setattr(- "src.agent.grounding._normalize_symbol",+ "src.agent.grounding.identity._normalize_symbol",lambda value: str(value or "").strip().upper(),)ledger = GroundingLedger(run_dir=tmp_path, user_message="600519 现价多少")@@ -2812,7 +2814,7 @@ def test_a_report_style_date_cell_still_matches_its_evidence_row() -> None:price in that row was reported numeric_claim_unavailable even though therun had fetched the bar."""- from src.agent.grounding import _timestamp_matches_claim_date+ from src.agent.grounding.evidence import _timestamp_matches_claim_datestamp = "2026-08-10T15:00:00Z"for claim in ("08-10", "8-10", "08-10(一)", "08-10(周一)", "08-10(周一)盘中", "08-10盘中", "08-10收盘"):@@ -2824,7 +2826,7 @@ def test_a_report_style_date_cell_still_matches_its_evidence_row() -> None:def test_a_us_csv_stem_resolves_to_its_venue_suffix() -> None:"""``INTC_US.csv`` is ``INTC.US``; without the row it was no evidence at all."""- from src.agent.grounding import _symbol_from_csv_filename+ from src.agent.grounding.evidence import _symbol_from_csv_filenameassert _symbol_from_csv_filename("INTC_US") == "INTC.US"assert _symbol_from_csv_filename("BYN_V") == "BYN.V"@@ -2837,7 +2839,7 @@ class TestFiatPairAndIndexNormalization:"""Search, fetch and grounding agree on one FX spelling; ^ is a symbol."""def test_fiat_pair_spellings_normalize_to_yahoo_form(self) -> None:- from src.agent.grounding import _normalize_symbol+ from src.agent.grounding.identity import _normalize_symbolassert _normalize_symbol("GBP/USD") == "GBPUSD=X"assert _normalize_symbol("GBPUSD") == "GBPUSD=X"@@ -2848,12 +2850,12 @@ class TestFiatPairAndIndexNormalization:def test_scanned_slashed_pair_matches_resolver_answer(self) -> None:"""The query-as-asserted scan must agree with the chosen candidate."""- from src.agent.grounding import _scan_symbols+ from src.agent.grounding.identity import _scan_symbolsassert _scan_symbols("use GBP/USD spot") == {"GBPUSD=X"}def test_index_symbols_are_scanned_and_typed(self) -> None:- from src.agent.grounding import (+ from src.agent.grounding.identity import (_infer_currency,_infer_instrument_type,_scan_symbols,@@ -2866,7 +2868,7 @@ class TestFiatPairAndIndexNormalization:def test_ingest_search_symbol_does_not_create_conflicting_identity(self) -> None:"""The flagship regression: ingest('GBP/USD') must lock, never conflict."""- from src.agent.grounding import _normalize_symbol+ from src.agent.grounding.identity import _normalize_symbol# Chosen (from search_symbol) and asserted (the query text) must be# the same canonical identity — the comparison in _ingest_resolution.@@ -3427,7 +3429,7 @@ def test_research_paper_reported_metrics_are_grounded(tmp_path: Path) -> None:def test_compound_metric_leaf_kind_resolution() -> None:"""Token-split kind resolution covers the compound-leaf family."""- from src.agent.grounding import _metric_kind_for_path+ from src.agent.grounding.evidence import _metric_kind_for_pathassert _metric_kind_for_path("results[0].reported_annualized_return") == "return"assert _metric_kind_for_path("strategy_max_drawdown") == "drawdown"@@ -3742,7 +3744,7 @@ def test_crypto_pair_tables_match_the_resolver() -> None:identity, which outranks every later lock and blocks all market tools —so the duplication needs a guard, not a comment."""- from src.agent import grounding as g+ from src.agent.grounding import identity as gfrom src.tools import symbol_search_tool as ssassert set(g._CRYPTO_USD_BASES) == set(ss._CRYPTO_USD_BASES)diff --git a/agent/tests/test_grounding_recovery.py b/agent/tests/test_grounding_recovery.pyindex f5ae778ea..fe1e6ab04 100644--- a/agent/tests/test_grounding_recovery.py+++ b/agent/tests/test_grounding_recovery.py@@ -18,11 +18,11 @@ from unittest.mock import patchimport pytest-from src.agent.grounding import (+from src.agent.grounding import GroundingLedger+from src.agent.grounding.release import (MAX_GROUNDING_RECOVERY_ROUNDS,MAX_PRICE_EVIDENCE_ATTEMPTS,MAX_SYMBOL_RESOLUTION_ATTEMPTS,- GroundingLedger,)from src.providers.chat import LLMResponsefrom tests.message_roles_helpers import assert_system_messages_only_lead@@ -234,7 +234,7 @@ class TestRecoveryAction:validation = ledger.validate_final_answer("机器人ETF 现价 1.171。")with patch.multiple(- "src.agent.grounding",+ "src.agent.grounding.release",MAX_SYMBOL_RESOLUTION_ATTEMPTS=10_000,MAX_PRICE_EVIDENCE_ATTEMPTS=10_000,):diff --git a/agent/tests/test_grounding_release.py b/agent/tests/test_grounding_release.pyindex 6686ca4fa..0fa421a71 100644--- a/agent/tests/test_grounding_release.py+++ b/agent/tests/test_grounding_release.py@@ -21,18 +21,18 @@ from typing import Any, Callableimport pytest-from src.agent.grounding import (+from src.agent.grounding import GroundingLedger, ValidationResult+from src.agent.grounding.evidence import (_PRICE_INDICATOR_TOKENS,- _REDACTION_MARKER_EN,- _REDACTION_MARKER_ZH,- GroundingLedger,- ValidationResult,+ _is_price_denominated_indicator,+)+from src.agent.grounding.figures import (_CLAUSE_SEPARATOR_RE,_THOUSANDS_SEPARATOR_RE,_clause_spans,- _is_price_denominated_indicator,_lines_with_offsets,)+from src.agent.grounding.release import _REDACTION_MARKER_EN, _REDACTION_MARKER_ZHfrom src.agent.loop import AgentLoopfrom src.agent.tools import BaseTool, ToolRegistryfrom src.agent.trace import TraceWriter