DEV Community: Bazi Clarity

Testing a Two-Chart Compatibility Engine Without Inventing Missing Data

Bazi Clarity — Fri, 31 Jul 2026 18:00:23 +0000

A compatibility engine can be deterministic and still be dishonest. The obvious failure is a wrong calculation. The subtler failure is unjustified certainty: turning a blank birth time into noon, allowing a nickname to change a result, or comparing an Hour Branch that was never calculated.

This tutorial describes a test strategy for a two-chart pipeline. The domain example is BaZi, a traditional symbolic framework for reflection. It is not scientifically validated as a prediction method. The fixture below is fictional software test data, not a customer story. Its public evidence repository is brand-owned by Bazi Clarity, so it is implementation evidence—not independent validation or social proof.

The engineering goal is narrow: given two input records, preserve what is known, expose what is unknown, and make every comparison reproducible.

Define the integrity contract before the formula

Start with invariants, not an attractive compatibility percentage. A useful contract for this pipeline is:

calculate Person A and Person B independently;
use birth date, optional time, and resolved place data for each chart;
never infer an Hour Pillar from a missing time;
keep names outside every numeric and symbolic calculation;
compare only stems, branches, and element data that exist;
return observations and reflection prompts, not a verdict.

These rules define which outputs are allowed. They also produce strong negative tests. It is easy to assert that a result contains a Day Master. It is more valuable to assert that it contains no score, no assumed hour, and no relationship guarantee.

Calculate two charts before comparing either one

The safest architecture is a composition of three boundaries:

const leftChart = calculateNatal(normalize(leftInput));
const rightChart = calculateNatal(normalize(rightInput));
const comparison = compareKnownFacts(leftChart, rightChart);

calculateNatal should know nothing about the other person. compareKnownFacts should receive calculated chart objects, not raw form fields. That separation prevents Person A's city, time setting, or display name from leaking into Person B's chart.

A metamorphic test makes this visible: change only the left record and assert that the serialized right chart remains byte-for-byte equal. Then swap the input order and assert that each natal chart still matches its original owner. If either test fails, the comparison layer is contaminating chart construction.

Make unknown time an explicit state

An empty string is too easy to coerce into a convenient default. Represent time precision in the input contract:

const known = { time: "09:30", timePrecision: "exact" };
const unknown = { time: null, timePrecision: "unknown" };

An unknown birth time must produce no Hour Pillar. A compact serialized boundary is { label: "Hour", unknown: true }. It should survive calculation, caching, rendering, export, and later comparison.

The comparison code can filter unavailable pillars before building cross-chart pairs:

const available = (pillars) => pillars.filter((p) => !p.unknown);

for (const left of available(leftChart.pillars)) {
  for (const right of available(rightChart.pillars)) {
    inspectBranchPair(left, right);
  }
}

Test both directions: left time unknown and right time unknown. Also test that an explicitly supplied 12:00 differs from unknown time. Noon may be a real user value; it must never double as a missing-data sentinel.

Prove that names cannot change the result

Names are display metadata, not calculation inputs or compatibility score ingredients. This is best protected with an invariance test rather than a code comment.

Create two requests with identical birth facts and different labels—full name, nickname, Unicode characters, and an empty label. Remove display-only fields from the response and assert deep equality across all variants. Run the same test on both sides of the pair.

Do not hash a whole form object if it contains a name. Build a canonical calculation payload from an allowlist of relevant fields. This keeps cache identity aligned with the actual model and prevents a renamed person from generating a supposedly different chart.

The public model also omits a compatibility percentage. That is a separate contract: assert that score is absent, rather than merely hiding it in the interface.

Treat birthplace as a resolution pipeline

A city label alone is not enough. It should resolve to an IANA time zone plus latitude and longitude. For a supplied clock time, the engine applies the historical UTC offset, calculates the disclosed true solar time correction, and reports a DST flag from offset comparisons. That flag is not a complete classification of every historical civil-time change.

Those values have boundaries. An IANA time zone represents civil-time history, not longitude. Coordinates support the meridian correction, but they do not reveal a missing clock time. The equation-of-time adjustment is date-dependent, and different BaZi schools may choose different solar-time conventions. Version and disclose the chosen profile instead of presenting it as universal.

Tests should include dates on both sides of a DST transition, places with the same zone but different longitudes, and times close to a two-hour branch boundary. A nearby-city change may leave the final pillar unchanged; the test should still prove that the intermediate resolution used the selected coordinates.

Compare only facts that survived calculation

