Jyotisha/docs/tasks/TASK-upstream-sync8-20261017.md

# TASK · 上游同步第八轮：上游 10-16 通知答复分支 + 10-08 以来四项计算修正（2026-10-17）

- 日期：2026-10-17
- 来源：
  - 10-16 产品要求复查上游 Skill 仓（GitHub `732642856/yinduzhanxing`，本机 `/workspace/yinduzhanxing`）。上游 `0337b77f → 3c2dad95` 共 14 个提交，其中 8 个是计算修正。
  - 我们把对方仍存在的 7 处代码问题和 5 个口径问题写成通知 `docs/research/upstream_notice_2026_10_16.md`（staging `9b750915`）发给 skill 作者。
  - 10-17 作者在分支 `codex/upstream-notice-20261016`（`caf1ed4e`）修复并逐条答复，答复见上游 `docs/research/upstream_notice_reply_2026_10_16.md`。
  - 产品 10-17 决定直接按该分支出本单。
- 执行方：**Grok（Windows）**，分支 `codex/upstream-sync8-20261017`，只推这个分支
- 验收：Claude（Linux）
- BUG 编号：**BUG-1380 起**。写作时 `docs/BUG_HISTORY.md` 最大号为 BUG-1366；在途单已占用 BUG-1367～1369（窄交付）和 BUG-1370～1374（婚恋合盘）。开工时再核对一次最大号，冲突则整体顺延。

## 1. 基线

- 基线 commit：`origin/staging` `53608d8b`。我方核对时用的是 `1eb504d3`，两者之间 `scripts/` 无改动。sync7（BUG-1318～1322）的代码已在其中。
- 上游参照：分支 `origin/codex/upstream-notice-20261016` 的 `caf1ed4e`（10-17）。
  - **注意：该分支未合入上游 main。** 上游 main（`3c01a214`）与它从 `97dea658` 分叉，main 上缺 Argala 裁决、Avastha 并存条件和 dasha_analyzer 修复。
  - 本单一律以 `caf1ed4e` 为准，不参照上游 main。
- 取上游：仓库是公开 GitHub，执行方可以加 remote 后 `git fetch` 读 diff（见 §9）。下表每项写了上游提交号，只按语义移植，**不整文件覆盖**；我方文件和上游已经分叉，补丁不能直接 apply。

## 2. 事故实证（`53608d8b`，按符号定位）

