(** RG 91's Table of Precedence for the EF (1962) rite: ranks any candidate
    for a given day by its RG 91 entry number. See
    docs/research/rules-register.md §4, whose 28-entry transcription this
    module follows line by line. *)

open Colitur_kernel

(** The universal (base) sanctoral layer's {!Celebration.t}.layer id. A
    Sanctoral-origin candidate whose layer is anything else is an overlay:
    "proper" (RG 91 entries 12, 19, 23) unless its layer id also carries
    {!indult_prefix} ("indult", entries 13, 20). This id and the prefix are
    colitur's own data-modelling convention, not an RG citation -- RG 91
    prescribes the ranking, not a machine encoding for it. Whichever task
    loads the real EF sanctoral base layer and its overlays must either
    reuse these two constants or this classifier will misfile them. *)
val universal_layer : string

(** See {!universal_layer}. *)
val indult_prefix : string

(** Slug suffix marking a celebration as a vigil (RG 91 entries 21, 26),
    e.g. "ef-ascension-vigil". Also colitur's own convention, not an RG
    citation, exposed for the same reason as {!universal_layer}: only the
    Ascension Vigil exists today (rite_ef/temporal_ef.ml); the Assumption,
    John Baptist, Peter & Paul and Lawrence vigils arrive as sanctoral data
    in a future task, and must use this same suffix or {!band} will band
    them 16/24 (an ordinary feast of the same rank) instead of 21/26. *)
val vigil_suffix : string

(** Slug prefixes marking a celebration as one of RG 91 entry 18's three
    Ember-day sets (Advent, Lent, September -- the Pentecost/Whitsun set is
    I class and matched by entry 10 before this is ever consulted). Also
    colitur's own convention mirroring rite_ef/temporal_ef.ml's own "ef-<set>
    -ember-<day>" slug format, not re-derived from first principles; exposed
    so a rename of that format has somewhere to be caught other than a
    silently-wrong entry 18. *)
val ember_prefixes : string list

(** Returned for a candidate shape RG 91's 28-entry table has no row for --
    e.g. a [Class1] vigil that is not the Nativity or Pentecost (entries 5,
    9 are the only I-class vigils the table names), or a [Class4] candidate
    also marked as a vigil. Deliberately outside 1..28 and larger than any
    real entry, so an unclassified candidate can never win an occurrence
    contest by accident; a caller that sees it back knows the shape needs a
    new rule, not a silently wrong one. *)
val unclassified : int

(** [band ctx c]: RG 91's Table of Precedence. Returns the table's own entry
    number -- I class 1-13, II class 14-21, III class 22-26, IV class 27-28;
    lower wins (see {!Precedence.rules.band}) -- EXCEPT where the table's own
    text states an exception: entry 8 (All Souls, register line 334) reads
    "yields to an occurring Sunday", so on a Sunday this returns a value that
    loses to entry 15 rather than the literal integer 8 (see the comment on
    entry 8 in precedence_ef.ml for the exact value and why). Total over
    every candidate {!Precedence.resolve} or {!Calendar} can construct,
    including shapes the 1962 table itself does not describe (see
    {!unclassified}). *)
val band : Vocab_ef.season Precedence.context -> Vocab_ef.rank Precedence.candidate -> int