DEV Community: Hyunbin Kim

A calendar library returned the same answer for every year — and my tests agreed with it

Hyunbin Kim — Tue, 01 Sep 2026 11:04:49 +0000

I build a Korean saju (BaZi) service. The whole pitch is that the numbers are computed deterministically and only the prose is written by a model, so the calculation layer is the one part that is not allowed to be vaguely right.

Two days ago I found out it had been wrong for five years of birthdays, and that my test suite had been cheerfully confirming it the entire time.

What the function was supposed to do

A saju chart's year and month pillars do not change on January 1st. They change at solar terms — the 24 points where the sun reaches a fixed ecliptic longitude. The year pillar turns at 입춘 (315°), which lands somewhere around February 4th, at a specific minute that differs every year, because the Earth's orbit does not care about our calendar.

So if you are born on February 4th, whether your chart says 癸卯 or 甲辰 depends on what time of day you were born, compared against an astronomical instant.

I was getting those instants from a calendar library:

const terms = getSolarTermsByYear(year)

The symptom

An agent working on unrelated copy flagged a contradiction: a FAQ page claimed minute-level solar term precision, while a comment in the engine said the data only covered 2020–2030. I went to check which one was lying.

I dumped 입춘 for eleven consecutive years and diffed it against an independent astronomical computation:

        library          computed (KST)
2024    Feb 4, 05:02     Feb 4, 17:26
2025    Feb 4, 05:02     Feb 3, 23:10
2026    Feb 4, 05:02     Feb 4, 05:01
2027    Feb 4, 05:02     Feb 4, 10:46

Eleven years, one value. The function took a year argument and ignored it. It happened to be right for 2026 — presumably whenever the table was generated — and wrong for everything else, sometimes by twelve hours, sometimes landing on the wrong day.

Twelve hours is not a rounding error here. It is the difference between two different charts:

2024-02-04 06:00  →  癸卯 乙丑   (before 17:26)
2024-02-04 18:00  →  甲辰 丙寅   (after)

Same date. Opposite answer. Anyone born on a solar term day between 2020 and 2030 — except 2026 — could have been handed the wrong one.

Now the part that actually bothered me

I have a golden test suite. Solar term boundaries are the first thing it locks. It was green the whole time.

Here is the shape of what it asserted:

// probes chosen around the "known" boundary of 05:02
assert.equal(chartFor('2024-02-04', '04:00').year, '癸卯')
assert.equal(chartFor('2024-02-04', '05:03').year, '甲辰')

Both of those passed. Of course they did. The engine read the boundary from the library, and the fixture values were written by reading the boundary from the library. My test and my code shared a single source of truth, so the test could only ever confirm the library's opinion — never reality.

That is the bug class, and it has nothing to do with calendars. A test is only an oracle if it knows something the code does not. The moment your expected values are derived from the same dependency the code under test calls, the assertion degrades into a change detector: it will tell you when behavior changes, and it will never tell you the behavior was wrong to begin with.

The second failure was subtler. Every probe I had chosen — 04:00, 05:01, 05:03 — sat on the same side of the real boundary at 17:26. So even a test written against real-world truth would have passed with the wrong table, because my examples all fell into one bucket. Example-based tests cannot see a parameter being ignored unless the examples straddle something.

The test that would have caught it

One property, no domain knowledge required:

test('different years produce different solar term instants', () => {
  const seen = new Set<string>()
  for (let y = 2020; y <= 2030; y++) {
    const t = solarTermsOfYear(y).find((x) => x.name === '입춘')!
    seen.add(`${t.month}-${t.day} ${t.hour}:${t.minute}`)
  }
  assert.equal(seen.size, 11)   // the old table produced 1
})

It asserts a relationship rather than a value: this function's output must vary with its argument. It would have failed on day one, in a single line, without me knowing a single thing about astronomy.

