glossarist 2.13.5 → 2.13.7

data/lib/glossarist/v3/hyperedge_index.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module V3
+    # HyperedgeIndex — derived reverse-lookup index over a flat list
+    # of hyperedges.
+    #
+    # A hyperedge is directional: 1 comprehensive → N members. To
+    # answer the reverse query ("which hyperedges is X a member of?"),
+    # build a HyperedgeIndex on demand from the flat list and consult
+    # #for_member. The index is NOT stored on the concept — it's a
+    # derived view.
+    #
+    # Use cases:
+    #   index.for_comprehensive("OIML:5.1")
+    #     # => 6 hyperedges (different criteria — the OIML pattern)
+    #   index.for_member("OIML:5.13")
+    #     # => hyperedges where 5.13 appears as a member
+    class HyperedgeIndex
+      attr_reader :by_comprehensive, :by_member
+
+      def initialize(hyperedges)
+        @by_comprehensive = {}
+        @by_member = {}
+
+        Array(hyperedges).each do |h|
+          register_comprehensive(h)
+          register_members(h)
+        end
+
+        @by_comprehensive.freeze
+        @by_member.freeze
+      end
+
+      # All hyperedges where the given concept is the comprehensive.
+      # Accepts either a qualified-id string ("VIM:1.2") or a ConceptRef.
+      def for_comprehensive(qualified_id_or_ref)
+        key = resolve_key(qualified_id_or_ref)
+        @by_comprehensive[key] || []
+      end
+
+      # All hyperedges where the given concept is one of the members.
+      # Accepts either a qualified-id string or a ConceptRef.
+      def for_member(qualified_id_or_ref)
+        key = resolve_key(qualified_id_or_ref)
+        @by_member[key] || []
+      end
+
+      # Every concept that appears anywhere in this hyperedge set
+      # (as comprehensive OR as a member), with its roles.
+      def all_concept_ids
+        (@by_comprehensive.keys | @by_member.keys).freeze
+      end
+
+      private
+
+      def register_comprehensive(hyperedge)
+        return unless hyperedge.is_a?(AbstractHyperedge)
+
+        key = Glossarist::ConceptRef.qualified_id(hyperedge.comprehensive)
+        return unless key
+
+        (@by_comprehensive[key] ||= []) << hyperedge
+      end
+
+      def register_members(hyperedge)
+        return unless hyperedge.is_a?(AbstractHyperedge)
+
+        Array(hyperedge.members).each do |m|
+          next unless m.is_a?(HyperedgeMember)
+          next unless m.ref.is_a?(Glossarist::ConceptRef)
+
+          key = Glossarist::ConceptRef.qualified_id(m.ref)
+          next unless key
+
+          (@by_member[key] ||= []) << hyperedge
+        end
+      end
+
+      def resolve_key(qualified_id_or_ref)
+        if qualified_id_or_ref.is_a?(Glossarist::ConceptRef)
+          Glossarist::ConceptRef.qualified_id(qualified_id_or_ref)
+        else
+          qualified_id_or_ref.to_s
+        end
+      end
+    end
+  end
+end

