merge origin/staging into python hygiene (issue #68)

Docs-only catch-up; agent-loop rule A.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LutgzyJqNhPpZy1nFsJtN3

docs/tasks/PROGRESS-contracts-helpers-dedupe-20261013.md

@@ -0,0 +1,98 @@
+# PROGRESS · 契约与小工具去重 · 2026-10-13
+
+分支 `codex/contracts-helpers-dedupe-20261013`，基线 `origin/staging` `cd7e0a34933bd288ad7a529d51477c7099e1f6b1`。只搬定义和引用。哈希字节、状态字符串、主题枚举值不变。没有改表、迁移、依赖、`page.tsx`、`scripts/jyotish_api_server.py`。没有写 BUG_HISTORY、CHANGELOG、DESIGN.md。`docs/agents/domain.md` 与 `CONTEXT.md` 里没有 EvidenceDomain，未加术语句。本分支 BUG 最大号 1357，本单没有新缺陷，不占新号。
+
+## 做了什么
+
+- T1：报告创建请求的 zod、默认主题、深度枚举收进 `frontend/src/lib/contracts/personal-report-request.ts`。服务端类型用 `z.infer`，客户端发送类型用 `z.input`。原导出名在 route-core、plan、contract 里 re-export。按钮删掉手写 interface。
+- T2：校正状态列表与入口类型收进 `frontend/src/lib/contracts/rectification-entry.ts`。线上形状的 status 仍是 `string`。服务端类型在此之上收窄。`case-status.ts` 再导出这些数组，import 无环。客户端解析器仍接受任意字符串 status。
+- T3：旧引导流程的 `EvidenceDomain` / `evidenceDomains` 改名为 `LegacyGuidedEvidenceDomain` / `legacyGuidedEvidenceDomains`（数组里的字符串没变）。出生时间证据的 `CandidateResult` 改名为 `LegacyCandidateResult`。`ChoiceKey` 只留在 `probe-explain.ts`（`choice-card.ts` 已经 import 它，反向会成环），choice-card 再导出。`ClaimStatus` 只留在 `personal-report-contract.ts`。v9 的 EvidenceDomain 与快照的 CandidateResult 没改名。
+- T4：同义的对象判断和有限数判断收进 `frontend/src/lib/guards.ts`。`sha256Hex` 收进 `frontend/src/lib/hash.ts`（仅服务端）。长文、兑换码、消息正文改为调用它。
+
+## 替换清单（文件 → 共享函数）
+
+调用处多数保留原来的局部名字，用 import 别名接到共享函数。原因见文末「偏离」。别名不是另一份实现。
+
+| 共享函数 | 文件 |
+| --- | --- |
+| `isRecord` | `generate-personal-report-button.tsx`、`personal-report-page.tsx`、`account-deletion.ts`、`skill-package-registry.ts`、`report-public-projection.ts`、`compose-receipt.ts` |
+| `asRecord`（调用名本来就是 asRecord） | `varga-observations.ts`、`refinement-packet.ts`、`inference-adapter.ts`、`confirmation-gate.ts`、`ephemeris-view.ts`、`daily-starlanguage.ts`、`consultation-step-timing.ts` |
+| `asRecord`（别名 `recordOf`） | `subject-birth.ts`、`consultation-subject-resolver.ts`、`chart-subject-write.ts` |
+| `asRecord`（别名 `record`，非数组否则 null） | `birth-profile-timezone.ts`、`chart-view-mapper.ts`、`consultation-route-service.ts`、`general-daily-panchanga.ts`、`personal-report-longform-generate.ts`、`rectification-adopted-chart-tiers.ts`、`reply-quality-capture.ts`、`report-birth-binding.ts`、`v9/engine-client.ts`、`v9/segment-contract.ts`、`personal-report-route-core.ts`、`personal-report-worker.ts`、`personal-report-generation.ts` |
+| `recordOrEmpty`（别名 `record`，非数组否则 `{}`） | `consultation-workflow.ts`、`chart-birth-truth.ts`、`consultation-evidence-card.ts`、`consultation-judgment-table.ts`、`admin/rectification-telemetry-summary.ts`、`report-fact-table-values.ts`、`report-fact-tables.ts` |
+| `finiteNumberOrNull`（别名 `finiteNumber`） | `personal-report-route-core.ts`、`personal-report-worker.ts`、`personal-report-generation.ts`、`rectification-candidate-result.ts` |
+| `sha256Hex` | `personal-report-generation.ts` 再导出；`hashLongformMarkdown`、`hashRedeemCode`、`messageContentHash` 改为调用它 |
+
+## 未合并及原因
+
+| 留下的私有函数 | 原因 |
+| --- | --- |
+| `rectification-candidate-result.ts` 的 `function record` | 数组也当对象，否则 null。与 `asRecord` 不同义 |
+| `geoapify-location-service.ts` 的 `function record` | 数组也当对象，否则 `{}` |
+| `server-owned-birth-profile.ts` 的 `function finiteNumber` | 接受数字字符串，失败返回 undefined |
+| `chart-profiles/route.ts`、`chart-profiles/[id]/route.ts`、`synastry-reports/route.ts`、`admin/admin-error-response.ts` 的 `errorMessage` | 三种错误提取方式，任务书要求不并 |
+| `personal-report-service-core.ts` 的 `PERSONAL_REPORT_DEPTHS` | 名字和用途都不是 T1 的 `REPORT_DEPTHS`，没有硬合 |
+
+任务书 §2.3 把「含数组否则 null」记在 `rectification-adopted-chart-tiers.ts`。当前 staging 上该函数已经排除数组，所以并入 `asRecord`。真正含数组否则 null 的那份在 `rectification-candidate-result.ts`，保留。
+
+## 断言
+
+| 原值 | 新值 | 原因 |
+| --- | --- | --- |
+| `workflow.indexOf("function record(")` | `workflow.indexOf("function rectificationBoundaryFromGate(")` | 非数组否则空对象的私有 `record` 已删除。切片终点改到紧随其后的既有函数。锁住的 schema 字段没改，`chart: z.record(z.unknown())` 仍在 |
+
+文件：`frontend/tests/consultation-workflow-contract.test.ts`。其余点名测试没有改断言。
+
+## 仅 import
+
+这些文件只改了 import 行，esbuild 转译结果与 staging 相同：
+
+`rectification-choice-card.tsx`、`rectification-message-entry.tsx`、`use-rectification-case-snapshot.ts`、`answer-choice.ts`、`block-scan.ts`、`choice-action.ts`、`turn-intent-classifier.ts`、`turn-question.ts`、`window-widen.ts`、`rectification-chat-choice-run.ts`。
+
+## esbuild 差分
+
+对 `frontend/src` 里每个改动文件，用 esbuild `transform`（`.ts` / `.tsx`，`format=esm`，不打包）对比 `origin/staging` 与工作区。结果：相同 26，有差异 49，新文件 4，转译失败 0。
+
+新文件：`contracts/personal-report-request.ts`、`contracts/rectification-entry.ts`、`guards.ts`、`hash.ts`。
+
+有差异的原因，按文件：
+
+| 文件 | 原因 |
+| --- | --- |
+| `generate-personal-report-button.tsx` | 手写请求类型删除，默认主题改为从 contracts 取值 |
+| `personal-report-page.tsx`、`account-deletion.ts`、`compose-receipt.ts`、`report-public-projection.ts`、`skill-package-registry.ts` | 本地 `isRecord` 删除，改为 import |
+| `consultation-step-timing.ts`、`daily-starlanguage.ts`、`ephemeris-view.ts`、`confirmation-gate.ts`、`inference-adapter.ts`、`refinement-packet.ts`、`varga-observations.ts` | 本地 `asRecord` 删除，改为 import |
+| `subject-birth.ts`、`consultation-subject-resolver.ts`、`chart-subject-write.ts` | 本地 `recordOf` 删除，import `asRecord` 并别名为 `recordOf` |
+| `birth-profile-timezone.ts`、`chart-view-mapper.ts`、`consultation-route-service.ts`、`general-daily-panchanga.ts`、`personal-report-longform-generate.ts`、`rectification-adopted-chart-tiers.ts`、`reply-quality-capture.ts`、`report-birth-binding.ts`、`engine-client.ts`、`segment-contract.ts` | 本地「非数组否则 null」的 `record` 删除，import `asRecord` 并别名为 `record` |
+| `consultation-workflow.ts`、`chart-birth-truth.ts`、`consultation-evidence-card.ts`、`consultation-judgment-table.ts`、`rectification-telemetry-summary.ts`、`report-fact-table-values.ts`、`report-fact-tables.ts` | 本地「非数组否则空对象」的 `record` 删除，import `recordOrEmpty` 并别名为 `record`。`z.record(...)` 没改 |
+| `rectification-candidate-result.ts` | 只把「有限数否则 null」改为 import。含数组的 `record` 仍在文件里 |
+| `personal-report-route-core.ts`、`personal-report-worker.ts` | 同上，再加上 schema / 调用处的 guard import |
+| `personal-report-generation.ts` | guard 搬家，并且 `sha256Hex` 改为从 `hash.ts` 再导出 |
+| `personal-report-longform-appendix.ts`、`supabase/codes.ts`、`message-origin.ts` | 哈希函数体改为调用 `sha256Hex`。输入仍按 utf8 |
+| `personal-report-plan.ts`、`personal-report-contract.ts` | `REPORT_DEPTHS` 字面量搬到 contracts，本文件 re-export |
+| `case-status.ts` | 状态数组搬到 contracts，本文件 re-export。数组内容相同 |
+| `rectification-entry.ts` | 本地状态列表删除，Set 改用共享常量 |
+| `birth-time-question-planner.ts`、`birth-time-journey-turn.ts`、`birth-time-journey-transitions.ts`、`birth-time-journey-turn-persistence.ts`、`birth-time-journey-case-loader.ts` | 运行时常量改名 `legacyGuidedEvidenceDomains`。不打包，所以导出名出现在转译结果里。数组里的字符串没变 |
+
+相同的 26 个文件里，上面「仅 import」10 个只动了 import。其余是类型改名或类型再导出，类型擦除后转译结果与 staging 相同（含 `open-request.ts`、`choice-card.ts`、`report-evidence-bundle-v2.ts`、`birth-time-evidence.ts` 及其余 Legacy* 引用）。
+
+## 测试
+
+开工没有跑全量 `npm test`（本轮不做全量，也没有新的全量基线数字）。完工数字：
+
+| 检查 | 命令 | 结果 |
+| --- | --- | --- |
+| 类型 | `frontend` 下 `tsc --noEmit -p .` | 0 错 |
+| 规范 | `frontend` 下 `npm run lint` | 0 错，123 条警告。警告是原来就有的。本轮删过 `personal-report-worker.ts` 里不再使用的 `JsonRecord`，没有留下新警告 |
+| 改到的测试与任务书点名的测试 | `node node_modules/tsx/dist/cli.mjs --test`（guards、报告入口、首页校正解析、校正契约、报告生成与长文哈希、咨询 workflow 契约、出生时间改名相关） | 209 通过，0 失败，0 取消，0 跳过 |
+
+没有跑前端全量 `npm test`、Python 快速门、`test:db`。`supabase/codes.ts` 只改了哈希函数体，没有改查询、表或迁移。
+
+## 偏离
+
+1. 调用处没有改成共享函数名，改用 import 别名。把调用处全部改名时，已跟踪 diff 为 621 增、852 删（合计 1473），加上当时的新文件 248 行，约 1721 行，超过硬红线 1500。别名之后已跟踪 diff 为 229 增、461 删。共享函数仍只有 `guards.ts` / `hash.ts` 里的那一份。
+2. 报告按钮是客户端组件，但它要取值 `DEFAULT_REPORT_THEMES`，而这份常量和 zod schema 在同一个文件。因此这个按钮会把 zod 带进自己的包。任务书允许「zod 已在该组件 bundle 内」的例外；首屏 gzip 由验收侧看。测试仍从按钮 re-export 引用该常量。
+3. `LegacyCandidateResult` 的引用比任务书点名的文件多（向导、旅程加载等）。不改的话 `tsc` 会报错，所以一并改了类型名，没有改运行时值。
+4. 含数组变体的文件名与任务书 §2.3 不一致，以当前 staging 的函数体为准，见上表。
+
+完工 diff：已跟踪 229 增 + 461 删，新文件与本记录 345 行，合计 1035，低于 1500。