edoxen 0.7.2 → 0.8.2

data/lib/edoxen/consideration.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 module Edoxen
-  # Basis for a resolution: a verb (having, noting, considering, ...) plus
-  # one effective date and the elaborated reasoning.
+  # Basis for a Decision: a verb (having, noting, considering, ...) plus
+  # one effective date and the per-field Localized reasoning. Each
+  # `Consideration` belongs to a `Decision`; the message field carries
+  # one `LocalizedString` per ISO 24229 spelling.
   class Consideration < Lutaml::Model::Serializable
     attribute :type, :string, values: Enums::CONSIDERATION_TYPE
-    attribute :date_effective, ResolutionDate
-    attribute :message, :string
+    attribute :date_effective, DecisionDate
+    attribute :message, LocalizedString, collection: true
   end
 end

data/lib/edoxen/contact.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # VCARD-like abstract contact. Generalises Person for cases where the
+  # contact may be a person, an organisation, a department, a role
+  # ("Secretariat"), or any other entity with a name and one or more
+  # communication channels.
+  #
+  # 1.0 (per-field localization, ISO 24229):
+  #   - All translatable fields are Localized<String/Name>[0..*]
+  #     (one entry per spelling/conversion system code).
+  #   - Added: `urn` for registry storage; `ref` for reference-by-URN.
+  #
+  # Reference vs inline: when `ref` is set, treat this Contact as a
+  # reference (other fields ignored). When `ref` is unset, the Contact
+  # is inline (full data). Both patterns are valid on every field that
+  # accepts a Contact.
+  class Contact < Lutaml::Model::Serializable
+    attribute :ref, :string
+    attribute :local_ref, :string
+    attribute :urn, :string
+    attribute :name, LocalizedName, collection: true
+    attribute :kind, :string
+    attribute :role, :string
+    attribute :title, LocalizedString, collection: true
+    attribute :affiliation, LocalizedString, collection: true
+    attribute :contact_methods, ContactMethod, collection: true
+    attribute :identifiers, ContactIdentifier, collection: true
+    attribute :address, LocalizedString, collection: true
+    attribute :extensions, MeetingExtension, collection: true
+
+    def reference?
+      (!ref.nil? && !ref.to_s.empty?) ||
+        (!local_ref.nil? && !local_ref.to_s.empty?)
+    end
+  end
+end

data/lib/edoxen/contact_identifier.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # One polymorphic external identifier for a Contact — ORCID, ISNI,
+  # Wikidata QID, ROR, Ringgold, GitHub handle, etc. Replaces the hard-
+  # coded `orcid` field. OCP: new identifier schemes are added via the
+  # ContactIdentifierKind enum (or `other` + extensions).
+  class ContactIdentifier < Lutaml::Model::Serializable
+    attribute :kind, :string, values: Enums::CONTACT_IDENTIFIER_KIND
+    attribute :value, :string
+    attribute :extensions, MeetingExtension, collection: true
+  end
+end

data/lib/edoxen/contact_method.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # One polymorphic communication channel — phone, email, fax, url, mail,
+  # etc. Replaces the hard-coded `email` / `phone` fields that used to
+  # live on Person and Venue. New channel kinds are added via the
+  # ContactMethodKind enum (or `other` + extensions for adopter-specific
+  # channels); the model itself never needs to change (OCP).
+  class ContactMethod < Lutaml::Model::Serializable
+    attribute :kind, :string, values: Enums::CONTACT_METHOD_KIND
+    attribute :value, :string
+    attribute :label, :string
+    attribute :primary, :boolean
+    attribute :extensions, MeetingExtension, collection: true
+  end
+end

data/lib/edoxen/contact_register.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Registry of Contacts indexed by scoped URN. Members carry
+  # `urn: urn:edoxen:contact:{scope}:{local-id}`; the collection's
+  # `scope` MUST match the scope segment in member URNs.
+  #
+  # Other documents (Meeting, MeetingComponent, HostRef, etc.) reference
+  # contacts via `ref: urn:edoxen:contact:{scope}:{local-id}` and
+  # resolve against the matching ContactRegister.
+  #
+  # Storage: single YAML file (typical) or YAML Stream (one Contact per
+  # document, for large registries that need partial updates). Stream
+  # loading is a service-layer concern (file-system I/O); the model
+  # owns only the (de)serialisation of one collection.
+  class ContactRegister < Lutaml::Model::Serializable
+    attribute :scope, :string
+    attribute :title, LocalizedString, collection: true
+    attribute :contacts, Contact, collection: true
+    attribute :extensions, MeetingExtension, collection: true
+
+    def find_by_urn(urn)
+      contacts&.find { |c| c.urn == urn }
+    end
+  end
+end