data/lib/glossarist/v3/hyperedge_member.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module V3
+    # HyperedgeMember — abstract base shape for members of any
+    # n-ary concept-system relation (PartitiveMember, GenericMember,
+    # future AssociativeMember, SequentialMember).
+    #
+    # Carries the shared ISO 704:2022 MECE dimensions: presence × count,
+    # plus the orthogonal is_delimiting flag.
+    #
+    # Concrete leaf classes inherit and may add type-specific fields.
+    # See docs/design/abstract-nary-relation.md (concept-model repo).
+    class HyperedgeMember < Lutaml::Model::Serializable
+      DEFAULT_PRESENCE = "required"
+      DEFAULT_COUNT = "exactly_one"
+
+      attribute :ref, ConceptRef
+      attribute :presence, :string,
+                values: Glossarist::GlossaryDefinition::MEMBER_PRESENCE_VALUES,
+                default: -> { DEFAULT_PRESENCE }
+      attribute :count, :string,
+                values: Glossarist::GlossaryDefinition::MEMBER_COUNT_VALUES,
+                default: -> { DEFAULT_COUNT }
+      attribute :is_delimiting, :boolean, default: -> { false }
+
+      key_value do
+        map :ref, to: :ref
+        map :presence, to: :presence
+        map :count, to: :count
+        map :is_delimiting, to: :is_delimiting
+      end
+
+      def initialize(*)
+        if instance_of?(HyperedgeMember)
+          raise NotImplementedError,
+                "HyperedgeMember is abstract; instantiate " \
+                "PartitiveMember or GenericMember instead"
+        end
+
+        super
+      end
+
+      def validate!
+        validate_ref!
+        validate_presence_count!
+        self
+      end
+
+      def required?
+        presence == "required"
+      end
+
+      def optional?
+        presence == "optional"
+      end
+
+      def delimiting?
+        is_delimiting == true
+      end
+
+      private
+
+      def validate_ref!
+        return if ref.is_a?(ConceptRef) && (ref.source || ref.id || ref.text)
+
+        raise ArgumentError,
+              "#{self.class.name}#ref must be a non-empty ConceptRef " \
+              "(source, id, or text required)"
+      end
+
+      # Delegates the MECE combination check to Multiplicity (the SSOT).
+      # Multiplicity.multiplicity_from_pair raises ArgumentError on the
+      # invalid (optional + at_least_one) combo with the canonical message.
+      # The returned name is discarded — only the validation side matters.
+      def validate_presence_count!
+        unless Glossarist::GlossaryDefinition::MEMBER_PRESENCE_VALUES
+            .include?(presence)
+          raise ArgumentError,
+                "#{self.class.name}#presence has invalid value " \
+                "#{presence.inspect}; must be one of " \
+                "#{GlossaryDefinition::MEMBER_PRESENCE_VALUES.join(', ')}"
+        end
+
+        unless Glossarist::GlossaryDefinition::MEMBER_COUNT_VALUES
+            .include?(count)
+          raise ArgumentError,
+                "#{self.class.name}#count has invalid value " \
+                "#{count.inspect}; must be one of " \
+                "#{GlossaryDefinition::MEMBER_COUNT_VALUES.join(', ')}"
+        end
+
+        Multiplicity.multiplicity_from_pair(presence, count)
+      end
+    end
+  end
+end

data/lib/glossarist/v3/hyperedge_registry.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module V3
+    # HyperedgeRegistry — single SSOT for hyperedge-class lookup by
+    # every external identifier (wire key, type tag, RDF type).
+    #
+    # Auto-populates on class inheritance via AbstractHyperedge.inherited.
+    # Concrete leaves declare WIRE_KEY / TYPE_TAG / RDF_TYPE constants
+    # in a per-class metadata block; the registry reads them once at
+    # registration time.
+    #
+    # Adding a new hyperedge type means declaring one leaf class with
+    # the metadata block. No edit to any other file (parser, serializer,
+    # validator, RDF emitter, RelationLoader) — they all iterate or
+    # resolve through this registry.
+    module HyperedgeRegistry
+      # Mutable: register adds entries at load time. DO NOT freeze.
+      BY_WIRE_KEY = {}
+      BY_TYPE_TAG = {}
+      BY_RDF_TYPE = {}
+
+      Mutex = ::Mutex.new
+
+      class << self
+        # Register a concrete hyperedge class. Idempotent.
+        def register(cls)
+          return if cls.nil? || cls.const_defined?(:WIRE_KEY) == false
+
+          Mutex.synchronize do
+            wire = cls::WIRE_KEY
+            tag  = cls::TYPE_TAG
+            rdf  = cls::RDF_TYPE
+
+            BY_WIRE_KEY[wire] = cls unless wire.nil? || wire.empty?
+            BY_TYPE_TAG[tag]  = cls unless tag.nil? || tag.empty?
+            BY_RDF_TYPE[rdf]  = cls unless rdf.nil? || rdf.empty?
+          end
+        end
+
+        # Iterate every concrete leaf (use this in parser / serializer
+        # / loader to stay type-blind).
+        def all_classes
+          BY_TYPE_TAG.values.uniq
+        end
+
+        def for_wire_key(key)
+          BY_WIRE_KEY[key]
+        end
+
+        def for_type_tag(tag)
+          BY_TYPE_TAG[tag]
+        end
+
+        def for_rdf_type(rdf_type)
+          BY_RDF_TYPE[rdf_type]
+        end
+
+        # Reset (spec helper — never call from production code).
+        def reset!
+          Mutex.synchronize do
+            BY_WIRE_KEY.clear
+            BY_TYPE_TAG.clear
+            BY_RDF_TYPE.clear
+          end
+        end
+      end
+    end
+  end
+end