| 项 | 上游提交 | 我方现状 |
| --- | --- | --- |
| T1 星宿拆解第一大运小运 | `8643bc9a`（上游测试 `test_first_remaining_md_is_not_repartitioned_into_new_ads`） | `scripts/nakshatra_dasha.py::calc_nakshatra_dasha_breakdown` 把 `first_remaining`（出生时剩余年数）交给 `_calc_vimshottari_antardasha_full`，等于把剩余段当完整大运重新切 9 段。用例：月亮在 Ashwini 中点，当前小运应为 Rahu，我方给 Ketu。结果经 `modules.nakshatra_dasha.vimshottari_nak_breakdown` 进完整报告与数据包 |
| T2 星宿边界 | `3c2dad95` 第①部分、`8643bc9a`、`9e04f0db`（只取 `lon_to_nakshatra`） | `jyotish_engine.py::cmd_dasha` 与 `dasha_analyzer.py::lon_to_nakshatra` 都是 `idx = int(m/ns)` 和 `progress = (m%ns)/ns` 分开算。月亮恰在星宿起点时，两者不一致。上游 27 起点参数化测试在我方挂 16/27：第一大运余额 0，整段大运被跳过 |
| T3 Sandhi 假交接 | `3c2dad95` 第②部分（按我方数据形状改写） | `jyotish_engine.py::_calc_dasha_sandhi` 把第一段小运被裁到出生日的 `start` 当成交接。我方第一大运 `start` 本来就是出生前的真实交接时刻（BUG-1268），所以上游「跳过第一大运起点」那条**不搬**。默认参考时刻带墙钟时分，没归零到当天 0 点 |
| T4 Yoga Pinda | `30b43643` | `scripts/ashtakavarga.py::calc_yoga_pinda` 只取本座 bindu ×4× 行星权重，没做 Trikona / Ekadhipatya 削减，也没做十二座、七曜求和。我方已有标准削减链 `ashtakavarga_shodhana.sodhita_chain`（BUG-1209） |
| T5 Bhava Bala | `a4d4a249` | `scripts/bhava_bala.py`：Dig 表里人象与四足共用一张，且多一个 vanaspati 档；摩羯前半归成水象；Sputa 用阶梯表，不是 BPHS 分段公式，也没有火、木、土的特殊相位；吉星取了水星而不是月亮。报告 Bhava Bala 三分量表与咨询卡每宫 `bhava_bala` 都受影响 |
| T6 Argala | `e7301feb`、`86935c0a`、`4f1536f2` | `scripts/argala.py::calc_argala_for_reference`：<br>• 计都所在宫没反向数；<br>• 同数直接判阻挡；<br>• H9 当次级 Argala；<br>• `net_result` 按有星宫数比，不按成对比；<br>• `_summarize_argala` 用占位式 Rajayoga 排序。<br>下游：`consultation_native_layers.build_argala`、`consult_card_domain_facts` 的 `worksheets.advanced_systems.argala` |
| T7 KP 分区 | `8eec9a54` | `scripts/kp_system.py::get_kp_lords` 与上游修复前逐字相同：浮点累加 sub-sub 区间，与 120° 取余混用，star / pada / sub 在边界上落在不同半开区间。按角秒扫一圈，129.6 万点中 499 处不同，全在精确边界上 |
| T8 Avastha | 上游 `e628118d`（09-24，只取 `avastha_calculator.py` 与相关测试）、`7d545039`、`f75a6e77`、`ac565836`（Shayanadi 接线） | `scripts/avastha_calculator.py` 停在 `e628118d` 之前：<br>• `_is_friend_sign` / `_is_enemy_sign` 恒 False；<br>• 旺、落只认精确点 ±5°；<br>• Bala 无奇偶宫翻转，Jagrat 按宫位，交点星未排除；<br>• 标签是落陷→Vikala、燃烧→Khala、友→Mudita、敌→Dina；<br>• Shayanadi 是按星座元素的启发式，没有 PVR 公式，也没有接线。<br>上游 `7d545039` 的 dignity 用例在我方 21 败 3 过 |
| T9 Saham 例外弧方向 | `ce9fed15` | `scripts/tajika.py::_calc_formula_saham` 检查「上升是否在第一→第二操作数的顺行弧上」，不在就 +30°。PVR §28.8.1 p394 的规则是检查**第三操作数 C** 是否在 **B→A** 顺行弧上，不在则 +30°。我方 `references/saham_rules.json` 7 条公式第三项都是上升，所以两种判法近乎互补：**大量 Saham 结果会差 30°** |
| T10 日出相关 | `9f9f16b3`（只取 `gulika.py`）、`872eaecf`（只取 `saham_daynight.py` 日窗口）、上游 `BIT_HINDU_RISING` 口径 | `scripts/gulika.py` 夜晚结束用 `sunrise + 1.0`，不是真实的下一次日出。`scripts/saham_daynight.py::determine_daytime` 从 jd−1 查日出日落，晚于出生就整减 1.0 天，也没有 Hindu rising 口径。**该函数同时被生时校正使用**（`active_rectification_event_engine.py` 里 `saham_daynight.determine_daytime`，用于 Hora / Ghati 起点） |

## 3. 根因

我方前七轮同步按上游提交标题筛选，只搬了被点名的修正。上述算法边界和来源口径问题，有的是两边同源的旧写法（T1、T2、T6、T7、T9、T10），有的是我方从未跟进上游 09-24 以后的改写（T5、T8）。T1 是 BUG-1268 修 `cmd_dasha` 时漏掉的同类函数。

## 4. 决策记录（产品授权）

