edoxen 0.5.0 → 0.8.1

data/lib/edoxen/link_checker.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "date"
+
+module Edoxen
+  # Walks a directory tree of Meeting and DecisionCollection YAML
+  # files and asserts that every cross-document URN link resolves.
+  #
+  # Invariants enforced:
+  #
+  #   * Every Meeting#urn (if set) is unique across the scanned tree.
+  #   * Every DecisionCollection#metadata.meeting_urn (if set)
+  #     resolves to a Meeting whose urn matches.
+  #
+  # Use from CLI / scripts via the public `check` class method. Returns
+  # an array of `LinkError` records (empty = ok).
+  #
+  # All file IO is read-only. No edits to the YAMLs.
+  #
+  # Architecture: two passes.
+  #
+  #   1. `index_pass` walks every file, classifies its top-level shape
+  #      via one of three MECE predicates (`meeting_collection_shape?`,
+  #      `meeting_shape?`, `decision_collection_shape?`), and records
+  #      URN → IndexEntry pairs. Duplicate URNs are reported here.
+  #   2. `verify_pass` checks every cross-document link in the indexed
+  #      collections against the indexed meetings.
+  #
+  # Adding a new link type is one new field-reading line in
+  # `index_pass` (if the source side needs indexing) plus one
+  # iteration in `verify_pass`. Adding a new top-level shape is one
+  # new predicate + one new branch in `index_pass`.
+  class LinkChecker
+    # Internal: file + line pair carried by the URN indexes.
+    IndexEntry = Struct.new(:file, :line)
+
+    # Cross-document link failure. `line` is 1-based. `pointer` is the
+    # dotted in-document path that carries the bad reference (e.g.
+    # `metadata.meeting_urn` or `meetings[2].urn`).
+    LinkError = Struct.new(:file, :line, :pointer, :urn, :kind) do
+      def message
+        "#{file}:#{line}: #{pointer} references #{urn} (#{kind})"
+      end
+
+      alias_method :to_clickable_format, :message
+    end
+
+    # Walk `dir` (recursive scan of *.yaml and *.yml), classify each
+    # file, and assert every cross-document URN resolves to a real
+    # record.
+    #
+    # @return [Array<LinkError>] empty when all links resolve.
+    def self.check(dir)
+      new(dir).check
+    end
+
+    def initialize(dir)
+      @dir = dir
+      @meetings_by_urn = {} # urn → IndexEntry(file, line)
+      @collections_by_meeting_urn = {} # meeting_urn → IndexEntry(file, line)
+    end
+
+    def check
+      errors = []
+      index_pass(errors)
+      verify_pass(errors)
+      errors
+    end
+
+    private
+
+    # Phase 1: walk the tree, classify each file, populate the URN
+    # indexes. Reports duplicate-URN errors as they surface — the
+    # first claim keeps the index slot; subsequent claimants are
+    # rejected and flagged, so dangling-link reports always point at
+    # the authoritative source.
+    def index_pass(errors)
+      # `Dir.glob` order is filesystem-dependent; the duplicate-URN
+      # specs assert on which file is the "first claim", so sort
+      # explicitly for determinism.
+      Dir.glob(File.join(@dir, "**", "*.{yaml,yml}")).sort.each do |file| # rubocop:disable Lint/RedundantDirGlobSort
+        content = File.read(file)
+        data = safe_load_yaml(content)
+        next unless data.is_a?(Hash)
+
+        line_map = SchemaValidator::LineMap.build(content)
+
+        case data
+        when ->(d) { meeting_collection_shape?(d) }
+          index_meeting_collection(data, file, line_map, errors)
+        when ->(d) { meeting_shape?(d) }
+          line = line_of(line_map, "/urn")
+          register_meeting(data["urn"], file, line, "urn", errors) if data["urn"]
+        when ->(d) { decision_collection_shape?(d) }
+          index_decision_collection(data, file, line_map)
+        end
+      end
+    end
+
+    # Phase 2: every cross-document link is checked here. New link
+    # types land as additional iterations over the relevant index.
+    def verify_pass(errors)
+      @collections_by_meeting_urn.each do |meeting_urn, entry|
+        next if @meetings_by_urn.key?(meeting_urn)
+
+        errors << LinkError.new(entry.file, entry.line, "metadata.meeting_urn", meeting_urn,
+                                "no matching Meeting")
+      end
+    end
+
+    # ---- Shape predicates (MECE) --------------------------------------
+    #
+    # The three predicates partition the universe of edoxen YAML
+    # shapes that participate in cross-document URN linking. Files
+    # that match none of them (e.g. MeetingSeries, random `_data/*.yaml`)
+    # are silently skipped.
+
+    # A MeetingCollection wraps its meetings under a top-level
+    # `meetings:` array. Its own top level carries no `identifier` or
+    # `type`, so this predicate is disjoint from `meeting_shape?`.
+    def meeting_collection_shape?(data)
+      data["meetings"].is_a?(Array)
+    end
+
+    # A standalone Meeting carries `identifier` (array) and `type`.
+    # MeetingSeries has `identifier` + `kind` (no `type`), so it is
+    # correctly excluded — MeetingSeries does not yet participate in
+    # cross-document URN linking.
+    def meeting_shape?(data)
+      data["identifier"].is_a?(Array) && data.key?("type")
+    end
+
+    # A DecisionCollection carries `decisions` or `resolutions`. The
+    # earlier `metadata.is_a?(Hash)` branch was too permissive — it
+    # matched any file with a top-level `metadata:` key, including
+    # unrelated YAML. A real DecisionCollection always has one of the
+    # two collection keys.
+    def decision_collection_shape?(data)
+      data["decisions"].is_a?(Array) || data["resolutions"].is_a?(Array)
+    end
+
+    # ---- Indexers -----------------------------------------------------
+
+    # Index each nested meeting that satisfies `meeting_shape?` — the
+    # same bar applied to standalone meeting files — so a malformed
+    # entry carrying only a `urn` cannot make a dangling link appear
+    # to resolve. Duplicate URNs are reported via `register_meeting`.
+    def index_meeting_collection(data, file, line_map, errors)
+      data["meetings"].each_with_index do |meeting, idx|
+        next unless meeting.is_a?(Hash) && meeting_shape?(meeting)
+        next unless meeting["urn"]
+
+        line = line_of(line_map, "/meetings/#{idx}/urn")
+        register_meeting(meeting["urn"], file, line, "meetings[#{idx}].urn", errors)
+      end
+    end
+
+    def index_decision_collection(data, file, line_map)
+      meeting_urn = data.dig("metadata", "meeting_urn")
+      return unless meeting_urn
+
+      line = line_of(line_map, "/metadata/meeting_urn")
+      @collections_by_meeting_urn[meeting_urn] = IndexEntry.new(file, line)
+    end
+
+    # Record a Meeting#urn → file/line entry. A second claim on the
+    # same URN is reported as a duplicate-URN error and the index
+    # keeps the first claim (so dangling-link reports point at the
+    # authoritative source, not the most-recent overwrite).
+    def register_meeting(urn, file, line, pointer, errors)
+      prior = @meetings_by_urn[urn]
+      if prior
+        errors << LinkError.new(file, line, pointer, urn,
+                                "duplicate Meeting URN (first seen at #{prior.file}:#{prior.line})")
+        return
+      end
+
+      @meetings_by_urn[urn] = IndexEntry.new(file, line)
+    end
+
+    # ---- Helpers ------------------------------------------------------
+
+    def line_of(line_map, json_pointer)
+      SchemaValidator::LineMap.locate(json_pointer, line_map).first
+    end
+
+    def safe_load_yaml(content)
+      YAML.safe_load(content, permitted_classes: [Date, Time])
+    rescue Psych::Exception, ArgumentError
+      nil
+    end
+  end
+end