data/lib/glossarist/v3/hyperedge_writer.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+require "pathname"
+
+module Glossarist
+  module V3
+    # HyperedgeWriter — the WRITE half of per-file hyperedge storage.
+    #
+    # Mirror of RelationLoader. Each hyperedge is serialized to
+    # `relations/<comprehensive-id>/<criterion-slug>.yaml` with the
+    # full per-file wire format ($id, type, comprehensive, members,
+    # criterion, sources, notes, status, completeness).
+    #
+    # Per-file storage means a single concept (e.g., OIML 5.1
+    # measurement standard) can have N hyperedges (one per criterion),
+    # each in its own file under relations/<comp-id>/.
+    class HyperedgeWriter
+      class WriteError < ::StandardError
+      end
+
+      class << self
+        # Write a single hyperedge to its per-file location under
+        # `relations_dir`. Creates the comprehensive-id subdirectory
+        # if missing. Returns the absolute path written.
+        def write(hyperedge, relations_dir)
+          new(relations_dir).write(hyperedge)
+        end
+
+        # Write a batch of hyperedges. Returns an Array<String> of
+        # paths written. Hyperedges with the same comprehensive are
+        # written to the same subdirectory.
+        def write_all(hyperedges, relations_dir)
+          new(relations_dir).write_all(hyperedges)
+        end
+      end
+
+      def initialize(relations_dir)
+        @relations_dir = Pathname.new(relations_dir)
+      end
+
+      def write(hyperedge)
+        raise WriteError, "not an AbstractHyperedge: #{hyperedge.class}" unless
+          hyperedge.is_a?(AbstractHyperedge)
+
+        path = hyperedge.file_path(@relations_dir)
+        raise WriteError,
+              "cannot derive file path — comprehensive must be non-empty" unless path
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, serialize(hyperedge))
+        path
+      end
+
+      def write_all(hyperedges)
+        Array(hyperedges).map { |h| write(h) }
+      end
+
+      private
+
+      # Serialize with stable key ordering: $id, type, status,
+      # comprehensive, members, completeness, criterion, sources,
+      # notes. Matches the concept-model per-file format.
+      def serialize(hyperedge)
+        hash = hyperedge.to_hash
+        hash["$id"] = hyperedge.file_id || hyperedge.derived_file_id
+        hash["type"] = hyperedge.class::TYPE_TAG
+        # Re-order for stable output.
+        ordered = {}
+        ordered["$id"]         = hash.delete("$id")
+        ordered["type"]        = hash.delete("type")
+        ordered["status"]      = hash.delete("status") if hash.key?("status")
+        ordered["comprehensive"] = hash.delete("comprehensive")
+        ordered["members"]     = hash.delete("members")
+        ordered["completeness"] = hash.delete("completeness") if hash.key?("completeness")
+        ordered["criterion"]   = hash.delete("criterion") if hash.key?("criterion")
+        ordered["sources"]     = hash.delete("sources") if hash.key?("sources")
+        ordered["notes"]       = hash.delete("notes") if hash.key?("notes")
+        ordered.merge!(hash) # any future fields append in declaration order
+        ordered.compact!
+
+        YAML.dump(ordered).gsub(/^---\s*\n/, "---\n")
+      end
+    end
+  end
+end

data/lib/glossarist/v3/managed_concept.rb

@@ -2,18 +2,41 @@
 
 module Glossarist
   module V3
+    # V3 ManagedConcept.
+    #
+    # V3 storage model:
+    # - Concept metadata lives here on the concept (data, related,
+    #   dates, sources, status).
+    # - Hyperedges (PartitiveHyperedge, GenericHyperedge) are PER-FILE:
+    #   stored at relations/<comprehensive-id>/<criterion-slug>.yaml
+    #   and loaded via Glossarist::V3::RelationLoader. They are NOT
+    #   serialized inline on the concept YAML.
+    #
+    # This is the v3 clean break — the bundled format
+    # (`partitive_relations: [...]` inline on the concept YAML) is
+    # removed. Concept-model removed it without backward compat in
+    # commit a62cf85; ruby aligns.
+    #
+    # #relations is the unified accessor. The list is populated by
+    # callers (GlossaryStore#relations_for, RelationLoader, direct
+    # construction). NO typed projections — callers filter:
+    #
+    #   concept.relations.select { |r| r.is_a?(PartitiveHyperedge) }
+    #   concept.relations.select { |r| r.comprehensive.id == my_id }
     class ManagedConcept < Glossarist::ManagedConcept
       attribute :data, V3::ManagedConceptData, default: -> { V3::ManagedConceptData.new }
       attribute :related, V3::RelatedConcept, collection: true
-      attribute :partitive_relations, V3::PartitiveRelation, collection: true
       attribute :dates, V3::ConceptDate, collection: true
       attribute :date_accepted, V3::ConceptDate
       attribute :sources, V3::ConceptSource, collection: true
 
