设计地图：Rust 紫微斗数排盘引擎库

[lzm0x219]

Destination

形成可实施的规格：一个由 Rust 实现、mise 管理工具链的紫微斗数排盘引擎库。它接收外部已归一化的 ZiweiBirth 或直接排盘种子 ZiweiInput，输出不可变 Ziwei，提供高性能只读查询，并拥有 Node.js/TypeScript 与 WebAssembly 适配层。

Notes

• 已开始按顶层到纵切片实施；每个公开 API 先用编译测试确立合同。
• 唯一项目排盘规则：不按流派分支、不设规则版本、不向调用方暴露规则选择。
• ZiweiBirth：gender 为 0 女 / 1 男；year 为外部确定的数字农历年；month 和 hour 均为 0..=11；day 为 1..=30。
• ZiweiInput：gender、组成有效六十甲子年柱的生年干和生年支、month、紫微所在地支索引、hour；地支索引为子=0至亥=11；紫微支只校验 0..=11，由调用方负责其正确性。
• ZiweiBirth 以局数和农历日的统一公式推导紫微支，不采用五局 × 30 日查表；两类输入归一化为同一排盘种子。
• 两种输入统一构建不可变 Ziwei；不保留原始输入、source、inputType 或 day。它仅以可选 lunar_year 作为期间年份锚点：ZiweiBirth 为 Some(year)，ZiweiInput 为 None。
• 历法换算、闰月辨识和实际农历日期有效性由外部处理；引擎只校验字段结构与范围。
• V1 包含本命盘、大限与流年；大限、流年按需计算，核心暂不缓存。流月、流日、流时与解释仍排除。
• V1 包含来因宫、生年四化、宫干四化、自化与多跳飞化的原始关系；不输出解释或断语。
• Ziwei 保存不可变事实，ZiweiQuery 提供只读查询；绑定层持有命盘对象并提供快照。
• ZiweiSnapshot 包含简体、繁体名称；错误为稳定、机器可读合同；计算追踪按需启用。
• 每轮继续阅读 CONTEXT.md 和 docs/agents/domain.md；归档 Rust 与 Zig 仅作交叉参考，新规范和测试才是权威。

Decisions so far

• 研究：项目排盘规则的来源与验收事实 — 原典可支撑命身、十二宫、五虎遁、纳音五行局、星曜安置与生年四化的候选规则；闰月必须由外部归一化；来因宫、宫干飞化、自化未获核验来源，归档壬干四化与原典存在差异。研究证据在本地 docs/research/project-natal-charting-rules-sources.md。

• 研究：Rust、mise 与两种适配层的构建合同 — 候选为 Rust 1.98.0 由 mise 精确固定；Node 使用 Node-API + napi-rs，Wasm 使用 wasm32-unknown-unknown + wasm-bindgen --target web；精确 Node/绑定版本和测试 runtime 留待绑定实现前决定。研究证据在本地 docs/research/rust-mise-node-wasm-build-contract.md。

• 研究：转录并核验 V1 五行局与紫微定位表 — 已逐格核验五局 × 30 日的 150 个紫微定位格及紫微到天府的 12 宫映射。该表保留为研究证据，不进入运行时、规格或完整测试数据；研究证据在本地 docs/research/five-element-bureau-ziwei-placement-table.md。

• 梳理：确定 V1 星曜集合与核心规则表 — V1 固定 18 星、全局稳定排序、40 格生年四化项目表（壬干化科为左辅）、120 个宫干组合；紫微以公式推导，ZiweiInput 可信注入紫微支。

• 梳理：确定来因宫、宫位四化与自化的 V1 范围 — V1 纳入来因宫、四条各自落在目标星曜的生年四化、48 条宫干四化单跳关系与向心／离心自化；只输出原始关系，不输出解释或断语。

• 梳理：确定多跳宫干飞化的路径与循环合同 — 自化优先；同组或同类自化终止，不同组且不同类时保留原化象继续；无自化时由生年四化分叉，否则保留原化象；每条路径禁止重入宫位。

• 梳理：确定大限与流年规则及按需计算边界 — 本命盘只预计算本命事实；大限与流年按需计算、核心不缓存。大限 d 为 0..=11，每限十年；流年 i 为 0..=9。未选择 i 时返回该限十个虚岁及可得的数字农历年；选择时以生年支加虚岁减一确定流年命宫，并逆布十二流年宫职。期间只重排宫职。

• 梳理：本命 Ziwei 的事实合同 — 以 Zig Natal 为骨架：保留排盘种子、生肖、五行局、命宫地支、身宫和来因宫的宫名与地支；十二宫保留宫名、地支、宫干、星曜及四条宫干四化；四化保留源/目标宫名与地支。它不保留原始输入、输入来源、day 或预计算期间；可选 lunar_year 是期间年份锚点：ZiweiBirth 构建时存在，ZiweiInput 时不存在。

• 文档：Rust 包与适配层架构 — 当前只保留深核心包 ziwei_core；查询并入核心，Node/Wasm 在真实交付时作为单向 adapter 包创建；历法、分析和纯重导出门面均不预建。完整约束见 docs/architecture/rust-package-design.md。

• 初始化：Rust workspace 与 mise 工具链 — 单成员 ziwei_core workspace 与 mise Rust 1.98.0 已通过精确工具链下的格式、测试、Clippy 和 Rustdoc 验证；未创建绑定 crate 或引入依赖。

Not yet specified

• ZiweiSnapshot、Node 与 Wasm 的输出 interface。
• ZiweiQuery 的操作目录、错误码与计算追踪合同。
• 绑定实现前的精确 Node 版本、包管理器、Node-API level、napi-rs/wasm-bindgen 配对与 Wasm 测试 runtime。
• 正确性语料、公式的人工核验金样本、性能工作负载、固定基准环境与阈值。

Out of scope

• 提交、发布和向后兼容承诺。
• 历法换算、闰月、时区、真太阳时与实际农历日期验证。
• 流月、流日、流时、解释和分析功能。

[lzm0x219]

2026-09-08 当前状态校正：正文中的早期 Notes / Decisions 是历史记录，涉及现行规格时应以 CONTEXT.md、docs/architecture/v1-decision-map.md 和 docs/architecture/rust-package-design.md 的后续修订为准。

当前包名为 ziwei；Ziwei 提供 from_birth / from_parameters 创建入口，结果为不可变 Natal，输入为 Birth / Parameters。归一化资料归属 Profile；宫干四化按需计算；连续飞化已暂缓，不适用早期 #332 所述路径规则。大限、流年与年度摘要已经实现，#333 可按完成收尾。

#326 的剩余范围是追踪与稳定错误码处置；#327 尚需正式性能基线与阈值落实；#331 尚需可复核原典转录证据。正文中的 docs/research/ 链接在当前工作树缺失，不能继续作为可直接访问的材料入口。Node/Wasm 绑定仍待真实交付时确定运行时与 wire format，不据此提前创建绑定包。