opencdd 0.1.1 → 0.2.1

data/lib/opencdd/{model/yaml_entity.rb → entity/yaml.rb}

@@ -1,16 +1,28 @@
-# frozen_string: true
+# frozen_string_literal: true
 
 require "lutaml/model"
 
 module Opencdd
-  module Model
-    # CDD-native YAML entity. Every attribute uses the semantic name
-    # from the CDD ontology (preferred_name, superclass, class_type)
-    # rather than the IEC 62656-1 wire-format key (MDC_P004, MDC_P010,
-    # MDC_P011). Multilingual fields are Hash<String, String>;
-    # collection fields are Array<String>.
+  class Entity < Lutaml::Model::Serializable
+    # CDD-native YAML serialization model.
     #
-    # This is the canonical YAML shape for a CDD entity:
+    # This is the deepened YAML adapter: the conversion logic that
+    # translates between semantic CDD attribute names (preferred_name,
+    # superclass, class_type) and IEC 62656-1 wire-format keys
+    # (MDC_P004, MDC_P010, MDC_P011) lives here, inside Entity's
+    # namespace. Entity delegates +to_yaml+ / +from_yaml+ to this
+    # class.
+    #
+    # Why a separate class? lutaml-model serialization calls
+    # +public_send(attr_name)+ during +to_format+, which invokes the
+    # getter method. Entity's field DSL getters read from +@properties+
+    # and return domain objects (IRDI, source-language String, parsed
+    # Array). The YAML attrs need flat types (String, Hash, Array).
+    # Sharing the same name would make the getter return the wrong
+    # type for serialization. Keeping the YAML model here avoids that
+    # conflict while keeping the adapter "inside" Entity.
+    #
+    # Canonical YAML shape:
     #
     #   ---
     #   irdi: 0112/2///61360_4#AAA001
@@ -20,15 +32,12 @@ module Opencdd
     #     en: Vehicle
     #     fr: Véhicule
     #   class_type: ITEM_CLASS
-    #   superclass: UNIVERSE
+    #   superclass: 0112/2///61360_4#AAA000
     #   applicable_properties:
-    #     - vehicle_length
-    #     - vehicle_weight
-    #
-    # Conversion between YamlEntity and the existing Entity model
-    # is via #from_entity and #to_entity, which bridge the semantic
-    # attributes to the raw properties Hash.
-    class YamlEntity < Lutaml::Model::Serializable
+    #     - 0112/2///61360_4#AAAP001
+    #   extra:
+    #     C016: released
+    class Yaml < Lutaml::Model::Serializable
       # ── Identity ────────────────────────────────────────────
       attribute :irdi, :string
       attribute :type, :string               # :class, :property, :unit, ...
@@ -41,6 +50,7 @@ module Opencdd
       attribute :definition, :hash
       attribute :note, :hash
       attribute :remark, :hash
+      attribute :description, :hash
 
       # ── Version ─────────────────────────────────────────────
       attribute :version, :string
@@ -67,18 +77,26 @@ module Opencdd
       attribute :unit_text, :string
 
       # ── Value-list-specific ─────────────────────────────────
-      attribute :enumerated_values, :string, collection: true
       attribute :list_type, :string
+      attribute :code_list, :string, collection: true
+      attribute :term_irdis, :string, collection: true
+
+      # ── Value-term-specific ─────────────────────────────────
+      attribute :enumeration_code, :string
 
       # ── Relation-specific ───────────────────────────────────
       attribute :relation_type, :string
-      attribute :domain, :string, collection: true
       attribute :codomain, :string
+      attribute :formula, :string
+
+      # ── View-control-specific ───────────────────────────────
+      attribute :controlled_classes, :string, collection: true
+      attribute :shown_properties, :string, collection: true
 
       # ── Catch-all for unknown properties (lossless) ────────
       attribute :extra, :hash
 
-      # ── Conversion: Entity → YamlEntity ────────────────────
+      # ── Conversion: Entity → Entity::Yaml ───────────────────
       def self.from_entity(entity)
         attrs = {
           irdi: entity.irdi&.to_s,
@@ -89,64 +107,74 @@ module Opencdd
           revision: entity[Opencdd::PropertyIds::MDC_P002_2],
         }
 