data/lib/edoxen/localized_name.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # One language-specific value of a translatable Name field.
+  # Mirrors LocalizedString but carries a structured Name value rather
+  # than a plain String.
+  #
+  # Use case: a single Contact can be known by different names in
+  # different languages — `张建方` (zho-Hans) and `Jianfang Zhang`
+  # (acadsin:zho-Hani:Latn:2002 Pinyin romanization) are the same person.
+  class LocalizedName < Lutaml::Model::Serializable
+    attribute :spelling, :string
+    attribute :value, Name
+    attribute :extensions, MeetingExtension, collection: true
+  end
+end

data/lib/edoxen/localized_string.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # One language-specific value of a translatable String field.
+  # Replaces the v2.x pattern of a separate MeetingLocalization/
+  # Localization/ComponentLocalization object that duplicated the
+  # entity's translatable fields.
+  #
+  # `spelling` is an ISO 24229 spelling/conversion system code:
+  #   - Spelling system:   {lang}-{script}[-{country}][-{extension}]
+  #                        e.g. `eng`, `zho-Hans`, `ind-Latn-pre1972`
+  #   - Conversion system: {authority}:{source}:{target}:{identifying}
+  #                        e.g. `acadsin:zho-Hani:Latn:2002`
+  #
+  # Always verbose — single-language data uses the same
+  # `[{ spelling, value }]` shape as multi-language data.
+  class LocalizedString < Lutaml::Model::Serializable
+    attribute :spelling, :string
+    attribute :value, :string
+    attribute :extensions, MeetingExtension, collection: true
+  end
+end