data/lib/edoxen/date_time_range.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Start + end pair with sub-day precision. Parallel to DateRange;
+  # use when day granularity is insufficient — e.g.
+  # `Meeting#occurred_date_range` (a meeting that ran 09:00–11:30).
+  #
+  # The two are intentionally separate types so the granularity is
+  # visible at the type level: a caller who sees DateRange knows
+  # it is day-granularity; a caller who sees DateTimeRange knows
+  # sub-day precision is available.
+  class DateTimeRange < Lutaml::Model::Serializable
+    attribute :start, :date_time
+    attribute :end, :date_time
+  end
+end

data/lib/edoxen/deadline.rb

@@ -5,6 +5,6 @@ module Edoxen
   # registration cutoff, report-submission deadline, etc.
   class Deadline < Lutaml::Model::Serializable
     attribute :date, :date
-    attribute :description, :string
+    attribute :description, LocalizedString, collection: true
   end
 end

data/lib/edoxen/decision.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # A formal Decision — the base type for any outcome adopted by a Meeting.
+  # Was `Resolution` in legacy; renamed in 1.0 because the same formal concept
+  # has many names across bodies (resolution, order, ruling, determination,
+  # finding, opinion). `Resolution` is one `kind` value, not a class name.
+  #
+  # 1.0 (per-field localization, ISO 24229):
+  #   - Removed `localizations[]` collection.
+  #   - Per-field LocalizedString for title, subject, message, considering.
+  class Decision < Lutaml::Model::Serializable
+    attribute :identifier, StructuredIdentifier, collection: true
+    attribute :kind, :string, values: Enums::DECISION_KIND
+    attribute :status, :string, values: Enums::DECISION_STATUS
+    attribute :doi, :string
+    attribute :urn, :string
+    attribute :agenda_item, :string
+    attribute :dates, DecisionDate, collection: true
+    attribute :categories, :string, collection: true
+    attribute :meeting, MeetingIdentifier
+    attribute :relations, DecisionRelation, collection: true
+    attribute :urls, Url, collection: true
+    attribute :brought_by_motions, :string, collection: true
+    attribute :about_topics, :string, collection: true
+    attribute :made_in_component, :string
+    attribute :body_type, :string
+    attribute :title, LocalizedString, collection: true
+    attribute :subject, LocalizedString, collection: true
+    attribute :message, LocalizedString, collection: true
+    attribute :considering, LocalizedString, collection: true
+    attribute :considerations, Consideration, collection: true
+    attribute :approvals, Approval, collection: true
+    attribute :actions, Action, collection: true
+    attribute :extensions, MeetingExtension, collection: true
+
+    # --- 1.0 derivation accessors (1.0 design review) -------------------
+
+    def brought_by_motions_in(meeting:)
+      return [] unless meeting && urn
+
+      meeting.motions.select do |motion|
+        motion.resulting_decision == urn ||
+          motion.resulting_decision_ref&.urn == urn
+      end
+    end
+
+    def component_in(meeting:)
+      return nil unless meeting && made_in_component
+
+      meeting.components&.find do |component|
+        component.identifier == made_in_component ||
+          component.urn == made_in_component
+      end
+    end
+  end
+end

data/lib/edoxen/decision_collection.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Top-level container for a published decision collection: metadata
+  # plus the list of decisions. Was ResolutionCollection in legacy.
+  class DecisionCollection < Lutaml::Model::Serializable
+    attribute :metadata, DecisionMetadata
+    attribute :decisions, Decision, collection: true
+  end
+end

data/lib/edoxen/decision_date.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Date with semantic kind. Was ResolutionDate in legacy.
+  class DecisionDate < Lutaml::Model::Serializable
+    attribute :date, :date
+    attribute :type, :string, values: Enums::DECISION_DATE_TYPE
+  end
+end