-        # Multilingual fields
         attrs[:preferred_name] = extract_ml(entity, Opencdd::PropertyIds::MDC_P004)
         attrs[:short_name]     = extract_ml(entity, Opencdd::PropertyIds::MDC_P005)
         attrs[:definition]     = extract_ml(entity, Opencdd::PropertyIds::MDC_P006)
         attrs[:note]           = extract_ml(entity, Opencdd::PropertyIds::MDC_P008)
         attrs[:remark]         = extract_ml(entity, Opencdd::PropertyIds::MDC_P009)
+        attrs[:description]    = extract_ml(entity, Opencdd::PropertyIds::MDC_P112)
 
-        # Class-specific
-        if entity.type == :class
-          ct = entity.read_field(:class_type)
-          attrs[:class_type] = ct&.to_s
+        case entity.type
+        when :class
+          attrs[:class_type] = entity.read_field(:class_type)&.to_s
           attrs[:superclass] = entity.read_field(:superclass_irdi)&.to_s
           attrs[:is_case_of] = entity.read_field(:is_case_of_irdis)&.map(&:to_s) || []
           attrs[:applicable_properties] = entity.read_field(:applicable_property_irdis)&.map(&:to_s) || []
           attrs[:imported_properties] = entity.read_field(:imported_property_irdis)&.map(&:to_s) || []
           attrs[:sub_class_selection] = entity.read_field(:sub_class_selection_irdis)&.map(&:to_s) || []
-        end
-
-        # Property-specific
-        if entity.type == :property
-          dt = entity.read_field(:parsed_data_type)
-          attrs[:data_type] = dt&.to_s
+        when :property
+          attrs[:data_type] = entity.read_field(:parsed_data_type)&.to_s
           attrs[:value_format] = entity.read_field(:parsed_value_format)&.to_s
-          dc = entity.read_field(:definition_class_irdi)
-          attrs[:definition_class] = dc&.to_s
-          ui = entity.read_field(:unit_irdi)
-          attrs[:unit] = ui&.to_s
+          attrs[:definition_class] = entity.read_field(:definition_class_irdi)&.to_s
+          attrs[:unit] = entity.read_field(:unit_irdi)&.to_s
           attrs[:condition] = entity.read_field(:condition)&.to_s
           attrs[:property_data_element_type] = entity.read_field(:property_data_element_type)&.to_s
+        when :unit
+          attrs[:unit_structure] = entity.read_field(:structure)
+          attrs[:unit_text] = entity.read_field(:text_representation)
+        when :value_list
+          attrs[:list_type] = entity.read_field(:list_type)&.to_s
+          attrs[:code_list] = entity.read_field(:code_list) || []
+          attrs[:term_irdis] = entity.read_field(:term_irdis)&.map(&:to_s) || []
+        when :value_term
+          attrs[:enumeration_code] = entity.read_field(:enumeration_code)
+        when :relation
+          attrs[:relation_type] = entity.read_field(:relation_type)&.to_s
+          attrs[:codomain] = entity.read_field(:codomain_irdi)&.to_s
+          attrs[:formula] = entity.read_field(:formula)
+        when :view_control
+          attrs[:controlled_classes] = entity.read_field(:controlled_class_irdis)&.map(&:to_s) || []
+          attrs[:shown_properties] = entity.read_field(:shown_property_irdis)&.map(&:to_s) || []
         end
 
+        extra = extract_extra(entity)
+        attrs[:extra] = extra if extra
+
         new(**attrs.compact)
       end
 
-      # ── Conversion: YamlEntity → Entity ────────────────────
-      def to_entity(database = nil)
+      # ── Conversion: Entity::Yaml → Entity ───────────────────
+      def to_entity(_database = nil)
         props = {}
 
         props[Opencdd::PropertyIds::MDC_P066] = guid if guid
         props[Opencdd::PropertyIds::MDC_P002_1] = version if version
         props[Opencdd::PropertyIds::MDC_P002_2] = revision if revision
 
-        # Multilingual
         merge_ml_into(props, Opencdd::PropertyIds::MDC_P004, preferred_name)
         merge_ml_into(props, Opencdd::PropertyIds::MDC_P005, short_name)
         merge_ml_into(props, Opencdd::PropertyIds::MDC_P006, definition)
         merge_ml_into(props, Opencdd::PropertyIds::MDC_P008, note)
         merge_ml_into(props, Opencdd::PropertyIds::MDC_P009, remark)
