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

# TASK · 上游同步 3：返照时区本地化 / 年运面板保留 / PL9 紧凑写出（小单，2026-09-29）

## 基线

- `origin/staging` @ `6e393780`（写作时 head；开工时以最新 `origin/staging` 为准）。
- 分支 `codex/upstream-sync3-20260929`，工作树 `.worktrees/upstream-sync3-20260929`。
- 上游：`/workspace/yinduzhanxing` 本机干净检出 @ `db8cdf4a`（`origin/main`，2026-09-27）。本仓上次对照点 `19195f6e`（09-24）。
- **不推进快照锁**：`references/upstream/yinduzhanxing/SKILL.md` 与 `references/cross_project_contract/imports/*` 不动（上游仍有 29 处私人标记、10 个文件，`BLOCKED.md` 私人案例一节维持）。
- **文件范围**：只动 `scripts/jyotish_engine.py`、`scripts/solar_return.py`、`scripts/annual_tajika_pack.py`（如需）、`scripts/full_report_quality_gate.py` 及其测试。不碰 `sealed_holdout_rerun.py::PRODUCTION_FILES` 的 10 个校正冻结文件，因此不涉及 ERR-110 重冻结。
- **与同日报告两单的关系**：`TASK-report-reader-polish-20260929.md`、`TASK-report-english-edition-20260929.md` 改 `pl9_reader_export.py` 与前端，与本单文件不重叠，可并行；若执行中发现要动同一处 `jyotish_engine.py`，本单（改动小）先合。同日校正两单（扩集、打分研究）只改 `scripts/research/` 与数据，不重叠。

## 对照实证（Claude 2026-09-29 逐提交核过）

上游 `19195f6e..db8cdf4a` 共 63 提交、490 文件、+91,863 行。三个产品面里只有报告面有三条值得抄的正确性 / 性能修复；聊天与校正零相关改动。

| 上游提交 | 内容 | 本仓现状 |
| --- | --- | --- |
| `41d1c740` feat: separate return location and local timezone from birth place | `solar_return.py` 新增 `_localize_return_datetime(dt_ut, utc_offset, timezone_id)`：用 `ZoneInfo` 按返照**瞬间**取偏移；返照地点可选 `current_location`（`--solar-return-location-mode`、`--current-lat/lon/tz/timezone-id`） | `scripts/solar_return.py:275` `dt_local = approx_dt_utc + timedelta(hours=tz)` 固定偏移。有夏令时地区的用户，年运返照本地时间可能差 1 小时；中国盘无影响 |
| `089858c0` fix: preserve computed annual tables and panels through report assembly | `_preserve_annual_report_surface(packet, annual_snapshot)`：`selected_report_scope == 'full'` 时把 `annual_tajika_pack` 的 12 个键（`profile`、`monthly_chart_pack`、`normalized_tables`、`patyayini_dasha`、`lifetime_annual_chart_pages`、`annual_chart_series_pack`、`pl9_annual_visual_panels`、`pl9_annual_page_map`、`pl9_current_year_results`、`pl9_annual_dasha_results`、`annual_special_points`、`tripataki_chakra`）只补空叶、不重算 | `scripts/jyotish_engine.py:17859` 有同一条 `selected_report_scope == 'full'` 装配路径；是否同样丢面板**未核实**。09-25 `4d801e53` 修的是年主 / Muntha 空（BUG-1028 修复单），不是这一层 |
| `59c9139f` perf: stream compact PL9 JSON while preserving report payload | `output_json(data, *, stream=None)`：`json.dump` 直接写流；`schema == 'pl9_style_professional_export_v1'` 时 `indent=None`、`separators=(',', ':')`；落盘同样走流 | `scripts/jyotish_engine.py:768` `output_json` 仍是 `print(json.dumps(..., indent=2))`；`cmd_pl9_export` 落盘 `write_text(json.dumps(...))`，报告大小的字符串在内存里再造一份 |

同批**不抄**：`SKILL.md` 快照（差 32 行叙述性内容，依赖本仓没有的 `skills/` 与脚本）、`skills/` 13 个家族目录、`professional-report-h5` 店面、`technique_gap_scanner`、MCP `get_blocked_state_recovery_dashboard`、`--gender` Yoga 分支、日食 / Pushkara、KP 入参校验、126 个技法脚本、`candidate_signal_layers.py`。

## 决策记录（产品 2026-09-29）

- **批准**抄上表三条；第 2 条**先核实再抄**，不丢面板就记"不适用"关单。
- **MEVG 不跟上游放松。** 上游 `strict-workflow-router.md` 09-27 把 `MEVG / Global Web Evidence` 从 must 降为 optional、"外部 oracle 缺口不再阻塞传统解读"。本仓 `AGENTS.md` Part B3 / B4 维持原文：MEVG 是面向用户的诚实边界，拿不到外部证据就降置信度或 `blocked`。本仓 `references/strict-workflow-router.md` 已与上游分叉，本单不改它。
- 不推进快照锁、不重导入 SKILL.md、不动 `BLOCKED.md` 私人案例一节。
- 第 1 条：返照地点 `current_location` 模式**只接引擎侧参数**，本单不加前端入口（产品未要求）；默认 `birth_place` 行为对中国盘必须逐字节不变。

