edoxen 0.5.0 → 0.8.1

data/lib/edoxen/person.rb

@@ -1,14 +1,10 @@
 # frozen_string_literal: true
 
 module Edoxen
-  # Identity + role + affiliation + contact. Used for meeting officers
-  # (chair, secretary, local contact) and host-ref contacts.
-  class Person < Lutaml::Model::Serializable
-    attribute :name, :string
-    attribute :role, :string
-    attribute :affiliation, :string
-    attribute :email, :string
-    attribute :phone, :string
-    attribute :orcid, :string
+  # A Contact that is specifically an individual human. Inherits all
+  # Contact fields. The old `email`, `phone`, and `orcid` fields are
+  # replaced by entries in `contact_methods` (kind=email / kind=phone)
+  # and `identifiers` (kind=orcid).
+  class Person < Contact
   end
 end

data/lib/edoxen/physical_venue.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # PhysicalVenue — type marker for a Venue with kind == "physical".
+  #
+  # The wire format is flat on Venue (all fields live there). This
+  # subclass exists for type-checking and to host physical-only helpers
+  # so callers can ask `venue.is_a?(PhysicalVenue)` and validators
+  # can dispatch by type.
+  class PhysicalVenue < Venue
+    def initialize(attributes = {})
+      super(attributes.merge(kind: "physical"))
+    end
+  end
+end

data/lib/edoxen/recurrence.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Recurrence — structured representation of ISO 8601-2 §13 recurring
+  # time intervals. QUERYABLE (each BYxxx part is its own attribute).
+  #
+  # Round-trip to/from ISO 8601-2 wire string is handled by adapters
+  # in ReferenceData (NOT hand-rolled to_h — declared via lutaml-model
+  # mapping).
+  class Recurrence < Lutaml::Model::Serializable
+    attribute :freq, :string, values: Enums::RECURRENCE_FREQ
+    attribute :interval, :integer, default: 1
+    attribute :count, :integer
+    attribute :until, :date_time
+    attribute :by_day, RecurrenceByDay, collection: true
+    attribute :by_month_day, :integer, collection: true
+    attribute :by_month, :integer, collection: true
+    attribute :by_week_no, :integer, collection: true
+    attribute :by_year_day, :integer, collection: true
+    attribute :by_hour, :integer, collection: true
+    attribute :by_minute, :integer, collection: true
+    attribute :by_second, :integer, collection: true
+    attribute :by_set_pos, :integer, collection: true
+    attribute :week_start, :string, default: "MO"
+    attribute :extensions, MeetingExtension, collection: true
+  end
+end

data/lib/edoxen/recurrence_by_day.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # RecurrenceByDay — a BYDAY part of an ISO 8601-2 §13 recurrence.
+  # `ordinal` is null for "every", +1 for "first", -1 for "last", etc.
+  class RecurrenceByDay < Lutaml::Model::Serializable
+    attribute :ordinal, :integer
+    attribute :weekday, :string
+  end
+end

data/lib/edoxen/reference.rb

@@ -8,6 +8,6 @@ module Edoxen
   class Reference < Lutaml::Model::Serializable
     attribute :ref, :string
     attribute :kind, :string
-    attribute :title, :string
+    attribute :title, LocalizedString, collection: true
   end
 end