+        merge_ml_into(props, Opencdd::PropertyIds::MDC_P112, description)
 
-        # Class-specific
         props[Opencdd::PropertyIds::MDC_P011] = class_type if class_type
         props[Opencdd::PropertyIds::MDC_P010] = superclass if superclass
-        props[Opencdd::PropertyIds::MDC_P013] = "{#{is_case_of.join(",")}}" if is_case_of&.any?
-        props[Opencdd::PropertyIds::MDC_P014] = "{#{applicable_properties.join(",")}}" if applicable_properties&.any?
-        props[Opencdd::PropertyIds::MDC_P090] = "{#{imported_properties.join(",")}}" if imported_properties&.any?
-        props[Opencdd::PropertyIds::MDC_P016] = "{#{sub_class_selection.join(",")}}" if sub_class_selection&.any?
+        props[Opencdd::PropertyIds::MDC_P013] = rejoin_set(is_case_of) if is_case_of&.any?
+        props[Opencdd::PropertyIds::MDC_P014] = rejoin_set(applicable_properties) if applicable_properties&.any?
+        props[Opencdd::PropertyIds::MDC_P090] = rejoin_set(imported_properties) if imported_properties&.any?
+        props[Opencdd::PropertyIds::MDC_P016] = rejoin_set(sub_class_selection) if sub_class_selection&.any?
 
-        # Property-specific
         props[Opencdd::PropertyIds::MDC_P022] = data_type if data_type
         props[Opencdd::PropertyIds::MDC_P024] = value_format if value_format
         props[Opencdd::PropertyIds::MDC_P021] = definition_class if definition_class
@@ -154,17 +182,31 @@ module Opencdd
         props[Opencdd::PropertyIds::MDC_P028] = condition if condition
         props[Opencdd::PropertyIds::MDC_P020] = property_data_element_type if property_data_element_type
 
-        # Determine entity class from type
-        entity_class = Opencdd::MetaClasses.entity_class_for_type(type&.to_sym) || Opencdd::Klass
-        meta_code = Opencdd::MetaClasses.meta_class_for_type(type&.to_sym) || "MDC_C002"
+        props[Opencdd::PropertyIds::MDC_P023] = unit_structure if unit_structure
+        props[Opencdd::PropertyIds::MDC_P023_1] = unit_text if unit_text
+
+        props[Opencdd::PropertyIds::MDC_P046] = list_type if list_type
+        props[Opencdd::PropertyIds::MDC_P044] = rejoin_set(code_list) if code_list&.any?
+        props[Opencdd::PropertyIds::MDC_P043] = rejoin_set(term_irdis) if term_irdis&.any?
+
+        props[Opencdd::PropertyIds::MDC_P044] = enumeration_code if enumeration_code
 
-        parsed_irdi = irdi ? Opencdd::IRDI.parse(irdi) : nil
-        parsed_meta = Opencdd::IRDI.parse(meta_code)
+        props[Opencdd::PropertyIds::MDC_P200] = relation_type if relation_type
+        props[Opencdd::PropertyIds::MDC_P203] = codomain if codomain
+        props[Opencdd::PropertyIds::MDC_P204] = formula if formula
+
+        props[Opencdd::PropertyIds::EXT_P002] = rejoin_set(controlled_classes) if controlled_classes&.any?
+        props[Opencdd::PropertyIds::EXT_P003] = rejoin_set(shown_properties) if shown_properties&.any?
+
+        extra&.each { |k, v| props[k.to_s] = v }
+
+        entity_class = Opencdd::MetaClasses.entity_class_for_type(type&.to_sym) || Opencdd::Klass
+        meta_code = Opencdd::MetaClasses.meta_class_for_type(type&.to_sym) || Opencdd::MetaClasses::MDC_C002
 
         entity_class.new(
-          irdi: parsed_irdi,
+          irdi: irdi ? Opencdd::IRDI.parse(irdi) : nil,
           properties: props,
-          meta_class_irdi: parsed_meta,
+          meta_class_irdi: Opencdd::IRDI.parse(meta_code),
         )
       end
 
@@ -181,6 +223,31 @@ module Opencdd
       end
       private_class_method :extract_ml
 