1. **10-17 产品决定：直接按作者修复分支 `caf1ed4e` 出单**，不等上游合 main。
2. 作者 10-17 口径答复，本单照此实现：
   - **Khala**：取 Science of Light 定义（落陷 = Khala；燃烧 = Kopa；友 Shanta、中性 Dina、敌 Duhkhita）。同时成立的条件**全部保留展示**（如擢升与燃烧并存）；旧单标签顺序只作兼容字段，并标明「无经典出处」。大友、凶星同宫条件标「未计算」。
   - **日出**：不强制全站统一。Saham 昼夜、Gulika、Shayanadi 改用 Hindu rising（日面中心、不计折射）；Panchanga 维持现有配置。
   - **Argala 同数**：只按 Rath p363 前两级比较，即先比占星数，同数再比水星、木星、宫主的合相 / 星座相位关联；仍平手的保留 `unresolved`，**不得**用 Shadbala 或其他常数顶替。第 3 宫「两颗以上凶星」门槛保留为参数敏感候选。
   - **Bhava Bala 吉星**：固定月亮、木星、金星，水星中性。结果里注明这是具名实现 `jyotishganit_mirrored_equal_house_v2` 的契约，**不写成经典定论**。
   - **Pinda**：按 PVR §12.7 表 28–29（处女座 6），以 PVR 例 43 = 152 校验；同主一占一空且同值时，按 Raman 15(c) 清空空宫。不向 PyJHora 常数靠拢。
3. **10-16 产品范围：本单不改生时校正打分。** 日出口径只跟作者改的几处。凡是会改变校正输出的移植，一律保住校正路径原行为（见 §5 红线 1）。
4. 用户可见变化已知并接受：
   - 报告 Avastha 表与咨询卡措辞会变；
   - Pinda 数值约 ×3、强弱排序会变；
   - Bhava Bala 每宫约 ±10%、排序会变；
   - 年运 Saham 不少会差 30°；
   - 咨询层 Argala 会出现「待定」。
5. 不搬：
   - `c3346847`：我方没有 `formation_status`，燃烧降级已由 sync5 处理；
   - `raman_sahams.py`：我方无此表；
   - 上游 `ac23c2ee` / `8abbfd91` / `c74fd96c` 研究工具；
   - `001033df` 测试环境隔离；
   - 分支上其余提交（年运计算域、D12 联动、英文报告、完整解读元数据、Narayana Rath seed `6b9cd74e`、交付 pin 等）。这些另行评估，**本单不碰**。
   - 上游 `9e04f0db` 把 `dasha_analyzer` 整体转调原生时钟、保留时分秒：会改变校正打分，本单**只取 `lon_to_nakshatra` 边界部分**，其余记入进度记录待研究。

## 5. 硬红线

1. **生时校正输出逐字节不变。**
   - 校正打分读 `dasha_analyzer.lon_to_nakshatra / build_dasha_timeline / build_antardasha`、`saham_daynight.determine_daytime`、`kp_system.get_kp_lords`。
   - T2 只许改变「恰在星宿起点」那几个浮点点的结果。
   - T7 只许改变精确边界点。
   - T10 必须让校正调用点保持现有日出口径与日窗口：例如 `determine_daytime` 新增显式参数，默认值即现行为，只有 Saham / Gulika / Shayanadi 调用方传新口径；或者校正侧显式固定旧口径。具体写法执行方定，结果必须相同。
   - 验收：改动前后各跑一次 `scripts/research/reported_offset_sweep.py` 与 `scripts/research/sealed_holdout_rerun.py`（用法同 sync6），结果 JSON 除时间戳外逐项相同。若有任何差异，**停下回报**，不得自行重新冻结（ERR-110）。
   - `tests/test_sealed_holdout_contract_freshness.py` 等冻结身份测试必须保持绿。
   - 不得改 `sealed_holdout_rerun.PRODUCTION_FILES` 所列文件。
2. `scripts/jyotish_api_server.py` 不得增长（`tests/test_api_server_growth_contract.py`）。本单应当不需要改它。
3. golden 由真实引擎重新生成，不手造。改任何既有断言写「原值 / 新值 / 原因」三栏（AGENTS §7.3）。前端合同测试里的 golden（如 `consult-evidence-card-golden.json`）同样由引擎重生。
4. Argala 的 `unresolved` / `strength_comparison_required` / `mixed` 不得在下游被压成 `none` 或「无」。
5. 不改数据库、不改 workflow、不提升 main、不推 staging；只推 `codex/upstream-sync8-20261017`。
6. 不写真实用户资料；示例只用公开名人盘（如乔布斯 AA）或虚构盘。实测数字段落推送前跑 `tests/test_repo_privacy_markers.py`。

