dsh-metaphysics 0.62.1 → 0.62.3

package/docs/assets/verification-badge.svg

@@ -1,13 +1,13 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="470" height="28" role="img" aria-label="公开对拍：0 处不符｜128 例 · 5 剔除 · 312 紫微 · 20 奇门 · 12 交运">
-  <title>公开对拍：0 处不符｜128 例 · 5 剔除 · 312 紫微 · 20 奇门 · 12 交运</title>
+<svg xmlns="http://www.w3.org/2000/svg" width="455" height="28" role="img" aria-label="公开对拍：0 处不符｜128 例 · 5 剔除 · 127 未核 · 312 紫微 · 20 奇门 · 12 交运">
+  <title>公开对拍：0 处不符｜128 例 · 5 剔除 · 127 未核 · 312 紫微 · 20 奇门 · 12 交运</title>
   <linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient>
-  <rect width="470" height="28" rx="4" fill="#555"/>
-  <rect x="62" width="408" height="28" rx="4" fill="#1f6f3f"/>
-  <rect x="62" width="408" height="28" fill="url(#s)"/>
+  <rect width="455" height="28" rx="4" fill="#555"/>
+  <rect x="62" width="393" height="28" rx="4" fill="#1f6f3f"/>
+  <rect x="62" width="393" height="28" fill="url(#s)"/>
   <rect width="66" height="28" rx="4" fill="#555"/>
   <rect x="62" width="4" height="28" fill="#555"/>
   <g fill="#fff" text-anchor="middle" font-family="Verdana,DejaVu Sans,sans-serif" font-size="11">
     <text x="33" y="18">对拍</text>
-    <text x="266" y="18">0 处不符｜128 例 · 5 剔除 · 312 紫微 · 20 奇门 · 12 交运</text>
+    <text x="258.5" y="18">0 处不符｜128 例 · 5 剔除 · 127 未核 · 312 紫微 · 20 奇门 · 12 交运</text>
   </g>
 </svg>

package/engine/almanac.js

@@ -10,7 +10,7 @@
 import { solarToLunar } from './lunar.js';
 import { nayinOf } from './nayin.js';
 import {
-  toJDN, fromJDN, dayGanzhiIndex, ganzhiName, termWindow, termInstantJd, partsToJd, STEMS, BRANCHES, TERM_NAMES,
+  toJDN, fromJDN, dayGanzhiIndex, ganzhiName, termWindow, termInstantJd, STEMS, BRANCHES, TERM_NAMES,
 } from './calendar.js';
 import { HEX64 } from './interpret-data.js';
 import { sanheGroupOf } from './sanhe.js';
