Architecture and Astronomical Reference Model of the Quizzman Lunisolar Calendar System

Abstract

Background / Context: Eastern lunisolar calendar systems and traditional civil chronometry demand computational integration between modern celestial mechanics and intricate historical-cultural conventions. In distributed computational systems, discrepancies in local civil day boundaries, dynamical time projections, and planetary theories frequently cause critical discrepancies, such as shifted new moon days, misaligned solar terms, and corrupted sexagenary cycles.
Methodology: This paper comprehensively specifies the system architecture of the @quizzman/qm-calendar computational engine (version 1.2.0). The engine integrates a high-precision celestial reduction pipeline: international continuous Julian Date conversion, apparent solar ecliptic longitude approximations via the VSOP87 planetary theory (129-term abridged series per Jean Meeus), analytical astronomical new moon solutions per Meeus (Chapter 49), a 5-year continuous linear blending model for $\Delta T$, and UTC-instant solvers for the 24 solar terms projected onto local civil days. Concurrently, the engine standardizes True Solar Time (TST) reductions with the Equation of Time (EoT), early rat and late rat (Dạ Tý / Chính Tý) midnight transition boundaries, the 60 Sexagenary Cycle, the Twelve Day Officers (Thập Nhị Trực) governed by solar term branch invariants, the Twenty-Eight Mansions (Nhị Thập Bát Tú) anchored to a fixed Julian Day Number epoch, and historical timezone lookup tables covering Vietnam's eight historical eras.
Results: Systematic algorithmic audits identified and resolved nine core boundary defects (A01 through A09). The verified engine achieved a 100% pass rate (139/139) on the independent benchmark suite, passed 834 boundary test vectors, and completed an exhaustive 146,462-day continuous bi-directional roundtrip test from the year 1800 to 2200 with zero discrepancies. Solar longitude verification against the United States Naval Observatory (USNO) 2024 cardinal points yielded absolute errors $|\Delta\lambda_\odot| < 0.0005^\circ$, and new moon instances matched NASA ephemerides within 0.1 minutes.
Conclusion: The @quizzman/qm-calendar system establishes a verifiable, reproducible mathematical framework serving as the canonical executable source of truth for lunisolar calendrical science and associated enterprise computational services.

1 Scope

This document specifies the architectural framework, mathematical models, and normative rules of the Quizzman lunisolar calendar computation system (@quizzman/qm-calendar), covering:

1. Time-scale representations and continuous conversions to Julian Day Number (JDN) and Julian Date (JD).
2. Celestial mechanics pipelines: VSOP87 planetary theory reductions, astronomical new moon determination, the Equation of Time (EoT), and dynamical time ($\Delta T$) secular acceleration blending.
3. Lunisolar month assignment, leap month (intercalation) determination based on the No Major Term Rule, and analytical divergence mechanisms between Vietnam (UTC+07:00) and China (UTC+08:00) civil calendars.
4. Mathematical formulations of traditional East Asian civil cycles: the Sexagenary Cycle (Can Chi year, month, day, hour), Early Rat and Late Rat midnight conventions, the Twelve Day Officers, and the Twenty-Eight Mansions.
5. True Solar Time (TST) reductions and effective date rollover (effectiveJdn) propagation across metaphysical charts (Four Pillars / Bát Tự).
6. Reduction models for the eight historical timezone eras of Vietnam from pre-1906 to post-1975.
7. Algorithmic audit findings, root-cause analyses, and formal resolutions for the nine systemic boundary defects (A01 through A09).

The scope encompasses all calendar services, astronomical toolchains, and chronological data engines within the Quizzman ecosystem.

2 Normative references

The following referenced documents are indispensable for the application of this standard:

• ISO 8601-1:2019 ^[1], Date and time — Representations for information interchange — Part 1: Basic rules.
• ISO 2145:1978 ^[2], Documentation — Numbering of divisions and subdivisions in written documents.
• ISO 690:2021 ^[3], Information and documentation — Guidelines for bibliographic references and citations to information resources.
• Jean Meeus (1998) ^[4], Astronomical Algorithms, 2nd Edition, Willmann-Bell, Richmond, Virginia.
• P. Bretagnon, G. Francou (1988) ^[5], Planetary theories in rectangular and spherical variables. VSOP87 solutions, Astronomy and Astrophysics, Vol. 202, pp. 309–315.
• E. M. Standish (1998) ^[6], JPL Planetary and Lunar Ephemerides, DE405/LE405, JPL Interoffice Memorandum 312.F.
• R. S. Park et al. (2021) ^[7], The JPL Planetary and Lunar Ephemerides DE440 and DE441, The Astronomical Journal, Vol. 161, No. 3.
• J. Chapront, G. Francou (2003) ^[8], The lunar theory ELP/MPP02, Astronomy and Astrophysics, Vol. 404, pp. 735–742.
• F. Espenak, J. Meeus (2006) ^[9], Five Millennium Catalog of Solar Eclipses: -1999 to +3000, NASA TP-2006-214141.
• Hồ Ngọc Đức (2000) ^[10], Lunisolar Calendar Calculations and Vietnamese Standard Meridian, Leipzig University.
• IANA Time Zone Database (2026a) ^[11], Time Zone Database, Internet Assigned Numbers Authority.
• USNO & HMNAO (2023) ^[12], The Astronomical Almanac for the Year 2024, Washington: US Government Publishing Office.
• Hong Kong Observatory (2024) ^[13], Gregorian-Lunar Calendar Conversion Tables of the Hong Kong Observatory (1901–2100).
• Doãn Lộc, Mai Giác Thành (1741) ^[14], Khâm Định Hiệp Kỷ Biện Phương Thư (欽定協紀辨方書), Siku Quanshu Vol. 807.
• Quách Thủ Kính, Vương Tuần (1281) ^[15], Thọ Thời Lịch (授時曆), History of Yuan Vols. 52–55.
• Lê Quý Đôn (1777) ^[16], Vân Đài Loại Ngữ (芸臺類語), Vol. 1: Ngôn tạo khảo.
• Quizzman Technical Reference (2026) ^[17], Quizzman Lunisolar Calendar Engine Technical Reference and Architecture v2.1.
• Quizzman Quality Group (2026) ^[18], Quizzman Calendar Engine Algorithm Audit and Fix Verification Report, Technical Dossier AUD-2026-CAL-02.

3 Terms and definitions

For the purposes of this document, the following terms and definitions apply:

3.1 civil day

Continuous duration spanning 86,400 seconds on a local civil time scale, measured from 00:00:00 to 24:00:00.

3.2 astronomical new moon

Astronomical instant when the geocentric apparent ecliptic longitudes of the Moon and Sun are identical (relative longitude equals $0^\circ$), historically designated in East Asian calendrical science as Sóc.

3.3 major solar term

Central solar term (Trung khí / Zhongqi), corresponding to instants when the apparent ecliptic longitude of the Sun reaches integer multiples of $30^\circ$ ($\lambda_\odot = 0^\circ, 30^\circ, 60^\circ, \dots, 330^\circ$).

3.4 minor solar term

Intermediate solar term (Tiết khí / Jieqi), corresponding to instants when the apparent ecliptic longitude of the Sun reaches odd multiples of $15^\circ$ ($\lambda_\odot = 15^\circ, 45^\circ, 75^\circ, \dots, 345^\circ$).

3.5 true solar time

Time measured directly by the hour angle of the apparent Sun at a specific geographical meridian, equivalent to local mean solar time adjusted by the Equation of Time (EoT).

3.6 early rat and late rat

Conventions governing the two-hour Rat branch period (23:00 to 01:00). Early Rat (Dạ Tý, 23:00–23:59) retains the current civil day; Late Rat (Chính Tý, 00:00–00:59) transitions to the subsequent civil day.

4 Symbols and abbreviated terms

• $Y, M, D$: Year, month, day in the Gregorian civil calendar.
• $\text{JDN}$: Julian Day Number, integer day counter starting from Greenwich noon on January 1, 4713 BCE (proleptic Julian calendar).
• $\text{JD}$: Julian Date, continuous real-valued time measure including day fractions.
• $\text{UT}$ / $\text{UTC}$: Universal Time / Coordinated Universal Time.
• $\text{TT}$: Terrestrial Time (uniform dynamical time), satisfying $\text{TT} = \text{UT} + \Delta T$.
• $\Delta T$: Difference between Terrestrial Time and Universal Time ($\text{TT} - \text{UT1}$), accounting for Earth's rotational deceleration.
• $\tau$: Time in Julian millennia ($10,000$ Julian years of $365.25$ days) measured from the epoch J2000.0.
• $T$: Time in Julian centuries ($36,525$ days) measured from the epoch J2000.0.
• $\lambda_\odot$: Apparent geocentric ecliptic longitude of the Sun.
• $\text{EoT}$: Equation of Time, difference between apparent solar time and mean solar time.
• $\text{LMT}$: Local Mean Time.
• $\text{TST}$: True Solar Time.

5 Conventions and assumptions