## 6. 任务分解

每项一个提交，提交说明写上游提交号与 BUG 号。

| 项 | 内容 | 验收 |
| --- | --- | --- |
| T1 | 星宿拆解第一大运：小运从**完整大运真实起点**排，再裁到出生之后；复用 `cmd_dasha` 已有逻辑，不另写一套 | 移植上游 `tests/test_nakshatra_native_dasha_clock.py::test_first_remaining_md_is_not_repartitioned_into_new_ads` 通过（Ashwini 中点 → 当前小运 Rahu） |
| T2 | `cmd_dasha`、`dasha_analyzer.lon_to_nakshatra` 以及其他按 `int(m/ns)` + `m%ns` 分开算的星宿定位，改为同一个量一次算出序号与进度，并按上游 `8643bc9a` 的统一边界语义（不吞掉真实邻点） | 移植上游 27 起点参数化测试 `test_native_vimshottari_exact_star_birth_balance`，**27/27 通过**；另加一条：月亮在起点左右相邻浮点数时，序号分别为前、后星宿；红线 1 的校正回放相同 |
| T3 | Sandhi：小运交接用 `unclipped_start_datetime` 判断，第一段被出生裁剪的小运起点不算交接；默认参考时刻归零到当天 0 点 | 移植上游 `tests/test_dasha_sandhi_birth_clip.py`，按我方数据形状改写（第一大运 `start` 在出生前），三栏说明改写处；出生 30 天的虚构盘 Sandhi 表不再出现出生日假交接 |
| T4 | Pinda 改按 PVR §12.7：削减**复用 `sodhita_chain`**，十二座 × 星座权重（处女 6）+ 行星权重，求七曜；Raman 15(c) 同值清空空宫。更新报告表头说明 | 移植上游 `tests/test_ashtakavarga_pinda_source.py`；PVR 例 43 = 152；报告 Sodhita 表与 Pinda 用同一份削减结果（加一条断言）；`yoga_pinda_summary` 的 golden 由引擎重生 |
| T5 | Bhava Bala Dig 表、摩羯前后半、BPHS Sputa 分段公式、火木土特殊相位、吉星集合（月木金，水中性）；结果带方法名与 `claim_boundary`（上游最后一个元数据 hunk 我方缺 `status`，按我方结构补） | 移植上游 `tests/test_bhava_bala_vendor_profile.py`；`test_report_longform_gaps2` 等报告断言按三栏更新；BUG-1210 记录补关联 |
| T6 | Argala：<br>• 计都宫反向数、源对边界、H9 不当次级（`e7301feb`）；<br>• 同数按决策 2 的两级裁决，**复用我方 `narayana_dasha.select_narayana_seed_sign` 已有实现**，不移植后续层（`86935c0a`）；<br>• 解释文本与裁决一致（`4f1536f2`）；<br>• 待定状态透传到 `consultation_native_layers` 与 `consult_card_domain_facts` | 移植上游 `tests/test_argala_source_boundaries.py`、`tests/test_argala_strength_adjudication.py`；新增下游测试：同数仍平手时咨询层与咨询卡显示待定，不显示「无 / 被阻挡」 |
| T7 | `get_kp_lords` 改为边界安全的整数 / 精确分区（`8eec9a54`）。新版对 None、bool、字符串、NaN/inf 抛 `ValueError`：先 grep 调用点（`active_rectification_questions.py`、`flexible_birth_time_profile.py`、`rectification/kp_cusp_observation.py`、`cmd_kp`），确认没有依赖旧 `TypeError` 的 try/except，有就同步改 | 移植上游 `tests/test_kp_exact_angular_boundaries.py`；20 万随机经度新旧结果 0 差异；红线 1 回放相同 |
| T8 | Avastha 一批：<br>• 友敌座判定、旺落按星座、Bala 奇偶翻转、Jagrat 按尊贵、交点星排除（`e628118d` 的 avastha 部分）；<br>• Deeptadi 标签按决策 2（`7d545039`）；<br>• 并存条件全部保留（`f75a6e77`）；<br>• PVR Shayanadi `calculate_pvr_shayanadi` 移植并在主链接线：传月亮经度、上升经度、**实际前一次日出（Hindu rising）以来小时数**（`ac565836`）；<br>• 报告 Avastha 表、`report-fact-tables.ts`、咨询卡 avastha 行、`pl9_reader_export` 的 Markdown 表跟着改字段 | 移植上游 `tests/test_avastha_dignity_regressions.py`（7d545039 与 f75a6e77 版）、`tests/test_shayanadi_pvr.py` 通过；主链输出里 Shayanadi 的 `method_status` 不再是 `simplified_heuristic`；中英文报告各一例快照（公开盘） |
| T9 | Saham 例外：改为 C 在 B→A 顺行弧上、不在则 +30°；两个入口（`_calc_formula_saham` 与 trace）都改，规则说明同步改 `references/saham_rules.json` 的描述字段 | 移植上游 `tests/test_saham_directed_operand_contract.py` 与 `tests/test_tajika.py` 的改动（`ce9fed15`）；构造 C 在 A→B 弧上的例子，新旧结果差 30°；年运报告快照按三栏更新 |
| T10 | 日出：<br>• `gulika.py` 两处夜晚结束改用真实 `next_sunrise`；<br>• `saham_daynight` 增加 Hindu rising 口径与真实相邻事件日窗口（`872eaecf`），只给 Saham 昼夜、Gulika、Shayanadi 用；<br>• 校正调用点行为不变（红线 1） | 移植上游 `tests/test_saham_daynight.py` 的四季 × 四时用例（Hindu 口径）通过；新增测试：校正调用 `determine_daytime` 的结果与改前逐字节相同；高纬度冬季例子 Gulika 夜段终点等于真实次日日出 |

