ask every binding the same question and insist on the same answer

There is one engine and nine doors into it, and nothing until now checked
that the doors agree. CI tested each binding against itself: the Python
wheel imported, the C demo compiled, the npm package type-checked. None
of that would have caught a field that crosses one boundary wrong, which
is the failure this library is most exposed to, because a wrong answer
about a fast day looks exactly like a right one.

So: twelve days, chosen where the bindings could plausibly differ, and
all twenty-two fields compared against what the command line says. The
days are Pascha itself, the Nativity on both calendars, a Wednesday of
the Great Fast under Byzantine Catholic law and again at the Typikon, a
weekday of the Nativity Fast where Greek and Slavic usage part, the one
Orthodox church on the Gregorian Paschalion, and a day with no feast.

A release now runs what a push runs. It had been gated on cargo test
alone, so the C ABI, the Lua binding, the Python parity check and the
README examples were checked on the branch that led to a release and not
on the release. Neither registry will reuse a version, so the gate
belongs before the upload.

Writing it found three things. The npm exports map did not expose the
wasm by package path, so a bundler asked for typikon/web/typikon_bg.wasm
was told no such path exists and had to reach into node_modules; the
documented init() call was never affected. The suite could hang instead
of fail, because the test web server was backgrounded inside a subshell
and killed by job spec, leaving bash in do_wait forever. And pointing
XDG_CONFIG_HOME at a path that does not exist isolates typikon and
breaks every other program that keeps state under it, a browser included.

A surface whose toolchain is missing is named as skipped, and fewer than
three surfaces running is a failure rather than a pass, so a container
with nothing installed cannot come out green.

tests/parity/README.md

@@ -0,0 +1,14 @@
+# Parity
+
+Every binding answers the same question, so every binding has to give the same
+answer. These probes ask each one for the same twelve days and compare all
+twenty-two fields against what the command line says.
+
+The probes are chosen for the places the bindings could plausibly disagree:
+Pascha itself, the Nativity on both calendars, a Wednesday of the Great Fast
+under Byzantine Catholic law and again at the Typikon, a weekday of the
+Nativity Fast where Greek and Slavic usage part, the one Orthodox church on the
+Gregorian Paschalion, and a day with no feast at all.
+
+Run them with `tests/parity.sh`. Surfaces whose toolchain is absent are skipped
+by name rather than silently passed.

tests/parity/compare.py

@@ -0,0 +1,29 @@
+"""One surface's answers against the oracle's.
+
+A surface need not expose every field; it must not disagree about one it does.
+"""
+import json
+import sys
+
+name, oracle_path, got_path = sys.argv[1:4]
+oracle = json.load(open(oracle_path))
+got = json.load(open(got_path))
+
+bad = []
+for key in sorted(set(oracle) - set(got)):
+    bad.append(f"missing probe {key}")
+for key in sorted(set(got) - set(oracle)):
+    bad.append(f"unexpected probe {key}")
+for key in sorted(set(oracle) & set(got)):
+    for field, expected in sorted(oracle[key].items()):
+        if field in got[key] and got[key][field] != expected:
+            bad.append(f"{key} {field}: {got[key][field]!r} != {expected!r}")
+
+fields = sorted({f for v in got.values() for f in v})
+for line in bad[:20]:
+    print(f"      {line}")
+if len(bad) > 20:
+    print(f"      ... and {len(bad) - 20} more")
+print(f"  {'ok  ' if not bad else 'FAIL'} {name}: "
+      f"{len(got)} probes, {len(fields)} fields, {len(bad)} differences")
+sys.exit(1 if bad else 0)

tests/parity/oracle.py

@@ -0,0 +1,35 @@
+"""The command line's answer, which every other surface is measured against."""
+import json
+import os
+import subprocess
+import sys
+
+FIELDS = [
+    "date", "weekday", "jurisdiction", "calendar", "churchDate", "season",
+    "cycle", "feast", "rank", "sign", "tradition", "title", "commemorations",
+    "fast", "fastLabel", "emoji", "reason", "obligation", "binds", "pascha",
+    "daysToPascha", "julianOffset",
+]
+
+cli, probes_path, out_path = sys.argv[1:4]
+
+# Neither a config file nor a fetched menaion may reach any surface, or the
+# comparison measures the machine rather than the code. The caller has already
+# pointed these at empty directories; this only refuses to run without them,
+# because an oracle that quietly read the developer's own jurisdiction would
+# make every surface agree about the wrong thing.
+env = dict(os.environ)
+for var in ("XDG_CONFIG_HOME", "XDG_DATA_HOME"):
+    if not env.get(var):
+        sys.exit(f"{var} must be set to an empty directory before reckoning the oracle")
+
+out = {}
+for date, jurisdiction, typikon in json.load(open(probes_path)):
+    args = [cli, "--date", date, "--jurisdiction", jurisdiction, "--json",
+            "--typikon" if typikon else "--no-typikon"]
+    day = json.loads(subprocess.run(args, capture_output=True, text=True,
+                                    env=env, check=True).stdout)
+    out[f"{date}|{jurisdiction}|{int(typikon)}"] = {k: day[k] for k in FIELDS}
+
+json.dump(out, open(out_path, "w"), ensure_ascii=False)
+print(f"oracle: {len(out)} probes, {len(FIELDS)} fields")