1. Internal Master Time Axis: All core storage and computational transactions in the Quizzman architecture SHALL be represented in UTC.
2. Standard Meridian of Vietnam: The standard national lunisolar calendar of Vietnam is computed with respect to the $105^\circ\text{E}$ meridian, corresponding to fixed UTC+07:00 (except for historical eras governed by Section 10).
3. Epoch J2000.0: The instant 12:00:00 TT on January 1, 2000 corresponds to $\text{JDN} = 2451545$ and $\text{JD} = 2451545.0$.
4. Continuous Conversion Offset: Midnight (00:00:00 UTC) on a date with integer index $\text{JDN}$ corresponds to continuous date $\text{JD} = \text{JDN} - 0.5$.

6 Architectural framework of the calendar engine

The @quizzman/qm-calendar computation system is organized into four decoupled architectural layers:

┌────────────────────────────────────────────────────────────────────────┐
│                        API & Application Layer                         │
│   solarToLunar, lunarToSolar, getHourCanChi, getDayCanChi, Almanac     │
├────────────────────────────────────────────────────────────────────────┤
│                       Calendar & Domain Layer                          │
│   Sóc (New Moon), Tiết Khí (Solar Terms), Nhuận, Can Chi, Trực, Tú     │
├────────────────────────────────────────────────────────────────────────┤
│                       Astronomy & Ephemeris Layer                      │
│   VSOP87 Sun Longitude, Meeus Ch.49 New Moon, Delta T Blend, EoT       │
├────────────────────────────────────────────────────────────────────────┤
│                       Time Base & Coordinate Layer                     │
│   Continuous Julian Date, Timezone Reductions, Geodetic Coordinates    │
└────────────────────────────────────────────────────────────────────────┘

The principal data pipeline processes an input civil date as follows:

1. Ingest $(Y, M, D)$ and local time; determine governing legal timezone offset based on geographic location and epoch.
2. Convert to integer $\text{JDN}$ and continuous $\text{JD}$ on the UTC scale.
3. Reduce to Terrestrial Time ($\text{TT} = \text{UT} + \Delta T$).
4. Compute solar coordinates via VSOP87 and solve astronomical new moon instants via Meeus Chapter 49 series.
5. Project new moon instants onto local civil day intervals $[00:00:00, 24:00:00)$ to establish lunisolar month boundaries.
6. Evaluate the 24 solar terms across the astronomical year (Winter Solstice to Winter Solstice) to determine leap month placement (No Major Term Rule).
7. Assemble output aggregates: lunar year, month, day, sexagenary pillars, element melodies (Nạp Âm), Day Officers, Mansions, and auspiciousness indicators.

7 Astronomical foundation and coordinate reduction

7.1 Continuous Julian Date conversion

Conversion from Gregorian civil date to integer Julian Day Number follows standard astronomical formulations:

$$\text{JDN} = 367Y - \left\lfloor \frac{7(Y + \lfloor (M+9)/12 \rfloor)}{4} \right\rfloor + \left\lfloor \frac{275M}{9} \right\rfloor + D + 1,721,013.5$$

Because $\text{JDN}$ is an integer anchored at noon (12:00:00 UTC), converting a continuous time instant to continuous $\text{JD}$ requires subtracting half a day:

$$\text{JD} = \text{JDN} + \frac{\text{hour} + \frac{\text{minute}}{60} + \frac{\text{second}}{3600}}{24} - 0.5$$

At 00:00:00 UTC, $\text{JD} = \text{JDN} - 0.5$; at 12:00:00 UTC, $\text{JD} = \text{JDN}$. This formulation prevents spurious half-day offsets in astronomical benchmarks (see Section 11.4).

7.2 Planetary reduction via VSOP87 theory

The engine employs the VSOP87 analytical planetary theory (Meeus 129-term abridged series) to compute the heliocentric ecliptic longitude of Earth, from which the geocentric coordinates of the Sun are derived. The time parameter $\tau$ denotes Julian millennia from J2000.0:

$$\tau = \frac{\text{JD} - 2451545.0}{365250}$$

Heliocentric longitude $L$ (radians) is evaluated through a power series:

$$L = \frac{L_0 + L_1\tau + L_2\tau^2 + L_3\tau^3 + L_4\tau^4 + L_5\tau^5}{10^8}$$

Each component $L_k$ is a harmonic series of periodic terms:

$$L_k = \sum_{i=1}^{N_k} A_i \cos(B_i + C_i \tau)$$

The distribution of harmonic terms across series orders is:

• $L_0$: 64 terms (fundamental Earth–Sun Keplerian orbit).
• $L_1$: 34 terms (annual periodic perturbations).
• $L_2$: 20 terms (secular perturbations).
• $L_3$: 7 terms (millennial corrections).
• $L_4$: 3 terms (long-period perturbations).
• $L_5$: 1 term (higher-order secular linear rate).

