tibetan-calendar-temporal 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,6 +4,12 @@ Compute Tibetan calendar dates in JavaScript — leap months, doubled and skippe
4
4
  year names and observances — for almanac applications, practice calendars, and anything that has to
5
5
  show a Tibetan date and be right about it.
6
6
 
7
+ It computes two calendars: **Phugpa**, the Men-Tsee-Khang standard and the basis of the almanacs most
8
+ Tibetans use, which is the default; and the **Bhutanese** calendar of the Royal Government of Bhutan.
9
+ The **Tsurphu** (Karma Kagyu) and **Mongolian** calendars are **not included yet**: the engine can
10
+ express them as configuration, and each will be exported once its dates have been checked against an
11
+ almanac of its own — see [Traditions](#traditions).
12
+
7
13
  ```sh
8
14
  npm install tibetan-calendar-temporal
9
15
  ```
@@ -57,7 +63,7 @@ see [why you can trust these dates](docs/why-trust-these-dates.md).
57
63
  | **Names in three renderings** | Tibetan script, Wylie, and THL Simplified phonetics (with eleven recorded corrections) for every weekday, element, gender, animal and rabjung year — each checked by machine against independent sources before it shipped |
58
64
  | **Observances** | The great holy days and the monthly cycle, as configurable rules. Each result says *how* it landed on its day, so a display can show the almanac's footnote instead of presenting a moved date as an exact one |
59
65
  | **Astrological attributes** | What kind of day it is, not just which day: the year's five elements, the month's and lunar day's labels, the calendar day's own, and the elemental yoga — which needs the moon's real position, not a cycle. A separate subpath, sourced piece by piece |
60
- | **Four traditions** | Phugpa and Bhutanese, each in two parameterisations. Constants and rules are injected as data, so a further tradition is a config object rather than a code change |
66
+ | **Two calendars, four configs** | Phugpa and Bhutanese, each in two parameterisations. Constants and rules are injected as data, so a further tradition is a config object rather than a code change; Tsurphu and Mongolian are expressible that way but not shipped, because no almanac has checked them |
61
67
  | **Date arithmetic** | Add days or months, count between two dates, find the next true full or new moon, and reduce a month to one sortable integer for a database key |
62
68
  | **Fast, and computed rather than looked up** | No date tables, no network, nothing asynchronous: every answer is integer arithmetic done on the spot, identical on every platform. On a 2026 laptop a conversion takes about 7 µs, a month grid about 0.14 ms and a year of observances in 2–3 ms, so it can run in a render path — [measured, with the machine](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/bench/RESULTS.md#re-recorded-2026-11-18) |
63
69
 
@@ -386,7 +392,7 @@ worked `switch` over every code is in [the guide](docs/guide.md#handling-errors)
386
392
  ### Traditions
387
393
 
388
394
  **v1 ships two calendars in four configurations.** Phugpa (*phug pa*) is the Men-Tsee-Khang
389
- standard and the basis of the almanacs most practitioners use; Bhutanese is the calendar of the
395
+ standard and the basis of the almanacs most Tibetans use; Bhutanese is the calendar of the
390
396
  Royal Government of Bhutan. Each ships twice, because each has two defensible parameterisations:
391
397
 
392
398
  ```js
@@ -412,10 +418,12 @@ back-projection is worse than the headline rate suggests. All three counts are r
412
418
  engine and asserted in `test/computation/conversion.test.ts`. The evidence for the default is in
413
419
  [docs/decisions/2026-08-12-lunar-anomaly-a2-default.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/decisions/2026-08-12-lunar-anomaly-a2-default.md).
414
420
 
415
- **The other real tradition is Tsurphu** (*mtshur phu*), the Karma Kagyu system, and it is **not
416
- shipped**. It is not shipped because nothing here has been validated against a Tsurphu almanac,
417
- and an unvalidated calendar published with this library's authority is exactly the failure this
418
- project exists to avoid — not because the algorithm cannot express it.
421
+ **Two other versions are not shipped: Tsurphu** (*mtshur phu*), the Karma Kagyu system, **and the
422
+ Mongolian** calendar, used in Mongolia and by the Buryats and Tuvinians. Neither ships because nothing
423
+ here has been validated against an almanac of its own, and an unvalidated calendar published with
424
+ this library's authority is exactly the failure this project exists to avoid — not because the
425
+ algorithm cannot express them. For a Mongolian date today, `@hnw/date-tibetan` is the shortest
426
+ route; see [when to use which](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/docs/other-implementations.md).
419
427
 
420
428
  It can. Every astronomical constant is injected through a `TraditionConfig` rather than hardcoded,
421
429
  including the scaling denominator, which is *derived* from the constants rather than fixed — Phugpa
@@ -570,7 +578,7 @@ from; in coordinate space a leap month is simply the next lunation.
570
578
  | `addDays` | `(date: TibetanDateFields, days: number, tradition?) => TibetanDate` | **Solar** days, the unit elapsed-time reckonings use. Total — it can never land on a skipped date, because stepping real days never reaches a label no day carries |
571
579
  | `daysBetween` | `(from: TibetanDateFields, to: TibetanDateFields, tradition?) => number` | Signed. If both dates came from this package, `a.isoDate.until(b.isoDate)` is the better route; this is for dates you built yourself |
572
580
  | `addMonths` | `(month: TibetanMonthFields & { day?: never }, months: number, tradition?) => TibetanMonth` | Month in, month out, so **total**. `+1` from a leap month is its twin. A `TibetanDate` does **not** compile — it would discard the day silently; use `addMonthsToDate` |
573
- | `addMonthsToDate` | `(date: TibetanDateFields, months: number, options?) => TibetanDate` | "The same day next month". `options` is `{ overflow?, tradition? }` — the key was `config` until 2026-09-24, and any other key is refused; `overflow` is `"constrain"` (default — fall to the nearest **lower** existing day, or day 2 when day 1 is skipped) or `"reject"`. A doubled day keeps the start's half, leap or regular, and an ordinary start lands on the regular half |
581
+ | `addMonthsToDate` | `(date: TibetanDateFields, months: number, options?) => TibetanDate` | "The same day next month". `options` is `{ overflow?, tradition? }`, and any other key is refused; `overflow` is `"constrain"` (default — fall to the nearest **lower** existing day, or day 2 when day 1 is skipped) or `"reject"`. A doubled day keeps the start's half, leap or regular, and an ordinary start lands on the regular half |
574
582
  | `monthsBetween` | `(from: TibetanMonthFields, to: TibetanMonthFields, tradition?) => number` | Signed, counted in **lunations** — month 5 to month 7 is three in a year that doubles month 6, two otherwise |
575
583
  | `lunationFromMonth` | `(month: TibetanMonthFields, tradition?) => number` | The month as one sortable integer, for a database or cache key. No consumer-side route: it needs the intercalation index |
576
584
  | `monthFromLunation` | `(lunation: number, tradition?) => TibetanMonth` | The inverse, for a stored coordinate with no year in hand. Narrower domain than its inverse — it returns boundaries, so it evaluates the calendar |
@@ -787,6 +795,19 @@ Implemented from Svante Janson, *Tibetan Calendar Mathematics*
787
795
  with any existing implementation — see [CONTRIBUTING.md](https://github.com/nyamlen/tibetan-calendar-temporal/blob/main/CONTRIBUTING.md) for the rules that
788
796
  keep it that way.
789
797
 
798
+ **How it was built.** I, Andreas Bothner, am a software architect, and I built this package with
799
+ Claude Code, Anthropic's AI coding assistant: it wrote the code, tests and documentation under my
800
+ direction and review, and the design decisions are mine. That changes where trust has to come from,
801
+ not how much is needed. The calendar arithmetic is taken from Janson's paper alone, and the dates are
802
+ checked against independent published calendars over stated ranges of years — see
803
+ [why you can trust these dates](docs/why-trust-these-dates.md). Before 1.0.0 the code went through a
804
+ source code review, two security reviews, an adversarial review, a maintainability review and an
805
+ audit of every documentation comment, each by sessions that had not written the code under review,
806
+ and through blind builds by clients working from a packed tarball alone. The clean-room rule binds
807
+ the assistant as it binds any contributor: no session read another implementation's source. What a
808
+ model saw in training cannot be ruled out, so the evidence of independent derivation is the commit
809
+ history itself, where the arithmetic is built up step by step from the paper's sections.
810
+
790
811
  ## Project identity
791
812
 
792
813
  | Thing | Name |
package/docs/guide.md CHANGED
@@ -245,9 +245,8 @@ nextObservance(from, ruleId, observanceConfig, traditionConfig);
245
245
  Both are positional. The observance config is **required**: no config is the default, because which
246
246
  days a practice keeps is a convention and the package does not choose one for you, so a call
247
247
  without one throws `TCT_INVALID_OBSERVANCE_CONFIG`. The tradition is last and optional, defaulting
248
- to `PHUGPA`. Until 2026-11-11 both travelled in one options bag; passing that bag, or a
249
- `TraditionConfig`, where the config belongs throws the same code, and the message names the function
250
- you called and its own signature.
248
+ to `PHUGPA`. Passing an options bag, or a `TraditionConfig`, where the config belongs throws the
249
+ same code, and the message names the function you called and its own signature.
251
250
 
252
251
  | | `TraditionConfig` | `ObservanceConfig` |
253
252
  |---|---|---|
@@ -909,9 +908,8 @@ isoToTibetan(Temporal.PlainDate.from('2003-06-01')).year; // 2130, after it
909
908
  **A year of dates, serialised, is about 126 KB** (354 days, ordinary year 2153) or **137 KB** for a
910
909
  thirteen-month leap year like 2151 — measured, not assumed, in `test/serialisation.test.ts`.
911
910
 
912
- Those figures used to be 293 KB and 324 KB. **Year-level naming is no longer a field on a date**: the
913
- element–animal name and the rabjung position describe the *year*, so on a date they were one value
914
- repeated across all 354 days, and together they were more than half of a serialised year. Reach them
911
+ **Year-level naming is not a field on a date**: the element–animal name and the rabjung position
912
+ describe the *year*, so on a date they would be one value repeated across all 354 days. Reach them
915
913
  with `yearNameFor(date.year)` and `rabjungFor(date.year)`, which are closed forms and touch no lunar
916
914
  arithmetic. `TibetanMonth` still carries `yearName`, so the `monthsFor` → `datesFor` path keeps it
917
915
  one hop away.
@@ -189,9 +189,7 @@ Stating this is the point of the page.
189
189
  - **The calendar is usable from 1447**, when the Phugpa system was introduced. Earlier dates are
190
190
  computed, and they are a back-projection: the system did not exist, and the year numbering is a
191
191
  modern convention applied backwards.
192
- - **The astrological attributes are computed but corroborated much less than the dates.** This said
193
- "no astrological information is computed" until 2026-09-12, when the `./astrology` subpath landed,
194
- and the honest version is longer. The cycles — the year's five elements, the month's and lunar
192
+ - **The astrological attributes are computed but corroborated much less than the dates.** The cycles — the year's five elements, the month's and lunar
195
193
  day's labels, the calendar day's — are closed forms checked against Janson's own printed tables,
196
194
  which catches a transcription or formula error and is **not** external corroboration. The **lunar
197
195
  mansion** needs real astronomy and agrees, for Phugpa, with FPMT's published codes on **98.0%** of the 1,821 days
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tibetan-calendar-temporal",
3
- "version": "1.0.0",
3
+ "version": "1.0.2",
4
4
  "description": "Tibetan calendar computation engine built on Temporal — the Phugpa and Bhutanese traditions, with the Tsurphu and Mongolian variants addable as config.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -18,6 +18,7 @@
18
18
  "phugpa",
19
19
  "buddhist",
20
20
  "lunisolar",
21
+ "lunisolar-calendar",
21
22
  "tibetan-calendar",
22
23
  "losar",
23
24
  "bhutanese",