+      # Unified hyperedge accessor. NOT serialized (per-file storage);
+      # populated externally by GlossaryStore / RelationLoader.
+      attribute :relations, V3::AbstractHyperedge, collection: true
+
       key_value do
         map :data, to: :data
         map :related, to: :related
-        map :partitive_relations, to: :partitive_relations
         map :dates, to: :dates
         map %i[date_accepted dateAccepted],
             with: { from: :date_accepted_from_yaml, to: :date_accepted_to_yaml }
@@ -22,6 +45,7 @@ module Glossarist
                          with: { from: :uuid_from_yaml, to: :uuid_to_yaml }
         map :schema_version, to: :schema_version
         map :sources, to: :sources
+        # relations: intentionally NOT mapped — per-file storage only.
       end
 
       def date_accepted_from_yaml(model, value)
@@ -29,6 +53,33 @@ module Glossarist
           { "date" => value, "type" => "accepted" },
         )
       end
+
+      # Strict setter — rejects duplicates by identity (type +
+      # comprehensive + criterion fingerprint). Adding the same
+      # hyperedge twice is always a bug; dedupe hides bugs.
+      def relations=(list)
+        seen = {}
+        Array(list).each do |rel|
+          key = hyperedge_identity(rel)
+          if seen[key]
+            raise ArgumentError,
+                  "duplicate hyperedge #{key.inspect} — pass each " \
+                  "decomposition once"
+          end
+          seen[key] = rel
+        end
+        super(seen.values)
+      end
+
+      private
+
+      def hyperedge_identity(rel)
+        return rel.object_id.to_s unless rel.is_a?(V3::AbstractHyperedge)
+
+        comp = Glossarist::ConceptRef.qualified_id(rel.comprehensive)
+        crit = rel.criterion.is_a?(Hash) ? rel.criterion.sort.to_h : rel.criterion
+        "#{rel.class}:#{comp}:#{crit}"
+      end
     end
   end
 end

data/lib/glossarist/v3/managed_concept_data.rb

@@ -47,4 +47,3 @@ module Glossarist
     end
   end
 end
-

data/lib/glossarist/v3/partitive_hyperedge.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module V3
+    # PartitiveHyperedge — an ISO 704 / ISO 1087-1 / ISO 12620 partitive
+    # hyperedge connecting a comprehensive concept (superordinate concept
+    # partitive) to two or more partitive concepts (subordinate concepts
+    # partitive) which fitted together constitute the comprehensive.
+    #
+    # Inherits structure and validations from AbstractHyperedge.
+    # The `comprehensive` field denotes the whole concept.
+    #
+    # Per-file storage: lives at
+    # relations/<comprehensive-id>/<criterion-slug>.yaml — see
+    # docs/design/relations-as-files.md (concept-model repo).
+    #
+    # The `key_value` mapping is inherited from AbstractHyperedge
+    # (single SSOT). Only the typed member collection is narrowed here.
+    #
+    # Per-class metadata block — the SSOT for this leaf's external
+    # identifiers. Adding a new hyperedge type means declaring a new
+    # class with an equivalent block; no other file needs editing
+    # (parsers, serializers, validators, RDF emitters, and the loader
+    # all dispatch through HyperedgeRegistry by these constants).
+    class PartitiveHyperedge < AbstractHyperedge
+      # YAML key on Concept (legacy bundled-format wire name; kept for
+      # backward compat with concept-model).
+      WIRE_KEY = "partitive_relations"
+
+      # Per-file `type:` discriminator in relations/<id>/<slug>.yaml.
+      TYPE_TAG = "partitive_relation"
+
+      # RDF type URI (gloss: ontology — concept-model contract).
+      RDF_TYPE = "gloss:PartitiveRelation"
+
+      # Member class — narrows the parent's members: HyperedgeMember.
+      MEMBER_CLASS = PartitiveMember
+
+      # Legacy v1 wire keys that migrate to this class on parse.
+      V1_WIRE_KEYS = %w[partitive_hyperedges].freeze
+
+      # Short label for diff display ("PART" / "GEN" / etc.).
+      KIND_LABEL = "PART"
+
+      attribute :members, PartitiveMember, collection: true
+    end
+
+    # Auto-register with HyperedgeRegistry. Adding a new hyperedge
+    # type means adding a class with an equivalent block + this one
+    # register call — nothing else in the codebase changes.
+    HyperedgeRegistry.register(PartitiveHyperedge)
+  end
+end

data/lib/glossarist/v3/partitive_member.rb

@@ -2,112 +2,15 @@
 
 module Glossarist
   module V3
