Jyotisha/docs/tasks/PROGRESS-upstream-sync3-20260929.md

# PROGRESS · 上游同步 3：返照时区本地化 / 年运面板核实 / PL9 紧凑写出（2026-09-29）

任务书：`TASK-upstream-sync3-20260929.md`。分支 `codex/upstream-sync3-20260929`，基线 `origin/staging` = `15be6a06`。上游本机检出 `/workspace/yinduzhanxing` @ `db8cdf4a`。执行方：Claude fork 子代理；只 commit 不 push。

## 一句话结论

- **T1 做了，且比任务书写的更严重**：本仓返照的 `dt_local` 从来就是 UT 原样（`find_solar_return_ut` 注释「调用方另行加 tz」，但没有任何调用方加过）。北京盘读者版报告里的「Varshapravesha：2026-06-15 08:04:52」实际是 UT，应为 16:04:52；2028 年那行连日期都错（06-14 → 06-15）。所以**硬红线 1「北京盘逐字节相同」无法满足，也不应满足**——差异恰好只有被修正的三处（见 §T1 等价比对表），已把改前改后每个差异路径列出，请验收方按语义判断。
- **T2 不适用**：12 个键里 10 个在本仓从来没有生产者（`annual_tajika_pack.py` 不产出面板类键，只有 `pl9_reader_export.py` 防御性读取），不是装配时丢失。BUG-1096 记 `closed_not_applicable`。
- **T3 做了，但没抄上游的实现**：实测 `json.dump` 流式在 CPython 走纯 Python 编码器，比 `dumps` 慢 45%；改为紧凑 `dumps` 一次写出，保留上游 `stream=` 签名。文件 9.57 MB → 4.61 MB、序列化峰值 46.9 → 22.1 MB、0.41 → 0.30 s。

## 上游对照与取舍

| 上游 SHA | 内容 | 本仓落点 | 取舍 |
| --- | --- | --- | --- |
| `41d1c740` | `_localize_return_datetime`（ZoneInfo 按返照瞬间取偏移）、`annual_location`、返照地点 `current_location` 模式与 CLI 参数、外部 PyJHora 回放在异地时 blocked | `scripts/solar_return.py`（helper、`calc_solar_return_chart` / `solar_return_full_report` 四个新 kwargs、`dt_local` 真正本地化、Sahams 用 `annual_location`）；`scripts/cmd_solar_return.py`（新增 `solar_return_location_kwargs`，同时接受年运包命名空间 `return_*` 与 CLI 命名空间 `--solar-return-location-mode` / `--current-*` / `--timezone-id` / API `timezone`）；`scripts/annual_tajika_pack.py`（`_args_from_payload` 读 `settings.current_location`，出生 `timezone`/`timezone_id` 是 IANA 时传 `return_timezone_id`；新增 `_iana_timezone_id`）；`scripts/jyotish_engine.py`（`_annual_payload_from_args` 写 `current_location` 与 `birth.timezone_id`；`_build_pl9_full_annual_section` 异地时回放 blocked；full-reading Step 4.12 透传；`_add_solar_return_location_args` 挂到 `solar-return` / `full-reading` / `pl9-export`） | 全抄，另加 `--timezone-id`（出生地 IANA 区）——上游只在 `current_location` 模式带 IANA 区，出生地模式仍是固定偏移；本仓把出生地 IANA 区也接上，否则 T1 对默认模式没有意义。`tajika_monthly.py` / `_local_eight_year_overview` / `_annual_special_points` 本仓不存在，对应块不抄 |
| `089858c0` | `_preserve_annual_report_surface`：全量报告装配时把 12 个年运面板键从快照补回 | 无 | **不适用**（§T2 核实表）。同批 `full_report_quality_gate.py` +86 行（`80756803`）内容是逐年 Muntha / Year Lord 一致性与 Ashtakavarga 12 宫映射校验，与面板无关，任务书假设的「面板覆盖检查」不存在，未接 |
| `59c9139f` | `output_json(data, *, stream=None)` 流式写出，PL9 紧凑 | `scripts/jyotish_engine.py::output_json` 与 `main()` 的 pl9 `--output` 落盘 | 签名照抄，实现改为紧凑 `dumps`（§T3 数据） |

## T1 · 返照时刻本地化（BUG-1095）

### 事实

