Skip to content

"Vibe-Trading: Your Personal Trading Agent"

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.py
deleted file mode 100644
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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 records
diff --git a/agent/src/agent/grounding/figures.py b/agent/src/agent/grounding/figures.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.
+ return
diff --git a/agent/src/agent/grounding/policies.py b/agent/src/agent/grounding/policies.py
new file mode 100644
index 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 unique
diff --git a/agent/src/agent/grounding/release.py b/agent/src/agent/grounding/release.py
new file mode 100644
index 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), count
diff --git a/agent/tests/test_agent_grounding.py b/agent/tests/test_agent_grounding.py
index 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, Callable
import pytest
from 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 the
run had fetched the bar.
"""
- from src.agent.grounding import _timestamp_matches_claim_date
+ from src.agent.grounding.evidence import _timestamp_matches_claim_date
stamp = "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_filename
assert _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_symbol
assert _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_symbols
assert _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_path
assert _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 g
from src.tools import symbol_search_tool as ss
assert 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.py
index 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 patch
import 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 LLMResponse
from 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.py
index 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, Callable
import 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_ZH
from src.agent.loop import AgentLoop
from src.agent.tools import BaseTool, ToolRegistry
from src.agent.trace import TraceWriter