///|
/// Selects index entries using exact evidence, inclusive values, and pagination.
pub(all) struct RomanIndexQuery {
  document_id : String?
  source_text : String?
  normalized_text : String?
  canonical_text : String?
  mode : RomanMode?
  min_value : Int?
  max_value : Int?
  used_unicode : Bool?
  normalized_input : Bool?
  offset : Int
  limit : Int?
} derive(Eq, Debug)

///|
/// Rejects invalid query bounds before any entry is inspected.
pub(all) enum RomanIndexQueryError {
  IndexQueryMinimumAboveMaximum(Int, Int)
  NegativeIndexQueryOffset(Int)
  NonPositiveIndexQueryLimit(Int)
} derive(Eq, Debug)

///|
/// Retains page entries and the complete filtered count.
pub(all) struct RomanIndexQueryPage {
  entries : Array[RomanIndexEntry]
  total_matches : Int64
  offset : Int
  limit : Int?
} derive(Eq, Debug)

///|
/// Groups equal numeric values in first-occurrence order.
pub(all) struct RomanIndexValueGroup {
  value : Int
  entries : Array[RomanIndexEntry]
} derive(Eq, Debug)

///|
/// Groups equal canonical spellings in first-occurrence order.
pub(all) struct RomanIndexCanonicalGroup {
  canonical : String
  entries : Array[RomanIndexEntry]
} derive(Eq, Debug)

///|
/// Groups accepted entries by document in first entry occurrence order.
pub(all) struct RomanIndexDocumentGroup {
  document_id : String
  entries : Array[RomanIndexEntry]
} derive(Eq, Debug)

///|
/// Groups notation modes in first-occurrence order.
pub(all) struct RomanIndexModeGroup {
  mode : RomanMode
  entries : Array[RomanIndexEntry]
} derive(Eq, Debug)

///|
/// Groups Unicode evidence in false/true first-occurrence order.
pub(all) struct RomanIndexUnicodeGroup {
  used_unicode : Bool
  entries : Array[RomanIndexEntry]
} derive(Eq, Debug)

///|
/// Groups input normalization evidence in first-occurrence order.
pub(all) struct RomanIndexNormalizationGroup {
  normalized_input : Bool
  entries : Array[RomanIndexEntry]
} derive(Eq, Debug)