+      KNOWN_WIRE_IDS = %w[
+        MDC_P002_1 MDC_P002_2 MDC_P066
+        MDC_P004 MDC_P005 MDC_P006 MDC_P008 MDC_P009 MDC_P112
+        MDC_P011 MDC_P010 MDC_P010_1
+        MDC_P013 MDC_P014 MDC_P090 MDC_P016
+        MDC_P022 MDC_P024 MDC_P021 MDC_P041 MDC_P028 MDC_P020
+        MDC_P023 MDC_P023_1
+        MDC_P046 MDC_P044 MDC_P043
+        MDC_P200 MDC_P203 MDC_P204
+        EXT_P002 EXT_P003
+      ].freeze
+
+      def self.extract_extra(entity)
+        extra = {}
+        entity.properties.each do |k, v|
+          key = k.to_s
+          next if key == "__row_index__"
+          base = key.split(".", 2).first
+          next if KNOWN_WIRE_IDS.include?(base)
+          extra[key] = v
+        end
+        extra.empty? ? nil : extra
+      end
+      private_class_method :extract_extra
+
       def self.merge_ml(props, pid, hash)
         return unless hash&.any?
         hash.each { |lang, val| props["#{pid}.#{lang}"] = val }
@@ -191,6 +258,10 @@ module Opencdd
       def merge_ml_into(props, pid, hash)
         self.class.merge_ml(props, pid, hash)
       end
+
+      def rejoin_set(list)
+        Opencdd::StructuredValues.rejoin(list)
+      end
     end
   end
 end

data/lib/opencdd/entity.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require "lutaml/model"
+
 module Opencdd
-  class Entity
+  class Entity < Lutaml::Model::Serializable
     include Opencdd::ParseHelpers
 
     # Open/closed field declaration. Each `field :foo, "MDC_P###",
@@ -12,6 +14,7 @@ module Opencdd
     autoload :FieldRegistry,   "opencdd/entity/field_registry"
     autoload :FieldReader,     "opencdd/entity/field_reader"
     autoload :VersionHistory,  "opencdd/entity/version_history"
+    autoload :Yaml,            "opencdd/entity/yaml"
 
     class << self
       # Declare a typed field on this entity class. Defaults for
@@ -80,9 +83,10 @@ module Opencdd
       Opencdd::MetaClasses.code_property_id_for(meta_class_irdi&.code)
     end
 
-    def initialize(irdi:, properties:, schema: nil, meta_class_irdi: nil)
+    def initialize(irdi: nil, properties: nil, schema: nil, meta_class_irdi: nil)
+      super({})
       @irdi = irdi
-      @properties = properties
+      @properties = properties || {}
       @schema = schema
       @meta_class_irdi = meta_class_irdi
       @version_history = Opencdd::Entity::VersionHistory.new
@@ -98,10 +102,6 @@ module Opencdd
 
     alias_method :short, :code
 
-    # ── Pure field reads (value_kind and multilingual auto-resolved
-    #     from PropertyIds::REGISTRY). `as:` aliases preserve the
-    #     existing JSON wire shape — ruby method names differ from
-    #     historical JSON keys for backward compatibility. ─────────
     # Note: irdi and code are NOT declared as DSL fields — they're
     # emitted explicitly by Exporters::Json#entity_payload because
     # the model's `irdi` accessor must return the Opencdd::IRDI object
@@ -251,5 +251,28 @@ module Opencdd
       @source_location = loc
       self
     end
+
+    # ── YAML persistence via Entity::Yaml ──────────────────────
+    # Entity extends Lutaml::Model::Serializable but its own attribute
+    # set is empty — the typed YAML model lives in Entity::Yaml
+    # (the deepened adapter). This avoids name conflicts between the
+    # field DSL getters (which read from @properties and return
+    # coerced values like IRDI objects, source-language Strings,
+    # parsed Arrays) and lutaml-model serialization attrs (which
+    # must return flat types: String, Hash, Array).
+    #
+    # lutaml-model serialization calls +public_send(attr_name)+
+    # during to_format, so any getter with the same name as a
+    # YAML attr is invoked. Keeping the YAML model in Entity::Yaml
+    # lets both worlds coexist: field DSL for domain access,
+    # Entity::Yaml for serialization.
+
+    def to_yaml(*args)
+      Opencdd::Entity::Yaml.from_entity(self).to_yaml(*args)
+    end
+
+    def self.from_yaml(yaml_str)
+      Opencdd::Entity::Yaml.from_yaml(yaml_str).to_entity
+    end
   end
 end