tests/parity/probe.c

@@ -0,0 +1,98 @@
+/* The C ABI, over the same probes, emitting the same JSON.
+ *
+ * The probe list is written out here rather than read from probes.json,
+ * because a JSON parser is exactly what this binding exists to spare its
+ * callers and it would be odd to need one to test it. tests/parity.sh checks
+ * the two lists have not drifted apart.
+ */
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <typikon.h>
+
+static void esc(FILE *f, const char *s) {
+    fputc('"', f);
+    for (; *s; s++) {
+        if (*s == '"' || *s == '\\') fprintf(f, "\\%c", *s);
+        else if ((unsigned char)*s < 0x20) fprintf(f, "\\u%04x", *s);
+        else fputc(*s, f);
+    }
+    fputc('"', f);
+}
+
+static void field(FILE *f, const char *k, const char *v, int *first) {
+    if (!*first) fputc(',', f);
+    *first = 0;
+    esc(f, k); fputc(':', f);
+    if (v) esc(f, v); else fputs("null", f);
+}
+
+int main(int argc, char **argv) {
+    (void)argc;
+    FILE *f = fopen(argv[1], "w");
+    fputc('{', f);
+    int firstkey = 1;
+
+    /* date, jurisdiction, discipline: the same twelve as probes.json. */
+    struct { int y, m, d; const char *j; int t; } probes[] = {
+        {2026,4,12,"moscow",-1}, {2026,4,12,"goarch",-1}, {2026,1,7,"moscow",-1},
+        {2025,12,25,"old",-1},   {2026,3,4,"ruthenian",0}, {2026,3,4,"ruthenian",1},
+        {2025,12,9,"old",-1},    {2026,2,16,"oca",-1},     {2026,8,15,"antiochian",-1},
+        {2026,9,18,"finnish",-1},{2027,5,2,"serbian",-1},  {2026,6,28,"constantinople",-1},
+    };
+
+    for (size_t i = 0; i < sizeof probes / sizeof *probes; i++) {
+        int32_t jdn = typikon_jdn_from_ymd(probes[i].y, probes[i].m, probes[i].d);
+        int disc = probes[i].t < 0 ? 0 : probes[i].t;   /* the CLI oracle passed --no-typikon */
+        typikon_day *day = typikon_describe_full(jdn, probes[i].j, NULL, disc);
+        if (!day) { fprintf(stderr, "%s\n", typikon_last_error()); return 1; }
+
+        char key[64];
+        snprintf(key, sizeof key, "%04d-%02d-%02d|%s|%d",
+                 probes[i].y, probes[i].m, probes[i].d, probes[i].j,
+                 probes[i].t == 1 ? 1 : 0);
+        if (!firstkey) fputc(',', f);
+        firstkey = 0;
+        esc(f, key); fputs(":{", f);
+        int first = 1;
+        field(f, "date",        typikon_day_iso(day), &first);
+        field(f, "weekday",     typikon_day_weekday(day), &first);
+        field(f, "jurisdiction",typikon_day_jurisdiction(day), &first);
+        field(f, "calendar",    typikon_day_calendar(day), &first);
+        field(f, "churchDate",  typikon_day_church_date(day), &first);
+        field(f, "season",      typikon_day_season(day), &first);
+        field(f, "cycle",       typikon_day_cycle(day), &first);
+        field(f, "feast",       typikon_day_feast(day), &first);
+        field(f, "rank",        typikon_day_rank(day), &first);
+        field(f, "sign",        typikon_day_sign(day), &first);
+        field(f, "tradition",   typikon_day_tradition(day), &first);
+        field(f, "title",       typikon_day_title(day), &first);
+        field(f, "fast",        typikon_day_fast(day), &first);
+        field(f, "fastLabel",   typikon_day_fast_label(day), &first);
+        field(f, "emoji",       typikon_day_emoji(day), &first);
+        field(f, "reason",      typikon_day_reason(day), &first);
+        field(f, "obligation",  typikon_day_obligation(day), &first);
+        field(f, "binds",       typikon_day_binds(day), &first);
+
+        fputs(",\"commemorations\":[", f);
+        for (uint32_t c = 0; c < typikon_day_commemoration_count(day); c++) {
+            if (c) fputc(',', f);
+            esc(f, typikon_day_commemoration(day, c));
+        }
+        fputc(']', f);
+
+        int32_t p = typikon_day_pascha(day);
+        int32_t py; uint32_t pm, pd;
+        typikon_ymd_from_jdn(p, &py, &pm, &pd);
+        char iso[16];
+        snprintf(iso, sizeof iso, "%04d-%02u-%02u", py, pm, pd);
+        fputs(",\"pascha\":", f); esc(f, iso);
+        fprintf(f, ",\"daysToPascha\":%d", typikon_day_days_to_pascha(day));
+        fprintf(f, ",\"julianOffset\":%d", typikon_day_julian_offset(day));
+        fputc('}', f);
+        typikon_day_free(day);
+    }
+    fputs("}\n", f);
+    fclose(f);
+    return 0;
+}