- 改前 `find_solar_return_ut` 返回 `'dt_local': dt_ut`（`scripts/solar_return.py:221`），`calc_solar_return_chart` 原样透传；`solar_return_full_report` 把它当本地时间交给 `calc_all_sahams(..., tz=birth_tz)` 做昼夜判定（`saham_daynight.determine_daytime` 再减一次 tz → 判定时刻比真实返照早 8 小时）。
- 读者版 `pl9_reader_export.py:1830/2201` 直接打印 `dt_local`。北京虚构盘（1990-06-15 10:30，39.9042/116.4074，+8，目标 2026）reader_main 渲染：

| 行 | 改前 | 改后 |
| --- | --- | --- |
| `- Varshapravesha：` | 2026-06-15 08:04:52 | 2026-06-15 16:04:52 |
| 2027 表行 | 2027-06-15 14:07:50 | 2027-06-15 22:07:50 |
| 2028 表行 | 2028-06-14 20:25:46 | 2028-06-15 04:25:46 |

- 昼夜判定时刻：`sahams.daynight_evidence.julian_day_ut` 2461206.5034（=06-15 00:04 UT）→ 2461206.8367（=真实返照 08:04:52 UT）。这张盘两者恰好都是白天，判定没翻；其他盘会翻。

### 等价比对（硬红线 1）

方法：改前用基线树（`git worktree add --detach <scratch> 15be6a06`，用完已删）、改后用本分支，同一命令、`PYTHONHASHSEED=0`，JSON 解析后递归比对，剔除 `generated_at` / `elapsed_seconds` / `*_hash` 等易变键。

| 命令 | 差异路径数 | 差异内容 |
| --- | --- | --- |
| `solar-return` 北京盘 | 6 | `solar_return.dt_local` 08:04:52 → 16:04:52；`solar_return.annual_location` / 顶层 `annual_location` 新增；`sahams.daynight_evidence.julian_day_ut` 改为真实返照时刻；`sunrise_jd_ut` / `sunset_jd_ut` 第 9 位小数浮动（rise_trans 起点变了） |
| `tajika --age 36` 北京盘 | **0** | — |
| `pl9-export --pack full` 北京盘 | 83 | 上面三项在 `full_report_pack.sections.annual.*`、`personal_report_producer.source_pack_contracts.annual_tajika_pack.*`、`raw_module_index[35].field_names` 的传播；其余全是易变项（VedAstro 快照 `called_at`、`slowest_stages` 顺序、authority / quality-gate 哈希 id——两次改后运行之间同样有 30 处这类差异） |
| `solar-return` 北京盘 固定 +8 vs `--timezone-id Asia/Shanghai` | **0** | 无夏令时地区 IANA 区与固定偏移等价 |

**结论：北京盘不是逐字节相同，差异恰为修正项本身；这一条需要验收方确认接受。**

### 夏令时与异地验证（虚构纽约盘 1985-07-04 08:00，40.7128/-74.006，`--tz -5`，目标 2026）

| 模式 | `dt_ut` | `dt_local` | `annual_location.utc_offset` | 返照盘上升 |
| --- | --- | --- | --- | --- |
| 固定偏移（改后默认） | 2026-07-05 01:08:03 | 2026-07-04 20:08:03 | −5.0 | Capricorn |
| `--timezone-id America/New_York` | 同 | 2026-07-04 **21:08:03** | **−4.0**（EDT） | Capricorn（盘按 UT 起，不变） |
| `--solar-return-location-mode current_location --current-lat 51.5074 --current-lon -0.1278 --current-tz 0 --current-timezone-id Europe/London` | 同 | 2026-07-05 02:08:03 | +1.0（BST） | **Taurus** |

### 时区 ID 能否传到年运路径（任务书要求核查）

- 引擎侧已通：CLI `--timezone-id`；API `birth.timezone` / `timezone_name`（`calculation_profile_contract._normalize_timezone` 认这两个键）→ profile `timezone.name` → `_annual_payload_from_args` 写 `birth.timezone_id` → `annual_tajika_pack._args_from_payload` → `return_timezone_id`；full-reading Step 4.12 走 `solar_return_location_kwargs(args)` 读 `timezone_id` / `timezone` / `timezone_name`。
- **前端缺口（未修，前端不在本单范围）**：`frontend/src/lib/personal-report-longform-birth.ts:79` 只传数字 `tz: profile.timezoneOffset`；账户资料其实存了 IANA 区（`account-profile-patch.ts:55` `timezone_id`，全球出生地必填）。网页报告因此仍走固定偏移：中国用户无影响；夏令时地区用户只有当资料里的偏移恰好等于返照瞬间的偏移时才对。补一行 `timezone: profile.timezone_id` 即可接上，建议另开前端小单。