data/lib/edoxen/reference_data.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Built-in reference data for ISO codes used across the Edoxen model:
+  # ISO 3166-1 alpha-2 country codes, ISO 639-3 language codes, ISO
+  # 15924 script codes, UN/LOCODEs, and IATA airport codes.
+  #
+  # UN/LOCODE lookups delegate to the `unlocodes` gem (the canonical
+  # Ruby registry of the UNECE UN/LOCODE dataset).
+  # IATA lookups delegate to the `iata` gem (the canonical Ruby registry
+  # of the IATA airport code list, sourced from Wikidata).
+  #
+  # Reference data sources:
+  # * https://www.iso.org/iso-3166-country-codes.html
+  # * https://iso639-3.sil.org/
+  # * https://unicode.org/iso15924/
+  # * https://unece.org/trade/cefact/unlocode-code-list-country-and-territory
+  # * https://www.wikidata.org/wiki/Property:P238 (IATA airport code)
+  module ReferenceData
+    require "unlocodes"
+    require "iata"
+
+    COUNTRY_CODES = %w[
+      AE AF AR AT AU BE BG BR BY CA CH CL CN CO CY CZ DE DK EE ES FI FR
+      GB GR HK HR HU ID IE IL IN IS IT JP KE KR LK LT LU LV MT MX MY NL NO PH
+      NZ PL PT RO RS RU SA SE SG SI SK TH TN TR TW UA US VN ZA
+    ].freeze
+
+    LANGUAGE_CODES = %w[
+      ara chi deu eng fra jpn rus spa zho
+    ].freeze
+
+    SCRIPT_CODES = %w[
+      Arab Cyrl Hans Hant Hang Hebr Jpan Kore Latn
+    ].freeze
+
+    UNLOCODES = %w[
+      AUMEL ATVIE BEBRU BGSOF BRBSB CHGVA CNCAN CNHKG CNSHA CNXSZ COCTG
+      CYLCA CZPRG DEBER DEHAM DEFRA DKCPH ESMAD FIHEL FRARC FRLYS FRMRS
+      FRPAR GBLON HKHKG HUBUD IDJKT IEDUB IEORK ILTLV INDEL ISREY ITROM
+      JPTYO KEMBA KRSEL LKCMB LVRIX LULUX MYKUL NLRTM NOOSL NZAKL PHMNL
+      PLWAW PTLIS ROBUH RSBEG SESTO SGSIN SKBTS THBKK THCNM TRIST TWTPE
+      UAIEV USMIA USNYC USORL VNSGN ZACPT
+    ].freeze
+
+    # Memoise the registries so we don't re-parse the bundled datasets on
+    # every lookup. Each gem's Registry is immutable after construction.
+    @unlocodes_registry = nil
+    @iata_registry = nil
+
+    class << self
+      # @return [Unlocodes::Registry]
+      def unlocodes_registry
+        @unlocodes_registry ||= Unlocodes::Registry.load_default
+      end
+
+      # @return [Iata::Registry]
+      def iata_registry
+        @iata_registry ||= Iata::Registry.load_default
+      end
+
+      # Look up a UN/LOCODE entry via the canonical `unlocodes` gem.
+      # @param code [String, #to_s] 5-character UN/LOCODE
+      # @return [Unlocodes::Entry, nil]
+      def find_unlocode(code)
+        unlocodes_registry.find(code.to_s.upcase)
+      end
+
+      def unlocode_exists?(code)
+        !find_unlocode(code).nil?
+      end
+
+      # Look up an IATA airport/city code via the canonical `iata` gem.
+      # @param code [String, #to_s] 3-character IATA code
+      # @return [Iata::Entry, nil]
+      def find_iata(code)
+        iata_registry.find(code.to_s.upcase)
+      end
+
+      def iata_exists?(code)
+        !find_iata(code).nil?
+      end
+    end
+  end
+end

data/lib/edoxen/schema_validator.rb

@@ -9,7 +9,7 @@ module Edoxen
   # The SchemaValidator is intentionally small and only owns one concern:
   # JSON-Schema validation with line-accurate error reporting. It does not
   # touch the Ruby model — CLI layers SchemaValidator and
-  # `ResolutionCollection.from_yaml` to catch both schema-level violations
+  # `DecisionCollection.from_yaml` to catch both schema-level violations
   # (additionalProperties, required, enum) and structural issues
   # (numeric/date coercion, missing nested classes) the schema can't express.
   #
@@ -72,7 +72,7 @@ module Edoxen
     end
 
     def load_schemer(path)
-      JSONSchemer.schema(YAML.safe_load(File.read(path), permitted_classes: [Date, Time]))
+      JSONSchemer.schema(YAML.safe_load_file(path, permitted_classes: [Date, Time]))
     end
 
     # Coerce Date/Time instances back to ISO strings before handing the
@@ -81,8 +81,7 @@ module Edoxen
     # here keeps the gem OCP-compliant (no json_schemer plugin/tweak).
     def normalize_dates(value)
       case value
-      when Date then value.iso8601
-      when Time then value.iso8601
+      when Date, Time then value.iso8601
       when Hash then value.transform_values { |v| normalize_dates(v) }
       when Array then value.map { |v| normalize_dates(v) }
       else value

data/lib/edoxen/source_url.rb

@@ -4,13 +4,13 @@ module Edoxen
   # Per-language canonical source URL (e.g. one PDF per language).
   # Carries the URL ref, its format, the ISO 639-3 language_code the URL
   # is the canonical source for, and an optional `kind` discriminator
-  # (agenda_pdf, minutes_pdf, resolutions_pdf, ...) used by the Meeting
-  # model. Existing Resolution fixtures without `kind` still parse —
-  # the field is optional.
+  # (agenda_pdf, minutes_pdf, decisions_pdf, ...) used by the Meeting
+  # model. Existing fixtures without `kind` still parse — the field is
+  # optional.
   class SourceUrl < Lutaml::Model::Serializable
     attribute :ref, :string
     attribute :format, :string
