(** The EF (1962) temporal cycle, per Rubricae Generales 71-77 and 91. *)

open Colitur_kernel

(** RG 71: Advent I Sunday of the Advent opening in civil year [y]. *)
val advent_start : int -> Date.t

(** First day of the liturgical year opening in civil year [y]. Same as
    {!advent_start}. *)
val year_start : int -> Date.t

val season : Date.t -> Vocab_ef.season

(** Last Sunday of October, per the 1960 calendar. *)
val christ_the_king : int -> Date.t

(** RG 17(b): the first Sunday after Epiphany, in civil year [y] -- the
    Feast of the Holy Family's own date. Always falls 7-13 January
    inclusive; never empty of a Sunday (unlike RG 17(a)'s Holy Name, whose
    narrower 2-5 January window can be, and carries an explicit calendarium
    fallback for it), so this needs none. *)
val holy_family_sunday : int -> Date.t

(** RG 17(a): the Sunday falling 2-5 January in civil year [y], the Most Holy
    Name of Jesus's own primary date -- [None] when no such Sunday exists
    that year (3,619 of the 8,417 years in [1583, 9999]), unlike
    {!holy_family_sunday}'s window, which never is. *)
val holy_name_sunday : int -> Date.t option

(** RG 17(a)'s own "secus die 2 ianuarii" fallback: 2 January in civil year
    [y]. Only actually carries the feast when {!holy_name_sunday} [y] is
    [None] for that year -- {!temporal} is what applies that condition. *)
val holy_name_fallback_date : int -> Date.t

(** The named temporal days: I-class feasts of the Lord, vigils, and days within
    the Octave of the Nativity. Returns (season, slug, colour, rank). Carries
    no week of its own -- {!temporal} computes it uniformly via {!week} for
    every day, named or not, so a named day inside a numbered season run
    always carries that run's week. *)
val named : Date.t -> (Vocab_ef.season * string * Colour.t * Vocab_ef.rank) option

(** The Sunday on which week 1 of a season begins, in civil year [y]. [None] for
    [Christmastide], which has no numbered weeks. *)
val week_origin : Vocab_ef.season -> int -> Date.t option

(** Week within the season. Sunday-aligned, so it is constant Sunday-to-Saturday.
    The origin is season-specific: time after Pentecost counts from Pentecost,
    time after Epiphany from the first Sunday after Epiphany. *)
val week : Date.t -> int option

(** The lectionary key for a Sunday, or [None] if [d] is not a Sunday. *)
val sunday_slug : Date.t -> string option

(** The calendarium's own bissextile (leap-year) footnote, February
    (docs/research/LT.txt:5011-5014): in a leap year the sixth kalends of
    March (24 February) is doubled rather than a 29th day appended, so every
    fixed entry from 24 through 28 February is kept one civil day later than
    usual (Matthias 24->25, Gabriel of Our Lady of Sorrows 27->28), and 24
    February itself carries no fixed office that year. Supplied as {!Rite.t}'s
    [fixed_key] field -- see that field's own doc comment and this function's
    definition for the full citation and the general-mechanism-vs-two-named-
    feasts reasoning. *)
val bissextile_fixed_key : Date.t -> (int * int) option

val id : string

(** Total over 1583..9999: every date yields exactly one temporal identity. *)
val temporal : Date.t -> (Vocab_ef.season, Vocab_ef.rank) Temporal.t

(** Independent restatement of {!named}'s fixed and Easter-relative dates for
    civil year [y], paired with the slug each should carry. Feeds
    {!Colitur_kernel.Validate.run}'s anchor-agreement check; not derived from
    {!named}, so an accidental single-site drift in an offset is caught
    rather than left invisible. *)
val anchors : int -> (string * Date.t) list