data/lib/edoxen/meeting.rb

@@ -1,68 +1,74 @@
 # frozen_string_literal: true
 
 module Edoxen
-  # A single Meeting — the event that produces Resolutions. Carries
-  # identity, time, venue, officers, agenda, schedule, deadlines, and
-  # URN links to one or more ResolutionCollection documents.
+  # A single Meeting (event) — produces Decisions via Motions and Votings.
+  # Carries identity, time, polymorphic venues, officers, agenda, components,
+  # attendance, minutes, and URN links to one or more DecisionCollection
+  # documents.
   #
-  # Meetings and ResolutionCollections are kept as separate documents
-  # and joined by URN (Meeting.resolution_refs ↔
-  # ResolutionCollection.metadata.meeting_urn) because they have
-  # different lifetimes: agendas exist weeks before a meeting;
-  # resolutions only after adoption.
+  # 1.0 (per-field localization, ISO 24229):
+  #   - Removed `localizations[]` collection.
+  #   - Added per-field LocalizedString for title, general_area,
+  #     practical_info, note.
   class Meeting < Lutaml::Model::Serializable
+    include OfficersHost
+
     attribute :identifier, StructuredIdentifier, collection: true
     attribute :urn, :string
     attribute :ordinal, :integer
+    attribute :series_ref, :string
     attribute :type, :string, values: Enums::MEETING_TYPE
     attribute :status, :string, values: Enums::MEETING_STATUS
-    attribute :year, :integer
-
-    attribute :date_range, DateRange
+    attribute :visibility, :string, values: Enums::VISIBILITY
+    attribute :body_type, :string
 
-    attribute :committee, :string
-    attribute :committee_group, :string
+    attribute :title, LocalizedString, collection: true
+    attribute :scheduled_date_range, DateRange
+    attribute :occurred_date_range, DateTimeRange
+    attribute :recurrence, Recurrence
 
-    attribute :venues, Location, collection: true
-    attribute :general_area, :string
+    attribute :venues, Venue, collection: true
+    attribute :general_area, LocalizedString, collection: true
+    attribute :practical_info, LocalizedString, collection: true
     attribute :city, :string
     attribute :country_code, :string
-    attribute :virtual, :boolean
 
-    attribute :chair, Person
-    attribute :secretary, Person
-    attribute :host, :string
+    attribute :committee, :string
+    attribute :committee_group, :string
+
+    attribute :officers, Officer, collection: true
     attribute :hosts, HostRef, collection: true
 
     attribute :source_urls, SourceUrl, collection: true
     attribute :landing_url, :string
     attribute :registration_url, :string
+    attribute :note, LocalizedString, collection: true
+    attribute :contact, Contact
 
     attribute :agenda, Agenda
-    attribute :schedule, ScheduleItem, collection: true
+    attribute :components, MeetingComponent, collection: true
     attribute :deadlines, Deadline, collection: true
 
-    attribute :localizations, MeetingLocalization, collection: true
-    attribute :relations, MeetingRelation, collection: true
-    attribute :resolution_refs, :string, collection: true
+    attribute :attendance, Attendance, collection: true
+    attribute :minutes, Minutes, collection: true
+    attribute :declarations, Declaration, collection: true
 