-    attribute :language_code, :string
+    attribute :spelling, :string
     attribute :kind, :string, values: Enums::SOURCE_URL_KIND
   end
 end

data/lib/edoxen/statement.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # One remark made by one or more meeting members on a topic or
+  # a minutes section. The `kind` discriminator separates the
+  # three BS 0:2006 statement types (statement, comment,
+  # standpoint); adding a new kind is a one-line StatementKind
+  # enum extension (OCP).
+  #
+  # Attachment points: `MinutesSection#statements[]` (per-meeting)
+  # and `Topic#statements[]` (standing position that travels with
+  # the topic across meetings). Same class, two attachment points
+  # — the semantic distinction comes from where the statement is
+  # attached, not from a subclass.
+  class Statement < Lutaml::Model::Serializable
+    attribute :kind, :string, values: Enums::STATEMENT_KIND
+    attribute :description, LocalizedString, collection: true
+    attribute :party, Person, collection: true
+    attribute :extensions, MeetingExtension, collection: true
+  end
+end

data/lib/edoxen/structured_identifier.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Edoxen
-  # A structured resolution identifier, e.g. prefix "ISO" + number "2019-01".
-  # A Resolution carries 1..* StructuredIdentifier so a single resolution can
+  # A structured decision identifier, e.g. prefix "ISO" + number "2019-01".
+  # A Decision carries 1..* StructuredIdentifier so a single decision can
   # hold its TC number, its SC number, and any cross-cutting reference number
   # without forcing callers to flatten them into one opaque string.
   class StructuredIdentifier < Lutaml::Model::Serializable

data/lib/edoxen/topic.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Topic — the subject of discussion at a Meeting.
+  # A Topic can have documents (text), assets (non-text), references
+  # (external pointers), and is the anchor for Motions and Decisions.
+  #
+  # Cross-meeting threading via `resumption_of` (URN to a prior Topic
+  # in a prior Meeting) — pattern from HK LegCo OData schema.
+  class Topic < Lutaml::Model::Serializable
+    attribute :identifier, :string
+    attribute :urn, :string
+    attribute :title, LocalizedString, collection: true
+    attribute :description, LocalizedString, collection: true
+    attribute :status, :string, values: Enums::TOPIC_STATUS
+    attribute :resumption_of, :string
+    attribute :documents, TopicDocument, collection: true
+    attribute :assets, TopicAsset, collection: true
+    attribute :references, Reference, collection: true
+    attribute :motions, :string, collection: true
+    attribute :decisions, :string, collection: true
+    attribute :statements, Statement, collection: true
+    attribute :declarations, Declaration, collection: true
+    attribute :extensions, MeetingExtension, collection: true
+
+    # --- 1.0 derivation accessor (1.0 design review) --------------------
+    # Returns the Decisions in `collection` whose `about_topics` includes
+    # this Topic's URN.
+    #
+    # Storage side: Decision.aboutTopics (SSOT for the relationship).
+    # The stored `decisions[]` field remains on the wire for back-compat
+    # through v2.x; 1.0 removes it and this becomes the only path.
+    def decisions_in(collection:)
+      return [] unless collection && urn
+
+      collection.decisions.select { |decision| decision.about_topics&.include?(urn) }
+    end
+  end
+end

data/lib/edoxen/topic_asset.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # TopicAsset — non-text resource about a Topic.
+  # Examples: image, dataset, model, video.
+  class TopicAsset < Lutaml::Model::Serializable
+    attribute :identifier, :string
+    attribute :title, LocalizedString, collection: true
+    attribute :kind, :string
+    attribute :url, :string
+    attribute :format, :string
+    attribute :extensions, MeetingExtension, collection: true
+  end
+end

data/lib/edoxen/topic_document.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # TopicDocument — text-bearing document about a Topic.
+  # Examples: bill text, ISO draft, report, agenda attachment.
+  class TopicDocument < Lutaml::Model::Serializable
+    attribute :identifier, :string
+    attribute :title, LocalizedString, collection: true
+    attribute :version, :string
+    attribute :status, :string
+    attribute :url, :string
+    attribute :format, :string
+    attribute :spelling, :string
+    attribute :extensions, MeetingExtension, collection: true
+  end
+end

