feat(finance): gate contract candidates by exit liquidity

[huangruiteng]

Summary / 摘要

Add a provider-neutral contract-liquidity evaluator to the public finance value-discovery extension. It admits or rejects research candidates using typed exit-capacity and exit-cost evidence, while preserving explicit unknown/stale reasons.

在 public finance value-discovery 扩展中加入 provider-neutral 的合约退出流动性评估器：基于退出容量与成本证据决定研究候选的准入，并保留 unknown/stale 的明确原因。

Boundary / 边界

• This changes research-pool admission only; it does not grant order, signing, transfer, or live-trading authority.

• Venue adapters and account facts remain outside public core/finance.

• CLI/managed capability is covered here. Frontend/Lark projection remains a separately tracked companion delivery (todo_67d7e3bd3767), so this PR is not presented as end-to-end product acceptance.

• 本 PR 只改变研究候选池准入，不授予下单、签名、转账或实盘权限。

• 券商适配与账户事实不进入 public core/finance。

• 本 PR 覆盖 CLI/managed capability；前端/Lark 同源投影由独立 companion Todo todo_67d7e3bd3767 跟踪，因此不把本 PR 宣称为端到端产品验收。

Validation / 验证

• loopx canary premerge --from-git-diff --git-diff-base origin/main --tier standard --goal-id finance-research-goal
• 4 direct checks passed
• 18 selected catalog/risk/boundary checks passed
• public/private boundary scan: 9 files, 0 hits
• focused finance tests and package build passed before the final rebase; the final exact-head premerge gate passed after rebasing onto e7ef75c08

Delivery / 交付

Target capability: public finance value discovery. Repository: loopx-project/loopx. Write scope: packages/loopx-finance-value-discovery/**, focused tests and bilingual contract docs.

[huangruiteng]

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

未发现 blocking finding。

动机

这个 PR 补的是 Finance 研究准入中一个明确缺口：衍生品候选即使有研究价值，也必须先证明“按当前持仓方向、在指定退出金额下，订单簿容量和退出成本是否可接受”。此前 finance_case_contract_v1 能验证研究方法/证据 gate，但不表达 long/sell、short/buy、requested notional、可执行金额和退出成本的联合约束。

exact head 35967e9b1e121d4d9996b3c1943f65986664de8f 提供了一个有独立使用价值的 backend/CLI 增量：venue adapter 负责合约发现、tick/lot 精度、订单簿测量与时间证据；公共 Finance extension 只接收冻结、public-safe、provider-neutral 的 measurement，推导 coverage/cost/disposition。Dashboard 与 Lark 的 companion adoption 明确不在本 PR 内，但 direct CLI 与 managed runtime 已经是可运行、可版本化、可回滚的真实入口，所以这不是只为未来 consumer 搭的空壳。

改动思路

我比较了现有 finance case gate、source coverage、operation request、CLI schema dispatch 与 extension placement。把 position-specific liquidity 塞进 finance_case_contract_v1 会把“研究方法 gate”与“某个方向/金额的退出执行证据”混成一个 contract；信任 adapter 自报 pass/fail 又会把 Finance 的准入规则外包。当前方案在既有 Finance extension 内新增独立 v0 schema，同时复用 boundary sanitization、console entrypoint 和 managed extension dispatch，是更窄且所有权清晰的选择。

完整数据流是：

1. caller 以 direct subcommand 或 managed stdin 提交 finance_contract_liquidity_input_v0；
2. _scenario 严格校验 direction/exit side、decimal string、evidence refs 与允许字段；
3. evaluator 独立计算 executable/requested coverage 与 spread + price impact + fee total cost；
4. freshness 先决定证据是否足够，只有 fresh 的容量/成本失败才会得到 insufficient_liquidity；
5. 输出固定声明 trading_allowed=false、automatic_ready_allowed=false，后续 consumer 只能把 passing 结果用于 bounded research successor。

具体改动

关键代码讲解

• evaluate_finance_contract_liquidity（contract_liquidity.py:151）拥有输入 schema、freshness window、coverage/cost 推导以及 per-scenario/aggregate disposition。它不访问 venue、账户或网络，也不接受 provider 自报 total/readiness。
• _scenario（contract_liquidity.py:91）把 long 固定为 sell exit、short 固定为 buy exit，并对数值文本、重复的 direction+notional identity、evidence refs 与 unsupported fields 做 fail-fast 验证。
• cli.run（cli.py:163）只在显式 subcommand 或 exact schema_version 下路由新 evaluator；安装包或命令可见性本身不会激活它，旧 schema 继续走原路径。

README 与 CONTRACT 提供了中英文语义、direct/managed 最小命令、authority exclusions 和 presentation companion 边界；manifest/package 同步升级为 0.8.0，并包含全合成示例。新模块属于可选 packages/loopx-finance-value-discovery provider，不扩张 Core capability catalog，也没有 persisted state 或 scheduler surface。

对主干的风险

语义与 CI 对齐

主要风险有三类：一是新 dispatch 误伤旧 Finance schema；二是 stale evidence 被错误解释成“流动性差”；三是 provider/consumer 把 research eligibility 当作交易或自动 ready 权限。

我做了以下验证：

• focused liquidity suite：12 passed；
• Ruff（changed runtime/test files）：passed；
• package sdist + wheel build：0.8.0 passed；
• 同一个 finance-case-gates-v1.json 经 origin/main@916763e2c 与 exact head 的公开 CLI 输出 SHA-256 均为 c8bb3804d2062d97ca0b7568043a275eb57c4734a379fe6f3823060f0f5a6d9f，证明 disabled/legacy path byte parity；
• 新 direct CLI 正向路径得到预期 1.2/1.1 coverage、11.5/12.3 bps cost 和 no-trading/no-ready boundary；
• 将 evaluation_as_of 改为 stale_after + 1s 后得到 insufficient_evidence；
• 把 long exit 改为 buy 后 exit 1，并返回明确的 must be sell for a long position；
• git diff --check 与 current-main merge-tree：passed/clean；
• packet 时 exact-head 远端检查 22 success，无 failure/pending。

残余风险是没有接入真实 venue adapter；这并不是用 mock 掩盖 postcondition，因为本 contract 有意从 adapter boundary 开始，并在输出中明确 venue_semantics_state=adapter_asserted。后续 presentation companion 必须直接消费 typed disposition/boundary，不能用文案重新分类或扩大 authority。

我的整体评价

这是一个 scope 合理的 justified_increment：它新增一条真实 direct/managed production path，复用现有 extension 生命周期，把 venue-specific measurement 与 Finance-owned admission 分开；旧输入/默认行为保持 byte-identical，不引入状态同步、交易权限或 Core 依赖。代码量主要由严格输入边界、确定性计算、负向测试和双语 contract 构成，没有发现可以在本 PR 内删除且保持同等语义的 speculative framework。

对 exact head 35967e9b1e121d4d9996b3c1943f65986664de8f 的结论为 APPROVE。未来-facing pass 也完成：当前最重要的相邻边界是 presentation adoption，但它有独立 consumer/验证理由，不应把 Dashboard/Lark 状态或 UI 逻辑提前塞进这个纯 evaluator。

English verdict: APPROVE — exact head 35967e9b1e121d4d9996b3c1943f65986664de8f adds a bounded, provider-neutral exit-liquidity evaluator with real direct/managed entrypoints, byte-identical legacy behavior, explicit stale-evidence handling, and no trading or automatic-readiness authority. No blocking finding identified.