## 7. 让步顺序

- **不可让**：红线 1。
- **尽量不让**：T1、T2，二者是确定的错误，影响儿童用户的当前小运。
- **可让**：
  - T8 体量最大，可拆为 T8a（判定与标签）和 T8b（Shayanadi 接线）先后交。
  - T10 若在不动校正路径的前提下改动面超预期，可只交 Gulika 部分，Hindu rising 写清卡点。
  - T6 的下游透传若牵动前端过多，可先交引擎层，下游写清卡点。
- 次序建议：T1 → T2 → T3 → T7 → T4 → T5 → T6 → T9 → T10 → T8。T8 依赖 T10 的 Hindu 日出。

## 8. 验收门（执行方自测 + Claude 复验）

- Python：`ruff`、`py_compile`、定向测试；**全量 pytest 与基线逐名对比**（引擎数值改动，快速门曾漏过报告测试，BUG-1220）；快速门 `scripts/run_quality_gate.py --profile quick`；冻结身份测试绿；隐私标记测试。
- 校正回放：红线 1 的前后两次结果 JSON 附在进度记录。
- 碰到前端（T6 / T8 极可能）：tsc / lint / `npm test`（失败名单与基线逐名相同）/ build。
- 文档：
  - `docs/BUG_HISTORY.md`（BUG-1380 起，每项一号）；
  - `CHANGELOG.md`（用户可见：Avastha 措辞、Pinda、Bhava Bala、Saham、Argala 待定）；
  - `docs/tasks/PROGRESS-upstream-sync8-20261017.md`；
  - `docs/tasks/README.md` 状态。

## 9. 开工前置

```
git fetch origin --prune
git status -sb
git worktree add -b codex/upstream-sync8-20261017 .worktrees/upstream-sync8-20261017 origin/staging
cd .worktrees/upstream-sync8-20261017
git remote add upstream-skill https://github.com/732642856/yinduzhanxing.git   # 已有则跳过
git fetch upstream-skill codex/upstream-notice-20261016
git log --oneline -1 FETCH_HEAD    # 应为 caf1ed4e
```

读上游改动：`git show <提交号>`，以及作者答复 `git show caf1ed4e:docs/research/upstream_notice_reply_2026_10_16.md`。

开工时核对 `origin/staging` 是否仍为 `53608d8b`。若已前进，以最新 staging 为基，进度记录写明。