Once both charts exist, the comparison layer can describe a limited set of relationships: the two Day Master elements, each chart's Five Element snapshot, and combinations, clashes, or harms among known branches.

The fictional regression pair uses a known time for Shanghai and an unknown time for New York. The right chart therefore contains Year, Month, and Day Pillars plus an unknown Hour marker. Known branches can still participate in comparisons. The missing right Hour Branch cannot.

That distinction matters when reading an interaction list. An interaction between the known left Hour Branch and the known right Year Branch is allowed. An interaction involving the right Hour position would be fabricated. Assert every returned interaction against the set of available pillar labels for its own side.

Element summaries should also remain separate. Combining two distributions into one relationship grade destroys provenance. Preserve the left and right raw contributions, seasonal weights, rounded percentages, strongest element, and weakest element as two inspectable objects.

Build one fixture that tells a complete story

A useful integration fixture stores the inputs, expected natal charts, expected comparison, method version, and source hashes together. It should be large enough to cross the important boundaries without pretending to be a representative human case.

For the mixed-time fixture, assert at least these facts:

assert.equal(result.leftChart.timeKnown, true);
assert.equal(result.rightChart.timeKnown, false);
assert.deepEqual(result.rightChart.pillars[3], {
  label: "Hour",
  unknown: true,
});
assert.equal("score" in result.comparison, false);
assert.match(result.comparison.confidence.notice, /provided data/i);

Then validate interaction provenance. Each referenced branch must equal the branch stored at the referenced Year, Month, Day, or known Hour position. This catches an easy snapshot-testing blind spot: a list can look stable while silently containing a value derived from a fallback hour.

Hash evidence, but understand what the hash proves

Canonical JSON plus SHA-256 can make silent fixture changes detectable. Sort object keys recursively, serialize the value, and compare its digest with a checked-in manifest. Recorded source hashes are provenance references, not independently reproducible unless the matching source and build procedure are public.

This shows that the package matches its checked-in manifest. Detecting changes relative to a reviewed release also requires an independently retained digest. It does not prove that a traditional interpretation is scientifically true, that every time-zone record is perfect, or that the software covers every BaZi school. Integrity and validity are different claims.

Run the static verifier in a clean checkout. It should recalculate package hashes, confirm the unknown-hour object, reject a score field, and scan for prohibited verdict language. It checks package consistency; it does not rerun the production engine or validate recorded source hashes.

Add negative vectors for input boundaries

Happy-path snapshots are not enough. Reject a city without a time zone, an invalid date, or a location without valid longitude. Treat ambiguous civil time according to an explicit policy. The current engine deliberately downgrades an "exact" flag with empty time to the explicit unknown-time state; test that behavior so it never becomes an invented hour. Rejecting the mismatch would be a versioned contract change.

Property-style tests add useful pressure. Changing names must leave the model unchanged. Repeating identical inputs must produce identical canonical output. Removing a known time may remove Hour-dependent findings but must not add any. No branch interaction may reference an unknown pillar. These relations remain valuable even when the expected Chinese calendar values differ under another disclosed school profile.

Keep interpretation outside the evidence claim

The deterministic layer can prove which inputs and rules produced which chart facts. The text layer may turn those facts into neutral prompts about support, boundaries, or repairing tension. It must not turn software reproducibility into a soulmate label, clinical judgment, or guaranteed outcome.

That boundary belongs in tests and interface copy. A paid or longer explanation can add context, but it cannot create missing birth data. Real-world compatibility still depends on behavior, consent, communication, safety, and circumstances that no natal calculation measures.

Review the published evidence package

The compatibility calculation evidence guide contains the fictional mixed-time vector, manifest, and verifier described here. You can also try the free two-chart comparison without supplying an email; birth time remains optional for either chart.

The durable lesson applies beyond BaZi: missing data is a fact about your data. Model it, preserve it, and test that no later layer upgrades uncertainty into certainty.

Disclosure: AI assistance was used to draft and edit this tutorial. Technical claims and links were checked against the brand-owned evidence package and its static consistency verifier before publication.

Why Birth City Is a Real Calculation Input in BaZi Software

Bazi Clarity — Thu, 30 Jul 2026 06:52:59 +0000

Time zones, daylight-saving rules, longitude, solar terms, and true solar time are not optional details in a transparent calculator.

The city field is part of the calculation

Many online forms ask for a birth city, but the result would be unchanged if you typed a different place. That makes the field decorative rather than meaningful.

In a transparent BaZi calculator, a city field is a computational input. It helps identify the civil time zone that applied at the birthplace, the historical daylight-saving rule for that date, and the location’s longitude. Those details can change the time used to determine a pillar, especially when a birth falls close to an hour or solar-term boundary.