data/lib/opencdd/entity_diff.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Opencdd
+  # Compute a structured diff between two entities of the same IRDI.
+  #
+  # Pure value object: doesn't mutate its inputs, doesn't reach
+  # beyond +entity.properties+. Iterates the union of keys and
+  # categorizes each into +added+, +removed+, or +changed+.
+  #
+  # Multilingual fields (<tt>MDC_P001.en</tt>, <tt>MDC_P001.fr</tt>)
+  # are diffed as a group keyed by their base property ID. A change
+  # in any language counts as one change to the base field.
+  #
+  # Example:
+  #   diff = Opencdd::EntityDiff.between(v001, v002)
+  #   diff.added      # => ["MDC_P999"]
+  #   diff.removed    # => []
+  #   diff.changed    # => [{ field: "preferred_name", from: "X", to: "Y" }]
+  #   diff.empty?     # => false
+  class EntityDiff
+    Change = Struct.new(:field, :from, :to, keyword_init: true)
+
+    attr_reader :from_entity, :to_entity, :added, :removed, :changed
+
+    def self.between(from_entity, to_entity)
+      new(from_entity, to_entity)
+    end
+
+    def initialize(from_entity, to_entity)
+      raise ArgumentError, "EntityDiff requires same IRDI (#{from_entity.irdi} vs #{to_entity.irdi})" unless from_entity.irdi == to_entity.irdi
+      @from_entity = from_entity
+      @to_entity   = to_entity
+      compute_diff
+    end
+
+    def empty?
+      added.empty? && removed.empty? && changed.empty?
+    end
+
+    # Total change count (added + removed + changed).
+    def size
+      added.size + removed.size + changed.size
+    end
+
+    # Wire-format summary suitable for JSON emit or browser diff view.
+    def to_h
+      {
+        irdi: from_entity.irdi.to_s,
+        added: added,
+        removed: removed,
+        changed: changed.map(&:to_h),
+      }
+    end
+
+    private
+
+    def compute_diff
+      @added = []
+      @removed = []
+      @changed = []
+      from_groups = grouped_properties(from_entity)
+      to_groups   = grouped_properties(to_entity)
+      (from_groups.keys | to_groups.keys).sort.each do |field|
+        from_val = from_groups[field]
+        to_val   = to_groups[field]
+        if from_val.nil? && !to_val.nil?
+          @added << field
+        elsif !from_val.nil? && to_val.nil?
+          @removed << field
+        elsif values_differ?(from_val, to_val)
+          @changed << Change.new(field: field, from: from_val, to: to_val)
+        end
+      end
+    end
+
+    # Group multilingual keys (<base>.<lang>) under their <base>.
+    # Returns +{ base_property_id => grouped_value }+ where
+    # +grouped_value+ is a string for monolingual fields or a
+    # sorted +{ lang => value }+ hash for multilingual fields.
+    def grouped_properties(entity)
+      groups = Hash.new { |h, k| h[k] = {} }
+      entity.properties.each do |key, value|
+        next if value.nil?
+        k = key.to_s
+        base, lang = split_language_suffix(k)
+        if lang
+          groups[base][lang] = value.to_s
+        else
+          groups[base] = value.to_s
+        end
+      end
+      # Collapse empty hashes (a group that had only nil values).
+      groups.transform_values { |v| v.is_a?(Hash) && v.empty? ? nil : v }
+    end
+
+    def split_language_suffix(key)
+      m = key.match(/\A(?<base>.+?)\.(?<lang>[a-z]{2,3}(?:-[a-z0-9]+)?)\z/i)
+      return [key, nil] unless m
+      [m[:base], m[:lang].downcase]
+    end
+
+    def values_differ?(from_val, to_val)
+      return from_val != to_val unless from_val.is_a?(Hash) && to_val.is_a?(Hash)
+      # For multilingual groups: compare as normalized hashes.
+      from_val == to_val ? false : true
+    end
+  end
+end

data/lib/opencdd/exporters/json.rb

@@ -53,7 +53,34 @@ module Opencdd
         @nodes << view_control_node(vc)
       end
 