@@ -196,13 +196,18 @@ export function buildAlmanac(input) {
   if (day > daysInMonth(year, month)) {
     throw new Error(`非法日期：${year} 年 ${month} 月没有 ${day} 日`);
   }
-  const jdNoon = partsToJd({ year, month, day, hour: 12, minute: 0 });
   const lunar = solarToLunar(year, month, day);
   const jdn = toJDN(year, month, day);
 
+  // 黄历是「按日」出版的：交节当天即算新节（通书本子口径），所以节气一律比「日序」，
+  // 不比当天正午的时刻。用正午比时刻时，交节落在午后的那半年，整天还挂在上个月——
+  // 每年 12 个「节」约一半在午后，等于每年约 6 天的月柱、建除、值日神全错。
+  // 八字侧仍按精确到分的交节时刻判月柱（见 bazi.js），两者不共用这一层。
+  const termDayIndex = (jd) => Math.floor(jd + 0.5);
+
   // 年柱：立春界；同时给出春节界口径
   const lichunJd = termInstantJd(year, 2);
-  const ganzhiYear = jdNoon < lichunJd ? year - 1 : year;
+  const ganzhiYear = termDayIndex(lichunJd) <= jdn ? year : year - 1;
   const yearIdx = (((ganzhiYear - 4) % 60) + 60) % 60;
   const yearGz = ganzhiName(yearIdx);
   const springYear = lunar.lunarYear;
@@ -211,9 +216,8 @@ export function buildAlmanac(input) {
   // 月柱：以「节」为界
   const jieTerms = termWindow(year, { jieOnly: true });
   let prevJie = null;
-  let nextJie = null;
   for (const t of jieTerms) {
-    if (t.jd <= jdNoon) prevJie = t; else { if (!nextJie) nextJie = t; }
+    if (termDayIndex(t.jd) <= jdn) prevJie = t;
   }
   const monthBranchIdx = ((2 + (prevJie.index - 2) / 2) % 12 + 12) % 12;
   const yinMonthStem = ((STEMS.indexOf(yearGz.stem) % 5) * 2 + 2) % 10;
@@ -231,7 +235,7 @@ export function buildAlmanac(input) {
   let prevTerm = null;
   let nextTerm = null;
   for (const t of allTerms) {
-    if (t.jd <= jdNoon) prevTerm = t; else { if (!nextTerm) nextTerm = t; }
+    if (termDayIndex(t.jd) <= jdn) prevTerm = t; else { if (!nextTerm) nextTerm = t; }
   }
   const fmtJdDate = (jd) => {
     const p = fromJDN(Math.floor(jd + 0.5));

package/engine/bazi.js

@@ -8,18 +8,22 @@ import { resolveAddress } from './geo.js';
 import { computeBaziShensha } from './shensha.js';
 import { assertCivil, assertShifted, daysInMonth } from './validate.js';
 import { applyDst } from './dst.js';
+import { bool } from './bool.js';
 import { nayinOf } from './nayin.js';
 import { SANHE } from './sanhe.js';
 import { analyzeBaziFrame, scoreLuck } from './geju.js';
 
 // 地支藏干（本气 / 中气 / 余气）
+// 巳的顺序是「丙庚戊」而不是「丙戊庚」：庚长生于巳，是中气；戊是辰月余气，排末位。
+// 本表与下面 RENYUAN_TABLE（巳月：戊 5 日 → 庚 9 日 → 丙 16 日）互为倒序，
+// 也与寅（甲丙戊）、申（庚壬戊）、亥（壬甲）的「长生=中气」写法一致。
 export const HIDDEN_STEMS = {
   子: ['癸'],
   丑: ['己', '癸', '辛'],
   寅: ['甲', '丙', '戊'],
   卯: ['乙'],
   辰: ['戊', '乙', '癸'],
-  巳: ['丙', '戊', '庚'],
+  巳: ['丙', '庚', '戊'],
   午: ['丁', '己'],
   未: ['己', '丁', '乙'],
   申: ['庚', '壬', '戊'],
@@ -333,13 +337,13 @@ export function buildBazi(input) {
   let { year, month, day, hour = 0, minute = 0, gender = 'male' } = input;
   // 时辰未知：内部仍按「正午」跑完整条管线（大运、旺衰都要有个基准才能算），
   // 但对外一律不承认这个钟点——时柱置空、文本不出现具体时刻、精度降为按日。
-  const hourUnknown = input.hourUnknown === true;
+  const hourUnknown = bool(input.hourUnknown);
   if (hourUnknown) { hour = 12; minute = 0; }
-  const lateZi = input.lateZi !== false;
-  const useTrueSolar = input.trueSolar !== false;
+  const lateZi = bool(input.lateZi, true);
+  const useTrueSolar = bool(input.trueSolar, true);
   // 1986–1991 中国夏令时：出生证钟面时间普遍是「拨快 1 小时」的钟面时间，
   // 不校正会让时柱（乃至跨 23:00 的日柱）整档偏；显式传 dst:false 可关闭。
-  const dst = input.dst === false ? { applied: false, note: null } : applyDst({ year, month, day, hour, minute });
+  const dst = bool(input.dst, true) ? applyDst({ year, month, day, hour, minute }) : { applied: false, note: null };
   if (dst.applied) {
     year = dst.year; month = dst.month; day = dst.day; hour = dst.hour; minute = dst.minute;
   }
@@ -443,7 +447,7 @@ export function buildBazi(input) {
 
   // 流年（默认从「今年」起排 10 年；传 input.nowYear 可钉死基准年，用于复现历史结论；
   // input.liunianTo 可把窗口延到指定年，生时校正要拿几十年前的事件逐年对账）
-  const thisYear = Number(input.nowYear) || new Date().getFullYear();
+  const thisYear = Number(input.nowYear) || new Date().getFullYear(); // allow-clock: 未传 nowYear 时取本机年份；工具层 asOf 可钉死
   const liunianTo = Math.max(thisYear, Number(input.liunianTo) || thisYear + 9);
   const liunian = [];
   for (let y = thisYear; y <= liunianTo; y++) {

package/engine/bool.js

@@ -0,0 +1,195 @@
+/**
+ * 读参数里的布尔值只走这里。
+ *
+ * 本文件是引擎入口的「参数口径归一」：布尔（bool / canonicalFlags）与
+ * 数字（canonicalNumbers）各一道，盘面读的、句柄编码的、指纹比的是同一份值。
+ *
+ * 直接写 `args.cross === true` 会把字符串 "true" 与数字 1 都当成 false——
+ * 模型经 JSON 传参时这三种写法都出现过，界面层归一后仍可能有旧句柄或直接调用
+ * 引擎的路径。defaultValue 决定「没给值」时的口径（如 lateZi 默认 true）。
+ */
+export function bool(value, defaultValue = false) {
+  if (value === undefined || value === null || value === '') return defaultValue;
+  if (value === true || value === 1 || value === 'true' || value === '1') return true;
+  if (value === false || value === 0 || value === 'false' || value === '0') return false;
+  return defaultValue;
+}
+
+/**
+ * 引擎入口的开关归一表：键 → 未给值时的默认口径。
+ * 只收 schema 里声明为 boolean 的参数；盘面读值与句柄编码必须看到同一份值。
+ */
+export const FLAG_DEFAULTS = {
+  lateZi: true, trueSolar: true, dst: true,
+  isLeapMonth: false, leapAsNext: false,
+  cross: false, hourUnknown: false, diff: false, shadow: false,
+  trace: false, rectify: false, withInterpret: false,
+};
+
+/** 合盘对方 / 第三方对象里的同名开关（见 hepan、shadowPerson）：键 → 未给值时的默认口径。
+ *  hourUnknown 的缺省是 false（合盘遇到 true 会拦），不能跟着 lateZi 等默认开。 */
+const PARTNER_FLAGS = {
+  lateZi: true,
+  trueSolar: true,
+  dst: true,
+  hourUnknown: false,
+};
+
+function canonicalInto(source, defaults) {
+  let out = source;
+  const put = (key, value) => {
+    if (Object.is(source[key], value)) return;
+    if (out === source) out = { ...source };
+    out[key] = value;
+  };
+  const drop = (key) => {
+    if (out === source) out = { ...source };
+    delete out[key];
+  };
+  for (const [key, fallback] of Object.entries(defaults)) {
+    // 没给这个键就一个键都不加：凭空补 true 会改掉所有旧句柄的身份
+    if (source[key] === undefined) continue;
+    // 空串 / 空白串按「没给」处理（宿主 normalizeArgs 也是这么收的）：
+    // 各体系的缺省并不相同——奇门 lateZi 缺省 same-day、紫微 lateZishi 缺省 current-day，
+    // 若把 "" 折成全局缺省 true，同一次输入走工具层和直调引擎会排出两张盘。
+    if (typeof source[key] === 'string' && source[key].trim() === '') { drop(key); continue; }
+    put(key, bool(source[key], fallback));
+  }
+  return out;
+}
+
+function canonicalPartner(person) {
+  if (!person || typeof person !== 'object' || Array.isArray(person)) return person;
+  let out = person;
+  for (const [key, fallback] of Object.entries(PARTNER_FLAGS)) {
+    if (person[key] === undefined) continue;
+    if (typeof person[key] === 'string' && person[key].trim() === '') {
+      if (out === person) out = { ...person };
+      delete out[key];
+      continue;
+    }
+    const v = bool(person[key], fallback);
+    if (Object.is(person[key], v)) continue;
+    if (out === person) out = { ...person };
+    out[key] = v;
+  }
+  return out;
+}
+
+/**
+ * 把 args 里的字符串布尔 / 数字布尔统一成真布尔，返回**新对象**（无改动时返回原对象）。
+ *
+ * 为什么要在入口做一次：0.62.x 的盘面读开关用 `!== false`（只认字面 false），
+ * 句柄却直接编码传进来的原文。于是 `trueSolar:"false"` 排出「开真太阳时」的盘，
+ * 句柄里却写着 false——同一张盘两个身份，影子盘对拍、深链回放、跨版本 diff 全跟着错。
+ * 现在读值已统一走 `bool()`，这道归一仍要在入口做：它保证句柄与指纹拿到的
+ * 也是同一份真布尔，而不只是「读的时候碰巧算出同一个结果」。
+ */
+export function canonicalFlags(args) {
+  if (!args || typeof args !== 'object') return args;
+  let out = canonicalInto(args, FLAG_DEFAULTS);
+  for (const key of ['partner', 'partner2']) {
+    const person = out[key];
+    const fixed = canonicalPartner(person);
+    if (fixed !== person) {
+      if (out === args) out = { ...args };
+      out[key] = fixed;
+    }
+  }
+  return out;
+}
+
+// ── 数字归一 ────────────────────────────────────────────────
+// 只把「整串就是一个数」的字符串转成数字：count:"3" → 3、period:"9" → 9。
+// "9运" / "十" / 空串原样留着，让各体系原有的范围校验报 E_INPUT，
+// 而不是先变成 NaN 再以「没给」的身份混过去。
+
+/** schema 里 type 为 number / integer 的顶层键（options 由工具层摊平到顶层） */
+export const NUMERIC_KEYS = [
+  'hour', 'minute', 'longitude', 'verifyPast', 'seed',
+  'days', 'lunarYear', 'lunarMonth', 'lunarDay',
+  'num1', 'num2', 'num3', 'upper', 'lower', 'changing',
+  'count', 'toAge', 'fortuneYear', 'period', 'limit',
+  'sittingOffset', 'sittingDegree', 'facingOffset', 'facingDegree',
+  'year', 'month', 'day',
+];
+
+/** 数值数组：逐项转，任一项不是数字就整组不动，交给原有校验报错 */
+export const NUMERIC_ARRAY_KEYS = ['lines', 'rectifyHours', 'answers'];
+
+/** 字形 → 笔画的映射：值也是数字（起名的 strokeOverrides / surnameStrokes） */
+export const NUMERIC_MAP_KEYS = ['strokeOverrides', 'surnameStrokes'];
+
+// 与宿主 normalizeArgs 同一把尺：指数写法（1e3）与尾点（5.）都算「整串是一个数」。
+// 收窄成十进制会把 seed:"1e3" 留在字符串态——randomOf 照样按 1000 出牌，句柄却记着
+// "1e3"，同一张盘两个身份，正是这刀要消掉的东西。
+const NUMERIC_RE = /^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/;
+
+function numericOf(value) {
+  if (typeof value !== 'string') return value;
+  const s = value.trim();
+  if (!NUMERIC_RE.test(s)) return value;
+  const n = Number(s);
+  return Number.isFinite(n) ? n : value;
+}
+
+function canonicalMap(obj) {
+  let changed = false;
+  const next = {};
+  for (const [k, v] of Object.entries(obj)) {
+    const n = v === null ? null : numericOf(v);
+    if (!Object.is(n, v)) changed = true;
+    next[k] = n;
+  }
+  return changed ? next : obj;
+}
+
+/**
+ * 把数字串统一成数字，返回**新对象**（无改动时返回原对象）。
+ *
+ * 为什么也要在入口做一刀：句柄直接编码参数原文，`count:"3"` 与 `count:3`
+ * 抽出同一副牌、却拿到两个句柄——影子盘对拍、深链回放会认成两张盘。
+ * 另有两处不只影响身份，是实打实的算错：
+ *   * 风水 `period:"9"` 被 1–9 校验拒掉，报错里还写着「收到「9」」，看着像误报；
+ *   * 起名 `strokeOverrides:{"秋":"9"}` 被 overridesOf 静默丢掉，五格退回字库笔画，
+ *     用户给的笔画根本没参与计算。
+ */
+export function canonicalNumbers(args) {
+  if (!args || typeof args !== 'object') return args;
+  let out = args;
+  const put = (key, value) => {
+    if (Object.is(args[key], value)) return;
+    if (out === args) out = { ...args };
+    out[key] = value;
+  };
+  for (const key of NUMERIC_KEYS) {
+    if (args[key] === undefined) continue;
+    // 空串 / 空白串按「没给」处理（与宿主 normalizeArgs 一致）。留着会变成另一条路：
+    // 梅花数字起卦 Number("") = 0、风水 period 直接报「收到「」」——同一份输入两种结果。
+    if (typeof args[key] === 'string' && args[key].trim() === '') {
+      if (out === args) out = { ...args };
+      delete out[key];
+      continue;
+    }
+    put(key, numericOf(args[key]));
+  }
+  for (const key of NUMERIC_ARRAY_KEYS) {
+    const v = args[key];
+    if (!Array.isArray(v)) continue;
+    let changed = false;
+    const next = v.map((x) => {
+      if (x === null) return null;
+      if (typeof x === 'string' && x.trim() === '') { changed = true; return undefined; }
+      const n = numericOf(x);
+      if (!Object.is(n, x)) changed = true;
+      return n;
+    });
+    if (changed) put(key, next);
+  }
+  for (const key of NUMERIC_MAP_KEYS) {
+    const v = args[key];
+    if (!v || typeof v !== 'object' || Array.isArray(v)) continue;
+    put(key, canonicalMap(v));
+  }
+  return out;
+}

package/engine/calendar.js

@@ -1,5 +1,6 @@
 import { earthL } from './vsop-earth.js';
 import { createLru } from './lru.js';
+import { bool } from './bool.js';
 // 历法底座：儒略日、干支、二十四节气、真太阳时
 // 全部为纯函数，不依赖 DOM / Node API，Host 与 Client 可共用。
 
@@ -146,7 +147,14 @@ export function deltaTSeconds(year) {
       return v0 + ((v1 - v0) * (year - y0)) / (y1 - y0);
     }
   }
-  return knots[knots.length - 1][1];
+  // 2100 年后用 Morrison & Stephenson (2004) 抛物线外推：ΔT ≈ 32 × ((y − 1820)/100)² 秒。
+  // 注意单位：括号里是「世纪」，不是年——写成 32×(y−1820)² 会在 2400 年给出 1076 万秒（约 124 天），
+  // 把节气、朔望整体推后好几个月。这里以 2100 端点（110s）接续抛物线增长率，保证 2100→2101 连续：
+  // 2101 约 111.8s、2200 约 321s、2400 约 936s。
+  const [yLast, vLast] = knots[knots.length - 1];
+  const uLast = (yLast - 1820) / 100;
+  const u = (year - 1820) / 100;
+  return vLast + 32 * (u * u - uLast * uLast);
 }
 
 // 1929 年元旦之前，中国历书按「北京地方平时」（116.4°E，UTC+7.7611）推算朔与中气；
@@ -289,7 +297,7 @@ function termYearList(year, jieOnly) {
  * @param {{jieOnly?: boolean}} [opts] jieOnly=true 时只返回十二节（default：false，含气）
  */
 export function termWindow(year, opts = {}) {
-  const jieOnly = opts.jieOnly === true;
+  const jieOnly = bool(opts.jieOnly);
   const cacheKey = jieOnly ? `${year}|jie` : year;
   const cached = TERM_WINDOW_CACHE.get(cacheKey);
   if (cached) return cached;

package/engine/chenggu.js

@@ -5,6 +5,7 @@ import { ganzhiName, toJDN, fromJDN, dayGanzhiIndex } from './calendar.js';
 import { assertCivil, assertShifted } from './validate.js';
 import { hourToBranch } from './almanac.js';
 import { fail } from './fail.js';
+import { bool } from './bool.js';
 
 /** 六十甲子年骨重（单位：钱；索引 = (农历年 - 4) mod 60，0 = 甲子）。 */
 export const YEAR_WEIGHT = [
@@ -147,7 +148,7 @@ export function buildChenggu(input) {
   }
   // 晚子时换日与八字/六壬/奇门同口径：23:00–23:59 按次日取农历日与日柱，
   // 否则同一子时的前后两个钟点会差一天的日重
-  const lateZi = input.lateZi !== false;
+  const lateZi = bool(input.lateZi, true);
   let sy = year;
   let sm = month;
   let sd = day;

package/engine/convert.js

@@ -10,6 +10,7 @@
 import { solarToLunar } from './lunar.js';
 import { fromJDN, toJDN } from './calendar.js';
 import { buildAlmanac } from './almanac.js';
+import { bool } from './bool.js';
 import { assertCivil, assertObject, daysInMonth } from './validate.js';
 import { fail } from './fail.js';
 
@@ -91,7 +92,7 @@ export function buildConvert(input) {
     if (m < 1 || m > 12) throw fail('E_INPUT', '农历月份须在 1–12');
     const months = lunarMonths(y);
     if (!months.length) throw fail('E_INPUT', `农历 ${y} 年无法定位正月，请核对年份（1600–2400）`);
-    const isLeap = input.isLeapMonth === true;
+    const isLeap = bool(input.isLeapMonth);
     const hit = months.find((x) => x.month === m && x.isLeap === isLeap);
     if (!hit) {
       const leapMonths = months.filter((x) => x.isLeap).map((x) => `闰${MONTH_TEXT[x.month - 1]}月`);

package/engine/daliuren.js

@@ -4,6 +4,7 @@
 import { toJDN, dayGanzhiIndex, ganzhiName, termWindow, formatJd, jdToParts, xunKongOf } from './calendar.js';
 import { assertCivil, assertShifted } from './validate.js';
 import { SANHE_ELEMENT } from './sanhe.js';
+import { bool } from './bool.js';
 
 const GAN = ['甲', '乙', '丙', '丁', '戊', '己', '庚', '辛', '壬', '癸'];
 const ZHI = ['子', '丑', '寅', '卯', '辰', '巳', '午', '未', '申', '酉', '戌', '亥'];
@@ -308,7 +309,7 @@ function fanYin(ke, dayGan, dayZhi, stats, isFB) {
 export function buildDaliuren(input) {
   assertCivil(input);
   const { year, month, day, hour = 0, minute = 0 } = input;
-  const lateZi = input.lateZi !== false;
+  const lateZi = bool(input.lateZi, true);
   const jdnBase = toJDN(year, month, day);
   const jdn = lateZi && hour >= 23 ? jdnBase + 1 : jdnBase;
   const dayIdx = dayGanzhiIndex(jdn);

package/engine/diff.js

@@ -6,6 +6,8 @@
 //
 // 只做结构化比对，不改动任何引擎的输出。
 
+import { bool } from './bool.js';
+
 /** 比对时忽略的字段：文案、时间戳、口径回显、内部儒略日数字 */
 const IGNORE_KEYS = new Set([
   'summary', 'interpret', 'castAt', 'asOf', 'precision', 'disclaimer', 'note',
@@ -276,7 +278,7 @@ export const CALIBER_SWITCHES = {
       key: 'lateZi',
       title: '晚子时：23:00 后是否换日',
       short: '晚子时',
-      read: (a) => a.lateZi !== false,
+      read: (a) => bool(a.lateZi, true),
       alt: (v) => !v,
       label: (v) => (v ? '换日' : '不换日'),
     },
@@ -284,7 +286,7 @@ export const CALIBER_SWITCHES = {
       key: 'trueSolar',
       title: '真太阳时：是否按出生地经度修正',
       short: '真太阳时',
-      read: (a) => a.trueSolar !== false,
+      read: (a) => bool(a.trueSolar, true),
       alt: (v) => !v,
       label: (v) => (v ? '修正' : '不修正'),
     },
@@ -302,7 +304,7 @@ export const CALIBER_SWITCHES = {
       key: 'trueSolar',
       title: '真太阳时：是否按出生地经度修正',
       short: '真太阳时',
-      read: (a) => a.trueSolar !== false,
+      read: (a) => bool(a.trueSolar, true),
       alt: (v) => !v,
       label: (v) => (v ? '修正' : '不修正'),
     },

package/engine/fengshui.js

@@ -6,6 +6,8 @@ import {
 } from './calendar.js';
 import { applyDst } from './dst.js';
 import { fail } from './fail.js';
+import { bool } from './bool.js';
+import { assertCivil, MIN_YEAR, MAX_YEAR } from './validate.js';
 
 /** 九星名称表：数 → {name, color, element, star(北斗名), lucky}。 */
 export const NINE_STARS = {
@@ -94,7 +96,10 @@ const GUA_BY_NUM = ['坎', '坤', '震', '巽', '中', '乾', '兑', '艮', '离
  */
 export function mingGua(birthYear, gender) {
   const tail = ((birthYear % 100) + 100) % 100;
-  const century = birthYear >= 2000 ? { male: 99, female: 3 } : { male: 100, female: 4 };
+  // 世纪常数每个世纪减 1：1900s 男 100 / 女 4，2000s 99 / 3，2100s 98 / 2……
+  // 以前只在「>=2000」时切一次 99/3，2100 年以后（引擎支持到 2400）会整档算错。
+  const shift = Math.floor(birthYear / 100) - 19;
+  const century = { male: 100 - shift, female: 4 - shift };
   const mod9 = (n) => { const r = ((n % 9) + 9) % 9; return r === 0 ? 9 : r; };
   let num = gender === 'male' ? mod9(century.male - tail) : mod9(tail - century.female);
   if (num === 5) num = gender === 'male' ? 2 : 8;
@@ -114,10 +119,11 @@ export function eightStars(gua) {
   return result;
 }
 
-/** 立春界节气年：生日在当年立春前 → 上一年（按正午判，与黄历一致）。 */
+/** 立春界节气年：生日在当年立春前 → 上一年。
+ *  按「日」判（立春当日即算新年），与黄历同一口径；本函数只收年月日，不看当天交节时刻——
+ *  命卦本来就只按出生年取，同一天出生的人不因生在 16:27 前后换卦。 */
 export function guaYearOf(year, month, day) {
-  const birthJd = partsToJd({ year, month, day, hour: 12, minute: 0 });
-  return birthJd < termInstantJd(year, 2) ? year - 1 : year;
+  return Math.floor(termInstantJd(year, 2) + 0.5) <= toJDN(year, month, day) ? year : year - 1;
 }
 
 /**
@@ -214,13 +220,20 @@ export function timeFlyingOf(at) {
   const hour = Number.isInteger(at.hour) ? at.hour : 12;
   const minute = Number.isInteger(at.minute) ? at.minute : 0;
   const jd = partsToJd({ year, month, day, hour, minute });
+  // 交节的判定基准：给了时刻就按精确时刻（14:30 出生、当天 17:03 才立春，仍在上一月）；
+  // 只给日期则按「日」——当天交节即算新节。旧实现一律用正午，交节在午后的那半天会算成上个月，
+  // 与同一页黄历的月柱（已按日判）自相矛盾。
+  const hasHour = Number.isInteger(at.hour);
+  const jdTerm = hasHour ? jd : toJDN(year, month, day) + 0.5 - 1e-6;
   const terms = termWindow(year);
-  const guaYear = guaYearOf(year, month, day);
+  // 年紫白同样以立春为界，且与上面月/日/时用同一个基准：给时刻按时刻，只给日期按日。
+  // 若这里改回只看日期的 guaYearOf，立春当天的「年」会是新年、「月」还是上一月，同盘自相矛盾。
+  const guaYear = jdTerm >= termInstantJd(year, 2) ? year : year - 1;
   const yearBranch = yearBranchOf(guaYear);
   const yearGroup = branchGroupOf(yearBranch);
-  const prevJie = previousJie(terms, jd);
+  const prevJie = previousJie(terms, jdTerm);
   const monthNum = JIE_MONTH_NUM[prevJie ? prevJie.name : '立春'] || 1;
-  const half = zibaiHalfAt(terms, jd);
+  const half = zibaiHalfAt(terms, jdTerm);
   const jdn = toJDN(year, month, day) + (hour >= 23 ? 1 : 0);
   const dayIdx = dayGanzhiIndex(jdn);
   const dayName = ganzhiName(dayIdx).name;
@@ -440,9 +453,10 @@ export function xuankongChart(period, sitting, facing, opts = {}) {
 
 /** DST 校正出生日期（1986–1991），返回校正后的年月日。 */
 function civilDate(input) {
-  const dst = input.dst === false
-    ? { year: input.year, month: input.month, day: input.day, hour: 0, minute: 0, applied: false, note: null }
-    : applyDst({ year: input.year, month: input.month, day: input.day, hour: 0, minute: 0 });
+  // 开启 DST 校正（默认开）才走 applyDst；显式关闭时不动日期
+  const dst = bool(input.dst, true)
+    ? applyDst({ year: input.year, month: input.month, day: input.day, hour: 0, minute: 0 })
+    : { year: input.year, month: input.month, day: input.day, hour: 0, minute: 0, applied: false, note: null };
   return { year: dst.year, month: dst.month, day: dst.day, dst };
 }
 
@@ -471,6 +485,10 @@ export function buildFengshui(input) {
   if (input.fortuneYear !== undefined && input.fortuneYear !== null && input.fortuneYear !== '') {
     const fy = Number(input.fortuneYear);
     if (!Number.isInteger(fy)) throw fail('E_INPUT', `fortuneYear 必须是整数年份，收到「${input.fortuneYear}」`);
+    // 只校验「是整数」会放过 0 / 负数：年紫白照样按公式给出一颗星，看着像算过。
+    if (fy < MIN_YEAR || fy > MAX_YEAR) {
+      throw fail('E_INPUT', `fortuneYear 超出支持范围 ${MIN_YEAR}–${MAX_YEAR}（收到 ${fy}）`);
+    }
     input = { ...input, fortuneYear: fy };
   }
   const action = input.action;
@@ -486,6 +504,9 @@ export function buildFengshui(input) {
   if (!Number.isInteger(input.year) || !Number.isInteger(input.month) || !Number.isInteger(input.day)) {
     throw fail('E_INPUT', '风水命卦需要完整出生年月日（公历）——只知道年份不够：命卦按立春界划分出生年');
   }
+  // 与其它体系同一把尺：2 月 30 日、13 月、越界年份必须在入口报错，
+  // 否则会被 Date 静默滚到下个月，命卦按另一天算出来却没人知道。
+  assertCivil(input, '风水命卦');
   const civil = civilDate(input);
   const guaYear = guaYearOf(civil.year, civil.month, civil.day);
   const { num, gua, direction } = mingGua(guaYear, gender);
@@ -648,7 +669,7 @@ function parseFortuneAt(input) {
   }
   const [hour, minute] = rawTime.split(':').map(Number);
   if (hour > 23 || minute > 59) throw fail('E_INPUT', `fortuneTime 超出范围（HH:MM）：「${rawTime}」`);
-  const dst = input.dst === false ? null : applyDst({ year, month, day, hour, minute });
+  const dst = bool(input.dst, true) ? applyDst({ year, month, day, hour, minute }) : null;
   const at = dst ? { year: dst.year, month: dst.month, day: dst.day, hour: dst.hour, minute: dst.minute } : { year, month, day, hour, minute };
   return { at, dst };
 }
@@ -706,7 +727,7 @@ function buildXuankong(input) {
       action: 'xuankong',
       period,
       periodLabel: yearInfo ? yearInfo.label : `${period}运`,
-      ...(yearInfo ? { year: input.fortuneYear || (fortune && fortune.at.year), periodStart: yearInfo.start, periodEnd: yearInfo.end } : {}),
+      ...(yearInfo ? { year: input.fortuneYear ?? (fortune && fortune.at.year), periodStart: yearInfo.start, periodEnd: yearInfo.end } : {}),
       sitting: `${sitting.m}山（罗盘 ${sitting.deg}°）`,
       facing: `${facing.m}山（罗盘 ${facing.deg}°）`,
       sittingGua: sitting.gua,

package/engine/geju.js

@@ -26,7 +26,7 @@ const GENERATES = { 木: '火', 火: '土', 土: '金', 金: '水', 水: '木' }
 const OVERCOMES = { 木: '土', 土: '水', 水: '火', 火: '金', 金: '木' };
 const HIDDEN = {
   子: ['癸'], 丑: ['己', '癸', '辛'], 寅: ['甲', '丙', '戊'], 卯: ['乙'],
-  辰: ['戊', '乙', '癸'], 巳: ['丙', '戊', '庚'], 午: ['丁', '己'], 未: ['己', '丁', '乙'],
+  辰: ['戊', '乙', '癸'], 巳: ['丙', '庚', '戊'], 午: ['丁', '己'], 未: ['己', '丁', '乙'],
   申: ['庚', '壬', '戊'], 酉: ['辛'], 戌: ['戊', '辛', '丁'], 亥: ['壬', '甲'],
 };
 const HIDDEN_W = [1, 0.5, 0.3];
@@ -117,10 +117,23 @@ function monthPattern(pillars, dayStem, monthBranch) {
     w: HIDDEN_W[i] ?? 0.1,
   }));
   const others = ['year', 'month', 'hour'];
-  const exposedKey = others.find((k) => cands.some((c) => c.stem === pillars[k].stem));
   const base = cands[0];
+  // 取格按「藏干位阶」定先后：本气透则取本气，本气不透再取中气、余气（子平通例）。
+  // 不能按柱位「先遇上谁就用谁」——那样月干透出的中气会输给年干透出的余气，
+  // 实测约 13% 的盘有两处以上不同藏干并透，其中七成以上会因此取错格局名。
+  // 同一藏干多柱并透时，「月」优先报出（离月令最近）。
+  let exposedKey = null;
+  let use = null;
+  for (const c of cands) {
+    const hits = others.filter((k) => pillars[k].stem === c.stem);
+    if (hits.length) {
+      use = c;
+      exposedKey = hits.includes('month') ? 'month' : hits[0];
+      break;
+    }
+  }
   const hui = exposedKey ? null : huiCandidate(pillars, monthBranch, cands);
-  const use = exposedKey ? cands.find((c) => c.stem === pillars[exposedKey].stem) : (hui || base);
+  if (!use) use = hui || base;
   const usedBy = exposedKey ? '透干' : (hui ? '会支' : '本气');
   const exposedPos = exposedKey ? { year: '年', month: '月', hour: '时' }[exposedKey] : null;
 

package/engine/geo.js

@@ -2,6 +2,7 @@
 // 坐标为近似值（±0.2°≈0.8 分钟时差），足够真太阳时使用。
 // 联网（Nominatim）是显式可选项：只有调用方传 online: true 才会把地址原文发出去，
 // 默认走内置表，不上传任何数据。
+import { bool } from './bool.js';
 const RAW = `
 北京 116.41 39.90;上海 121.47 31.23;天津 117.20 39.13;重庆 106.55 29.56
 广州 113.26 23.13;深圳 114.06 22.55;珠海 113.58 22.27;东莞 113.75 23.02;佛山 113.12 23.02
@@ -229,7 +230,7 @@ export async function geocodeAddress(input, opts = {}) {
   const text = String(input || '').trim();
   if (!text) return local;
   // 默认离线：联网必须显式开启（会把出生地原文发给第三方）
-  const wantOnline = opts.online === true;
+  const wantOnline = bool(opts.online);
   if (!wantOnline) return local;
   if (local && typeof local.lon === 'number' && !DETAIL.test(text)) return local;
   const remote = await onlineLookup(text, opts);

package/engine/hepan.js

@@ -5,6 +5,7 @@ import { buildBazi, tenGod } from './bazi.js';
 import { STEMS, BRANCHES } from './calendar.js';
 import { assertCivil } from './validate.js';
 import { SANHE_GROUPS } from './sanhe.js';
+import { bool } from './bool.js';
 
 const WX_GAN = { 甲: '木', 乙: '木', 丙: '火', 丁: '火', 戊: '土', 己: '土', 庚: '金', 辛: '金', 壬: '水', 癸: '水' };
 const WX_ZHI = { 子: '水', 丑: '土', 寅: '木', 卯: '木', 辰: '土', 巳: '火', 午: '火', 未: '土', 申: '金', 酉: '金', 戌: '土', 亥: '水' };
@@ -217,7 +218,7 @@ export function buildHepan(input) {
       tenGodToA: godB,
       text: he5
         ? `日干五合（${aStem}${bStem}），传统称「天干五合」，主彼此吸引强，也容易黏在一起分不开。`
-        : `日干无五合：你在对方盘里是「${godA}」，对方在你盘里是「${godB}」。`,
+        : `日干无五合：对方在你盘里是「${godA}」，你在对方盘里是「${godB}」。`,
     },
     crossBranches: uniqCross.slice(0, 8),
     nayin: { a: nyA, b: nyB, label: nayinRel.name, text: nayinRel.text },
@@ -239,7 +240,7 @@ export function buildHepan(input) {
       wuxing: wxA,
       // 真太阳时口径要能被看到：合盘与单盘用同一套修正，否则同一个人会出现两套四柱
       longitude: A.input.longitude ?? null,
-      trueSolar: A.input.trueSolar !== false,
+      trueSolar: bool(A.input.trueSolar, true),
       solarNote: A.solarTime ? A.solarTime.note : '',
       summary: A.summary,
     },
@@ -252,7 +253,7 @@ export function buildHepan(input) {
       favor: favorB.join(''),
       wuxing: wxB,
       longitude: B.input.longitude ?? null,
-      trueSolar: B.input.trueSolar !== false,
+      trueSolar: bool(B.input.trueSolar, true),
       solarNote: B.solarTime ? B.solarTime.note : '',
       summary: B.summary,
     },