This does not mean that changing a nearby city will always produce a different chart. Often it will not. The important question is whether the location is actually used, whether the correction is disclosed, and whether a boundary-sensitive result can be reproduced.

Civil time, UTC, and history are different layers

A birth certificate normally records local civil time: the clock time recognized by local authorities at that place and date. It is not automatically the same as mean solar time, and it is not useful globally until it can be related to a UTC offset.

That offset is not always the modern offset shown by a phone today. Historical time-zone rules matter. Countries and regions have changed offsets, moved borders, introduced daylight-saving time, suspended it, or used it only in selected years. A calculator that applies the current offset to every historical date can silently shift the underlying timestamp.

A responsible workflow therefore starts with a place, resolves an IANA time zone identifier, applies the rule in force on the stated date, and records the resulting UTC conversion. The calculation should also handle ambiguous or nonexistent clock times around seasonal clock changes. If two instants shared the same clock label, the interface should explain how the ambiguity was resolved rather than quietly choosing one.

No public location database is perfect for every place and era. A responsible service cannot promise universal historical completeness. It can state which database and version it uses, disclose fallback behavior, and flag cases that need extra caution.

Daylight-saving time must follow the date

Daylight-saving time is a historical rule, not a permanent property of a city. “New York is UTC−5” is only a partial statement: the applicable historical UTC offset depends on the date, and past transition dates have not always matched today’s schedule.

The same issue appears in many countries, including places that tried seasonal clock changes briefly and later abandoned them. A checkbox asking the user to remember whether daylight-saving time applied may be better than ignoring the issue, but it still transfers a difficult historical lookup to the person least likely to know the answer.

An auditable calculator should derive the rule from the birthplace and date, show the selected zone and offset, and let the user report a known discrepancy. It should never imply that a city name alone guarantees a perfectly resolved historical record.

Longitude and true solar time require disclosure

Civil time zones cover wide areas, yet the sun does not cross the local meridian at the same clock minute across an entire zone. Longitude provides a correction between a zone’s reference meridian and the birthplace. Some BaZi traditions also apply the equation of time, which reflects the seasonal difference between apparent and mean solar time.

Together, these adjustments are often described as true solar time. They can move a recorded time across a two-hour branch boundary in some cases. However, not every BaZi school or convention applies the same correction. The honest approach is not to present one choice as universally settled; it is to name the convention, show the corrected time, and allow another analyst to reproduce it.

A useful result should display at least the recorded civil time, resolved time zone, UTC offset, location coordinates, any daylight-saving adjustment, the solar-time correction method, and the final time used for the pillars. Without that chain, a polished chart may still be impossible to audit.

Solar terms can affect more than the hour

BaZi year and month pillars are not simply copied from January 1 or the first day of a Gregorian month. Common calculation systems use solar terms as boundaries. A birth near Li Chun or another relevant term may therefore sit on a different side of the year or month boundary than a simple calendar lookup suggests, affecting the year or month pillar.

The boundary has an exact instant, which must be interpreted in the correct local context. A wrong UTC conversion, an ignored daylight-saving rule, or an undocumented solar-time adjustment can place a near-boundary birth on the other side. That is why solar-term boundaries, time-zone history, and location handling belong in one calculation pipeline rather than in separate decorative features.

Most births are not close enough to a boundary for every small correction to change a pillar. Transparency still matters: the system should show the boundary instant and the birth instant it compared, not claim precision while hiding the comparison.

When the birth time is unknown

If the birth time is unknown, the correct response is to preserve that uncertainty. A calculator should build a three-pillar view from the known date and location, omit the Hour Pillar, and label any time-dependent interpretation as unavailable.

Inventing noon, midnight, or a random hour creates false precision. It can affect the hour branch, hidden stems, relationship patterns, and any later interpretation built on them. A time-unknown chart may be less complete, but it is more trustworthy than a four-pillar chart based on a fabricated input.

The interface should also distinguish “unknown” from a blank field accidentally submitted under an “exact time” setting. Those are different states and deserve different validation messages.

A practical calculator checklist

Before relying on a BaZi result, ask:

Does changing the birthplace affect the disclosed time-zone or longitude data?
Is the historical UTC offset shown for the actual birth date?
Is daylight-saving time derived from a dated rule rather than a modern assumption?
Are coordinates and the true-solar-time convention visible?
Are near-boundary solar terms shown with precise comparison times?
Does an unknown time remain unknown, without an invented Hour Pillar?
Can the same inputs reproduce the same pillars and intermediate values?