tests/parity/probe.cjs

@@ -0,0 +1,20 @@
+// Node, by require. The other half of Node's world, and the half an exports
+// map gets wrong.
+const { readFileSync, writeFileSync } = require("node:fs");
+const { describeIso } = require("typikon");
+
+const [probesPath, outPath] = process.argv.slice(2);
+const out = {};
+for (const [date, jurisdiction, typikon] of JSON.parse(readFileSync(probesPath, "utf8"))) {
+  const d = describeIso(date, { jurisdiction, typikon });
+  out[`${date}|${jurisdiction}|${typikon ? 1 : 0}`] = {
+    date: d.date, weekday: d.weekday, jurisdiction: d.jurisdiction,
+    calendar: d.calendar, churchDate: d.churchDate, season: d.season,
+    cycle: d.cycle, feast: d.feast, rank: d.rank, sign: d.sign,
+    tradition: d.tradition, title: d.title, commemorations: d.commemorations,
+    fast: d.fast, fastLabel: d.fastLabel, emoji: d.emoji, reason: d.reason,
+    obligation: d.obligation, binds: d.binds, pascha: d.pascha,
+    daysToPascha: d.daysToPascha, julianOffset: d.julianOffset,
+  };
+}
+writeFileSync(outPath, JSON.stringify(out));

tests/parity/probe.lua