## T2 · 年运面板核实表（BUG-1096，closed_not_applicable）

北京盘 `pl9-export --pack full --format json`（`selected_report_scope = full`），`worksheets.timing_and_predictive_systems.annual_tajika_pack`：

| 键 | 状态 | 说明 |
| --- | --- | --- |
| `profile` | 有 | |
| `patyayini_dasha` | 有 | 同时出现在 `external_engine_comparison.pyjhora` 与 `exports.json.field_statuses` |
| `monthly_chart_pack` | 缺 | 全包任何路径都没有；本仓 `annual_tajika_pack.py` 无生产者 |
| `normalized_tables` | 缺 | 同上 |
| `lifetime_annual_chart_pages` | 缺 | 同上 |
| `annual_chart_series_pack` | 缺 | 同上 |
| `pl9_annual_visual_panels` | 缺 | 同上 |
| `pl9_annual_page_map` | 缺 | 同上（本仓源码 0 处引用） |
| `pl9_current_year_results` | 缺 | 同上 |
| `pl9_annual_dasha_results` | 缺 | 同上 |
| `annual_special_points` | 缺 | 同上 |
| `tripataki_chakra` | 缺 | 同上 |

本仓年运包实际键：`annual_chart, audit, exports, external_engine_comparison, monthly_windows, mudda_dasha, muntha, patyayini_dasha, profile, report_sections, sahams, schema, solar_return, tajika_yogas, year_lord`（15 个）。「缺」不是装配丢失（`_apply_pl9_pack_selection` 在 `full` 时原样返回 packet），而是从未生成；上游的补回逻辑没有可补的来源。不抄代码。

## T3 · PL9 紧凑写出（BUG-1097）

### 序列化单步基准（改后 4.61 MB 语义包，`tracemalloc`，5 次取中位）

| 变体 | 耗时 | 峰值内存 | 文件 |
| --- | --- | --- | --- |
| A 旧：`dumps(indent=2)` + 写 | 0.410 s | 46.9 MB | 9.57 MB |
| B 上游：`json.dump(stream, compact)` | 0.593 s | 0.1 MB | 4.61 MB |
| C 采用：紧凑 `dumps` 一次写出 | **0.303 s** | 22.1 MB | 4.61 MB |

B 慢是因为 `json.dump` 只能走 `iterencode` 纯 Python 路径（C 编码器只在 `dumps` 且 `indent=None` 时启用）。本仓生产 API 路径（`jyotish_api_server.py`）不经过 `output_json`，本项只影响 CLI 与 `--output` 落盘，所以选耗时最优的 C，保留 `stream=` 签名。三种变体解析后与源对象相等。

### 整条 CLI 交错 A/B（`pl9-export --pack full --format json`，基线树 / 本分支交替各 3 次，`resource.getrusage` 子进程）

| 轮 | 基线耗时 | 基线 RSS | 改后耗时 | 改后 RSS |
| --- | --- | --- | --- | --- |
| 1 | 6.92 s | 197.9 MB | 6.58 s | 191.3 MB |
| 2 | 6.62 s | 169.2 MB | 6.42 s | 159.4 MB |
| 3 | 6.42 s | 169.6 MB | 6.38 s | 159.0 MB |

输出文件 9.57 MB → 4.61 MB；非 PL9 命令（`solar-return` / `tajika`）仍 `indent=2`，输出逐字节不变（tajika 0 差异）。

## 测试