-      private
+      # ─────────────────────────────────────────────────────────────
+      # Public per-entity payload API
+      #
+      # `payload_for(entity, database:)` returns the wire-format Hash
+      # for a single entity. Dispatch is via the PAYLOAD_BUILDERS
+      # registry — adding a new entity type means adding one entry to
+      # the registry and one builder method, not editing a switch.
+      #
+      # The optional `database:` enables cross-entity resolution
+      # (e.g. property → value_list). Without it, cross-links are
+      # omitted (payload still has all the entity's own fields).
+      # ─────────────────────────────────────────────────────────────
+      PAYLOAD_BUILDERS = {
+        Opencdd::Klass        => :class_node,
+        Opencdd::Property     => :property_node,
+        Opencdd::Unit         => :unit_node,
+        Opencdd::ValueList    => :value_list_node,
+        Opencdd::ValueTerm    => :value_term_node,
+        Opencdd::Relation     => :relation_node,
+        Opencdd::ViewControl  => :view_control_node,
+      }.freeze
+
+      def payload_for(entity, database: nil)
+        @database = database if database
+        builder = PAYLOAD_BUILDERS[entity.class]
+        raise ArgumentError, "No JSON payload builder for #{entity.class}" unless builder
+        public_send(builder, entity)
+      end
 
       # ─────────────────────────────────────────────────────────────
       # Open/closed payload builders
@@ -98,6 +125,8 @@ module Opencdd
         entity_payload(vc).merge(type: "view_control").compact
       end
 
+      private
+
       # Iterates every declared field on the entity's class (walking
       # the ancestor chain via FieldRegistry.fields_for). Each field's
       # value is read by name (synthetic fields call their custom

data/lib/opencdd/model/entity_store.rb

@@ -1,25 +1,31 @@
-# frozen_string: true
+# frozen_string_literal: true
 
 require "lutaml/store"
 require "fileutils"
 
 module Opencdd
   module Model
-    # Per-entity YAML persistence using lutaml-store as the backend.
-    # Each entity is stored as a single YAML file in a directory layout,
-    # serialized via Lutaml::Model (YamlEntity). Diff-friendly at the
-    # entity level — one git diff shows exactly which entity changed.
+    # Per-entity YAML persistence using lutaml-store's DatabaseStore
+    # as the backend. Each entity is stored as a single YAML file,
+    # serialized via Lutaml::Model (Entity::Yaml — the deepened
+    # adapter inside Entity's namespace). Diff-friendly at the entity
+    # level — one git diff shows exactly which entity changed.
     #
-    # Directory layout (managed by lutaml-store's FileSystem adapter):
+    # Uses DatabaseStore#save_all and #load_all with format: :yaml
+    # and layout: :separate (one file per entity). This is the
+    # proper lutaml-store API — not the low-level adapter.set/get
+    # bypass that the previous version used.
+    #
+    # Directory layout (managed by DatabaseStore's separate layout):
     #
     #   data/
     #   └── entities/
-    #       ├── AA/
-    #       │   ├── AAA001.data
-    #       │   └── AAA010.data
+    #       ├── 0112_2___61360_4_AAA001.yaml
+    #       ├── 0112_2___61360_4_AAA010.yaml
     #       └── ...
     #
-    # The FileSystem adapter shards by first 2 chars for scalability.
+    # The filename is the model's key field (irdi), sanitized by
+    # the FileSystem adapter (non-alphanumeric chars → underscore).
     class EntityStore
       attr_reader :path, :store
 
@@ -28,23 +34,21 @@ module Opencdd
         FileUtils.mkdir_p(@path)
         @store = Lutaml::Store.new(
           adapter: :filesystem,
-          adapter_options: { path: @path },
+          adapter_options: { path: @path, extension: ".yaml" },
           models: [
-            { model: Opencdd::Model::YamlEntity, key: :irdi, dir: "entities" },
+            { model: Opencdd::Entity::Yaml, key: :irdi, dir: "entities" },
           ],
         )
       end
 
       # Save all entities from +database+ to individual YAML files
-      # via lutaml-store's FileSystem backend. Returns self.
+      # via DatabaseStore#save_all. Returns self.
       def save_database(database)
