edoxen 0.7.2 → 2.1.1

data/lib/edoxen/{resolution_metadata.rb → decision_metadata.rb}

@@ -4,7 +4,9 @@ module Edoxen
   # Collection-level metadata: the title (string for default / single-language
   # collections, or `title_localized[]` for multilingual), the meeting date,
   # the source secretariat, per-language source PDFs, and the host venue.
-  class ResolutionMetadata < Lutaml::Model::Serializable
+  class DecisionMetadata < Lutaml::Model::Serializable
+    include BodyVocabularyHost
+
     attribute :title, :string
     attribute :title_localized, Localization, collection: true
     attribute :date, :date
@@ -14,13 +16,10 @@ module Edoxen
     attribute :country_code, :string
 
     # URN back-reference to the Meeting that produced this collection.
-    # Join key for the Meeting ↔ ResolutionCollection link. Optional —
-    # collections without a parent meeting (e.g., ad-hoc resolution
-    # sets) simply omit it.
     attribute :meeting_urn, :string
 
-    # Resolve the collection's host-city UN/LOCODE via the canonical
-    # `unlocode` gem registry. Returns an `Unlocodes::Entry` or nil.
+    attribute :extensions, MeetingExtension, collection: true
+
     def city_entry
       return nil if city.nil? || city.to_s.empty?
 

data/lib/edoxen/decision_relation.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Directed relation between two decisions, identified by their
+  # StructuredIdentifier (prefix + number).
+  class DecisionRelation < Lutaml::Model::Serializable
+    attribute :source, StructuredIdentifier
+    attribute :destination, StructuredIdentifier
+    attribute :type, :string, values: Enums::DECISION_RELATION_TYPE
+  end
+end

data/lib/edoxen/entity_ref.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # EntityRef — a typed cross-reference between entities (v2.1, TODO.refactor/44).
+  #
+  # Single identity: exactly one of `urn`, `identifier`, or `local_ref`
+  # must be set. Optional metadata: `kind`, `role`, `note`.
+  #
+  # Encapsulation:
+  #   - Read the identity via `#resolved_identity` (returns the canonical
+  #     form — URN string, StructuredIdentifier, or local key).
+  #   - Validate via `#valid?` (true when exactly one identity field is
+  #     set; `#multiple_identities?` flags the rare ambiguous case).
+  #
+  # Pilot: `Motion.resulting_decision_ref` (parallel to the existing
+  # `resulting_decision: String`). v3.0 will remove the String form.
+  class EntityRef < Lutaml::Model::Serializable
+    attribute :urn, :string
+    attribute :identifier, StructuredIdentifier
+    attribute :local_ref, :string
+
+    attribute :kind, :string
+    attribute :role, :string
+    attribute :note, :string
+
+    # True when exactly one identity field is set. The wire contract
+    # (TODO.refactor/44 + JSON-Schema) is XOR: setting 0 or ≥2 identity
+    # fields is a data error.
+    def valid?
+      identities_set.size == 1
+    end
+
+    # True when two or more identity fields are set. Useful for
+    # migration tooling that wants to warn on ambiguity without
+    # rejecting outright.
+    def multiple_identities?
+      identities_set.size > 1
+    end
+
+    # Returns the canonical identity (URN > identifier > local_ref
+    # precedence). Callers that need a single value should validate
+    # first via `#valid?`; on a multiple-identity ref the precedence
+    # is still applied but the data is suspect.
+    def resolved_identity
+      return urn if urn && !urn.to_s.empty?
+      return identifier if identifier
+      return local_ref if local_ref && !local_ref.to_s.empty?
+
+      nil
+    end
+
+    def to_s
+      identity = resolved_identity
+      return "(invalid EntityRef)" unless identity
+
+      case identity
+      when StructuredIdentifier then "#{identity.prefix}/#{identity.number}"
+      else identity.to_s
+      end
+    end
+
+    private
+
+    def identities_set
+      [urn, identifier, local_ref].reject do |value|
+        case value
+        when nil then true
+        when String then value.empty?
+        else false
+        end
+      end
+    end
+  end
+end

data/lib/edoxen/enums.rb

@@ -26,13 +26,37 @@ module Edoxen
       emphasizing concerned accepts observing referring acting empowers
     ].freeze
 
