Compare commits

..
@@ -0,0 +1,81 @@
# 生时纠正用途扫描:用算法性质给 Arudha 与应期出覆盖依据(2026-11-17,Claude)
Bug 编号:BUG-1938(#304 拆出的前一半)。关联 BUG-1932(#297)。后一半「缺生产器的层」另开 BUG-1953,等占星师回复,不在本单。
## 背景
#297 的扫描里,两类层在真实范围下永远到不了 `policy_covered`:
- Arudha(A1、A7、A10、UL):`_arudha_provider` 要求已检查点之间的最大间隔不超过 1 秒才算覆盖,30 分钟的范围做不到,只能给 `sampled_only`。
- 应期(Vimshottari、Narayana):`_timing_provider` 只有范围不超过 180 秒才逐秒检查,更宽的范围一律 `sampled_only`。
这两类层其实不需要逐秒检查,它们什么时候变可以从算法本身推出来。本单把这些性质写成代码和测试,让覆盖判定有依据。**只改覆盖判定的依据,不改任何层的计算结果,不放宽 `_receipt` 的规则。**
文件:`scripts/rectification_purpose_gate/providers.py`(主要)、`native.py`(只在需要暴露中间量时)。
## 一、Arudha
要证明并使用的性质:在一个范围内,如果上升星座不变、七颗行星(加上所用的交点)的星座都不变,那么 A1、A7、A10、UL 都不变。所以 Arudha 可能变化的时刻只在这些换座时刻上。
做法:
1. 先读 `scripts/jaimini.py::calc_arudha_padas`,确认它的输入只有上升星座和各行星星座。如果它还读了别的随时间变的量(度数、逆行、强弱比较等),把这些量也列进「可能变化的时刻」的来源;列不全就不要声称覆盖,在 PROGRESS 写明差在哪里。
2. 新的 Arudha 提供器:
- 上升换座时刻:用已有的 `find_lines(..., (1,), longitude_at=...)`,条件与 `_varga_provider` 相同(纬度不超过 60 度、网格上黄经单调前进)。
- 行星换座时刻:对每颗行星的黄经,按 `_sector_provider` 的办法在分钟网格上找跨 30 度整数倍的位置再二分到秒。逆行的行星黄经会倒退,跨界检测要两个方向都认。`sample` 的 `raw` 里目前只有上升和月亮的黄经;需要的行星黄经从 `native.py` 的 `_chart` 结果里加进 `raw`,不另算一遍。
- 在每个候选时刻的前一秒和这一秒各取一次 Arudha 值,值变了的才记为这一层的边界。
- 所有候选时刻都检查过、各段内首尾值相同,才给 `policy_covered`,`method_id` 写 `sign_change_enumeration`,`max_unchecked_gap_seconds` 写实际的网格间隔,并在回执的 `reason` 之外新增一个字段 `basis`,写明依据(例如 `arudha_depends_on_signs_only`)。`_receipt` 目前会把 `resolution > 1` 或 `error > 1` 的降成 `sampled_only`,这条不动;边界时刻本身仍然二分到 1 秒。
- 高纬度、黄经不单调、任一行星黄经取不到:退回现在的做法(`sampled_only`)。
3. 反例测试(必须有,不能只测通过的情况):
- 用确定性假函数造一个「星座都没变但 Arudha 值变了」的输入,新提供器必须**不给** `policy_covered`(靠段内首尾值核对或段中点抽查发现)。为此在每个无换座的段里至少再抽查一个中点。
- 行星逆行跨回上一个星座的情况能检出边界。
- 同一秒内上升和行星同时换座,只记一次边界。
## 二、Vimshottari
要证明并使用的性质:出生时刻往后移,月亮黄经单调增加,所有 Vimshottari 周期的起止日期随之**单调**向前移(月亮跨星宿边界的那一刻除外,那一刻整个序列跳变)。所以在一个月亮不跨星宿的段内,任何一条周期边界跨过「用户问的日期 / 月末 / 年末」的次数至多一次,分钟网格发现签名变化后二分到秒就是完整的。
做法:
1. 先读 `native.py::_vimshottari` 和它调用的引擎,确认上面的单调性在代码里成立(余额按月亮在星宿内的位置线性算出)。不成立就停下来在 PROGRESS 写明,不要硬套。
2. 新的应期提供器(Vimshottari):
- 月亮跨星宿的时刻用已有的 `_sector_provider` 逻辑求出,作为强制分段点。
- 每个段内:分钟网格上算 `period_signature`,相邻两点签名不同就二分到秒;再加一条单调性核对——段内各网格点上同一条周期边界的日期必须单调不减,发现倒退就不给覆盖。
- 通过则 `policy_covered`,`method_id` 写 `moon_monotone_minute_grid_bisection`,`basis` 写 `vimshottari_boundaries_monotone_in_moon_longitude`。
- 范围不超过 180 秒时保留现在的逐秒做法。
3. 反例测试:
- 假函数造一个段内签名 A→B→A(一分钟内变过去又变回来)的输入:单调性成立时这不可能发生,所以用「边界日期非单调」的假输入验证提供器会拒绝给覆盖。
- 月亮跨星宿的范围:分段点被检出,两段分别判定。
- 真实引擎一例:±30 分钟范围、按月粒度,逐秒暴力扫描得到的边界集合与新提供器给出的完全一致(暴力扫描只在这条测试里跑一次,范围可以缩到 ±5 分钟控制耗时,并标 `slow` 以外的现有标记方式;写明耗时)。
## 三、Narayana
要证明并使用的性质:Narayana 的周期顺序和年数只由上升星座和各行星星座决定;出生时刻在一个「星座都不变」的段内移动时,所有周期边界随出生时刻**整体平移同样的时长**(年龄不变,起点跟着出生时刻走)。所以段内签名变化同样至多发生在边界平移跨过问的日期时,分钟网格加二分足够;星座换座时刻是强制分段点。
做法:
1. 先读 `native.py::_narayana`、`_narayana_periods`、`_narayana_antardasha_table`,确认输入只有上升星座和行星星座(以及出生时刻作为起点)。有别的依赖按第一节第 1 条的办法处理。
2. 提供器结构同 Vimshottari,分段点用第一节求出的上升与行星换座时刻(两处共用,不重复计算)。`method_id` 写 `sign_segments_minute_grid_bisection`,`basis` 写 `narayana_periods_fixed_within_sign_segment`。
3. 反例测试:段内周期顺序变了的假输入必须不给覆盖;跨上升换座的范围被分成两段;真实引擎一例与逐秒暴力扫描对齐(同上,缩小范围)。
## 四、不做的事
- 不接宫主、Chara 征象星、金星/木星、过运、财富 Yoga、Ashtakavarga 的生产器(BUG-1953)。本单之后领域用途(事业、钱财、婚恋)仍然会因为这些层 `blocked` 而到不了 `scope_ready`,这是预期,写进 PROGRESS 的「已知边界」。
- 不改 `scope._policy` 的层表,不改 `assess_use`,不改 `scan._receipt`、`_assessment` 的判定规则。
- 不接任何生产入口(API、页面、聊天都不导入新代码)。
- 不改 `scripts/chart_choice/`、`frontend/`、`scripts/report_render/`、`references/real_case_calibration/`。
- 不改 `scripts/jaimini.py` 和大运引擎的计算。
## 五、交付
- 代码与测试:`tests/test_rectification_purpose_coverage.py`(新文件,放本单全部测试);`tests/test_rectification_purpose_scan.py`、`test_rectification_purpose_binding.py`、`test_active_rectification_candidates.py`、`test_rectification_purpose_gate.py` 照旧通过,不删改旧断言。旧断言里写死 Arudha 或应期为 `sampled_only` 的,确实因本单变成 `policy_covered` 时可以改,逐条在 PROGRESS 说明。
- `docs/research/rect-purpose-coverage-20261117.md`:三条性质各一节,写「代码依据(文件和函数)→ 性质 → 提供器怎么用它 → 反例测试名」,再给一张表:三例真实引擎输入(用 #297 夹具里的那三例)在本单前后各层的覆盖状态对照。这份文档会转给占星师审,用普通话写,不堆术语。
- `docs/BUG_HISTORY.md` 在 BUG-1938 一节记录(没有就新增;只在自己那一节内编辑;不写姓名、出生资料、邮箱、ID)。`CHANGELOG.md` 一行;`docs/tasks/PROGRESS-rect-purpose-coverage-20261117.md`。
## 验收
- `PATH=<venv>/bin:$PATH python scripts/run_quality_gate.py --profile quick --skip-frontend-runtime` 通过;
- 新测试文件全部通过,三类层各有至少一条反例测试和一条与逐秒暴力扫描对齐的真实引擎测试;
- 用命令行入口 `python -m scripts.rectification_purpose_gate --input <json>` 跑一个 ±30 分钟、按月粒度的合成输入:A1/A7/A10/UL、Vimshottari、Narayana 的回执为 `policy_covered` 并带 `basis`;整次扫描的计算次数不超过默认预算 4000;
- `cd frontend && npx eslint .` 0 错误(本单不应有前端改动);
- 没有任何生产入口导入 `scripts/rectification_purpose_gate`(验收时会 grep)。