1 files changed, 79 insertions, 0 deletions
diff --git a/lib/citation/book.mli b/lib/citation/book.mli
new file mode 100644
index 0000000..0ca229c
--- /dev/null
+++ b/lib/citation/book.mli
@@ -0,0 +1,79 @@
+(* SPDX-License-Identifier: AGPL-3.0-or-later *)
+
+(** Bible books: one canonical id per book, and the tradition that decides
+    which book an id denotes.
+
+    Ids follow the VULGATE structure ([kings_3], [esdras_2],
+    [ecclesiasticus]), because the Vulgate is the default tradition and the
+    shipped 1962 data is Vulgate throughout. An id is internal -- it is never
+    shown to a reader, exactly as a slug is never shown. *)
+
+type id
+
+val to_string : id -> string
+
+(** Resolve one spelling as it appears in the data. Returns [None] for
+    anything not in {!tokens}.
+
+    SIXTEEN books arrive in more than one spelling, surveyed across all
+    three citation-bearing files ([lectionary.sexp], [sanctoral.sexp],
+    [commons.sexp] -- not the lectionary alone, which undercounts: the
+    sanctoral propers alone carry more citations than the lectionary does).
+    Most are a dotted/undotted pair ([Isa]/[Isa.], [3 Kgs.]/[3 Kings], and
+    others); two also carry a MODERN spelling sitting inside otherwise-
+    Vulgate data ([Sir] alongside [Ecclus]/[Eccli], [Rev] alongside [Apoc]).
+    All of this is INHERITED from lectio's own ini, which is itself
+    generated from missalemeum/Divinum Officium -- it is not a colitur
+    transcription error, and the data is deliberately left untouched. Every
+    accepted spelling resolves here to the same, single Vulgate id: [Sir]
+    resolves to [ecclesiasticus] and [Rev] to [apocalypse], never to the
+    tradition-only targets [sirach]/[revelation] -- see those below. *)
+val of_token : string -> id option
+
+(** Every id this build knows, for coverage checks. *)
+val all : id list
+
+(** Every accepted spelling paired with its id. *)
+val tokens : (string * id) list
+
+(** The first spelling registered for an id -- the form the shipped data
+    itself uses ([luke] -> ["Luke"], [kings_3] -> ["3 Kings"]).
+
+    This is the FALLBACK display name, and it exists because the obvious
+    alternative is actively worse. A language file's [\[bible\]] lookup is
+    total and returns THE KEY on a miss, so a book with no entry would
+    otherwise render as ["luke.abbr 5:12-14"]. Falling back here instead makes
+    an unnamed book render as ["Luke 5:12-14"] -- exactly what colitur printed
+    before this feature existed. The degraded case is the OLD behaviour, not a
+    broken page, the same principle {!Colitur_naming.Lang} states for its own
+    key-returning misses.
+
+    An id with no registered spelling -- only a {!tradition} target such as
+    [kings_1] or [sirach], which the Vulgate data never cites -- returns the id
+    itself. Reachable only from a user language file that selects a tradition
+    without naming its target books; every SHIPPED language file is asserted
+    complete over {!all}. *)
+val default_spelling : id -> string
+
+(** A numbering tradition: which book an id denotes. Separate from NAMING
+    (what a book is called), which lives in a language file's [\[bible\]]
+    section, because naming varies by language and this does not -- "modern
+    numbering" is the same decision in Latin, Polish and English. *)
+type tradition
+
+(** The identity tradition: the Vulgate, as the 1962 Missal prints it. The
+    default; colitur never silently renumbers. *)
+val vulgate : tradition
+
+(** Build a tradition from an ini section's fields. An entry naming an
+    unknown id on either side is IGNORED, not fatal: a traditions file
+    written for a newer colitur must still work on an older one. Use
+    {!unknown_fields} to report them. *)
+val tradition_of_fields : (string * string) list -> tradition
+
+(** The fields {!tradition_of_fields} silently dropped -- either side naming
+    an id outside {!all}. Never raises; a caller that cares can report these,
+    a caller that does not can ignore the return value entirely. *)
+val unknown_fields : (string * string) list -> string list
+
+val map : tradition -> id -> id