data/lib/edoxen/venue.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Venue — polymorphic by discriminator, flat on the wire.
+  #
+  # The `kind` field discriminates between physical and virtual venues.
+  # All possible fields (physical-specific and virtual-specific) live on
+  # this one class as optional attributes — only the ones matching the
+  # `kind` are populated.
+  #
+  # 1.0 (per-field localization, ISO 24229):
+  #   - All translatable fields are Localized<String>[0..*].
+  #   - Added: `urn` for registry storage; `ref` for reference-by-URN.
+  class Venue < Lutaml::Model::Serializable
+    attribute :ref, :string
+    attribute :urn, :string
+    attribute :kind, :string, values: Enums::VENUE_KIND
+    attribute :name, LocalizedString, collection: true
+    attribute :label, LocalizedString, collection: true
+    attribute :description, LocalizedString, collection: true
+    attribute :capacity, :integer
+    attribute :url, :string
+    attribute :contact_methods, ContactMethod, collection: true
+
+    # Physical-venue fields (populated when kind == "physical").
+    attribute :unlocode, :string
+    attribute :iata_code, :string
+    attribute :address, LocalizedString, collection: true
+    attribute :city, :string
+    attribute :country_code, :string
+    attribute :lat, :float
+    attribute :lon, :float
+    attribute :building, LocalizedString, collection: true
+    attribute :floor, LocalizedString, collection: true
+    attribute :room, LocalizedString, collection: true
+    attribute :access_notes, LocalizedString, collection: true
+
+    # Virtual-venue fields (populated when kind == "virtual").
+    attribute :uri, :string
+    attribute :features, :string, collection: true, values: Enums::VIRTUAL_FEATURE
+    attribute :passcode, :string
+    attribute :meeting_id, :string
+    attribute :dial_in_numbers, :string, collection: true
+    attribute :waiting_room, :boolean
+    attribute :registration_required, :boolean
+
+    attribute :extensions, MeetingExtension, collection: true
+
+    def reference?
+      !ref.nil? && !ref.to_s.empty?
+    end
+
+    def physical?
+      kind == "physical"
+    end
+
+    def virtual?
+      kind == "virtual"
+    end
+
+    def unlocode_entry
+      return nil if unlocode.nil? || unlocode.to_s.empty?
+
+      Edoxen::ReferenceData.find_unlocode(unlocode)
+    end
+
+    def iata_entry
+      return nil if iata_code.nil? || iata_code.to_s.empty?
+
+      Edoxen::ReferenceData.find_iata(iata_code)
+    end
+
+    def features_list
+      return "" if features.nil? || features.empty?
+
+      features.join(", ")
+    end
+  end
+end

data/lib/edoxen/venue_collection.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Registry of Venues indexed by scoped URN. Mirrors ContactCollection:
+  # members carry `urn: urn:edoxen:venue:{scope}:{local-id}`; the
+  # collection's `scope` MUST match the scope segment in member URNs.
+  # Stream loading belongs to the service layer.
+  class VenueCollection < Lutaml::Model::Serializable
+    attribute :scope, :string
+    attribute :title, LocalizedString, collection: true
+    attribute :venues, Venue, collection: true
+    attribute :extensions, MeetingExtension, collection: true
+
+    def find_by_urn(urn)
+      venues&.find { |v| v.urn == urn }
+    end
+  end
+end

data/lib/edoxen/venue_validator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # VenueValidator — validates Venue instances using the `unlocodes`
+  # and `iata` gems. Returns a list of errors; empty list means valid.
+  #
+  # For a Venue with `kind: "physical"`, validates that any populated
+  # `unlocode` and `iata_code` exist in the canonical registries.
+  #
+  # `valid?` and `validate` are pure queries — they do not mutate the
+  # venue. Callers who want city/country_code back-filled from the
+  # UN/LOCODE registry use `populate_from_registry!`, a separate,
+  # explicitly-mutating method.
+  class VenueValidator
+    attr_reader :venue, :errors
+
+    def initialize(venue)
+      @venue = venue
+      @errors = []
+    end
+
+    # Pure query. Populates `errors` and returns it; does not modify
+    # the venue.
+    def validate
+      errors.clear
+      validate_physical if venue.physical?
+      errors
+    end
+
+    # Pure boolean wrapper around `validate`.
+    def valid?
+      validate
+      errors.empty?
+    end
+
+    # Mutator: back-fill `venue.city` and `venue.country_code` from the
+    # UN/LOCODE entry. Raises `KeyError` when the unlocode is unknown
+    # or unset, so callers do not silently leave the venue untouched.
+    #
+    # Returns the venue (so callers can chain).
+    def populate_from_registry!
+      raise KeyError, "populate_from_registry! requires kind: physical" unless venue.physical?
+      raise KeyError, "populate_from_registry! requires unlocode" if venue.unlocode.nil? || venue.unlocode.to_s.empty?
+
+      entry = Edoxen::ReferenceData.find_unlocode(venue.unlocode)
+      raise KeyError, "Unknown UN/LOCODE: #{venue.unlocode}" if entry.nil?
+
+      venue.city ||= entry.name
+      venue.country_code ||= entry.country
+      venue
+    end
+
+    private
+
+    def validate_physical
+      validate_unlocode if venue.unlocode && !venue.unlocode.to_s.empty?
+      validate_iata_code if venue.iata_code && !venue.iata_code.to_s.empty?
+    end
+
+    def validate_unlocode
+      entry = Edoxen::ReferenceData.find_unlocode(venue.unlocode)
+      return if entry
+
+      errors << "Unknown UN/LOCODE: #{venue.unlocode}"
+    end
+
+    def validate_iata_code
+      entry = Edoxen::ReferenceData.find_iata(venue.iata_code)
+      return if entry
+
+      errors << "Unknown IATA code: #{venue.iata_code}"
+    end
+  end
+end