The apparent geocentric solar longitude $\lambda_\odot$ is obtained by adding $180^\circ$ and applying aberration and nutation corrections:

$$\lambda_\odot = L_{\text{heliocentric}} + 180^\circ - 0.00569^\circ - 0.00478^\circ \sin(\Omega)$$

where $\Omega = 125.04^\circ - 1934.136^\circ T$ represents the longitude of the ascending node of the Moon's orbit.

7.3 Dynamical time reduction and continuous Delta T blending

To convert between observed Universal Time (UT) and Terrestrial Time (TT), the system employs historical empirical tables for 1620–2025. To eliminate the $4.467\text{ s}$ discontinuity between the empirical table boundary ($70.000\text{ s}$ at 2025.0) and polynomial approximations ($74.467\text{ s}$ at 2025.000001), Quizzman implements a 5-year linear blend across $[2025, 2030]$:

$$w = \frac{y - 2025}{5}, \quad y \in [2025, 2030]$$

$$\Delta T(y) = (1 - w) \times 70.0 + w \times P(y)$$

where $P(y)$ is the Stephenson–Morrison polynomial. This ensures $C^0$ continuity of the time axis across the boundary era.

7.4 Astronomical New Moon determination

Astronomical new moon instants are solved via Jean Meeus (Chapter 49). The synodic month index $k$ relative to epoch 1900.0 is:

$$k = \lfloor (Y - 1900) \times 12.3685 \rfloor$$

The mean new moon instant is computed as:

$$\text{JD}_{\text{mean}} = 2415020.75933 + 29.53058868k + 0.0001178T^2 - 0.000000155T^3 + 0.00033 \sin(166.56^\circ + 132.87^\circ T - 0.009173^\circ T^2)$$