@@ -0,0 +1,59 @@
+-- The binding under test is the one in examples/lua.
+package.path = (os.getenv("TYPIKON_LUA") or "examples/lua") .. "/?.lua;" .. package.path
+local typikon = require("typikon")
+
+-- Minimal JSON writer: the binding hands back Lua tables, and the point is to
+-- compare them with everything else, not to pull in a dependency.
+local function esc(s)
+  return '"' .. s:gsub('[%c"\\]', function(c)
+    if c == '"' then return '\\"' elseif c == '\\' then return '\\\\' end
+    return string.format('\\u%04x', c:byte())
+  end) .. '"'
+end
+local function val(v)
+  if v == nil then return "null"
+  elseif type(v) == "number" then return tostring(math.floor(v))
+  elseif type(v) == "table" then
+    local parts = {}
+    for i = 1, #v do parts[i] = esc(v[i]) end
+    return "[" .. table.concat(parts, ",") .. "]"
+  else return esc(v) end
+end
+
+local probes = {
+  {2026,4,12,"moscow",false}, {2026,4,12,"goarch",false}, {2026,1,7,"moscow",false},
+  {2025,12,25,"old",false},   {2026,3,4,"ruthenian",false},{2026,3,4,"ruthenian",true},
+  {2025,12,9,"old",false},    {2026,2,16,"oca",false},     {2026,8,15,"antiochian",false},
+  {2026,9,18,"finnish",false},{2027,5,2,"serbian",false},  {2026,6,28,"constantinople",false},
+}
+
+local fields = {
+  {"date","iso"}, {"weekday","weekday"}, {"jurisdiction","jurisdiction"},
+  {"calendar","calendar"}, {"churchDate","church_date"}, {"season","season"},
+  {"cycle","cycle"}, {"feast","feast"}, {"rank","rank"}, {"sign","sign"},
+  {"tradition","tradition"}, {"title","title"}, {"fast","fast"},
+  {"fastLabel","fast_label"}, {"emoji","emoji"}, {"reason","reason"},
+  {"obligation","obligation"}, {"binds","binds"},
+  {"commemorations","commemorations"},
+}
+
+local out, firstkey = {}, true
+for _, p in ipairs(probes) do
+  local jdn = assert(typikon.jdn(p[1], p[2], p[3]))
+  local day = assert(typikon.describe(jdn, { jurisdiction = p[4], typikon = p[5] }))
+  local parts = {}
+  for _, f in ipairs(fields) do
+    parts[#parts + 1] = esc(f[1]) .. ":" .. val(day[f[2]])
+  end
+  local py, pm, pd = typikon.ymd(day.pascha_jdn)
+  parts[#parts + 1] = esc("pascha") .. ":" .. esc(string.format("%04d-%02d-%02d", py, pm, pd))
+  parts[#parts + 1] = esc("daysToPascha") .. ":" .. tostring(day.days_to_pascha)
+  parts[#parts + 1] = esc("julianOffset") .. ":" .. tostring(day.julian_offset)
+  local key = string.format("%04d-%02d-%02d|%s|%d", p[1], p[2], p[3], p[4], p[5] and 1 or 0)
+  out[#out + 1] = (firstkey and "" or ",") .. esc(key) .. ":{" .. table.concat(parts, ",") .. "}"
+  firstkey = false
+end
+
+local f = assert(io.open(arg[1], "w"))
+f:write("{" .. table.concat(out) .. "}\n")
+f:close()

tests/parity/probe.mjs

@@ -0,0 +1,12 @@
+// Node, by import.
+import { readFileSync, writeFileSync } from "node:fs";
+import { describeIso } from "typikon";
+import { shape } from "./shape.mjs";
+
+const [probesPath, outPath] = process.argv.slice(2);
+const out = {};
+for (const [date, jurisdiction, typikon] of JSON.parse(readFileSync(probesPath, "utf8"))) {
+  out[`${date}|${jurisdiction}|${typikon ? 1 : 0}`] =
+    shape(describeIso(date, { jurisdiction, typikon }));
+}
+writeFileSync(outPath, JSON.stringify(out));

tests/parity/probe.py

@@ -0,0 +1,37 @@
+"""The Python bindings."""
+import datetime
+import json
+import sys
+
+import typikon
+
+probes_path, out_path = sys.argv[1:3]
+out = {}
+for date, jurisdiction, tk in json.load(open(probes_path)):
+    y, m, d = map(int, date.split("-"))
+    day = typikon.describe(datetime.date(y, m, d), jurisdiction=jurisdiction, typikon=tk)
+    out[f"{date}|{jurisdiction}|{int(tk)}"] = {
+        "date": day.iso,
+        "weekday": day.weekday,
+        "jurisdiction": day.jurisdiction,
+        "calendar": day.calendar,
+        "churchDate": day.church_date,
+        "season": day.season,
+        "cycle": day.cycle,
+        "feast": day.feast,
+        "rank": day.rank,
+        "sign": day.sign,
+        "tradition": day.tradition,
+        "title": day.title,
+        "commemorations": day.commemorations,
+        "fast": day.fast,
+        "fastLabel": day.fast_label,
+        "emoji": day.emoji,
+        "reason": day.reason,
+        "obligation": day.obligation,
+        "binds": day.binds,
+        "pascha": day.pascha.isoformat(),
+        "daysToPascha": day.days_to_pascha,
+        "julianOffset": day.julian_offset,
+    }
+json.dump(out, open(out_path, "w"), ensure_ascii=False)

tests/parity/probe.ts

@@ -0,0 +1,36 @@
+// TypeScript, compiled under --strict and then run. Every field is annotated
+// on the way out, so a type that has drifted from what the package returns is
+// a compile error rather than a surprise at run time.
+import { readFileSync, writeFileSync } from "node:fs";
+import { describeIso, week, pascha, jurisdictions, type Day, type Options } from "typikon";
+
+const [probesPath, outPath] = process.argv.slice(2);
+type Probe = [string, string, boolean];
+
+const out: Record<string, Record<string, unknown>> = {};
+for (const [date, jurisdiction, typikon] of JSON.parse(readFileSync(probesPath, "utf8")) as Probe[]) {
+  const options: Options = { jurisdiction, typikon };
+  const d: Day = describeIso(date, options);
+  const season: string | null = d.season;
+  const commemorations: string[] = d.commemorations;
+  const daysToPascha: number = d.daysToPascha;
+  out[`${date}|${jurisdiction}|${typikon ? 1 : 0}`] = {
+    date: d.date, weekday: d.weekday, jurisdiction: d.jurisdiction,
+    calendar: d.calendar, churchDate: d.churchDate, season,
+    cycle: d.cycle, feast: d.feast, rank: d.rank, sign: d.sign,
+    tradition: d.tradition, title: d.title, commemorations,
+    fast: d.fast, fastLabel: d.fastLabel, emoji: d.emoji, reason: d.reason,
+    obligation: d.obligation, binds: d.binds, pascha: d.pascha,
+    daysToPascha, julianOffset: d.julianOffset,
+  };
+}
+
+// The rest of the surface, so nothing is typed only where it is called.
+const seven: Day[] = week(new Date(2026, 3, 12), 7, { jurisdiction: "moscow" });
+const p: Date = pascha(2027, "old");
+const keys: string[] = jurisdictions().map((j) => j.key);
+if (seven.length !== 7 || p.getFullYear() !== 2027 || keys.length < 20) {
+  throw new Error("the rest of the surface did not answer");
+}
+
+writeFileSync(outPath, JSON.stringify(out));

tests/parity/probes.json

@@ -0,0 +1,14 @@
+[
+  ["2026-04-12", "moscow",         false],
+  ["2026-04-12", "goarch",         false],
+  ["2026-01-07", "moscow",         false],
+  ["2025-12-25", "old",            false],
+  ["2026-03-04", "ruthenian",      false],
+  ["2026-03-04", "ruthenian",      true],
+  ["2025-12-09", "old",            false],
+  ["2026-02-16", "oca",            false],
+  ["2026-08-15", "antiochian",     false],
+  ["2026-09-18", "finnish",        false],
+  ["2027-05-02", "serbian",        false],
+  ["2026-06-28", "constantinople", false]
+]

tests/parity/shape.mjs

@@ -0,0 +1,14 @@
+// The fields, named once for every JavaScript surface. Written out rather than
+// spread, so that a field the package stops exporting is a missing key here and
+// not a silently absent one.
+export function shape(d) {
+  return {
+    date: d.date, weekday: d.weekday, jurisdiction: d.jurisdiction,
+    calendar: d.calendar, churchDate: d.churchDate, season: d.season,
+    cycle: d.cycle, feast: d.feast, rank: d.rank, sign: d.sign,
+    tradition: d.tradition, title: d.title, commemorations: d.commemorations,
+    fast: d.fast, fastLabel: d.fastLabel, emoji: d.emoji, reason: d.reason,
+    obligation: d.obligation, binds: d.binds, pascha: d.pascha,
+    daysToPascha: d.daysToPascha, julianOffset: d.julianOffset,
+  };
+}

tests/parity/web/entry.mjs

@@ -0,0 +1,16 @@
+// A bare "typikon" import under a browser-targeted bundler, which is what a
+// web app actually writes. It has to resolve to the web build and not the Node
+// one: the exports map is the only thing making that true.
+import init, { describeIso } from "typikon";
+import wasmUrl from "typikon/web/typikon_bg.wasm";
+import { shape } from "../shape.mjs";
+
+window.typikonProbe = async (probes) => {
+  await init({ module_or_path: wasmUrl });
+  const out = {};
+  for (const [date, jurisdiction, typikon] of probes) {
+    out[`${date}|${jurisdiction}|${typikon ? 1 : 0}`] =
+      shape(describeIso(date, { jurisdiction, typikon }));
+  }
+  return out;
+};

tests/parity/web/extract.py

@@ -0,0 +1,16 @@
+"""Pull the probe result back out of the DOM the browser printed."""
+import html
+import json
+import re
+import sys
+
+dom = open(sys.argv[1], encoding="utf-8").read()
+match = re.search(r'<pre id="out">(.*?)</pre>', dom, re.S)
+if not match:
+    sys.exit("the page produced no result element")
+text = html.unescape(match.group(1))
+if text == "running":
+    sys.exit("the page never finished; the wasm probably failed to load")
+if text.startswith("ERROR"):
+    sys.exit(text[:600])
+json.dump(json.loads(text), open(sys.argv[2], "w"), ensure_ascii=False)

tests/parity/web/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>typikon parity</title>
+<pre id="out">running</pre>
+<script type="module">
+import "./entry.js";
+const probes = await (await fetch("./probes.json")).json();
+try {
+  document.getElementById("out").textContent =
+    JSON.stringify(await window.typikonProbe(probes));
+} catch (e) {
+  document.getElementById("out").textContent = "ERROR " + (e && e.stack || e);
+}
+</script>