-    # Lookup by ISO 639-3 language code. Mirrors Resolution#in_language.
-    def in_language(code, fallback: false)
-      match = localizations&.find { |loc| loc.language_code == code.to_s }
-      return match if match
+    # Outcomes (canonical location on Meeting)
+    attribute :decisions, Decision, collection: true
+    attribute :motions, Motion, collection: true
+    attribute :votings, Voting, collection: true
 
-      fallback ? localizations&.first : nil
-    end
-
-    # English when available, else the first declared localization.
-    def primary_localization
-      in_language("eng", fallback: true)
-    end
+    attribute :relations, MeetingRelation, collection: true
+    attribute :extensions, MeetingExtension, collection: true
 
-    # Find an agenda item by label. Returns nil when no agenda or no
-    # matching label.
     def find_agenda_item(label)
       agenda&.find_item(label)
     end
+
+    def city_entry
+      return nil if city.nil? || city.to_s.empty?
+
+      Edoxen::ReferenceData.find_unlocode(city)
+    end
   end
 end

data/lib/edoxen/meeting_collection.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 module Edoxen
-  # Top-level container for many Meetings. Parallel to
-  # ResolutionCollection.
+  # Top-level container for many Meetings. Parallel to DecisionCollection.
   class MeetingCollection < Lutaml::Model::Serializable
     attribute :metadata, MeetingCollectionMetadata
     attribute :meetings, Meeting, collection: true

data/lib/edoxen/meeting_collection_metadata.rb

@@ -2,10 +2,12 @@
 
 module Edoxen
   # Top-level wrapper for many Meetings in a single YAML file. Parallel
-  # to ResolutionCollection. The metadata block carries display-level
+  # to DecisionCollection. The metadata block carries display-level
   # info (title, source); per-meeting identity lives on each Meeting.
   class MeetingCollectionMetadata < Lutaml::Model::Serializable
-    attribute :title, :string
+    include BodyVocabularyHost
+
+    attribute :title, LocalizedString, collection: true
     attribute :source, :string
   end
 end

data/lib/edoxen/meeting_component.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # MeetingComponent — flat sub-event of a Meeting.
+  # Replaces legacy ScheduleItem.
+  #
+  # 1.0 (per-field localization, ISO 24229):
+  #   - Removed `localizations[]` collection.
+  #   - Per-field LocalizedString for title, description, time_label.
+  class MeetingComponent < Lutaml::Model::Serializable
+    include OfficersHost
+
+    attribute :identifier, :string
+    attribute :urn, :string
+    attribute :kind, :string, values: Enums::COMPONENT_KIND
+    # Identifier of the body this component belongs to. Optional;
+    # usually inherited from the parent Meeting.
+    attribute :body_type, :string
+    attribute :title, LocalizedString, collection: true
+    attribute :description, LocalizedString, collection: true
+    attribute :starts_at, :date_time
+    attribute :ends_at, :date_time
+    attribute :time_label, LocalizedString, collection: true
+    attribute :venue_refs, :string, collection: true
+    attribute :officers, Officer, collection: true
+    attribute :agenda_ref, :string
+    attribute :minutes_ref, :string
+    attribute :attendance_refs, :string, collection: true
+    attribute :extensions, MeetingExtension, collection: true
+
+    def duration_seconds
+      return nil unless starts_at && ends_at
+
+      ends_at.to_time - starts_at.to_time
+    end
+  end
+end

data/lib/edoxen/meeting_extension.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # MeetingExtension — the profile mechanism (ISO 8601-2 §15).
+  # Every core entity has an `extensions: MeetingExtension[0..*]` slot.
+  # Adopters register their own profile namespace (e.g. "legco",
+  # "us-congress", "ietf") and define `kind` values within it.
+  #
+  # Field semantics (tightened 1.0, per 1.0 design review):
+  #
+  #   profile    — the profile namespace (lowercase, hyphen-separated).
+  #   kind       — discriminator within the profile.
+  #   ref        — URN of the profile document this extension references.
+  #   attributes — typed key/value pairs (ExtensionAttribute).
+  #
+  # Recursion (`extensions: MeetingExtension[0..*]`) was removed in
+  # 1.0 — no documented use case. Profiles needing nesting can encode
+  # it via dotted keys ("vote.count", "vote.method") in `attributes[]`.
+  class MeetingExtension < Lutaml::Model::Serializable
+    attribute :profile, :string
+    attribute :kind, :string
+    attribute :ref, :string
+    attribute :attributes, ExtensionAttribute, collection: true
+  end
+end