I now think of this as the cheapest test you can write against any parameterized lookup — tables, caches, config resolvers, i18n bundles, feature flags, per-tenant settings. Anything with the shape f(key) => data deserves one assertion that says f actually reads key. It is the class of bug that produces confident, plausible, uniformly wrong output, which is the worst kind to ship.

The fix

I stopped looking the values up and started computing them. astronomy-engine was already a dependency for something else, and solar terms are just a root-find on solar longitude:

// 입춘 = the moment the sun reaches 315° ecliptic longitude.
// Search from 15 days before the nominal date, over a 30-day window:
// wider than the ~15-day gap between terms, narrower than the next crossing.
const start = MakeTime(new Date(Date.UTC(year, 1, 4 - 15)))
const t = SearchSunLongitude(315, start, 30)

Twenty-four terms per year, 1900–2050, cached per year, returned as both wall-clock and absolute instant. The library stayed for what it is good at — sexagenary cycle and lunar/solar date conversion — and lost the job it was silently failing.

Then the golden test got re-anchored to the real boundary, with probes at 17:25 and 17:28 instead of on one side of a fiction, plus the variance property above.

Three things I would do differently, and will next time:

Cross-check a dependency against an independent implementation before trusting it as an oracle. Not continuously — once, at adoption, on a spread of inputs. It took twenty minutes and would have saved five years of charts.
Choose probes that straddle the boundary you are testing, computed from the truth, not from the code. If your fixtures come out of the system under test, you have written a snapshot, not a test.
Assert variance on anything parameterized. One line. Do it before the interesting assertions.

Housekeeping, since someone will ask

Charts already generated are stored as payloads and are not silently recomputed — a saved reading stays what it was when it was issued, and we regenerate on request if a birth date falls in the affected window. Rewriting people's charts underneath them without telling them seemed worse than the bug.

The calendar engine is open source as k-saju (MIT, TypeScript). The astronomical version is published — v0.1.3 and up; 0.1.0 has the stale table, so upgrade if you installed it early. The corrected engine is live in the product at ioreum.com/en.

I am deliberately not naming the library. I have not filed an issue yet, and honestly the interesting part is not that a table went stale. It is that I built a test suite around it that was structurally incapable of noticing.

Rendering CJK-heavy share cards with satori (and the three things that broke)

Hyunbin Kim — Sun, 30 Aug 2026 06:01:40 +0000

I run a small Korean saju (Four Pillars) reading service. Every reading ends with a share card — a PNG with the person's day pillar in Chinese characters, a hand-drawn animal, and a one-line epithet in Korean or English. We also generate 60 Pinterest pins and Open Graph images for a few hundred dictionary pages the same way.

All of it is rendered with satori through Next.js's ImageResponse. Satori is wonderful: you write JSX, you get a PNG, no headless browser. It is also a very specific subset of HTML/CSS, and CJK text hits the edges of that subset faster than Latin text does. Here is what broke, in the order it broke.

1. Your font does not have the glyph, and satori will not tell you

The brand font is a Korean handwriting face. It covers Hangul and Latin. It does not cover the hanja (Chinese characters) that a saju chart is made of — 甲子, 丙寅, and so on. Rendered with only that font, every pillar came out as tofu boxes.

Satori resolves glyphs per character across the fonts you pass, in order. So the fix is not "find one font with everything" — it is "pass a fallback set, most specific first":

// og-fonts.ts — module-cached; the TTFs are 2 MB each and this runs per request
let cached: Promise<{ son: Buffer; han: Buffer }> | null = null;

function loadHandFonts() {
  cached ??= (async () => {
    const [son, han] = await Promise.all([
      fs.readFile(path.join(process.cwd(), 'src/assets/fonts/OreumSon.ttf')), // Hangul + Latin
      fs.readFile(path.join(process.cwd(), 'src/assets/fonts/OreumHan.ttf')), // hanja
    ]);
    return { son, han };
  })();
  return cached;
}