Fourteen major periodic perturbation terms $C_1$ (functions of solar mean anomaly $M$, lunar mean anomaly $M'$, and lunar argument of latitude $F$) are aggregated to produce the true astronomical new moon instant:

$$\text{JD}$${\text{soc}} = \text{JD}{\text{mean}} + C_1 - \frac{\Delta T}{86400}

8 Lunisolar calendar calculation algorithms

8.1 Assignment of lunar months and civil folding

A civil day in a timezone with offset $Z$ starts at local midnight. To determine the first day (mồng 1) of a lunar month, the engine computes the local civil day of the astronomical new moon:

$$D_{\text{soc}} = \left\lfloor \text{JD}_{\text{soc}} + 0.5 + \frac{Z}{24} \right\rfloor$$

All civil days $D$ satisfying $D \in [D_{\text{soc}, i}, D_{\text{soc}, i+1})$ belong to lunar month $i$, with lunar day index $d = D - D_{\text{soc}, i} + 1$.

8.2 Divergence mechanism between Vietnam and China lunisolar dates

Vietnam observes UTC+07:00 ($Z=7$), whereas China observes UTC+08:00 ($Z=8$). When an astronomical new moon occurs between 16:00 and 17:00 UTC:

• In Vietnam: Local time is $23:\text{xx}$ on day $D$. The new moon day falls on day $D$.
• In China: Local time is $00:\text{xx}$ on day $D+1$. The new moon day falls on day $D+1$.

Consequently, Lunar New Year (Tết) in Vietnam can occur one civil day earlier than in China. Historical examples include:

• Tết Mậu Thân 1968: The new moon occurred at 16:29 UTC on January 29, 1968. Vietnam celebrated Tết on January 29 (1st day of 1st lunar month), while China celebrated on January 30 (30th day of 12th lunar month).
• 1984–1985 Divergence: A new moon in November 1984 near the timezone boundary placed lunar month 11 in Vietnam on November 23, 1984, whereas China inserted a leap month 10. This one-month divergence persisted into early 1985.

8.3 Leap month determination rule

The engine strictly implements the traditional astronomical rule codified in the Shoushi Calendar ^[15]:

1. A lunar year containing 13 months between two consecutive Winter Solstices is a leap year.
2. The first lunar month after Winter Solstice that does not contain a Major Solar Term (Zhongqi) SHALL be designated as the leap month.

Because Major Solar Terms occur at exact $30^\circ$ solar longitude intervals, the precision of the VSOP87 model is decisive in resolving borderline intercalary months.

9 Metaphysical and civil almanac mathematical models

9.1 Sexagenary cycle (Can Chi) closed-form congruences

The 60 Sexagenary Cycle is mathematically isomorphic to the ring $\mathbb{Z}${10} \times \mathbb{Z}{12}.

1. Day Pillar (Can Chi Ngày): Given continuous integer Julian Day Number $\text{JDN}$: $$I_{\text{can}} = (\text{JDN} + 9) \pmod{10}$$ $$I_{\text{chi}} = (\text{JDN} + 1) \pmod{12}$$ Epoch J2000.0 Check: $\text{JDN} = 2451545 \rightarrow I_{\text{can}} = 4$ (Mậu / Yang Earth), $I_{\text{chi}} = 6$ (Ngọ / Horse) $\rightarrow$ Mậu Ngọ day.

2. Hour Pillar & Early/Late Rat Conventions: The Heavenly Stem of the Rat hour is derived from the Day Stem via the traditional "Five Rats" algorithm: $$I_{\text{rat_stem}} = (2 \times I_{\text{can}} + 1) \pmod{10}$$

   • When earlyRat = true (Early Rat, 23:00–23:59): The hour stem is evaluated with respect to the current day stem.
   • When earlyRat = false (Late Rat, 00:00–00:59): The hour stem is evaluated with respect to the subsequent day stem.

9.2 True Solar Time and effective date rollover

True Solar Time ($\text{TST}$) corrects for geographical longitude and Earth's orbital eccentricity:

$$\text{TST} = \text{Clock Time} + (\lambda_{\text{local}} - \lambda_{\text{std}}) \times 4\text{ min/deg} + \text{EoT}$$

The standard legal meridian of Vietnam is $\lambda_{\text{std}} = 105^\circ\text{E}$ ($7 \times 15^\circ$). Using an incorrect reference meridian (e.g. $110^\circ\text{E}$) introduces a $20\text{ minute}$ systematic bias, corrupting the hour branch.

When $\text{TST}$ shifts across midnight ($< 00:00$ or $\ge 24:00$), the engine computes effectiveLocalDateTime and effectiveJdn. All downstream metaphysical calculations (lunar date, day pillar, hour pillar, solar term month) must evaluate against effectiveJdn.

9.3 Twelve Day Officers (Thập Nhị Trực)

The 12 Day Officers (Jian, Chu, Man, Ping, Ding, Zhi, Po, Wei, Cheng, Shou, Kai, Bi) cycle based on the relationship between the day branch and the solar month branch ^[14]:

$$I_{\text{officer}} = (I_{\text{chi}} - I_{\text{term_branch}} + 12) \pmod{12}$$

Solar month branches are strictly demarcated by solar terms: the month beginning with Lichun carries the Tiger branch ($I=2$), and Liqiu carries the Monkey branch ($I=8$). Civil Gregorian or lunar month numbers MUST NOT be used as inputs.

9.4 Twenty-Eight Mansions (Nhị Thập Bát Tú)

The 28 Mansions constitute an independent modulus-28 sequence over $\text{JDN}$. The system anchors this sequence to January 1, 1995 (Sunday, Xu / Hư Mansion, index 10), corresponding to $\text{JDN} = 2449719$:

$$I_{\text{mansion}} = (\text{JDN} - 2449719 + 10) \pmod{28}$$

If negative, add 28 to normalize into $[0, 27]$.

10 Historical timezone reduction and civil boundaries

Quizzman encodes the eight official historical timezone eras of Vietnam per the IANA Time Zone Database (Asia/Ho_Chi_Minh) ^[11]:

Historical Chronology Impact: Between 1960 and 1975, South Vietnam observed UTC+08:00 while North Vietnam observed UTC+07:00 from 1968. A total of 270 days exhibited lunisolar divergences between the two regions, validated across the corpus. Notably, on February 1, 1965, North Vietnam observed the 1st day of Lunar New Year (Ất Tỵ), while South Vietnam observed the 30th day of the 12th lunar month (Giáp Thìn).

11 Algorithmic audit findings and formal resolution

A comprehensive 2026 algorithmic audit ^[18] identified and resolved nine architectural defects:

11.1 A01: Civil day boundary of 24 Solar Terms

• Defect: Legacy logic compared solar longitudes between consecutive noons (noon-to-noon window), causing solar terms occurring in the afternoon to shift into the subsequent day (12 of 24 terms in 2024 were shifted by one day).
• Resolution: Implemented getSolarTermTransitionsForYear solver to compute exact UTC transition instants, subsequently projected onto local civil day bounds $[00:00:00, 24:00:00)$.

11.2 A02: Inconsistency between solar term month branch and displayed solar terms

• Defect: Solar month branches evaluated solar longitude at 12:00 UTC on JDN, while displayed terms utilized legacy noon boundaries.
• Resolution: Unified a single source of truth getSolarTermTransitionsForYear across solar terms, month branches, and Day Officers.

11.3 A03: True Solar Time effective date rollover propagation

• Defect: When TST shifted across midnight, flags were raised without updating jdn, leaving Bát Tự day and hour pillars evaluated on the stale calendar date.
• Resolution: Propagated effectiveLocalDateTime and effectiveJdn across all astrological modules.

11.4 A04: Julian Date epoch offset in NASA benchmarks

• Defect: Benchmarks added UTC fractional hours directly to jdFromDate(Y, M, D) (already noon-anchored) without subtracting $0.5$ days, creating an artificial $\approx 0.5^\circ$ error.
• Resolution: Applied canonical utcDateTimeToJulianDate(). Solar longitude errors against USNO reduced to $|\Delta\lambda_\odot| < 0.0005^\circ$.

11.5 A05: Auspicious date selection interface contract

• Defect: Design specifications described a multi-factor Thần Sát scoring engine, while the actual public API implemented a deterministic purpose-rule resolver.
• Resolution: Updated contract documentation clarifying the public API as an auditable rule resolver, with Thần Sát data provided as informative metadata.

11.6 A06: Delta T step discontinuity at epoch 2025

• Defect: Empirical lookup ended at 2025 with $70.0\text{ s}$, while Stephenson–Morrison polynomials began at $74.467\text{ s}$, creating a $4.467\text{ s}$ discontinuity.
• Resolution: Implemented a 5-year linear blend across $[2025, 2030]$.

11.7 A07: Lunar month length boundary validation

• Defect: Lunar-to-solar conversions accepted day 30 in short 29-day lunar months, causing Gregorian dates to overflow into subsequent lunar months.
• Resolution: Added strict boundary guard: $1 \le d \le (D_{\text{soc}, i+1} - D_{\text{soc}, i})$.

11.8 A08: Test oracle alignment for Southern Vietnam 1975 timezone transition

• Defect: Legacy tests expected South Vietnam to transition to UTC+07:00 on May 1, 1975, conflicting with the June 13, 1975 decree and IANA tzdb.
• Resolution: Corrected test oracle to 00:00 on June 13, 1975.

11.9 A09: Prevention of out-of-range new moon indices producing lunar day zero

• Defect: Mean new moon estimation algorithms occasionally selected a future new moon, causing lunar day numbers to evaluate to zero.
• Resolution: Constrained search algorithm to select the latest new moon strictly on or before the current civil day.

12 Empirical validation and benchmark results

The engine underwent verification across four testing tiers:

12.1 USNO 2024 Cardinal Points Parity

Solar longitudes calculated by the engine's abridged VSOP87 theory were verified against official USNO publications for the 2024 equinoxes and solstices ^[12]:

| Event | UTC Instant | Expected $\lambda_\odot$ | Engine $\lambda_\odot$ | Absolute Error $|\Delta\lambda_\odot|$ | |---|---|---|---|---| | Vernal Equinox 2024 | 2024-03-20 03:06:00Z | $0.0^\circ$ | $359.999602^\circ$ | $0.000398^\circ$ | | Summer Solstice 2024 | 2024-06-20 20:51:00Z | $90.0^\circ$ | $90.000051^\circ$ | $0.000051^\circ$ | | Autumnal Equinox 2024 | 2024-09-22 12:43:00Z | $180.0^\circ$ | $179.999585^\circ$ | $0.000415^\circ$ | | Winter Solstice 2024 | 2024-12-21 09:20:00Z | $270.0^\circ$ | $269.999788^\circ$ | $0.000212^\circ$ |

All test points satisfy the stringent accuracy constraint $|\Delta\lambda_\odot| < 0.0005^\circ$ ($1.8''$).

12.2 NASA New Moon Parity

For the astronomical new moon on January 11, 2024, NASA records the minimum geocentric conjunction at 11:57 UTC. The Quizzman engine computes 11:56:56 UTC, exhibiting a deviation of only $0.07\text{ minutes}$ (well within the $2.0\text{ minute}$ tolerance).

12.3 Golden Date Verification: September 1, 2026 (Vietnam Civil Time)

Comprehensive multi-layer cross-check for the reference date September 1, 2026 (UTC+07:00):

12.4 Exhaustive Bi-directional Roundtrip

An exhaustive regression suite swept continuously through every civil day from January 1, 1800 to December 31, 2200 (146,462 days). Each day was converted from Solar to Lunar (solarToLunar) and immediately inverted back (lunarToSolar).

• Evaluated civil days: 146,462.
• Perfect roundtrip matches: 146,462 (100% rate).
• Errors and discrepancies: 0.

12.5 AI Hallucination in Benchmark Construction

During initial benchmark construction, a Large Language Model (Google Gemini) was employed to draft 12 edge cases. Seven cases failed initial validation. Root-cause analysis demonstrated that all seven failures stemmed from LLM hallucinations:

1. Assigned an incorrect Gregorian date to Tết Mậu Thân 1968 (generated February 16 instead of January 29).
2. Fabricated non-existent lunar divergences across the entire year 1972.
3. Conflated Lunar New Year 1984 with the onset of the November 1984 divergence.
4. Generated flawed predictions regarding the controversial intercalary year 2033.
5. Assumed a fictitious $110^\circ\text{E}$ meridian instead of standard $105^\circ\text{E}$ for Ho Chi Minh City.
6. Computed corrupted day branches for March 24, 2026 (guessed Đinh Tỵ instead of Đinh Dậu) and March 25, 2026 (guessed Mậu Ngọ instead of Mậu Tuất).

Core engineering conclusion: Calendrical and celestial reductions require deterministic analytical arithmetic and cannot rely on probabilistic language models.

13 Limitations

The @quizzman/qm-calendar engine exhibits the following engineering boundaries:

1. Optimal Chronological Range: The abridged VSOP87 model and $\Delta T$ tables achieve certified accuracy between years 1800 and 2200. Beyond this window, accumulated $\Delta T$ uncertainty may affect new moons occurring within seconds of midnight.
2. Analytical Lunar Theory: The engine currently utilizes Meeus Chapter 49. Upcoming roadmap phases will incorporate ELP/MPP02 and JPL DE440 ephemerides to deliver sub-second precision across multi-millennium spans.
3. Pre-1967 Northern Vietnam Almanac: Applying practical UTC+08:00 (Purple Mountain Observatory tables) reflects historical printing practices and does not represent an official retrospective civil timezone decree.

14 Conclusion

This specification codifies the technical architecture of the @quizzman/qm-calendar engine in strict adherence to the Quizzman Paper Standard (QPS-ISO 1.0). By resolving nine core boundary defects, standardizing continuous time conversion, and passing 146,462 continuous roundtrip days alongside USNO and NASA benchmarks, the engine provides an authoritative, reproducible foundation for contemporary calendrical computation.

Bibliography

[1] International Organization for Standardization. ISO 8601-1:2019 Date and time — Representations for information interchange — Part 1: Basic rules. Geneva: ISO, 2019.
[2] International Organization for Standardization. ISO 2145:1978 Documentation — Numbering of divisions and subdivisions in written documents. Geneva: ISO, 1978.
[3] International Organization for Standardization. ISO 690:2021 Information and documentation — Guidelines for bibliographic references and citations to information resources. Geneva: ISO, 2021.
[4] Jean Meeus. Astronomical Algorithms. 2nd edition. Richmond: Willmann-Bell, Inc., 1998.
[5] Pierre Bretagnon, Gérard Francou. Planetary theories in rectangular and spherical variables. VSOP87 solutions. Astronomy and Astrophysics, 1988, vol. 202, pp. 309–315.
[6] E. Myles Standish. JPL Planetary and Lunar Ephemerides, DE405/LE405. JPL Interoffice Memorandum 312.F, 1998.
[7] Ryan S. Park, William M. Folkner, James G. Williams, Dale H. Boggs. The JPL Planetary and Lunar Ephemerides DE440 and DE441. The Astronomical Journal, 2021, vol. 161, no. 3, p. 105.
[8] Jean Chapront, Gérard Francou. The lunar theory ELP/MPP02. Astronomy and Astrophysics, 2003, vol. 404, no. 2, pp. 735–742.
[9] Fred Espenak, Jean Meeus. Five Millennium Catalog of Solar Eclipses: -1999 to +3000. NASA Technical Publication TP-2006-214141, 2006.
[10] Hồ Ngọc Đức. Lunisolar Calendar Calculations and Vietnamese Standard Meridian. Leipzig University Technical Report, 2000.
[11] Internet Assigned Numbers Authority. Time Zone Database (tzdb), version 2026a, 2026.
[12] United States Naval Observatory, Her Majesty's Nautical Almanac Office. The Astronomical Almanac for the Year 2024. Washington: U.S. Government Publishing Office, 2023.
[13] Hong Kong Observatory. Gregorian-Lunar Calendar Conversion Tables of the Hong Kong Observatory (1901–2100). Hong Kong SAR Government, 2024.
[14] Doãn Lộc, Mai Giác Thành. Khâm Định Hiệp Kỷ Biện Phương Thư (欽定協紀辨方書). Beijing: Qianlong 6th year, 1741.
[15] Quách Thủ Kính, Vương Tuần. Thọ Thời Lịch (授時曆). Dadu: Yuan Dynasty, 1281.
[16] Lê Quý Đôn. Vân Đài Loại Ngữ (芸臺類語) — Vol. 1: Ngôn tạo khảo. Thăng Long, 1777.
[17] Quizzman Research & Engineering Team. Quizzman Lunisolar Calendar Engine Technical Reference and Architecture v2.1. Quizzman Engineering Reports, 2026.
[18] Quizzman Research & Quality Assurance Group. Quizzman Calendar Engine Algorithm Audit and Fix Verification Report. Technical Audit Dossier AUD-2026-CAL-02, 2026.

Annex A (normative) Algorithmic Specifications and Core Functions

This section specifies reference implementations of core computational functions in the @quizzman/qm-calendar engine:

A.1 Continuous time conversion to Julian Date

export function utcDateTimeToJulianDate(
  year: number,
  month: number,
  day: number,
  hour: number = 0,
  minute: number = 0,
  second: number = 0
): number {
  const a = Math.floor((14 - month) / 12);
  const y = year + 4800 - a;
  const m = month + 12 * a - 3;
  const jdn =
    day +
    Math.floor((153 * m + 2) / 5) +
    365 * y +
    Math.floor(y / 4) -
    Math.floor(y / 100) +
    Math.floor(y / 400) -
    32045;
  const dayFraction = (hour + minute / 60 + second / 3600) / 24;
  return jdn + dayFraction - 0.5;
}

A.2 Standardized Twelve Day Officers algorithm

export function getDayOfficer(
  dayBranchIndex: number,
  solarMonthBranchIndex: number
): { index: number; name: string } {
  const OFFICERS = [
    'Kiến', 'Trừ', 'Mãn', 'Bình', 'Định', 'Chấp',
    'Phá', 'Nguy', 'Thành', 'Thu', 'Khai', 'Bế'
  ];
  const index = (dayBranchIndex - solarMonthBranchIndex + 12) % 12;
  return {
    index,
    name: OFFICERS[index]
  };
}

A.3 Julian Day Number anchored Twenty-Eight Mansions algorithm

export function getMansion(jdn: number): { index: number; name: string } {
  const MANSHIONS_EPOCH_JDN = 2449719; // 1995-01-01 (Sunday) = Xu Mansion (index 10)
  const MANSION_NAMES = [
    'Giác', 'Cang', 'Đê', 'Phòng', 'Tâm', 'Vĩ', 'Cơ',
    'Đẩu', 'Ngưu', 'Nữ', 'Hư', 'Nguy', 'Thất', 'Bích',
    'Khuê', 'Lâu', 'Vị', 'Mão', 'Tất', 'Chủy', 'Sâm',
    'Tỉnh', 'Quỷ', 'Liễu', 'Tinh', 'Trương', 'Dực', 'Chẩn'
  ];
  let index = (jdn - MANSHIONS_EPOCH_JDN + 10) % 28;
  if (index < 0) index += 28;
  return {
    index,
    name: MANSION_NAMES[index]
  };
}

Annex B (informative) Historical Timezone Decrees of Vietnam

Chronological register of legal instruments governing civil time in Vietnam:

1. Governor-General Decree of May 18, 1906: Mandated the time of meridian $105^\circ\text{E}$ (UTC+07:00) across the Indochinese Union, effective 00:00 on July 1, 1906.
2. Decree of December 23, 1942: Advanced Indochina time by 60 minutes to UTC+08:00, effective 23:00 on December 31, 1942.
3. Japanese Military Command Order of March 14, 1945: Enforced Tokyo time (UTC+09:00) across Indochina, effective March 15, 1945.
4. Decree No. 46-SL of October 12, 1945 by the Provisional Government of the Democratic Republic of Vietnam: Re-established official time at meridian $105^\circ\text{E}$ (UTC+07:00).
5. Decree No. 362-CAB/MI of September 4, 1959 by the Republic of Vietnam Presidency: Advanced South Vietnam time from UTC+07:00 to UTC+08:00, effective 23:00 on December 31, 1959.
6. Decision No. 121-CP of August 8, 1967 by the Council of Government of the DRV: Promulgated calendar calculation rules and standardized on Time Zone 7 (UTC+07:00), effective January 1, 1968.
7. Saigon–Gia Dinh Military Management Committee Communique: Retarded South Vietnam time by 60 minutes from UTC+08:00 to UTC+07:00, effective 00:00 on June 13, 1975, completing national civil time unification.