You can inspect these details in the free chart, read the documented calculation methodology, and review the public calculation-evidence repository. The repository’s evidence vectors are fictional software tests created to check reproducibility and boundary behavior; they are not customer stories or proof of predictive accuracy.

What reproducible calculation can—and cannot—show

A deterministic pipeline can show that the same stated inputs, rules, and data version produce the same calendar result. It can expose where a time-zone correction, solar-term boundary, or unknown input affected the output. That is valuable engineering evidence.

BaZi is not a scientifically validated prediction method. It is a traditional symbolic framework, and interpretations should be treated as reflective material rather than guaranteed forecasts. They are not substitutes for qualified medical, legal, financial, or psychological advice, and they cannot guarantee an outcome.

The strongest standard is therefore twofold: make the calendar calculation reproducible, and keep interpretive claims proportionate. Birth city matters because transparent inputs and visible transformations let a reader understand how a chart was constructed—even when the final symbolic meaning remains a matter of tradition and personal reflection.

Unknown Time Is Not Noon: Modeling Missing Temporal Data Without Inventing Facts

Bazi Clarity — Wed, 29 Jul 2026 15:35:19 +0000

Missing data is not the same thing as a convenient default. That sounds obvious, yet temporal software regularly converts an empty time field into midnight, noon, the current time, or the start of a day. The interface may look complete after that conversion, but the program has silently changed an unknown fact into a known one.

This matters anywhere an hour can change the result: medical timelines, transport schedules, legal deadlines, astronomical calculations, historical records, and calendrical systems. I encountered the problem while working with a BaZi calculation pipeline. A BaZi chart can use year, month, day, and hour components. If the birth time is absent, the honest result is a three-component analysis with hour-dependent conclusions withheld. Inserting noon would make the output look richer while making its provenance weaker.

The useful engineering question is not “Which fallback time should we choose?” It is “How do we keep uncertainty visible through every layer of the system?”

The public calculation evidence repository provides the concrete calendar-domain fixtures referenced below. The rest of this article focuses on the reusable software boundary behind them.

Model knowledge, not just a string

A common input model makes absence too easy to erase:

const birthTime = form.time || "12:00";

After this line runs, downstream code cannot tell whether noon came from the user or the fallback. Validation, analytics, caching, and the result renderer all see the same string. The information loss happens before the calculation begins.

A small discriminated union keeps the two states separate:

/**
 * @typedef {{ kind: "known", localTime: string, source: "user" }}
 *   KnownTime
 * @typedef {{ kind: "unknown" }} UnknownTime
 * @typedef {KnownTime | UnknownTime} BirthTime
 */

function parseBirthTime(value) {
  const normalized = value?.trim();
  return normalized
    ? { kind: "known", localTime: normalized, source: "user" }
    : { kind: "unknown" };
}

This type makes the missing state part of the program's vocabulary. A caller must inspect kind before using localTime. More importantly, the source of a known value remains available for debugging and display.

The same pattern works in TypeScript, Rust enums, database check constraints, JSON Schema, or protocol buffers. The syntax is less important than preserving the distinction between observed and inferred data.

Separate date-level context from hour-level output

Unknown time does not make every calculation impossible. A date and place may still establish civil-date context, time-zone rules, and some date-level boundaries. The mistake is to let an internal helper value escape as if it were supplied by the user.

For example, a pipeline may need a stable instant to ask whether a date lies near a time-zone transition. It can use an internal reference time, provided that reference is labeled and never becomes an hour result:

function buildTemporalContext({ date, city, birthTime }) {
  return {
    date,
    city,
    birthTime,
    dateProbe:
      birthTime.kind === "known"
        ? { localTime: birthTime.localTime, purpose: "user-instant" }
        : { localTime: "12:00", purpose: "date-context-only" },
  };
}

Here noon is not a birth-time fallback. It is a bounded implementation detail used only for date-level context. Naming the purpose prevents a later maintainer from reusing dateProbe.localTime to calculate an hour-dependent field.

Time zones are also data, not a fixed numeric offset. Historical offsets and daylight-saving rules change by place and date. A production system should use a maintained zone identifier and a versioned data source such as the IANA Time Zone Database, while retaining the original city and resolution result for auditability.

Make derived sections conditional by construction

Rendering logic should not ask whether an hour value happens to exist after several transformations. It should receive an explicit capability map from the calculation layer.