data/lib/edoxen/meeting_identifier.rb

@@ -2,7 +2,7 @@
 
 module Edoxen
   # Identifier of a meeting (venue + date). Singular — the meeting a
-  # particular Resolution belongs to.
+  # particular Decision belongs to.
   class MeetingIdentifier < Lutaml::Model::Serializable
     attribute :venue, :string
     attribute :date, :date

data/lib/edoxen/meeting_series.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # MeetingSeries — parent of recurring Meeting instances.
+  # Crossref `proceedings-series`, IETF meeting series, Apache Board
+  # meetings, etc. Carries a `Recurrence` (ISO 8601-2 §13) rule and
+  # a list of member Meeting URNs.
+  class MeetingSeries < Lutaml::Model::Serializable
+    attribute :identifier, StructuredIdentifier, collection: true
+    # Identifier of the body this series represents (e.g. 'ciml').
+    # Meetings and Decisions belonging to this series inherit the body
+    # via the series_ref join. Optional; most consumers have a single
+    # body and leave this unset.
+    attribute :body_type, :string
+    attribute :urn, :string
+    attribute :name, LocalizedString, collection: true
+    attribute :description, LocalizedString, collection: true
+    attribute :recurrence, Recurrence
+    attribute :term, :string
+    attribute :contact, Contact
+    attribute :hosts, HostRef, collection: true
+    attribute :kind, :string
+    attribute :meeting_refs, :string, collection: true
+    attribute :extensions, MeetingExtension, collection: true
+  end
+end

data/lib/edoxen/minutes.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # The narrative record of a Meeting — what was said, by whom, in
+  # what order, with what outcome. Mirrors
+  # edoxen-model/models/minutes.lutaml (P2.8 from
+  # TODO.meeting-agenda/10-future-enhancements.md).
+  #
+  # Distinct from Agenda (the business order drafted before the
+  # meeting) and from DecisionCollection (the formal decisions
+  # adopted). The Minutes are the running record.
+  #
+  # Sections are typically keyed by agenda-item number so consumers
+  # can join Minutes ↔ AgendaItem ↔ Decision by `number`/`label`.
+  class Minutes < Lutaml::Model::Serializable
+    attribute :identifier, StructuredIdentifier, collection: true
+    attribute :urn, :string
+    attribute :spelling, :string
+    attribute :source_doc, :string
+    attribute :source_pages, :string
+    attribute :sections, MinutesSection, collection: true
+
+    def find_section(number)
+      return nil if number.nil?
+
+      target = number.to_s
+      sections&.find { |s| s.number.to_s == target }
+    end
+  end
+end

data/lib/edoxen/minutes_section.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # One section of a Meeting's minutes — typically tied to an agenda
+  # item by its `number` field. Carries the narrative as Markdown
+  # (the format the GLM-OCR pipeline emits) plus optional page range
+  # for provenance back to the source PDF.
+  #
+  # Localization lives on the parent Minutes document, not on each
+  # section — Minutes has a per-document language_code; the section
+  # lookup is `Minutes#find_section(number)`. Earlier copies of this
+  # class inherited `in_language`/`primary_localization` from
+  # ScheduleItem/Meeting, but those methods referenced an undeclared
+  # `localizations` attribute and raised NameError on every call.
+  # Removed 2026-07-05.
+  class MinutesSection < Lutaml::Model::Serializable
+    attribute :number, :string
+    attribute :title, LocalizedString, collection: true
+    attribute :narrative, LocalizedString, collection: true
+    attribute :page_start, :integer
+    attribute :page_end, :integer
+    attribute :references, Reference, collection: true
+    attribute :statements, Statement, collection: true
+    attribute :topic_ref, :string
+  end
+end

