# About `time_compute` -- Why This Crate Exists
`time_compute` is a from-scratch, near-zero-dependency reimplementation of `chrono`'s public API. This document is not about what it does -- see `docs/API_Reference.md` and `docs/Use_Example.md` for that -- but about why it was worth building at all, and what kind of long-term bet it represents.
## Date and time arithmetic is mathematics, not fashion
Most software ages because the world it models keeps changing: business rules change, regulations change, user expectations change, a competitor ships something new and the target moves. A library that has to track a moving domain is, by nature, never really finished -- it has to keep being rewritten to stay true to a reality that keeps shifting under it.
Calendar arithmetic is a rare exception to that pattern. The proleptic Gregorian calendar's leap-year rule, the ISO 8601 definition of a week, the day count between two dates, which weekday a given date falls on -- none of this is a matter of opinion, business strategy, or changing taste. It was fixed by mathematics and international standardization long ago (the Gregorian calendar in 1582, ISO 8601 in 1988), and there is no more reason for it to change tomorrow than for the multiplication table to change. The handful of extensions in this crate that touch real astronomy -- solar terms, lunisolar new moons -- are the same story one level up: they are governed by the Sun and Moon's actual physical positions, computed with the same classical algorithms (Meeus') that have needed no revision in decades. Even the calendars that are more custom or traditional than astronomical -- the Hebrew molad-based reckoning, the Hijri tabular calendar, Matariki's published dates -- are each anchored to one independently verified real date and then reached by pure, deterministic counting from it. None of it is arbitrary, and none of it is expected to move.
This changes what "maintenance" actually means for a crate like this one. In most software, needing maintenance means the requirements drifted and the old code no longer describes reality. Here, once a function has been proven correct -- checked against a published festival table, an astronomical reference, an independent reference implementation -- it stays correct forever, because there is no requirements drift to chase in the first place: there are no requirements beyond the underlying mathematics itself. What actually remains to maintain is a narrower, far more mechanical problem: keeping the code compiling and idiomatic as the Rust language and its tooling evolve (new editions, deprecated idioms, MSRV bumps), and keeping the crate's small set of dependencies current. That is a fundamentally easier, more boring kind of maintenance than tracking a moving domain -- and in software, boring is a compliment.
## A deliberately small dependency surface
`time_compute` is built around a default of zero dependencies, with a small, individually named and justified set of exceptions -- see `docs/About_dependencies.md` for the exact scope of each one. `tzdb`/`tz-rs` exist because the real, historical UTC-offset rules of the world's time zones are administrative facts no formula can derive; `astro` exists because a handful of genuinely astronomical functions need real physics, not calendar arithmetic. Everything else -- the entire chrono-compatible core, and the great majority of the calendar extensions -- has no dependency at all.
This is not just an aesthetic preference for a short `Cargo.lock`. Every dependency is a second codebase whose own bugs, breaking changes, security advisories, and abandonment risk become this crate's problem too, whether or not the crate's own logic ever changes. Fewer dependencies means fewer things that can break the crate for reasons that have nothing to do with whether its own math is right.
## Room to grow: contributors, and a different era of maintenance
`time_compute` has no outside contributors today, but there is no good reason to assume it never will, and the crate is deliberately shaped for that possibility. Every calendar extension lives in its own, largely self-contained module (Hebrew, Hijri, Chinese, Thai/Buddhist, Japanese, Matariki each have their own file), every function's tests sit immediately below the code they test rather than in a separate integration tree, and every non-obvious result is checked against a named, external authority rather than against the author's own judgment. A newcomer does not need to understand the whole crate to safely improve one calendar's corner of it, and does not have to take anyone's word for whether a change is correct -- the ground truth is external and checkable by anyone who looks.
That last point matters more today than it would have a few years ago. A meaningful share of the maintenance work on any piece of software -- reviewing a change, tracking a regression, porting code across a language edition -- is increasingly done with the help of an AI, and that changes what makes a codebase easy to maintain well. An AI reviewing a change to a business-rules engine has to somehow absorb years of undocumented tribal context, because the rules themselves are a human decision, not a derivation -- there is no way to check a proposed change is "right" except by asking whoever remembers why the rule was written that way. An AI reviewing a change to a calendar function does not need any of that: the correct answer is derivable from the calendar's own definition, or checkable against an external table, whether or not anyone ever wrote down the history. A closed, well-defined mathematical domain, with a small dependency graph and tests that already encode the ground truth, is close to the ideal shape of a codebase for this newer mode of maintenance -- not because the domain is simple, but because it is *settled*: there is a real, checkable right answer, and it will not move out from under whoever -- human or AI -- goes looking for it next.
## Chrono-compatible, chrono-free
`time_compute` deliberately mirrors `chrono`'s public API: the same type names, the same method names and signatures, the same behavior, so that migrating an existing project is, in the overwhelming majority of cases, a matter of changing `use chrono::...` to `use time_compute::...` and nothing else. Proving that the same surface could be rebuilt on a fundamentally different foundation, without breaking anyone who already depends on it, was the entire point of the exercise.
But "compatible with" is not "built from." `time_compute` contains no `chrono` source code, copied or adapted -- every algorithm in it, from the core calendar/day-count conversion to formatting and parsing to every calendar extension, was implemented from its own primary sources: the underlying mathematics, published standards, astronomical algorithms, and independent reference implementations, not from reading `chrono`'s own code. During development, a now-removed, dev-only diagnostic tool ran `time_compute` and the real `chrono` crate side by side purely to compare their *output* and catch behavioral divergences before release (see `docs/About_testing.md`) -- treating `chrono` strictly as an external, black-box oracle to check against, never as a source to copy from. `chrono` was never a dependency of the published library, in any configuration (see `docs/About_dependencies.md`). The two crates arrive at the same answers because they are both correctly solving the same well-defined mathematical problem, not because one copies the other.
## Is `time_compute` more maintainable than `chrono`? An opinion
Structurally, I think the case is real, not just marketing -- but it deserves an honest, not a one-sided, answer. `chrono` is a mature, excellent, and far more battle-tested library, hardened over years by a large user base surfacing real-world edge cases this crate simply has not had the chance to encounter yet. That kind of accumulated real-world exposure is a genuine form of correctness, and it should not be waved away.
But maintainability is a different question from current correctness, and on maintainability specifically, several concrete factors favor a small, young, deliberately narrow crate like this one -- especially under an AI-assisted maintenance model: a much smaller dependency graph to audit and keep current; a single, explicit, uniformly applied naming convention (`_opt` fallible constructors, `checked_*` arithmetic) rather than several eras of API idiom accumulated over a decade; every test living next to the code it exercises rather than in a separate tree; and a running project convention of writing down *why* a decision was made, in the code and in documents like this one, instead of leaving it to be reconstructed later from a changelog or an old issue thread. Those are exactly the properties that let an outside reviewer -- an AI included -- verify a change is safe without first absorbing years of accumulated context.
My honest opinion: `time_compute` is not, today, more *correct* than `chrono` -- it hasn't earned that yet, and won't until it has been used and battle-tested at anything like `chrono`'s scale. But it is arguably easier to *keep* correct, because so much less of what could go wrong is hidden inside a dependency, an unwritten convention, or years of undocumented history. For a domain this settled, that is the trade worth making.
## Why use `time_compute`
Put together, the case for this crate is not "it does more than `chrono`" -- for the frozen, chrono-compatible core, it deliberately does exactly the same, no more and no less. The case is a different set of guarantees: a drop-in-compatible API backed by an independently written and independently verified implementation; a wider representable date range than `chrono`'s own; a near-zero dependency footprint with every exception individually named, scoped, and justified; a substantial set of calendar and festival extensions with no `chrono` equivalent at all -- Christian movable feasts, the Hebrew and Hijri calendars, the Japanese era system and its festivals, the Chinese lunisolar calendar, the Thai/Buddhist calendar, Matariki -- each checked against its own external authority; 492 unit tests, none of them decorative; and a codebase, and a set of project documents (this one included), written so that the reasoning behind every non-obvious decision survives past the person who made it. That, in the end, is the actual point of all of the above.