-        database.entities.each do |entity|
-          yaml_entity = Opencdd::Model::YamlEntity.from_entity(entity)
-          key = safe_key(yaml_entity.irdi || yaml_entity.code)
-          next unless key
-          yaml_str = yaml_entity.to_yaml
-          @store.store.adapter.set(key, yaml_str)
+        yaml_entities = database.entities.filter_map do |entity|
+          yaml = Opencdd::Entity::Yaml.from_entity(entity)
+          yaml.irdi ? yaml : nil
         end
+        @store.save_all(yaml_entities, path: @path, format: :yaml, layout: :separate)
         self
       end
 
@@ -52,33 +56,27 @@ module Opencdd
       # Returns a finalized Database.
       def load_database(database = nil)
         database ||= Opencdd::Database.new
-        @store.store.adapter.keys.each do |key|
-          raw = @store.store.adapter.get(key)
-          next unless raw
-          begin
-            yaml_entity = Opencdd::Model::YamlEntity.from_yaml(raw)
-            entity = yaml_entity.to_entity(database)
-            database.add_entity(entity)
-          rescue StandardError => e
-            warn "EntityStore: skipping #{key}: #{e.message}"
-          end
+        yaml_entities = @store.load_all(
+          Opencdd::Entity::Yaml,
+          path: @path,
+          format: :yaml,
+          layout: :separate,
+        )
+        yaml_entities.each do |yaml_entity|
+          entity = yaml_entity.to_entity(database)
+          database.add_entity(entity)
+        rescue StandardError => e
+          warn "EntityStore: skipping entity: #{e.message}"
         end
         database.finalize!
         database
       end
 
-      # Fetch a single entity by key.
+      # Fetch a single entity's YAML model by key.
       def fetch(key)
-        raw = @store.store.adapter.get(safe_key(key))
-        return nil unless raw
-        Opencdd::Model::YamlEntity.from_yaml(raw)
-      end
-
-      private
-
-      def safe_key(key)
-        return nil if key.nil? || key.to_s.strip.empty?
-        key.to_s.split("#").last || key.to_s
+        @store.fetch(model: Opencdd::Entity::Yaml, irdi: key)
+      rescue Lutaml::Store::InvalidKeyError
+        nil
       end
     end
   end

data/lib/opencdd/model/yaml_database.rb

@@ -4,7 +4,7 @@ require "lutaml/model"
 
 module Opencdd
   module Model
-    # CDD-native YAML database. Wraps a collection of YamlEntity
+    # CDD-native YAML database. Wraps a collection of Entity::Yaml
     # objects with dictionary-level metadata (source language,
     # translation languages). Serializes to YAML via lutaml-model
     # — no hand-rolled serialization on the model class itself.
@@ -26,18 +26,16 @@ module Opencdd
     class YamlDatabase < Lutaml::Model::Serializable
       attribute :source_language, :string, default: "en"
       attribute :translation_languages, :string, collection: true
-      attribute :entities, YamlEntity, collection: true
+      attribute :entities, Opencdd::Entity::Yaml, collection: true
 
-      # ── Conversion: Database → YamlDatabase ─────────────────
       def self.from_database(database)
         new(
           source_language: "en",
           translation_languages: [],
-          entities: database.entities.map { |e| YamlEntity.from_entity(e) },
+          entities: database.entities.map { |e| Opencdd::Entity::Yaml.from_entity(e) },
         )
       end
 
-      # ── Conversion: YamlDatabase → Database ─────────────────
       def to_database(database = nil)
         database ||= Opencdd::Database.new
         entities.each { |ye| database.add_entity(ye.to_entity(database)) }

data/lib/opencdd/model.rb

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
 module Opencdd
-  # CDD-native model layer backed by Lutaml::Model. Provides typed
-  # attributes with semantic CDD names (preferred_name, superclass,
-  # class_type) — not wire-format keys (MDC_P004, MDC_P010). YAML
-  # is the canonical persistence format per user decision (2026-07-13).
+  # Database-level YAML persistence helpers. Entity-level YAML
+  # serialization lives on +Opencdd::Entity::Yaml+ (the deepened
+  # adapter inside Entity's namespace). This module holds the
+  # whole-database YAML wrapper and the per-entity file store.
   module Model
-    autoload :YamlEntity,   "opencdd/model/yaml_entity"
     autoload :YamlDatabase, "opencdd/model/yaml_database"
     autoload :EntityStore,  "opencdd/model/entity_store"
   end