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 核实表必须交，抄不抄取决于核实结果。

开工前置命令

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。