(** Cache entry flags management

    This module provides a type-safe interface for managing cache entry flags.
    Flags control entry behavior such as pinning (preventing eviction),
    marking entries as stale (needing revalidation), or temporary.

    Flags are encoded in the filesystem using Maildir++-style conventions,
    making them persistent across program restarts and visible to external tools. *)

(** Abstract type representing a set of flags *)
type t

(** Individual flag types *)
type flag = [
  | `Pinned     (** Entry is pinned and won't be automatically evicted during cleanup *)
  | `Stale      (** Entry needs revalidation before use *)
  | `Temporary  (** Entry is temporary and will be removed on cache clear *)
  | `Chunk      (** Entry is a partial chunk of a larger file (used for resume support) *)
]

(** {1 Construction} *)

(** Empty set of flags *)
val empty : t

(** Create a flag set from a list *)
val of_list : flag list -> t

(** Convert a flag set to a list *)
val to_list : t -> flag list

(** Create a flag set with a single flag *)
val singleton : flag -> t

(** {1 Operations} *)

(** Add a flag to the set *)
val add : flag -> t -> t

(** Remove a flag from the set *)
val remove : flag -> t -> t

(** Check if a flag is present *)
val mem : flag -> t -> bool

(** Union of two flag sets *)
val union : t -> t -> t

(** Intersection of two flag sets *)
val inter : t -> t -> t

(** Difference of two flag sets *)
val diff : t -> t -> t

(** Check if flag set is empty *)
val is_empty : t -> bool

(** {1 Predicates} *)

(** Check if pinned flag is set *)
val is_pinned : t -> bool

(** Check if stale flag is set *)
val is_stale : t -> bool

(** Check if temporary flag is set *)
val is_temporary : t -> bool

(** Check if chunk flag is set *)
val is_chunk : t -> bool

(** Check if this represents a complete file (not a chunk) *)
val is_complete : t -> bool

(** {1 Encoding} *)

(** Convert flags to a string representation (for filenames) *)
val to_string : t -> string

(** Parse flags from a string representation *)
val of_string : string -> t

(** {1 Comparison} *)

(** Equality of flag sets *)
val equal : t -> t -> bool

(** Comparison for ordering *)
val compare : t -> t -> int

(** {1 Pretty Printing} *)

(** Pretty printer for a single flag *)
val pp_flag : Format.formatter -> flag -> unit

(** Pretty printer for flag sets *)
val pp : Format.formatter -> t -> unit

(** {1 JSON Support} *)

(** Jsont codec for flags *)
val jsont : t Jsont.t