data/lib/edoxen/decision_metadata.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Collection-level metadata: the localized title, the meeting date,
+  # the source secretariat, per-language source PDFs, and the host venue.
+  class DecisionMetadata < Lutaml::Model::Serializable
+    include BodyVocabularyHost
+
+    attribute :title, LocalizedString, collection: true
+    attribute :date, :date
+    attribute :source, :string
+    attribute :source_urls, SourceUrl, collection: true
+    attribute :city, :string
+    attribute :country_code, :string
+
+    # URN back-reference to the Meeting that produced this collection.
+    attribute :meeting_urn, :string
+
+    attribute :extensions, MeetingExtension, collection: true
+
+    def city_entry
+      return nil if city.nil? || city.to_s.empty?
+
+      Edoxen::ReferenceData.find_unlocode(city)
+    end
+  end
+end

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/declaration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # A formal declaration made by one or more meeting members.
+  # Covers the two BS 0:2006 declaration types via the `kind`
+  # discriminator: `conflict_of_interest` and `ipr`.
+  #
+  # The IPR-specific fields (`ipr_subject_ref`, `ipr_target_ref`)
+  # are populated only when `kind == "ipr"`. This mirrors edoxen's
+  # "flat class, kind discriminates which subset is populated"
+  # pattern (cf. Venue: physical + virtual fields on one flat
+  # class).
+  #
+  # Attachment points: `Meeting#declarations[]` (per-meeting) and
+  # `Topic#declarations[]` (standing position that travels with
+  # the topic).
+  class Declaration < Lutaml::Model::Serializable
+    attribute :kind, :string, values: Enums::DECLARATION_KIND
+    attribute :description, LocalizedString, collection: true
+    attribute :party, Person, collection: true
+    attribute :ipr_subject_ref, EntityRef
+    attribute :ipr_target_ref, EntityRef
+    attribute :extensions, MeetingExtension, collection: true
+  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 (1.0, 1.0 design review).
+  #
+  # 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`). 1.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
+    # (1.0 design review + 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/entity_resolver.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # EntityResolver — resolves Contact/Venue/Body references by walking
+  # the three-tier scope hierarchy:
+  #
+  #   1. Inline: if the entity has no +ref+ and no +local_ref+, return
+  #      it as-is (it carries full data).
+  #   2. Document-scoped: if +local_ref+ is set, look up in the
+  #      document-scoped collection (e.g. Meeting#contacts) by matching
+  #      +urn+ against +local_ref+.
+  #   3. Global register: if +ref+ is set, look up in the global
+  #      register (e.g. ContactRegister) by matching +urn+ against +ref+.
+  #
+  # Pure service: no mutation. Returns the resolved entity or nil.
+  class EntityResolver
+    attr_reader :scoped_collections, :global_registers
+
+    def initialize(scoped: {}, registers: {})
+      @scoped_collections = scoped
+      @global_registers = registers
+    end
+
+    def resolve(entity)
+      return entity unless entity.reference?
+
+      resolve_local(entity) || resolve_global(entity)
+    end
+
+    def resolve_all(entities)
+      entities.map { |e| resolve(e) }
+    end
+
+    private
+
+    def resolve_local(entity)
+      return nil if entity.local_ref.nil? || entity.local_ref.to_s.empty?
+
+      collection = find_scoped_collection(entity.class)
+      return nil unless collection
+
+      collection.find { |member| member_key(member) == entity.local_ref }
+    end
+
+    def resolve_global(entity)
+      return nil if entity.ref.nil? || entity.ref.to_s.empty?
+
+      register = find_global_register(entity.class)
+      return nil unless register
+
+      register.find_by_urn(entity.ref)
+    end
+
+    def find_scoped_collection(klass)
+      @scoped_collections[klass] ||
+        @scoped_collections[klass.superclass]
+    end
+
+    def find_global_register(klass)
+      @global_registers[klass] ||
+        @global_registers[klass.superclass]
+    end
+
+    def member_key(member)
+      member.urn
+    end
+  end
+end

data/lib/edoxen/enums.rb

@@ -26,13 +26,33 @@ 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 — short abstract classification of decision
+    # kinds. Cap: 5 canonical values (hard limit per the design review).
+    DECISION_KIND_CANONICAL = %w[decision recommendation statement finding other].freeze
 
-    RESOLUTION_RELATION_TYPE = %w[
-      annexOf hasAnnex updates refines replaces considers
+    # DecisionStatus — lifecycle state machine.
+    DECISION_STATUS = %w[
+      draft proposed under_consideration
+      decided negatived withdrawn deferred
     ].freeze
 
-    RESOLUTION_DATE_TYPE = %w[adoption drafted discussed].freeze
+    DECISION_RELATION_TYPE = %w[
+      annex_of has_annex updates refines replaces considers cites
+    ].freeze
+
+    DECISION_DATE_TYPE = %w[
+      adoption drafted discussed proposed decided negatived withdrawn published effective
+    ].freeze
 
     APPROVAL_TYPE = %w[affirmative negative].freeze
 
@@ -44,31 +64,125 @@ 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 — short abstract classification of meeting
+    # types. Cap: 4 canonical values (no `other`).
+    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 1.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 (1.0, 1.0 design review).
+    # `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
+
+    # --- BS 0:2006 meeting-minutes concepts --------------------------------
+
+    # StatementKind — discriminates the three BS 0:2006 statement
+    # types. Adding a new kind is a one-line enum extension; the
+    # Statement model itself never needs to change (OCP).
+    STATEMENT_KIND = %w[statement comment standpoint].freeze
+
+    # DeclarationKind — discriminates the two BS 0:2006 declaration
+    # types (conflict of interest, IPR). Adding a new kind is a
+    # one-line enum extension; the Declaration model itself never
+    # needs to change (OCP).
+    DECLARATION_KIND = %w[conflict_of_interest ipr].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)