export async function handFontOptions() {
  const { son, han } = await loadHandFonts();
  return [
    { name: 'OreumSon', data: son, style: 'normal' as const, weight: 400 as const },
    { name: 'OreumHan', data: han, style: 'normal' as const, weight: 400 as const },
  ];
}

and in the element tree, fontFamily: 'OreumSon, OreumHan'. Hangul and Latin come from the first face, hanja fall through to the second. This is exactly the unicode-range trick you would do in CSS @font-face — satori just makes you do it with the font array.

Two things worth knowing:

Satori wants TTF/OTF, not woff2. Our web fonts are woff2 for the browser; we keep TTF copies in src/assets/fonts just for image routes.
Use a literal path.join(process.cwd(), '...'). Vercel's output file tracing follows the literal string and bundles the font with the function. Build the path dynamically and the file is not there at runtime.

2. There is no `mask-image`, and there is no CSS file

Our light/dark theme in the browser is done with icon masks: an SVG alpha mask, colored with background-color, so one asset serves both themes. Satori does not support mask-image (or filter, or backdrop-filter). It also does not read your stylesheet — every value must be inline in the JSX.

So the image routes do not share the site's CSS at all. They carry a tiny token mirror instead:

// tokens mirrored from oreum.css — light theme only
const T = {
  paper: '#fdfbf3',
  ink: '#221d16',
  seal: '#b1402b',
  faded: '#8a8166',
  muted: 'rgba(34, 29, 22, 0.5)',
} as const;

And the cards are light-only. Partly because masks are unavailable, partly because the places these images land (Pinterest feeds, link previews) are light backgrounds anyway. Accept the constraint; do not fight it with tricks.

For the animal art, we pre-render each of the twelve zodiac animals as a PNG with ink strokes baked in and inline it as a data URI:

const artCache = new Map<string, string | null>();

async function loadAnimal(file: string): Promise<string | null> {
  if (!artCache.has(file)) {
    try {
      const buf = await fs.readFile(path.join(process.cwd(), 'src/assets/card-animals', file));
      artCache.set(file, `data:image/png;base64,${buf.toString('base64')}`);
    } catch {
      artCache.set(file, null); // the pin must still render without the art
    }
  }
  return artCache.get(file) ?? null;
}

Note the null branch. An image route that 500s because an optional asset is missing takes your whole Open Graph preview down with it.

3. Every multi-child `div` needs `display: flex`

This one is documented, and I still hit it three times. Satori's layout engine is Yoga; a <div> with more than one child must declare display: 'flex' or you get a runtime error, not a fallback. It is easy to forget on the inner wrappers — the outer card is obviously flex, the little row that holds "element · stage · seated god" is not obviously anything, and that is the one that throws.

My rule now: every div in an image route gets display: 'flex' unless it has exactly one text child. span is for text only.

What the CJK detail actually changes

The hanja are the payload. A day pillar is two characters — showing them big, in the correct face, is the entire point of the card. If they render as boxes the card is decoration; if they render in a calligraphic face next to a handwriting Latin face, it reads as one object. The font fallback array is a five-line change and it is the difference between the two.

Sizes, for reference: the 2:3 Pinterest pin is 1000×1500 with the pillar at 116px and the hanja block at 210px; the 1200×630 OG card puts the two characters at 150px on the left and the title at 72px. Both come out around 50–160 KB as PNG.

The rendering code runs on a deterministic table — every one of the 60 pins is computed from the same data the dictionary pages use, so the pin can't disagree with the page. That part is not a satori trick; it is just refusing to hand-write sixty descriptions.

If you want to see the output: the 60 day-pillar pins live at ioreum.com/en/day-master, and the calendar math underneath is open source as k-saju (MIT, TypeScript).