- 新增 `tests/test_solar_return_timezone.py`（10 条）：ZoneInfo 夏令 / 标准偏移；北京 `dt_local = dt_ut + 8h` 与昼夜判定时刻回归；`Asia/Shanghai` 等价固定 +8；纽约 IANA 区差 1 小时且盘不变；伦敦异地返照盘上升不同；返照地点不全时报错；两种命名空间的 kwargs；年运包参数映射与缺字段报错；`output_json` 只对 PL9 紧凑且可解析。
- 任务书点名：`tests/test_tajika.py tests/test_annual_tajika_pack.py tests/test_full_report_quality_gate.py tests/test_professional_report_reference_api.py tests/test_api_server_growth_contract.py tests/test_cli_smoke.py` → 118 passed。
- 快速门（`run_quality_gate.py --profile quick`，系统 `python3` 3.13.5 + swisseph，`/workspace/Jyotisha/.venv` 在本机不存在）：
  - 基线 15be6a06 第一次（无 Node）：Python 步 1001 passed / 1 skipped，`npm test` exit 127（PATH 无 node）。
  - 基线第二次（`PATH=/exec-daemon` Node 22.14）：Python 步 **1 failed** `tests/test_consultation_native_layers.py::test_annual_route_attaches_the_annual_pack_verbatim`（`'blocked' == 'parameter_sensitive'`），门在 Python 步停下、未到 npm。该测试改后单独跑 3/3 通过（exit 0）；当时同机另有两个子代理在跑全量测试，判为负载相关的瞬时失败，不是本单改动（基线树、改动前）。
  - 改后（Node 22）：见文末「快速门改后」一节。

## 未完成 / 缺口

- 前端 IANA 区未传（见 T1 末节）。
- `full_report_quality_gate.py` 未改（上游同批改动与面板无关）。
- `saham_daynight` 的昼夜判定输入现在是真实返照本地时刻；其他盘的昼夜结论可能因此翻转（这是修正，不是回归），未逐盘统计。

## 快速门改后（`PATH=/exec-daemon` Node 22.14，系统 python3 3.13.5）

- Python 步：**1001 passed / 1 skipped / 3 subtests passed**（149.84 s），与基线第一次逐条一致；基线第二次瞬时失败的 `test_annual_route_attaches_the_annual_pack_verbatim` 本次通过。
- `npm test` 步：`sh: 1: tsx: not found` → exit 127。原因是本 worktree 没有 `frontend/node_modules`（基线两次同样在这一步 exit 127，逐条一致）。本单不改前端，另用临时软链到主检出的 `frontend/node_modules` 单独跑了一次 `npm test`（见下一节；软链跑完即删，不入库）。

## 前端 `npm test`（本单零前端改动；临时软链主检出 `frontend/node_modules`，Node 22.14，跑完即删）

`# tests 4357 / # pass 4302 / # fail 24 / # cancelled 0 / # skipped 31`，exit 1。24 条失败全是需要 Docker / 本地 PostgreSQL / 部署套件的用例（`local PostgreSQL applies the reviewed business schema…`、`migration runner…`、`staging backups…`、`Better Auth…` 等），与 09-29 已知基线 4302/24 的环境失败清单一致（无 Docker），无新增失败。

## Claude 验收（2026-09-29）

- 测试：`tests/test_solar_return_timezone.py` + 任务书点名 5 个文件 + `test_api_server_growth_contract.py` + `test_repo_privacy_markers.py` = 156 passed。
- 等价比对（独立重做）：基线 `15be6a06` 独立 worktree vs 本分支，虚构北京盘 1990-06-15 10:30，`PYTHONHASHSEED=0`：`solar-return` 6 处差异（`dt_local` 08:04:52→16:04:52、`annual_location` ×2 新增、`daynight_evidence.julian_day_ut` 改为真实返照时刻、sunrise/sunset 第 9 位小数）；`tajika --age 36` 0 差异。与执行方表逐条一致。
- 硬红线 1 裁定：旧代码 `solar_return.py:221/249` `'dt_local': dt_ut  # 调用方另行加 tz`，全仓无调用方加过，报告里的 Varshapravesha 时刻一直是 UT。「北京盘逐字节相同」的前提不成立，差异恰为修正项本身，**接受**。
- 快速门：Python 步 1001 passed / 1 skipped（与执行方基线一致）；`npm test` 步 exit 127 为本 worktree 无 `node_modules` 的环境缺口，本单零前端改动，执行方软链跑出 4302/24 与基线一致。
- 结论：T1 / T3 通过，T2 不适用成立。遗留另开小单：前端 `personal-report-longform-birth.ts:79` 只传数字 `tz`，需把账户 IANA `timezone_id` 送到引擎。