-    RESOLUTION_TYPE = %w[resolution recommendation decision declaration].freeze
+    # --- Decision-side (was Resolution; renamed 2026-07) -----------------
+
+    # DecisionKind — what kind of formal outcome this is. `resolution` is
+    # one value; the same formal concept has many names across bodies
+    # (order, ruling, determination, finding, opinion, etc.).
+    DECISION_KIND = %w[
+      resolution order ruling determination
+      recommendation statement finding opinion other
+    ].freeze
+
+    # DecisionKindCanonical — the short abstract set (v2.1, TODO.refactor/46).
+    # Bodies extend via `body_type: String` + per-dataset `body_vocabulary[]`
+    # on DecisionMetadata. `other` is a temporary escape while the
+    # vocabulary stabilises; v3.0 removes it.
+    #
+    # Cap: 5 canonical values (hard limit per the v2.1 design review).
+    DECISION_KIND_CANONICAL = %w[decision recommendation statement finding other].freeze
+
+    # DecisionStatus — lifecycle state machine.
+    DECISION_STATUS = %w[
+      draft proposed under_consideration
+      decided negatived withdrawn deferred
+    ].freeze
 
-    RESOLUTION_RELATION_TYPE = %w[
-      annexOf hasAnnex updates refines replaces considers
+    DECISION_RELATION_TYPE = %w[
+      annex_of has_annex updates refines replaces considers cites
     ].freeze
 
-    RESOLUTION_DATE_TYPE = %w[adoption drafted discussed].freeze
+    DECISION_DATE_TYPE = %w[
+      adoption drafted discussed proposed decided negatived withdrawn published effective
+    ].freeze
 
     APPROVAL_TYPE = %w[affirmative negative].freeze
 
@@ -44,31 +68,115 @@ module Edoxen
     # Mirrors edoxen-model/models/{meeting,agenda,...}_*.lutaml.
     # schema/meeting.yaml references these via $defs/<EnumName>.enum.
 
-    MEETING_TYPE = %w[plenary working_group task_group ad_hoc joint conference_session].freeze
+    MEETING_TYPE = %w[
+      plenary working_group task_group ad_hoc joint general_assembly
+      committee subcommittee conference workshop seminar webinar hearing
+      markup board_meeting annual_general_meeting other
+    ].freeze
+
+    # MeetingTypeCanonical — the short abstract set (v2.1, TODO.refactor/46).
+    # Bodies extend via `body_type: String` + per-dataset `body_vocabulary[]`
+    # on MeetingCollectionMetadata.
+    #
+    # Cap: 4 canonical values (no `other` — bodies pick the closest fit).
+    MEETING_TYPE_CANONICAL = %w[plenary governing working advisory].freeze
 
     MEETING_STATUS = %w[upcoming completed cancelled].freeze
 
     AGENDA_STATUS = %w[draft final amended cancelled superseded].freeze
 
-    AGENDA_ITEM_KIND = %w[numbered unnumbered header opening closing].freeze
+    AGENDA_ITEM_KIND = %w[numbered unnumbered header opening closing aob].freeze
 
-    AGENDA_ITEM_OUTCOME = %w[discussed resolved deferred adopted withdrawn].freeze
+    AGENDA_ITEM_OUTCOME = %w[discussed resolved deferred adopted withdrawn carried negatived].freeze
 
     HOST_TYPE = %w[national_body liaison associate organizer].freeze
 
     MEETING_RELATION_TYPE = %w[
       continues_from continues_to joint_with supersedes superseded_by rescheduled_from rescheduled_to
+      parent_of child_of sibling_of depends_on
+      finish_to_start finish_to_finish start_to_start start_to_finish
     ].freeze
 
     SOURCE_URL_KIND = %w[
-      agenda_pdf minutes_pdf resolutions_pdf report_pdf register_url landing_page
+      agenda_pdf minutes_pdf decisions_pdf report_pdf register_url landing_page
     ].freeze
 
-    # P2.6 / P2.7 — Attendance and Vote records.
     PARTICIPATION_STATUS = %w[present absent apologies observer excused].freeze
 
     VOTE_TYPE = %w[
       affirmative negative abstain absent not_applicable
     ].freeze
+
+    # --- New in v2.0 (broadened scope) -----------------------------------
+
+    VENUE_KIND = %w[physical virtual].freeze
+
+    VIRTUAL_FEATURE = %w[audio video chat phone screen feed].freeze
+
+    VISIBILITY = %w[public private confidential].freeze
+
+    ATTENDANCE_ROLE = %w[chair required optional non_participant].freeze
+
+    # iCalendar PARTSTAT, plain English (no jargon).
+    ATTENDANCE_RESPONSE = %w[
+      pending confirmed declined tentative delegated
+    ].freeze
+
+    COMPONENT_KIND = %w[
+      track session debate breakout bof
+      plenary_session working_group_session committee_of_the_whole
+      keynote address statement question_time
+      opening closing break reception registration networking other
+    ].freeze
+
+    # ComponentKindCanonical — the short abstract set (v2.1, TODO.refactor/46).
+    # `other` is a temporary escape while the vocabulary stabilises.
+    #
+    # Cap: 5 canonical values.
+    COMPONENT_KIND_CANONICAL = %w[deliberative working ceremonial break other].freeze
+
+    MOTION_STATUS = %w[
+      introduced seconded debating question_put voting
+      carried negatived withdrawn lapsed
+    ].freeze
+
+    # Terminal MotionStatus values — `Motion#pending?` is the complement.
+    # Kept as a separate constant (not derived) because the partition is
+    # semantic, not lexical; the spec in motion_spec.rb asserts the union
+    # equals MOTION_STATUS and the intersection is empty (MECE).
+    MOTION_TERMINAL = %w[carried negatived withdrawn lapsed].freeze
+
+    VOTING_STATUS = %w[called in_progress decided withdrawn deferred].freeze
+
+    VOTING_METHOD = %w[
+      voice division show_of_hands roll_call electronic
+      secret_ballot unanimous_consent consensus
+    ].freeze
+
+    VOTING_OUTCOME = %w[passed negatived tied withdrawn].freeze
+
+    TOPIC_STATUS = %w[open under_discussion decided deferred withdrawn].freeze
+
+    OFFICER_ROLE = %w[
+      chair vice_chair deputy_chair secretary treasurer
+      parliamentarian presiding_officer sergeant_at_arms other
+    ].freeze
+
+    RECURRENCE_FREQ = %w[
+      secondly minutely hourly daily weekly monthly yearly
+    ].freeze
+
+    # Polymorphic communication channel. OCP: adding a new kind does
+    # not change the model — only this enum (or use `other` + extensions).
+    CONTACT_METHOD_KIND = %w[
+      phone mobile fax email url mail pager message other
+    ].freeze
+
+    # Polymorphic external identifier for a Contact (ORCID, ISNI,
+    # Wikidata, ROR, etc.). OCP: adding a new scheme only extends this
+    # enum (or use `other` + extensions).
+    CONTACT_IDENTIFIER_KIND = %w[
+      orcid isni wikidata ror ringgold github other
+    ].freeze
   end
 end

data/lib/edoxen/error.rb

@@ -7,7 +7,7 @@ module Edoxen
   # Unified validation failure shape. Produced by both:
   #   * SchemaValidator — JSON-Schema violations and YAML syntax errors
   #     carry source: :schema (or :syntax for Psych::SyntaxError).
-  #   * ResolutionCollection.from_yaml rescues in the CLI — model parse
+  #   * DecisionCollection.from_yaml rescues in the CLI — model parse
   #     failures carry source: :model.
   #
   # One type at the seam means callers (CLI, future renderers, tests)

data/lib/edoxen/extension_attribute.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # ExtensionAttribute — one typed key/value pair within a
+  # MeetingExtension. Polymorphic on value type so consumers don't
+  # have to re-parse strings back into Int/Float/Bool/Date.
+  #
+  # Wire form (v2.1+, per TODO.refactor/47):
+  #
+  #   - key: "quorum"
+  #     type: "integer"
+  #     intValue: 7
+  #
+  #   - key: "name"
+  #     type: "string"
+  #     value: "quic"      # string variant uses bare `value` (v2.0 wire)
+  #
+  #   - key: "start"
+  #     type: "datetime"
+  #     dateTimeValue: 2026-07-04T10:00:00Z
+  #
+  # The `type` discriminator tells consumers which value field to read
+  # without probing all six. Exactly one of the value fields should be
+  # set; the schema enforces this.
+  #
+  # String values use the bare `value:` wire name for back-compat with
+  # v2.0 fixtures. Typed variants (integer/float/boolean/date/datetime)
+  # use camelCase wire names. The gem unifies them behind `#typed_value`.
+  class ExtensionAttribute < Lutaml::Model::Serializable
+    attribute :key, :string
+
+    # String variant — Ruby attribute is `value`, wire name is `value`
+    # (matches v2.0; `type: "string"` discriminator added in v2.1).
+    attribute :value, :string
+
+    # Typed variants — added in v2.1.
+    attribute :integer_value, :integer
+    attribute :float_value, :float
+    attribute :boolean_value, :boolean
+    attribute :date_value, :date
+    attribute :date_time_value, :date_time
+
+    # Wire discriminator: "string" | "integer" | "float" | "boolean" |
+    # "date" | "datetime". Tells consumers which value field to read.
+    attribute :type, :string
+
+    key_value do
+      map "key", to: :key
+      map "type", to: :type
+      map "value", to: :value
+      map "intValue", to: :integer_value
+      map "floatValue", to: :float_value
+      map "booleanValue", to: :boolean_value
+      map "dateValue", to: :date_value
+      map "dateTimeValue", to: :date_time_value
+    end
+
+    # Convenience: read whichever typed value is set. Returns nil when
+    # none of the value fields is populated.
+    def typed_value
+      case type
+      when "integer"  then integer_value
+      when "float"    then float_value
+      when "boolean"  then boolean_value unless boolean_value.nil?
+      when "date"     then date_value
+      when "datetime" then date_time_value
+      else
+        # Default to string for back-compat with v2.0 (no `type`).
+        value
+      end
+    end
+
+    # Back-compat alias — v2.1 introduced `value` as the canonical Ruby
+    # attribute; the older `string_value` alias keeps callers that
+    # already migrated to that name working.
+    alias string_value value
+  end
+end

data/lib/edoxen/host_ref.rb

@@ -9,6 +9,6 @@ module Edoxen
     attribute :ref, :string
     attribute :type, :string, values: Enums::HOST_TYPE
     attribute :role, :string
-    attribute :contact, Person
+    attribute :contact, Contact
   end
 end

data/lib/edoxen/link_checker.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
 module Edoxen
-  # Walks a directory tree of Meeting and ResolutionCollection YAML
+  # 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 referenced by exactly one
-  #     ResolutionCollection#metadata.meeting_urn (if the collection
+  #     DecisionCollection#metadata.meeting_urn (if the collection
   #     exists in the scanned directory).
-  #   * Every ResolutionCollection#metadata.meeting_urn (if set)
+  #   * 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
@@ -24,7 +24,7 @@ module Edoxen
     end
 
     # Walk `dir` (recursive scan of *.yaml and *.yml), classify each
-    # file as Meeting or ResolutionCollection, and assert every
+    # file as Meeting or DecisionCollection, and assert every
     # cross-document URN resolves to a real record.
     #
     # @return [Array<LinkError>] empty when all links resolve.
@@ -41,7 +41,7 @@ module Edoxen
     def check
       require "yaml"
 
-      Dir.glob(File.join(@dir, "**", "*.{yaml,yml}")).sort.each do |file|
+      Dir.glob(File.join(@dir, "**", "*.{yaml,yml}")).each do |file|
         data = safe_load_yaml(file)
         next unless data.is_a?(Hash)
 
@@ -56,7 +56,7 @@ module Edoxen
 
       errors = []
 
-      # ResolutionCollection → Meeting
+      # DecisionCollection → Meeting
       @collections_by_meeting_urn.each do |meeting_urn, file|
         next if @meetings_by_urn.key?(meeting_urn)
 
@@ -69,7 +69,7 @@ module Edoxen
     private
 
     def safe_load_yaml(file)
-      YAML.safe_load(File.read(file))
+      YAML.safe_load_file(file)
     rescue Psych::SyntaxError, ArgumentError
       nil
     end
@@ -79,7 +79,7 @@ module Edoxen
     end
 
     def collection_shape?(data)
-      data["resolutions"].is_a?(Array) || data["metadata"].is_a?(Hash)
+      data["decisions"].is_a?(Array) || data["resolutions"].is_a?(Array) || data["metadata"].is_a?(Hash)
     end
   end
 end

data/lib/edoxen/localization.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module Edoxen
-  # A monolingual rendering of a Resolution. Mirrors the glossarist
+  # A monolingual rendering of a Decision. Mirrors the glossarist
   # LocalizedConcept pattern: language-agnostic fields live on the
-  # parent Resolution; per-language content lives here.
+  # parent Decision; per-language content lives here.
   class Localization < Lutaml::Model::Serializable
     attribute :language_code, :string
     attribute :script, :string

data/lib/edoxen/localization_host.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Mixed into entities that carry a per-language `localizations[]`
+  # collection. Provides `in_language(code, fallback:)` and
+  # `primary_localization` in one place so Decision, Meeting, etc.
+  # share a single implementation.
+  #
+  # The including class must declare a typed `localizations` attribute
+  # whose entries expose `language_code` (ISO 639-3).
+  module LocalizationHost
+    def in_language(code, fallback: false)
+      match = localizations&.find { |loc| loc.language_code == code.to_s }
+      return match if match
+
+      fallback ? localizations&.first : nil
+    end
+
+    def primary_localization
+      in_language("eng", fallback: true)
+    end
+  end
+end

data/lib/edoxen/meeting.rb

@@ -1,82 +1,106 @@
 # 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.
+  # Meetings and DecisionCollections are kept as separate documents and
+  # joined by URN because they have different lifetimes: agendas exist
+  # weeks before a meeting; decisions only after adoption.
   class Meeting < Lutaml::Model::Serializable
+    include LocalizationHost
+    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 :visibility, :string, values: Enums::VISIBILITY
+    # v2.1 (TODO.refactor/46): free-form body-specific label (e.g.
+    # "CIML Meeting", "Plenary", "Board Meeting"). Resolves to a short
+    # canonical value via the parent collection's `body_vocabulary[]`.
+    attribute :body_type, :string
 
     attribute :date_range, DateRange
+    attribute :recurrence, Recurrence
 
-    attribute :committee, :string
-    attribute :committee_group, :string
-
-    attribute :venues, Location, collection: true
+    attribute :venues, Venue, collection: true
     attribute :general_area, :string
     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, :string
+    attribute :contact, Contact
 
     attribute :agenda, Agenda
-    attribute :schedule, ScheduleItem, collection: true
+    attribute :components, MeetingComponent, collection: true
     attribute :deadlines, Deadline, collection: true
 
     attribute :attendance, Attendance, collection: true
-    attribute :vote_records, VoteRecord, collection: true
     attribute :minutes, Minutes, collection: true
 
+    # Outcomes (canonical location on Meeting)
+    attribute :decisions, Decision, collection: true
+    attribute :motions, Motion, collection: true
+    attribute :votings, Voting, collection: true
+
     attribute :localizations, MeetingLocalization, collection: true
     attribute :relations, MeetingRelation, collection: true
-    attribute :resolution_refs, :string, 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
-
-      fallback ? localizations&.first : nil
-    end
+    attribute :extensions, MeetingExtension, collection: true
 
-    # English when available, else the first declared localization.
-    def primary_localization
-      in_language("eng", fallback: true)
-    end
-
-    # 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
 
-    # Resolve the meeting's UN/LOCODE via the canonical `unlocode` gem
-    # registry. Returns an `Unlocodes::Entry` (with `#name`, `#country`,
-    # `#coordinates`, `#iata`, `#functions`, etc.) or nil when the
-    # city field is empty / not in the registry.
+    # Resolve the meeting's UN/LOCODE via the canonical `unlocode` gem.
     def city_entry
       return nil if city.nil? || city.to_s.empty?
 
       Edoxen::ReferenceData.find_unlocode(city)
     end
+
+    def secretary
+      officers_with_role("secretary").first&.person
+    end
+
+    # All physical venues (polymorphic Venue filter).
+    def physical_venues
+      venues_by_kind("physical")
+    end
+
+    def virtual_venues
+      venues_by_kind("virtual")
+    end
+
+    def hybrid?
+      !physical_venues.empty? && !virtual_venues.empty?
+    end
+
+    def virtual_only?
+      !virtual_venues.empty? && physical_venues.empty?
+    end
+
+    def physical_only?
+      !physical_venues.empty? && virtual_venues.empty?
+    end
+
+    private
+
+    def venues_by_kind(kind)
+      (venues || []).select { |v| v.kind == kind }
+    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,9 +2,11 @@
 
 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
+    include BodyVocabularyHost
+
     attribute :title, :string
     attribute :source, :string
   end