-    # PartitiveMember — one member of a PartitiveRelation, carrying
-    # a ConceptRef to the partitive concept plus ISO 704:2022
-    # multiplicity and delimiting metadata.
+    # PartitiveMember — one member of a PartitiveHyperedge. Inherits
+    # the ISO 704:2022 MECE shape from HyperedgeMember; the
+    # `comprehensive` of its parent PartitiveHyperedge denotes the
+    # whole concept.
     #
-    # ISO 704:2022 partitive member notation uses two orthogonal
-    # dimensions (MECE decomposition):
-    #
-    #   presence (line style — solid vs dashed):
-    #     required   — solid line (must exist in every instance)
-    #     optional   — dashed line (may exist; exists in some instances)
-    #
-    #   count (line count — how many):
-    #     exactly_one  — 1 line
-    #     at_least_one — 1 solid + 1 dashed
-    #     multiple     — 2 lines
-    #
-    # Valid combinations (5):
-    #   required + exactly_one    = compulsory (1 solid)
-    #   optional + exactly_one    = optional (1 dashed)
-    #   required + multiple       = compulsory_multiple (2 solid)
-    #   optional + multiple       = optional_multiple (2 dashed)
-    #   required + at_least_one   = compulsory_at_least_one (1 solid + 1 dashed)
-    #
-    # Invalid: optional + at_least_one (collapses to optional + multiple
-    # because "at least one, if present" = "zero or more" = optional_multiple).
-    #
-    # is_delimiting (orthogonal, bold 3x-width line in diagram):
-    #   A delimiting part behaves like a delimiting characteristic:
-    #   it distinguishes the comprehensive from coordinate concepts.
-    #   Example (ISO 704 §5.5.4.2.2): for "optomechanical mouse",
-    #   the delimiting parts are mouse ball, x/y-axis rollers,
-    #   infrared emitter/sensor — they distinguish it from
-    #   "mechanical mouse" and "optical mouse". Mouse button is
-    #   NOT delimiting (all computer mice have buttons).
-    class PartitiveMember < Lutaml::Model::Serializable
-      DEFAULT_PRESENCE = "required"
-      DEFAULT_COUNT = "exactly_one"
-
-      attribute :ref, ConceptRef
-      attribute :presence, :string,
-                values: Glossarist::GlossaryDefinition::PARTITIVE_PRESENCE_VALUES,
-                default: -> { DEFAULT_PRESENCE }
-      attribute :count, :string,
-                values: Glossarist::GlossaryDefinition::PARTITIVE_COUNT_VALUES,
-                default: -> { DEFAULT_COUNT }
-      attribute :is_delimiting, :boolean, default: -> { false }
-
-      key_value do
-        map :ref, to: :ref
-        map :presence, to: :presence
-        map :count, to: :count
-        map :is_delimiting, to: :is_delimiting
-      end
-
-      def validate!
-        validate_ref!
-        validate_presence_count!
-        self
-      end
-
-      def required?
-        presence == "required"
-      end
-
-      def optional?
-        presence == "optional"
-      end
-
-      def delimiting?
-        is_delimiting == true
-      end
-
-      private
-
-      def validate_ref!
-        return if ref.is_a?(ConceptRef) && (ref.source || ref.id || ref.text)
-
-        raise ArgumentError,
-              "PartitiveMember#ref must be a non-empty ConceptRef " \
-              "(source, id, or text required)"
-      end
-
-      def validate_presence_count!
-        unless Glossarist::GlossaryDefinition::PARTITIVE_PRESENCE_VALUES
-                 .include?(presence)
-          raise ArgumentError,
-                "PartitiveMember#presence has invalid value " \
-                "#{presence.inspect}; must be one of " \
-                "#{GlossaryDefinition::PARTITIVE_PRESENCE_VALUES.join(', ')}"
-        end
-
-        unless Glossarist::GlossaryDefinition::PARTITIVE_COUNT_VALUES
-                 .include?(count)
-          raise ArgumentError,
-                "PartitiveMember#count has invalid value " \
-                "#{count.inspect}; must be one of " \
-                "#{GlossaryDefinition::PARTITIVE_COUNT_VALUES.join(', ')}"
-        end
-
-        if presence == "optional" && count == "at_least_one"
-          raise ArgumentError,
-                "PartitiveMember presence=optional + count=at_least_one is " \
-                "invalid — it collapses to optional + multiple (zero or more). " \
-                "Use presence: optional, count: multiple instead."
-        end
-      end
+    # Distinct leaf class for type safety and to leave room for
+    # partitive-specific extensions if needed.
+    class PartitiveMember < HyperedgeMember
+      # Inherits all attributes and validations from HyperedgeMember.
     end
   end
 end