data/lib/edoxen/motion.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Motion — a procedural act that brings a Decision. "I move that..."
+  # Distinct from a Decision (formal outcome) and from a TopicDocument
+  # (written text). A Motion does NOT require any document.
+  #
+  # State machine (MotionStatus):
+  #   introduced → seconded → debating → question_put → voting
+  #                                                ├── carried → resulting_decision set
+  #                                                ├── negatived
+  #                                                ├── withdrawn
+  #                                                └── lapsed
+  class Motion < Lutaml::Model::Serializable
+    attribute :identifier, :string
+    attribute :urn, :string
+    attribute :text, LocalizedString, collection: true
+    attribute :mover, Person
+    attribute :seconders, Person, collection: true
+    attribute :status, :string, values: Enums::MOTION_STATUS
+    attribute :introduced_at, :date_time
+    attribute :proposed_decision, :string
+    attribute :resulting_decision, :string
+    # Pilot EntityRef field (1.0, 1.0 design review). Parallel to
+    # `resulting_decision` (String). Prefer the typed form in new code;
+    # the bare String form is removed in 1.0.
+    attribute :resulting_decision_ref, EntityRef
+    attribute :votings, :string, collection: true
+    attribute :extensions, MeetingExtension, collection: true
+
+    def carried?
+      status == "carried"
+    end
+
+    def pending?
+      status && !Enums::MOTION_TERMINAL.include?(status)
+    end
+
+    # --- 1.0 derivation accessor (1.0 design review) --------------------
+    # Storage side: Voting.on_motion (SSOT for the Motion→Voting
+    # relationship). This computed method returns the Voting instances
+    # in `meeting` whose `on_motion` points at this Motion's URN.
+    # The stored `votings[]` field remains on the wire for back-compat
+    # through v2.x; 1.0 removes it and this becomes the only path.
+    def votings_in(meeting:)
+      return [] unless meeting && urn
+
+      meeting.votings.select { |voting| voting.on_motion == urn }
+    end
+  end
+end

data/lib/edoxen/name.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Structured personal/organisational name. VCARD conventions
+  # (RFC 6350): separate structured components (N) from a pre-formatted
+  # display string (FN). Either or both may be populated.
+  #
+  # `formatted` is the display string when callers have it pre-built;
+  # the structured fields (`family`, `given`, `additional`, `prefix`,
+  # `suffix`) let adopters store parsed components for sorting, indexing,
+  # or locale-aware rendering.
+  class Name < Lutaml::Model::Serializable
+    attribute :formatted, :string
+    attribute :family, :string
+    attribute :given, :string
+    attribute :additional, :string
+    attribute :prefix, :string
+    attribute :suffix, :string
+    attribute :extensions, MeetingExtension, collection: true
+
+    # Convenience: returns `formatted` if present, else builds one from
+    # the structured components. Useful for callers that always want a
+    # display string regardless of how the name was authored.
+    def display
+      formatted || [prefix, given, additional, family, suffix]
+        .reject { |s| s.to_s.empty? }.join(" ")
+    end
+  end
+end

data/lib/edoxen/officer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Officer — a person holding a structural role in a Meeting.
+  # Replaces legacy Meeting#chair and Meeting#secretary direct shortcuts.
+  # One list, role discriminates. Open for adopter extension via `other`.
+  class Officer < Lutaml::Model::Serializable
+    attribute :role, :string, values: Enums::OFFICER_ROLE
+    attribute :person, Person
+    attribute :term_start, :date
+    attribute :term_end, :date
+    attribute :extensions, MeetingExtension, collection: true
+
+    def current?(date = Date.today)
+      (term_start.nil? || date >= term_start) &&
+        (term_end.nil? || date <= term_end)
+    end
+  end
+end

data/lib/edoxen/officers_host.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Mixed into entities that carry an `officers` collection. Provides
+  # `officers_with_role(role)` and the `chair` accessor so Meeting and
+  # MeetingComponent share a single implementation.
+  #
+  # The including class must declare an `officers` attribute whose
+  # entries expose `role` and `person`.
+  module OfficersHost
+    def officers_with_role(role)
+      (officers || []).select { |o| o.role == role.to_s }
+    end
+
+    def chair
+      officers_with_role("chair").first&.person
+    end
+  end
+end