@openfate/bazi-engine 1.0.0 → 1.1.1

package/README.md

@@ -3,10 +3,10 @@
 ![NPM Version](https://img.shields.io/npm/v/@openfate/bazi-engine)
 ![License](https://img.shields.io/npm/l/@openfate/bazi-engine)
 
-> **The accurate, production-ready Four Pillars (八字) engine for JavaScript & TypeScript.**
+> **A deterministic, production-oriented Four Pillars (八字) engine for JavaScript and TypeScript.**
 > Powered by [OpenFate.ai](https://openfate.ai) — the AI-native metaphysical analysis platform.
 
-Getting the Four Pillars right is hard. Solar Term boundaries (节气), True Solar Time correction (真太阳时), day-change boundaries, Lunar calendar conversion — one wrong edge case and every chart is off. **We've solved all of it.**
+Getting the Four Pillars right is hard. Solar Term boundaries (节气), True Solar Time correction (真太阳时), day-change boundaries, and lunar conversion all require explicit, testable policy. This package exposes those calculations and the metadata needed to audit them.
 
 ---
 
@@ -155,6 +155,10 @@ Main entry point. Returns a `BaziChart` with:
 - `daYun` — 9 Major Luck Cycles with start year/age
 - `interactions` — All detected branch interactions (7 types)
 - `solarTimeInfo` — True Solar Time details (or null if disabled)
+- `calendar` — Civil solar input, calculation solar time, converted lunar date, and zodiac
+- `metadata` — Applied True Solar Time, timezone, DST, and day-boundary policy
+
+Each pillar preserves the simple `stem`, `branch`, and `element` fields and also includes Ten Gods, hidden stems, Na Yin, Xun, void branches, and growth stage.
 
 ### `detectInteractions(natal, annualBranch?): BranchInteraction[]`
 Detect interactions in a natal chart, optionally against an annual branch (太岁).
@@ -166,13 +170,15 @@ Low-level pillar generator — use when you've already handled time correction y
 
 ## 🛡️ Testing & Reliability
 
-Bazi calculations are notoriously prone to edge-case bugs. We maintain a **comprehensive regression suite** of 100+ global edge cases, verified against astronomical standards:
+Bazi calculations are notoriously prone to edge-case bugs. We maintain a regression suite of 100+ calendrical cases plus focused public-contract tests:
 
 - **24 Solar Terms**: Minute-level precision for *Li Chun*, *Jing Zhe*, etc.
 - **Early/Late Zi Hour**: Handles the 23:00 day-rollover across month/year boundaries.
 - **Global Distortion**: Extreme longitudes (e.g., Xinjiang, Iceland) and fractional timezones (e.g., India UTC+5.5).
-- **Historical DST**: Automatic handling of Chinese DST (1986-1991), UK Double DST, and more.
-- **Century Boundaries**: Verified accuracy for dates across 1800, 1900, 2000, and 2100.
+- **Historical DST**: Explicit `dstOffset` input or IANA timezone rules; the engine does not guess historical policy.
+- **Century Boundaries**: Regression coverage for dates across 1800, 1900, 2000, and 2100.
+- **Da Yun**: Exact start date, elapsed-age convention, direction, and cycle boundaries.
+- **Factual Enrichment**: Ten Gods, hidden stems, Na Yin, Xun, void branches, and growth stages.
 
 Run the tests yourself:
 ```bash
@@ -201,6 +207,28 @@ Birth input (civil time)
 
 `@openfate/bazi-engine` gives you the data. **[OpenFate.ai](https://openfate.ai/bazi)** gives you the complete AI-powered interpretation — relationship analysis, career forecasting, and interactive AI chat with your chart.
 
+## GitHub Pages Site
+
+This repository now includes a static GitHub Pages microsite in [`docs/index.html`](docs/index.html).
+
+To publish it:
+
+1. Push the repository to GitHub on the `main` branch.
+2. In the repository settings, open `Pages`.
+3. Under `Build and deployment`, select `GitHub Actions`.
+4. Push a new commit or manually run the `Deploy GitHub Pages` workflow.
+
+If the workflow fails with `Get Pages site failed`:
+
+- The repository does not have GitHub Pages enabled yet.
+- The fastest fix is to open `Settings` -> `Pages` and set `Source` to `GitHub Actions`, then rerun the workflow.
+- Optional: create a repository secret named `PAGES_TOKEN` with a token that can administer Pages. The workflow will then try to enable Pages automatically on the first run.
+
+Once enabled, the site will publish at:
+
+- `https://openfate-ai.github.io/bazi-engine/` for the current repository name
+- or `https://<owner>.github.io/<repo>/` for forks and renamed repositories
+
 ## License
 
 MIT — Free to use, modify, and distribute commercially.

package/dist/core/cycles.js

@@ -4,6 +4,8 @@
 // ============================================================================
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.calculateDaYun = calculateDaYun;
+const pillars_1 = require("./pillars");
+const tenGods_1 = require("./tenGods");
 /**
  * calculateDaYun
  *
@@ -21,6 +23,7 @@ exports.calculateDaYun = calculateDaYun;
 function calculateDaYun(eightChar, gender, birthYear) {
     const genderInt = gender === 'male' ? 1 : 0;
     const yun = eightChar.getYun(genderInt);
+    const dayStem = eightChar.getDayGan();
     const rawCycles = yun.getDaYun();
     const cycles = [];
     // Index 0 is the natal chart segment — cycles start at index 1
@@ -31,6 +34,7 @@ function calculateDaYun(eightChar, gender, birthYear) {
         const stem = ganZhi.substring(0, 1);
         const branch = ganZhi.substring(1, 2);
         const startYear = dy.getStartYear();
+        const endYear = dy.getEndYear();
         cycles.push({
             index: i,
             stem,
@@ -38,12 +42,26 @@ function calculateDaYun(eightChar, gender, birthYear) {
             ganZhi,
             startYear,
             startAge: startYear - birthYear,
+            endYear,
+            endAge: endYear - birthYear,
+            stemTenGod: (0, tenGods_1.calculateTenGod)(dayStem, stem),
+            branchTenGod: (0, tenGods_1.calculateTenGod)(dayStem, (0, pillars_1.getMainQi)(branch)),
         });
     }
+    const firstCycle = cycles[0];
+    if (!firstCycle)
+        throw new Error('Unable to calculate Da Yun cycles.');
     return {
         cycles,
         isForward: yun.isForward(),
-        startYear: yun.getStartYear(),
-        startAge: yun.getStartYear() - birthYear,
+        startYear: firstCycle.startYear,
+        startAge: firstCycle.startAge,
+        startDate: yun.getStartSolar().toYmdHms(),
+        startOffset: {
+            years: yun.getStartYear(),
+            months: yun.getStartMonth(),
+            days: yun.getStartDay(),
+            hours: yun.getStartHour(),
+        },
     };
 }

package/dist/core/interactions.js

@@ -59,8 +59,16 @@ function hasBranch(branches, target) {
     return branches.find(b => b.branch === target);
 }
 function groupHas(branches, group) {
-    const found = group.map(b => hasBranch(branches, b)).filter(Boolean);
-    return found.length === group.length ? found : null;
+    const remaining = [...branches];
+    const found = [];
+    for (const target of group) {
+        const index = remaining.findIndex(item => item.branch === target);
+        if (index === -1)
+            return null;
+        found.push(remaining[index]);
+        remaining.splice(index, 1);
+    }
+    return found;
 }
 // ── Main Detector ────────────────────────────────────────────────────────────
 /**

package/dist/core/pillars.d.ts

@@ -1,4 +1,4 @@
-import { FourPillars, DayBoundaryMode } from '../types';
+import { FourPillars, DayBoundaryMode, StemInfo } from '../types';
 /** Typed interface for the EightChar object returned by lunar-javascript */
 export interface LunarEightChar {
     setSect(sect: number): void;
@@ -10,6 +10,30 @@ export interface LunarEightChar {
     getDayZhi(): string;
     getTimeGan(): string;
     getTimeZhi(): string;
+    getYearNaYin(): string;
+    getYearShiShenGan(): string;
+    getYearShiShenZhi(): string[];
+    getYearDiShi(): string;
+    getYearXun(): string;
+    getYearXunKong(): string;
+    getMonthNaYin(): string;
+    getMonthShiShenGan(): string;
+    getMonthShiShenZhi(): string[];
+    getMonthDiShi(): string;
+    getMonthXun(): string;
+    getMonthXunKong(): string;
+    getDayNaYin(): string;
+    getDayShiShenGan(): string;
+    getDayShiShenZhi(): string[];
+    getDayDiShi(): string;
+    getDayXun(): string;
+    getDayXunKong(): string;
+    getTimeNaYin(): string;
+    getTimeShiShenGan(): string;
+    getTimeShiShenZhi(): string[];
+    getTimeDiShi(): string;
+    getTimeXun(): string;
+    getTimeXunKong(): string;
     getYun(gender: number): LunarYun;
 }
 /** Typed interface for the Yun (Luck Cycles) manager */
@@ -18,13 +42,20 @@ export interface LunarYun {
     getStartYear(): number;
     getStartMonth(): number;
     getStartDay(): number;
+    getStartHour(): number;
+    getStartSolar(): LunarSolar;
     getDaYun(): LunarDaYun[];
 }
+export interface LunarSolar {
+    toYmdHms(): string;
+}
 /** Typed interface for a single Da Yun period */
 export interface LunarDaYun {
     getGanZhi(): string;
     getStartYear(): number;
     getEndYear(): number;
+    getStartAge(): number;
+    getEndAge(): number;
 }
 export interface PillarResult {
     pillars: FourPillars;
@@ -53,9 +84,4 @@ export declare function getMainQi(branch: string): string;
 /**
  * getStemInfo - Returns enriched stem details
  */
-export declare function getStemInfo(stem: string): {
-    char: string;
-    pinyin: string;
-    element: import("../types").FiveElement;
-    polarity: import("../types").Polarity;
-};
+export declare function getStemInfo(stem: string): StemInfo;

package/dist/core/pillars.js

@@ -8,12 +8,41 @@ exports.getMainQi = getMainQi;
 exports.getStemInfo = getStemInfo;
 const lunar_javascript_1 = require("lunar-javascript");
 const constants_1 = require("../constants");
-function buildPillar(stem, branch) {
-    var _a;
+function getRequiredElement(value, mapping, label) {
+    const result = mapping[value];
+    if (!result)
+        throw new Error(`Unsupported ${label}: ${value}`);
+    return result;
+}
+function getRequiredPolarity(stem) {
+    const polarity = constants_1.STEM_TO_POLARITY[stem];
+    if (!polarity)
+        throw new Error(`Unsupported Heavenly Stem: ${stem}`);
+    return polarity;
+}
+function buildPillar(stem, branch, details) {
+    const hiddenStemDefinitions = constants_1.BRANCH_HIDDEN_STEMS[branch];
+    if (!hiddenStemDefinitions)
+        throw new Error(`Unsupported Earthly Branch: ${branch}`);
     return {
         stem,
         branch,
-        element: (_a = constants_1.STEM_TO_ELEMENT[stem]) !== null && _a !== void 0 ? _a : 'earth',
+        element: getRequiredElement(stem, constants_1.STEM_TO_ELEMENT, 'Heavenly Stem'),
+        ganZhi: `${stem}${branch}`,
+        stemPolarity: getRequiredPolarity(stem),
+        stemTenGod: details.stemTenGod,
+        branchElement: getRequiredElement(branch, constants_1.BRANCH_TO_ELEMENT, 'Earthly Branch'),
+        hiddenStems: hiddenStemDefinitions.map((hiddenStem, index) => ({
+            stem: hiddenStem.stem,
+            element: getRequiredElement(hiddenStem.stem, constants_1.STEM_TO_ELEMENT, 'Hidden Stem'),
+            polarity: getRequiredPolarity(hiddenStem.stem),
+            tenGod: details.hiddenStemTenGods[index],
+            isMain: Boolean(hiddenStem.isMain),
+        })),
+        naYin: details.naYin,
+        xun: details.xun,
+        voidBranches: details.voidBranches.split(''),
+        growthStage: details.growthStage,
     };
 }
 /**
@@ -46,10 +75,38 @@ function generatePillarsFromSolar(year, month, day, hour, minute, second, dayBou
     const dayStem = eightChar.getDayGan();
     return {
         pillars: {
-            year: buildPillar(eightChar.getYearGan(), eightChar.getYearZhi()),
-            month: buildPillar(eightChar.getMonthGan(), eightChar.getMonthZhi()),
-            day: buildPillar(dayStem, eightChar.getDayZhi()),
-            hour: hasTime ? buildPillar(eightChar.getTimeGan(), eightChar.getTimeZhi()) : null,
+            year: buildPillar(eightChar.getYearGan(), eightChar.getYearZhi(), {
+                stemTenGod: eightChar.getYearShiShenGan(),
+                hiddenStemTenGods: eightChar.getYearShiShenZhi(),
+                naYin: eightChar.getYearNaYin(),
+                xun: eightChar.getYearXun(),
+                voidBranches: eightChar.getYearXunKong(),
+                growthStage: eightChar.getYearDiShi(),
+            }),
+            month: buildPillar(eightChar.getMonthGan(), eightChar.getMonthZhi(), {
+                stemTenGod: eightChar.getMonthShiShenGan(),
+                hiddenStemTenGods: eightChar.getMonthShiShenZhi(),
+                naYin: eightChar.getMonthNaYin(),
+                xun: eightChar.getMonthXun(),
+                voidBranches: eightChar.getMonthXunKong(),
+                growthStage: eightChar.getMonthDiShi(),
+            }),
+            day: buildPillar(dayStem, eightChar.getDayZhi(), {
+                stemTenGod: eightChar.getDayShiShenGan(),
+                hiddenStemTenGods: eightChar.getDayShiShenZhi(),
+                naYin: eightChar.getDayNaYin(),
+                xun: eightChar.getDayXun(),
+                voidBranches: eightChar.getDayXunKong(),
+                growthStage: eightChar.getDayDiShi(),
+            }),
+            hour: hasTime ? buildPillar(eightChar.getTimeGan(), eightChar.getTimeZhi(), {
+                stemTenGod: eightChar.getTimeShiShenGan(),
+                hiddenStemTenGods: eightChar.getTimeShiShenZhi(),
+                naYin: eightChar.getTimeNaYin(),
+                xun: eightChar.getTimeXun(),
+                voidBranches: eightChar.getTimeXunKong(),
+                growthStage: eightChar.getTimeDiShi(),
+            }) : null,
         },
         eightChar,
         dayStem,
@@ -68,11 +125,10 @@ function getMainQi(branch) {
  * getStemInfo - Returns enriched stem details
  */
 function getStemInfo(stem) {
-    var _a, _b, _c;
     return {
         char: stem,
-        pinyin: (_a = constants_1.STEM_TO_PINYIN[stem]) !== null && _a !== void 0 ? _a : '',
-        element: (_b = constants_1.STEM_TO_ELEMENT[stem]) !== null && _b !== void 0 ? _b : 'earth',
-        polarity: (_c = constants_1.STEM_TO_POLARITY[stem]) !== null && _c !== void 0 ? _c : 'yang',
+        pinyin: constants_1.STEM_TO_PINYIN[stem],
+        element: getRequiredElement(stem, constants_1.STEM_TO_ELEMENT, 'Heavenly Stem'),
+        polarity: getRequiredPolarity(stem),
     };
 }

package/dist/core/tenGods.d.ts

@@ -0,0 +1,4 @@
+/**
+ * calculateTenGod - Returns the classical Ten God relationship between two stems.
+ */
+export declare function calculateTenGod(dayMaster: string, targetStem: string): string;

package/dist/core/tenGods.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateTenGod = calculateTenGod;
+const constants_1 = require("../constants");
+const ELEMENTS = ['wood', 'fire', 'earth', 'metal', 'water'];
+const TEN_GOD_NAMES = {
+    self: { same: '比肩', different: '劫财' },
+    output: { same: '食神', different: '伤官' },
+    wealth: { same: '偏财', different: '正财' },
+    power: { same: '七杀', different: '正官' },
+    resource: { same: '偏印', different: '正印' },
+};
+function getRelationship(dayMaster, target) {
+    const dayMasterIndex = ELEMENTS.indexOf(dayMaster);
+    const targetIndex = ELEMENTS.indexOf(target);
+    const difference = (targetIndex - dayMasterIndex + ELEMENTS.length) % ELEMENTS.length;
+    if (difference === 0)
+        return 'self';
+    if (difference === 1)
+        return 'output';
+    if (difference === 2)
+        return 'wealth';
+    if (difference === 3)
+        return 'power';
+    return 'resource';
+}
+/**
+ * calculateTenGod - Returns the classical Ten God relationship between two stems.
+ */
+function calculateTenGod(dayMaster, targetStem) {
+    const dayMasterElement = constants_1.STEM_TO_ELEMENT[dayMaster];
+    const targetElement = constants_1.STEM_TO_ELEMENT[targetStem];
+    const dayMasterPolarity = constants_1.STEM_TO_POLARITY[dayMaster];
+    const targetPolarity = constants_1.STEM_TO_POLARITY[targetStem];
+    if (!dayMasterElement || !dayMasterPolarity)
+        throw new Error(`Unsupported Day Master: ${dayMaster}`);
+    if (!targetElement || !targetPolarity)
+        throw new Error(`Unsupported target stem: ${targetStem}`);
+    const relationship = getRelationship(dayMasterElement, targetElement);
+    const names = TEN_GOD_NAMES[relationship];
+    return dayMasterPolarity === targetPolarity ? names.same : names.different;
+}

package/dist/core/validation.d.ts

@@ -0,0 +1,8 @@
+import { BaziInput } from '../types';
+export declare class BaziInputError extends RangeError {
+    constructor(message: string);
+}
+/**
+ * validateBaziInput - Validates the public calculation contract before invoking calendar libraries.
+ */
+export declare function validateBaziInput(input: BaziInput): void;

package/dist/core/validation.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaziInputError = void 0;
+exports.validateBaziInput = validateBaziInput;
+const lunar_javascript_1 = require("lunar-javascript");
+const MIN_YEAR = 1800;
+const MAX_YEAR = 2100;
+class BaziInputError extends RangeError {
+    constructor(message) {
+        super(message);
+        this.name = 'BaziInputError';
+    }
+}
+exports.BaziInputError = BaziInputError;
+function assertIntegerInRange(value, minimum, maximum, field) {
+    if (!Number.isInteger(value) || value < minimum || value > maximum) {
+        throw new BaziInputError(`${field} must be an integer between ${minimum} and ${maximum}.`);
+    }
+}
+function assertNumberInRange(value, minimum, maximum, field) {
+    if (!Number.isFinite(value) || value < minimum || value > maximum) {
+        throw new BaziInputError(`${field} must be between ${minimum} and ${maximum}.`);
+    }
+}
+function assertSolarDate(input) {
+    const date = new Date(Date.UTC(input.year, input.month - 1, input.day));
+    const isSameDate = date.getUTCFullYear() === input.year
+        && date.getUTCMonth() === input.month - 1
+        && date.getUTCDate() === input.day;
+    if (!isSameDate)
+        throw new BaziInputError('The supplied solar date does not exist.');
+    if (input.isLeapMonth)
+        throw new BaziInputError('isLeapMonth is only valid for lunar calendar input.');
+}
+function assertLunarDate(input) {
+    const lunarYear = lunar_javascript_1.LunarYear.fromYear(input.year);
+    const requestedMonth = input.isLeapMonth ? -input.month : input.month;
+    const lunarMonth = lunarYear.getMonth(requestedMonth);
+    if (!lunarMonth) {
+        const label = input.isLeapMonth ? 'leap lunar month' : 'lunar month';
+        throw new BaziInputError(`The supplied ${label} does not exist in ${input.year}.`);
+    }
+    if (input.day > lunarMonth.getDayCount()) {
+        throw new BaziInputError('The supplied lunar date does not exist.');
+    }
+}
+/**
+ * validateBaziInput - Validates the public calculation contract before invoking calendar libraries.
+ */
+function validateBaziInput(input) {
+    var _a, _b;
+    assertIntegerInRange(input.year, MIN_YEAR, MAX_YEAR, 'year');
+    assertIntegerInRange(input.month, 1, 12, 'month');
+    assertIntegerInRange(input.day, 1, 31, 'day');
+    if (input.hour !== undefined)
+        assertIntegerInRange(input.hour, 0, 23, 'hour');
+    if (input.minute !== undefined)
+        assertIntegerInRange(input.minute, 0, 59, 'minute');
+    if (input.minute !== undefined && input.hour === undefined) {
+        throw new BaziInputError('hour is required when minute is supplied.');
+    }
+    if (input.longitude !== undefined)
+        assertNumberInRange(input.longitude, -180, 180, 'longitude');
+    if (input.timezone !== undefined)
+        assertNumberInRange(input.timezone, -14, 14, 'timezone');
+    if (input.dstOffset !== undefined)
+        assertNumberInRange(input.dstOffset, -2, 2, 'dstOffset');
+    if (input.timezoneId !== undefined && input.timezoneId.trim().length === 0) {
+        throw new BaziInputError('timezoneId cannot be empty.');
+    }
+    const trueSolarTimeRequested = ((_a = input.enableTrueSolarTime) !== null && _a !== void 0 ? _a : true)
+        && input.longitude !== undefined
+        && input.hour !== undefined;
+    if (trueSolarTimeRequested && input.timezone === undefined && input.timezoneId === undefined) {
+        throw new BaziInputError('timezone or timezoneId is required for True Solar Time correction.');
+    }
+    if (((_b = input.calendarType) !== null && _b !== void 0 ? _b : 'solar') === 'lunar') {
+        assertLunarDate(input);
+    }
+    else {
+        assertSolarDate(input);
+    }
+}

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export * from './constants';
 export { detectInteractions } from './core/interactions';
 export { generatePillarsFromSolar, getStemInfo, getMainQi } from './core/pillars';
 export { calculateDaYun } from './core/cycles';
+export { calculateTenGod } from './core/tenGods';
+export { BaziInputError, validateBaziInput } from './core/validation';
 /**
  * calculateBaziChart
  *

package/dist/index.js

@@ -17,13 +17,14 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.calculateDaYun = exports.getMainQi = exports.getStemInfo = exports.generatePillarsFromSolar = exports.detectInteractions = void 0;
+exports.validateBaziInput = exports.BaziInputError = exports.calculateTenGod = exports.calculateDaYun = exports.getMainQi = exports.getStemInfo = exports.generatePillarsFromSolar = exports.detectInteractions = void 0;
 exports.calculateBaziChart = calculateBaziChart;
 const true_solar_time_1 = require("@openfate/true-solar-time");
 const lunar_javascript_1 = require("lunar-javascript");
 const pillars_1 = require("./core/pillars");
 const cycles_1 = require("./core/cycles");
 const interactions_1 = require("./core/interactions");
+const validation_1 = require("./core/validation");
 // Re-export all public types and constants
 __exportStar(require("./types"), exports);
 __exportStar(require("./constants"), exports);
@@ -35,6 +36,41 @@ Object.defineProperty(exports, "getStemInfo", { enumerable: true, get: function
 Object.defineProperty(exports, "getMainQi", { enumerable: true, get: function () { return pillars_2.getMainQi; } });
 var cycles_2 = require("./core/cycles");
 Object.defineProperty(exports, "calculateDaYun", { enumerable: true, get: function () { return cycles_2.calculateDaYun; } });
+var tenGods_1 = require("./core/tenGods");
+Object.defineProperty(exports, "calculateTenGod", { enumerable: true, get: function () { return tenGods_1.calculateTenGod; } });
+var validation_2 = require("./core/validation");
+Object.defineProperty(exports, "BaziInputError", { enumerable: true, get: function () { return validation_2.BaziInputError; } });
+Object.defineProperty(exports, "validateBaziInput", { enumerable: true, get: function () { return validation_2.validateBaziInput; } });
+function createDateTime(year, month, day, hour, minute, second) {
+    const hasTime = hour !== undefined;
+    return {
+        year,
+        month,
+        day,
+        hour: hasTime ? hour : null,
+        minute: hasTime ? minute !== null && minute !== void 0 ? minute : 0 : null,
+        second: hasTime ? second !== null && second !== void 0 ? second : 0 : null,
+    };
+}
+function createLunarDateTime(solarDateTime) {
+    const solar = solarDateTime.hour === null
+        ? lunar_javascript_1.Solar.fromYmd(solarDateTime.year, solarDateTime.month, solarDateTime.day)
+        : lunar_javascript_1.Solar.fromYmdHms(solarDateTime.year, solarDateTime.month, solarDateTime.day, solarDateTime.hour, solarDateTime.minute, solarDateTime.second);
+    const lunar = solar.getLunar();
+    const lunarMonth = lunar.getMonth();
+    return {
+        lunar: {
+            year: lunar.getYear(),
+            month: Math.abs(lunarMonth),
+            day: lunar.getDay(),
+            hour: solarDateTime.hour,
+            minute: solarDateTime.minute,
+            second: solarDateTime.second,
+            isLeapMonth: lunarMonth < 0,
+        },
+        zodiac: lunar.getYearShengXiao(),
+    };
+}
 /**
  * calculateBaziChart
  *
@@ -56,7 +92,8 @@ Object.defineProperty(exports, "calculateDaYun", { enumerable: true, get: functi
  * ```
  */
 function calculateBaziChart(input) {
-    var _a, _b, _c, _d, _e, _f;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
+    (0, validation_1.validateBaziInput)(input);
     let solarYear = input.year;
     let solarMonth = input.month;
     let solarDay = input.day;
@@ -64,6 +101,7 @@ function calculateBaziChart(input) {
     let solarMinute = (_a = input.minute) !== null && _a !== void 0 ? _a : 0;
     let solarSecond = 0;
     let solarTimeInfo = null;
+    const inputType = (_b = input.calendarType) !== null && _b !== void 0 ? _b : 'solar';
     // ── 1. Lunar → Solar Calendar Conversion ────────────────────────────────
     if (input.calendarType === 'lunar') {
         // lunar-javascript: negative month represents a leap month
@@ -74,18 +112,31 @@ function calculateBaziChart(input) {
         solarMonth = solar.getMonth();
         solarDay = solar.getDay();
     }
+    const civilSolar = createDateTime(solarYear, solarMonth, solarDay, input.hour, input.hour === undefined ? undefined : solarMinute, input.hour === undefined ? undefined : solarSecond);
     // ── 2. True Solar Time Correction ───────────────────────────────────────
-    const enableTST = ((_b = input.enableTrueSolarTime) !== null && _b !== void 0 ? _b : true) &&
+    const enableTST = ((_c = input.enableTrueSolarTime) !== null && _c !== void 0 ? _c : true) &&
         input.longitude !== undefined && input.longitude !== null &&
         input.hour !== undefined;
     if (enableTST) {
-        const detail = (0, true_solar_time_1.calculateTrueSolarTime)({
-            year: solarYear, month: solarMonth, day: solarDay,
-            hour: solarHour, minute: solarMinute,
-            timeZoneOffset: input.timezone,
-            dstOffset: (_c = input.dstOffset) !== null && _c !== void 0 ? _c : 0,
-            timeZoneId: input.timezoneId,
-        }, {
+        const civilTimeInput = input.timezone !== undefined
+            ? {
+                year: solarYear,
+                month: solarMonth,
+                day: solarDay,
+                hour: solarHour,
+                minute: solarMinute,
+                timeZoneOffset: input.timezone,
+                dstOffset: (_d = input.dstOffset) !== null && _d !== void 0 ? _d : 0,
+            }
+            : {
+                year: solarYear,
+                month: solarMonth,
+                day: solarDay,
+                hour: solarHour,
+                minute: solarMinute,
+                timeZoneId: input.timezoneId,
+            };
+        const detail = (0, true_solar_time_1.calculateTrueSolarTime)(civilTimeInput, {
             longitude: input.longitude,
         });
         const [dateStr, timeStr] = detail.trueSolarDateTime.split(' ');
@@ -101,13 +152,32 @@ function calculateBaziChart(input) {
             trueSolarTime: detail.trueSolarTime.substring(0, 5),
             trueSolarDateTime: detail.trueSolarDateTime,
             solarDate: dateStr,
+            standardMeridian: detail.standardMeridian,
             longitudeCorrectionMinutes: detail.longitudeCorrectionMinutes,
             equationOfTimeMinutes: detail.equationOfTimeMinutes,
             algorithm: detail.algorithm,
         };
     }
+    else if (((_e = input.dstOffset) !== null && _e !== void 0 ? _e : 0) !== 0 && input.hour !== undefined) {
+        // ── 2b. DST normalization without True Solar Time ────────────────────
+        // DST is a civil-clock correction, not a solar-time refinement: a birth
+        // recorded at 15:20 during a DST period (e.g. China 1986–1991 summer,
+        // Taiwan 1946–1961) actually occurred at 14:20 standard time. The TST
+        // path above already subtracts dstOffset inside calculateTrueSolarTime;
+        // when TST is disabled it must still be normalized out here, otherwise
+        // the pillars use the shifted clock hour — a wrong 时辰, and near
+        // midnight a wrong day pillar. Date-based math keeps day/month/year
+        // rollover safe (lunar input was already converted to solar above).
+        const shifted = new Date(Date.UTC(solarYear, solarMonth - 1, solarDay, solarHour, solarMinute));
+        shifted.setUTCMinutes(shifted.getUTCMinutes() - Math.round(((_f = input.dstOffset) !== null && _f !== void 0 ? _f : 0) * 60));
+        solarYear = shifted.getUTCFullYear();
+        solarMonth = shifted.getUTCMonth() + 1;
+        solarDay = shifted.getUTCDate();
+        solarHour = shifted.getUTCHours();
+        solarMinute = shifted.getUTCMinutes();
+    }
     // ── 3. Generate Four Pillars ─────────────────────────────────────────────
-    const { pillars, eightChar, dayStem } = (0, pillars_1.generatePillarsFromSolar)(solarYear, solarMonth, solarDay, solarHour, solarMinute, solarSecond, (_d = input.dayBoundaryMode) !== null && _d !== void 0 ? _d : 'MIDNIGHT_00');
+    const { pillars, eightChar, dayStem } = (0, pillars_1.generatePillarsFromSolar)(solarYear, solarMonth, solarDay, solarHour, solarMinute, solarSecond, (_g = input.dayBoundaryMode) !== null && _g !== void 0 ? _g : 'MIDNIGHT_00');
     // ── 4. Day Master ────────────────────────────────────────────────────────
     const dayMaster = (0, pillars_1.getStemInfo)(dayStem);
     // ── 5. Da Yun Cycles ─────────────────────────────────────────────────────
@@ -117,7 +187,29 @@ function calculateBaziChart(input) {
         year: pillars.year.branch,
         month: pillars.month.branch,
         day: pillars.day.branch,
-        hour: (_f = (_e = pillars.hour) === null || _e === void 0 ? void 0 : _e.branch) !== null && _f !== void 0 ? _f : '',
+        hour: (_j = (_h = pillars.hour) === null || _h === void 0 ? void 0 : _h.branch) !== null && _j !== void 0 ? _j : '',
     });
-    return { pillars, dayMaster, daYun, interactions, solarTimeInfo };
+    const calculationSolar = createDateTime(solarYear, solarMonth, solarDay, input.hour === undefined ? undefined : solarHour, input.hour === undefined ? undefined : solarMinute, input.hour === undefined ? undefined : solarSecond);
+    const lunarCalendar = createLunarDateTime(calculationSolar);
+    return {
+        pillars,
+        dayMaster,
+        daYun,
+        interactions,
+        solarTimeInfo,
+        calendar: {
+            inputType,
+            civilSolar,
+            calculationSolar,
+            lunar: lunarCalendar.lunar,
+            zodiac: lunarCalendar.zodiac,
+        },
+        metadata: {
+            trueSolarTimeApplied: enableTST,
+            dayBoundaryMode: (_k = input.dayBoundaryMode) !== null && _k !== void 0 ? _k : 'MIDNIGHT_00',
+            longitude: (_l = input.longitude) !== null && _l !== void 0 ? _l : null,
+            timezoneBasis: (_o = (_m = input.timezone) !== null && _m !== void 0 ? _m : input.timezoneId) !== null && _o !== void 0 ? _o : null,
+            dstOffset: (_p = input.dstOffset) !== null && _p !== void 0 ? _p : 0,
+        },
+    };
 }

package/dist/types.d.ts

@@ -20,6 +20,22 @@ export interface Pillar {
     stem: string;
     branch: string;
     element: FiveElement;
+    ganZhi: string;
+    stemPolarity: Polarity;
+    stemTenGod: string;
+    branchElement: FiveElement;
+    hiddenStems: HiddenStemInfo[];
+    naYin: string;
+    xun: string;
+    voidBranches: string[];
+    growthStage: string;
+}
+export interface HiddenStemInfo {
+    stem: string;
+    element: FiveElement;
+    polarity: Polarity;
+    tenGod: string;
+    isMain: boolean;
 }
 /** The Four Pillars (四柱) */
 export interface FourPillars {
@@ -36,6 +52,10 @@ export interface DaYunCycle {
     ganZhi: string;
     startYear: number;
     startAge: number;
+    endYear: number;
+    endAge: number;
+    stemTenGod: string;
+    branchTenGod: string;
 }
 /** Da Yun metadata */
 export interface DaYunInfo {
@@ -43,6 +63,13 @@ export interface DaYunInfo {
     isForward: boolean;
     startYear: number;
     startAge: number;
+    startDate: string;
+    startOffset: {
+        years: number;
+        months: number;
+        days: number;
+        hours: number;
+    };
 }
 export type InteractionType = 'CLASH' | 'COMBINATION_2' | 'TRINE' | 'DIRECTIONAL' | 'PUNISHMENT' | 'DESTRUCTION' | 'HARM';
 /** A detected branch interaction */
@@ -57,10 +84,36 @@ export interface SolarTimeInfo {
     trueSolarTime: string;
     trueSolarDateTime: string;
     solarDate: string;
+    standardMeridian: number;
     longitudeCorrectionMinutes: number;
     equationOfTimeMinutes: number;
     algorithm: string;
 }
+export interface CalendarDateTime {
+    year: number;
+    month: number;
+    day: number;
+    hour: number | null;
+    minute: number | null;
+    second: number | null;
+}
+export interface LunarDateTime extends CalendarDateTime {
+    isLeapMonth: boolean;
+}
+export interface CalendarInfo {
+    inputType: 'solar' | 'lunar';
+    civilSolar: CalendarDateTime;
+    calculationSolar: CalendarDateTime;
+    lunar: LunarDateTime;
+    zodiac: string;
+}
+export interface CalculationMetadata {
+    trueSolarTimeApplied: boolean;
+    dayBoundaryMode: DayBoundaryMode;
+    longitude: number | null;
+    timezoneBasis: number | string | null;
+    dstOffset: number;
+}
 /** Full output of calculateBaziChart() */
 export interface BaziChart {
     pillars: FourPillars;
@@ -68,6 +121,8 @@ export interface BaziChart {
     daYun: DaYunInfo;
     interactions: BranchInteraction[];
     solarTimeInfo: SolarTimeInfo | null;
+    calendar: CalendarInfo;
+    metadata: CalculationMetadata;
 }
 export interface BaziInput {
     year: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfate/bazi-engine",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Accurate Four Pillars (八字) chart engine with True Solar Time correction, Da Yun cycles, and interaction detection. Extracted from the OpenFate.ai core engine.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,7 +11,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "tsx --test tests/*.test.ts",
+    "test": "node --import tsx --test tests/*.test.ts",
     "release": "npm version patch && git push --follow-tags",
     "prepublishOnly": "npm run build && npm run test"
   },