data/lib/edoxen/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Edoxen
-  VERSION = "0.5.0"
+  VERSION = "0.8.1"
 end

data/lib/edoxen/virtual_venue.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # VirtualVenue — type marker for a Venue with kind == "virtual".
+  #
+  # The wire format is flat on Venue (all fields live there). This
+  # subclass exists for type-checking and to host virtual-only helpers
+  # so callers can ask `venue.is_a?(VirtualVenue)` and validators
+  # can dispatch by type.
+  class VirtualVenue < Venue
+    def initialize(attributes = {})
+      super(attributes.merge(kind: "virtual"))
+    end
+  end
+end

data/lib/edoxen/vote_record.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # A single vote on a Decision, recorded against the Voting instance
+  # that captured it. `voting_ref` links to the Voting URN; `decision_ref`
+  # links to the Decision URN (often derivable from the Voting's motion,
+  # but explicit for clarity).
+  #
+  # `role` is open for adopter-defined values: teller (parliamentary
+  # division counter), proxy_holder, observer, etc.
+  class VoteRecord < Lutaml::Model::Serializable
+    attribute :decision_ref, :string
+    attribute :voting_ref, :string
+    attribute :person, Person
+    attribute :affiliation, :string
+    attribute :vote, :string, values: Enums::VOTE_TYPE
+    attribute :role, :string
+    attribute :notes, :string
+    attribute :extensions, MeetingExtension, collection: true
+
+    def affirmative?
+      vote == "affirmative"
+    end
+
+    def teller?
+      role == "teller"
+    end
+  end
+end

data/lib/edoxen/voting.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Voting — state machine for a single vote on a Motion.
+  # Multiple votings can occur on the same Motion (e.g., unclear voice
+  # vote → chair calls a formal division → second Voting instance).
+  #
+  # State machine (VotingStatus):
+  #   called → in_progress → decided | withdrawn | deferred
+  class Voting < Lutaml::Model::Serializable
+    attribute :identifier, :string
+    attribute :urn, :string
+    attribute :on_motion, :string
+    attribute :status, :string, values: Enums::VOTING_STATUS
+    attribute :voting_method, :string, values: Enums::VOTING_METHOD
+    attribute :called_by, Person
+    attribute :called_at, :date_time
+    attribute :result_declared_at, :date_time
+    attribute :result, :string, values: Enums::VOTING_OUTCOME
+    attribute :counts, VotingCounts
+    attribute :casting_vote, VoteRecord
+    attribute :vote_records, VoteRecord, collection: true
+    attribute :extensions, MeetingExtension, collection: true
+
+    def decided?
+      status == "decided"
+    end
+
+    def in_progress?
+      status == "in_progress"
+    end
+
+    def passed?
+      decided? && result == "passed"
+    end
+
+    def negatived?
+      decided? && result == "negatived"
+    end
+
+    def tied?
+      decided? && result == "tied"
+    end
+  end
+end

data/lib/edoxen/voting_counts.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # VotingCounts — tally for a Voting instance.
+  class VotingCounts < Lutaml::Model::Serializable
+    attribute :ayes, :integer
+    attribute :noes, :integer
+    attribute :abstentions, :integer
+    attribute :absent, :integer
+
+    def total
+      (ayes || 0) + (noes || 0) + (abstentions || 0) + (absent || 0)
+    end
+
+    def margin
+      (ayes || 0) - (noes || 0)
+    end
+
+    def tied?
+      ayes == noes
+    end
+  end
+end