function buildCapabilities(birthTime) {
  const hasHour = birthTime.kind === "known";

  return {
    yearAnalysis: true,
    monthAnalysis: true,
    dayAnalysis: true,
    hourPillar: hasHour,
    hourInteractions: hasHour,
    preciseHourTiming: hasHour,
  };
}

function buildHourResult(birthTime) {
  if (birthTime.kind === "unknown") {
    return { unknown: true };
  }

  return calculateHourDependentFields(birthTime.localTime);
}

The serialized boundary for an absent hour is deliberately small:

{ "unknown": true }

That shape is easier to test than a collection of empty strings, zeroes, or placeholder labels. It also stops clients from treating null as a transient loading state. The UI can render a clear explanation: date-level sections are available, while hour-dependent sections require a supplied time.

Conditional output should be structural, not cosmetic. Hiding an invented hour in CSS does not repair a payload that already contains fabricated calculations. The server response, cached artifact, downloadable file, and on-screen result should all share the same boundary.

Preserve uncertainty in cache keys

Caching can reintroduce the bug even when the calculator is correct. Consider two requests with the same date and city: one has an unknown time, and the other contains a user-supplied noon. They must not share an identity.

A canonical cache payload can include the discriminant:

function canonicalInput(input) {
  return {
    date: input.date,
    cityId: input.cityId,
    time:
      input.birthTime.kind === "known"
        ? {
            kind: "known",
            localTime: input.birthTime.localTime,
            source: input.birthTime.source,
          }
        : { kind: "unknown" },
  };
}

Hash the canonical payload rather than a display string. The unknown result can still be cached and restored quickly, but it must restore the same limitations. A fast cache hit is not permission to upgrade uncertainty into precision.

If the user later supplies a time, that is a new input state and should produce a different key. The application may explain that more sections are now available, but it should not imply that the earlier result was wrong; it was correctly bounded by the earlier evidence.

Test the boundary, not the prose

Copy such as “time optional” is useful, but it cannot guarantee behavior. The contract belongs in executable tests that cover parsing, serialization, capabilities, and cache identity.

The following fictional test vector is named shanghai_unknown_time. It represents a software fixture, not a real person or customer:

import assert from "node:assert/strict";

const shanghai_unknown_time = {
  date: "1990-06-15",
  cityId: "Asia/Shanghai",
  birthTime: { kind: "unknown" },
};

const shanghai_known_noon = {
  ...shanghai_unknown_time,
  birthTime: { kind: "known", localTime: "12:00", source: "user" },
};

assert.deepEqual(
  buildHourResult(shanghai_unknown_time.birthTime),
  { unknown: true },
);
assert.equal(
  buildCapabilities(shanghai_unknown_time.birthTime).hourPillar,
  false,
);
assert.notDeepEqual(
  canonicalInput(shanghai_unknown_time),
  canonicalInput(shanghai_known_noon),
);

Additional fixtures should cover blank strings, whitespace, malformed times, daylight-saving transitions, places that changed civil offsets, and dates near domain-specific boundaries. The most important negative assertion is that a missing time never produces an hour-dependent value.

The repository shows this style of fictional vector and boundary documentation in a concrete calendar domain. Its value is reproducibility: a reader can inspect the input, expected behavior, and limitations without relying on a marketing claim.

Explanations are part of the data contract

An unknown result should not look like an error. The system successfully calculated everything justified by the available input. The UI therefore needs three distinct states:

Loading: the calculation has not finished.
Unknown: the calculation finished, but the required fact was not supplied.
Known: the calculation finished with a user-supplied fact.

Collapsing these states into one blank card creates confusion. Users may retry, assume the app is broken, or believe the system inferred something it did not. A concise explanation next to the omitted section is more trustworthy than silently filling the space.

This distinction should also survive exports and APIs. A generated document can say that hour-dependent sections were intentionally omitted. An API can return a typed unknown object. An event log can record time_kind=unknown without storing a fabricated clock value.

A practical review checklist

When reviewing any temporal feature with optional time input, ask:

Can the program distinguish a supplied value from an internal probe?
Does the missing state survive parsing, calculation, caching, rendering, and export?
Are hour-independent and hour-dependent capabilities separated?
Do known noon and unknown time produce different canonical inputs?
Is the unknown state explained without presenting it as a failure?
Can an executable fixture prove that no hour value is invented?

The broader principle is simple: uncertainty is information. Preserve it with the same care as a date, location, or identifier. A result with explicit limits is more useful than a precise-looking result built on a fact nobody supplied.

Disclosure: AI assistance was used to draft and edit this article. The examples, links, and boundary assertions were checked against the referenced repository and executable local tests before publication.