## 硬红线

1. 生产默认输出不变：用本仓现有 golden（`tests/golden/upstream_sync2/pl9_export_timing.json`、`pl9_time_system_table.md`）与一个虚构北京盘（1990-06-15 10:30）跑 `pl9-export` / `solar-return` / `tajika`，改前改后 JSON **解析后相等**（第 3 条只改序列化，语义不得变）。
2. `.venv/bin/python scripts/run_quality_gate.py --profile quick` 与开工基线逐条一致（先跑基线存日志）；`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` 全绿。
3. `scripts/jyotish_api_server.py` 不增长（§6 冻结）；本单不该碰它。
4. 不放宽任何置信度边界；不顺手升依赖、不顺手修无关 warning。
5. 隐私：测试只用虚构或公开名人盘。
6. 每条改动在 PROGRESS 写"上游 SHA / 本仓落点 / 取舍理由"，与 09-03 同步单的冲突表格式一致。

## 任务分解

- **T1 返照时刻按时区本地化（BUG-1095）**
  - 抄 `_localize_return_datetime`（ZoneInfo；无 `timezone_id` 时退回固定偏移），替换 `solar_return.py:275` 及同文件其他固定偏移处；`calc_solar_return_chart` / `solar_return_full_report` 增加可选 `local_timezone_id`。
  - 核查本仓报告链是否把 IANA 时区 ID 传到年运路径（`annual_tajika_pack.py`、`cmd_tajika`、`professional_report_reference.py` 入参）；传得到就接上，传不到就在 PROGRESS 写明"当前只能固定偏移，接入需前端改动"并列出缺口，不得伪称已修。
  - 引擎侧接 `--solar-return-location-mode` / `--current-*` 参数（默认 `birth_place`）；外部 PyJHora 回放在 `current_location` 时按上游返回 `blocked: separate_return_location_not_supported_by_external_adapter`。
  - 验收：新增测试——虚构纽约 1985-07-04 08:00 盘，返照年选一个夏令时生效年，本地时间按 `America/New_York` 与固定 `-5` 相差 1 小时；虚构北京盘改前改后逐字节相同；`tests/test_tajika.py` 全绿。
- **T2 年运面板保留（BUG-1096，先核实）**
  - 用虚构北京盘跑一次全量 `pl9-export`，检查上表 12 个键在最终交付包里是否为空 / 缺失；结果（每个键：有 / 空 / 缺）写进 PROGRESS。
  - 若有丢失：抄 `_preserve_annual_report_surface` 到 `jyotish_engine.py:17859` 装配路径，同年校验、只补空叶；并把上游 `full_report_quality_gate.py` 同批新增的面板覆盖检查接进本仓质量门当回归。
  - 若无丢失：BUG-1096 记 `closed_not_applicable`，附核实表；不抄代码。
  - 验收：丢失场景修后 12 个键非空、质量门测试先红后绿；无丢失场景只交核实表。
- **T3 PL9 紧凑流式写出（BUG-1097）**
  - `output_json(data, *, stream=None)` 按上游改；只对 `pl9_style_professional_export_v1` 去缩进；`cmd_pl9_export` 落盘改走流；其他命令输出格式（`indent=2`）不变。
  - 验收：同一输入改前改后 JSON 解析后相等；`pl9-export` 耗时与峰值内存（`/usr/bin/time -v` 或 `tracemalloc`）各测 3 次进 PROGRESS；非 PL9 命令输出逐字节不变。
- **T4 记录**
  - `docs/tasks/PROGRESS-upstream-sync3-20260929.md`（含上游对照表、取舍、数字）；`docs/BUG_HISTORY.md` 三条；`CHANGELOG.md` 一条（用户可感知：夏令时地区年运返照时间修正；报告导出更快）；`docs/tasks/README.md` 状态板行；`docs/research/pre_work_error_ledger.md` 若发现新的重复错误再追加。

## 让步顺序

T1 > T3 > T2 > T4 之外的性能数字。T1 与 T3 缺一不可合入；T2 核实表必须交，抄不抄取决于核实结果。

## 开工前置命令

```bash
git fetch origin --prune
git worktree add -b codex/upstream-sync3-20260929 .worktrees/upstream-sync3-20260929 origin/staging
cd .worktrees/upstream-sync3-20260929
python3 scripts/pre_work_check.py --remote-timeout 8 --command-timeout 45   # §9 引擎类任务预检
/workspace/Jyotisha/.venv/bin/python scripts/run_quality_gate.py --profile quick 2>&1 | tee /tmp/sync3-baseline.log
cd /workspace/yinduzhanxing && git show 41d1c740 089858c0 59c9139f --stat
```

## BUG 编号

开工时核对 `docs/BUG_HISTORY.md` 最大号。写作时 `BUG-1090` / `1091` 由校正两单预留，`1092`–`1094` 由报告两单预留（`6e393780`）。本单：**BUG-1095**（返照固定偏移）、**BUG-1096**（年运面板装配丢失，待核实）、**BUG-1097**（PL9 导出双份字符串）。号冲突则顺延并在 PROGRESS 说明。关联 BUG-608、BUG-1028。