Your LLM cannot compute a birth chart (and it won't tell you)

Hyunbin Kim — Sun, 30 Aug 2026 03:40:10 +0000

There is a genre of prompt going around: paste your birth date and time into a chatbot and ask for your Korean saju (or Chinese BaZi) chart — the four pillars, the day master, the whole thing. The answers read beautifully. They are also, structurally, guesses.

I run a saju reading service, so I care about this for selfish reasons. But the failure mode is interesting on its own, because it is the quiet kind.

What a chart actually requires

A Four Pillars chart is not text. It is the output of a calendar function:

Map the birth instant onto the sexagenary cycle — a 60-step cycle of stem–branch pairs that has been ticking continuously for centuries. The day pillar is literally "which of the 60 is today", counted from a known epoch.
Decide the year and month pillars from the 24 solar terms, which are astronomical instants (the sun reaching a given ecliptic longitude), not calendar dates. The year does not turn on January 1 or on lunar new year; it turns at 입춘 (ipchun) — in 2024 that was February 4, 16:27 KST.
Correct the hour pillar for true solar time — Korea keeps time on 135°E, Seoul sits near 127°E, so civil noon and solar noon differ by ~32 minutes before you add the equation of time.
Apply the late-night hour convention (23:00 belongs to the next day for the hour stem, under one common school).

Every one of these is exact arithmetic on instants. None of it is something you can approximate from having read a lot of astrology text.

Why a language model gets it wrong in a specific way

A general LLM does not run a sexagenary counter. It predicts what a chart usually looks like for a date that looks like yours. That works surprisingly often for the easy 95% of dates — the model has seen enough tables. It breaks at the boundaries, which are exactly the cases where a chart is decided:

born on the morning of ipchun → it hands you the new year's pillar when you are still in the old one;
born at 23:31 → it does not know which school's convention it silently picked;
born abroad → it compares your local date to a Korean solar-term date, when the term is a single global instant.

And here is the part that matters: it will not say "I'm not sure." The output has the same confident register whether the day pillar is right or off by one. There is no error term. A calculator that is wrong looks exactly like a calculator that is right, until you check it against an almanac.

You can test this yourself. Ask any chatbot for the four pillars of 2024-02-04 04:00, Seoul, then run:

npx k-saju 2024-02-04 04:00
# year 癸卯 — still the old year pillar, because 04:00 < 16:27

Then try 2000-05-15 23:31 and 2000-05-05 09:30 --lon 124.7. The boundary cases are where the two answers diverge.

The architecture that follows from this

If the numbers must be exact and the prose can be fluent, the two jobs should not live in the same component. Our split:

A deterministic engine computes the chart — solar terms stored as instants, sexagenary counting, true-solar-time correction, the hour convention written down rather than implied. It is a pure TypeScript module with golden tests for every boundary above. The calendar core is open source as k-saju (MIT).
An LLM writes the reading — and only the reading. It receives the computed facts as input and produces prose. It is not allowed to introduce a pillar, a stem, or a number that is not in its input; a sanitizer drops any section that does.

The model is the writer, not the calculator. That sentence is the whole design.

The same split, exposed as tools

Since chat assistants are where people are asking these questions, we put the calculator where the questions are: an MCP server (ioreum.com/api/mcp) that ChatGPT and Claude can call as tools. Four of them:

tool	returns
`calculate_saju`	the four pillars, elements, day master, hidden stems — computed
`luck_pillars`	the ten-year cycles with start ages
`check_zodiac_year`	which zodiac year a date falls in, with the ipchun boundary handled
`day_master_character`	reference entry for any of the sixty day pillars

The server instructions are explicit that the tools return calculated facts and that written interpretation lives elsewhere — so the assistant has no reason to invent a reading in the chart's voice. Setup is one URL; details at ioreum.com/en/connector.

What I am not claiming

I am not claiming the interpretation of a chart is verifiable. It is not; it is a tradition, and reasonable schools disagree. The claim is narrower: the calculation is verifiable, so it should be done by something that can be verified — and a language model is the one component in the stack that cannot be.

If you build anything on top of traditional calendars — Chinese, Korean, Hindu panchang, anything with astronomical boundaries — the same rule applies. Compute first. Let the model write.

Why every BaZi calculator disagrees with the almanac

Hyunbin Kim — Tue, 25 Aug 2026 12:02:44 +0000

Every Four Pillars calculator — saju in Korea, BaZi in China — agrees on the easy 95% of the job. Feed it a birth date and it maps that instant onto a traditional calendar: four pillars, each a heavenly stem paired with an earthly branch.

The remaining 5% is boundaries. And at the boundaries, nearly all of them quietly disagree with the printed almanac they claim to reproduce.

I maintain a saju reading service, and getting these four cases right was most of the actual engineering. Here they are, with the failing inputs.

1. A solar term is an instant, not a date

The year pillar does not turn on January 1, and not on lunar new year either. It turns at 입춘 (ipchun, "start of spring") — one of the 24 solar terms, defined by the sun's apparent longitude. In 2024 that moment was February 4, 17:27 KST.

A calculator that applies solar terms at day granularity says "February 4 → new year pillar" and hands the wrong year to everyone born that morning.

npx k-saju 2024-02-04 04:00
# year 癸卯 — still the old year pillar, because 04:00 < 16:27

The fix is unglamorous: store term boundaries as instants and compare instants. The subtlety is that this correction applies to the year and month pillars only — the day pillar runs on its own sexagenary count and must not be touched.

2. The 23:00 hour belongs to two days at once

Traditional practice starts the day at 23:00, not midnight — the hour of the Rat (자시). So for a birth at 23:31, there are two defensible answers about which day's stem the hour pillar derives from, and schools split on it.

The convention this engine declares: the day pillar keeps clock midnight, while the hour stem takes the next day's stem (the 야자시 rule).

npx k-saju 2000-05-15 23:31
# day 癸酉, hour 甲子

I am not claiming this is the One True Rule. I am claiming it should be written down. Most tools pick a side in silence, which is how two calculators give one person two charts and neither can explain why.

3. The clock is not the sun

Korea keeps time on the 135°E meridian. Seoul sits near 127°E. That is about 32 minutes of difference between civil noon and solar noon — before you add the equation of time, which swings solar noon by up to ~16 minutes across the year.

Hour pillars are two-hour buckets. A half-hour error puts a birth in the wrong bucket often enough to matter.

npx k-saju 2000-05-05 09:30 --lon 124.7   # hour 丙辰
npx k-saju 2000-05-05 09:30               # hour 丁巳  (Seoul default)

Same wall clock, different hour pillar, purely from longitude.

4. Foreign births need absolute time

This one bites hardest. A solar term is an astronomical instant, global. If someone is born in New York on February 3 at 16:00, that is already February 4 in Korea — and possibly already past the term.

npx k-saju 2024-02-03 16:00 --place new-york
# year 甲辰 — the new year pillar, on a local date of "Feb 3"

Compare local dates against KST term dates and you get this backwards. Convert both to absolute time and compare instants, and it falls out correctly.

Testing claims instead of asserting them

All four examples above are golden tests. The README table's example commands are the test inputs, so a claim that drifts from the code fails CI rather than sitting there being wrong.

That matters more than usual in this domain, because "accuracy" claims here normally hide two things: which school's conventions were chosen, and where the dataset runs out. Mine, stated openly: minute-exact term instants cover 2020–2030 (dataset range) and degrade to day granularity outside it; luck-pillar start ages use day-granular boundaries and can differ from a paper almanac by ±1 year.

What is deliberately missing

Interpretation. The library turns a birth instant into symbolic coordinates and stops.

I think that split is the honest one. The calendar math is verifiable — you can check it against an almanac and I can hand you a test suite. What those eight characters mean is not verifiable, and blending the two is how this whole genre earned its reputation. (My commercial product, ioreum, does write readings — with an LLM that is structurally forbidden from touching a number.)

The engine is MIT: https://github.com/bunhine0452/k-saju

npx k-saju 1995-03-16 07:30

If you have ever tried to reconcile two calculators at 2 a.m., issue #1 — extending minute-exact solar terms to 1900–2050 astronomically — is open and genuinely fun.