lutaml-model 0.8.32 → 0.8.34

data/lib/lutaml/model/schema/renderers/restricted_type.rb

@@ -7,9 +7,40 @@ module Lutaml
     module Schema
       module Renderers
         # Renders a Definitions::RestrictedType into a Ruby class extending
-        # a Lutaml::Model::Type::* with a cast body that mutates options
-        # with facet values and delegates to super.
+        # a Lutaml::Model::Type::* with Layer-2 facet macros (lazy validation
+        # + `.facets` round-trip) and a cast body that mutates options with
+        # the eager numeric facet values and delegates to super.
         class RestrictedType < Base
+          # XSD base types whose bounds/enumeration values are integer literals.
+          INTEGER_BASES = %i[
+            integer int long short byte
+            positiveInteger nonNegativeInteger negativeInteger nonPositiveInteger
+            unsignedLong unsignedInt unsignedShort unsignedByte
+          ].freeze
+
+          # Base types whose facet values must be emitted as a `cast` call on
+          # the Lutaml type, so the generated literal equals the cast attribute
+          # value it is compared against (temporal/boolean/float parse
+          # specially). Keyed on both the XSD spelling (`dateTime`, from the XSD
+          # compiler) and the snake_case spelling (`date_time`, from the RNG
+          # compiler) since both feed this shared renderer.
+          CAST_BASES = {
+            boolean: "Lutaml::Model::Type::Boolean",
+            float: "Lutaml::Model::Type::Float",
+            double: "Lutaml::Model::Type::Float",
+            date: "Lutaml::Model::Type::Date",
+            dateTime: "Lutaml::Model::Type::DateTime",
+            date_time: "Lutaml::Model::Type::DateTime",
+            time: "Lutaml::Model::Type::Time",
+          }.freeze
+
+          # Bases whose bounds render as bare numeric literals, so the eager
+          # `options[:min]/[:max]` path is valid Ruby. Every other base
+          # (temporal, boolean, string, or a user-defined type) carries a bound
+          # that is not a bare literal, so it stays macro-only and the eager
+          # path is skipped — the Layer-2 facet macros enforce it lazily.
+          EAGER_NUMERIC_BASES = (INTEGER_BASES + %i[decimal float double]).freeze
+
           def render
             Templates::RESTRICTED_SIMPLE_TYPE.result(binding)
           end
@@ -26,6 +57,28 @@ module Lutaml
 
           def restricted_simple_type_required_files = required_files_block
 
+          # Layer-2 facet macros declared in the class body. They store the
+          # facets on the type so generated models validate lazily through
+          # RestrictionValidation and round-trip via `.facets` back to XSD.
+          def restricted_simple_type_facet_declarations
+            f = @spec.facets
+            lines = [
+              ordered("inclusive", f.min_inclusive, f.max_inclusive),
+              ordered("exclusive", f.min_exclusive, f.max_exclusive),
+              length_macro,
+              # Mirror the eager `%r{#{pattern}}` form (not `pattern.inspect`):
+              # a built-in pattern (e.g. anyURI) is stored with live `#{...}`
+              # interpolation that `inspect` would escape, matching the literal
+              # source instead of the value.
+              (Utils.present?(f.pattern) ? "pattern(%r{#{f.pattern}})" : nil),
+              enumeration_macro(f.enumerations),
+              white_space_macro(f.white_space),
+              (Utils.present?(f.total_digits) ? "total_digits #{f.total_digits}" : nil),
+              (Utils.present?(f.fraction_digits) ? "fraction_digits #{f.fraction_digits}" : nil),
+            ]
+            lines.compact.map { |line| "#{@indent}#{line}\n" }.join
+          end
+
           def restricted_simple_type_cast_body
             [
               render_min_max,
@@ -35,15 +88,21 @@ module Lutaml
             ].compact.join
           end
 
+          # Eager numeric option path, valid only for bases whose bounds are
+          # bare numeric literals; other bases are macro-only (see above). The
+          # bound is rendered through `literal_for` so a decimal keeps its exact
+          # value (`BigDecimal("...")`, not a lossy/`.5`-invalid Float literal).
           def render_min_max
+            return nil unless EAGER_NUMERIC_BASES.include?(base_class_name)
+
             f = @spec.facets
             max = f.max_inclusive || f.max_exclusive
             min = f.min_inclusive || f.min_exclusive
             return nil unless max || min
 
             out = +""
-            out << "#{@extended_indent}options[:max] = #{max}\n" if max
-            out << "#{@extended_indent}options[:min] = #{min}\n" if min
+            out << "#{@extended_indent}options[:max] = #{literal_for(max)}\n" if max
+            out << "#{@extended_indent}options[:min] = #{literal_for(min)}\n" if min
             out
           end
 
@@ -65,6 +124,77 @@ module Lutaml
             t && "#{@extended_indent}value = #{t.expression}\n"
           end
 
+          # Format an ordered-facet macro (`inclusive`/`exclusive`) from its
+          # base-typed bounds, emitting only the bounds that are present.
+          def ordered(macro, min, max)
+            args = []
+            args << "min: #{literal_for(min)}" if Utils.present?(min)
+            args << "max: #{literal_for(max)}" if Utils.present?(max)
+            return if args.empty?
+
+            "#{macro} #{args.join(', ')}"
+          end
+
+          # Length facets are always plain integers (character/octet counts),
+          # independent of the base type: exact `length N`, or a min/max range.
+          def length_macro
+            f = @spec.facets
+            return "length #{f.length}" if Utils.present?(f.length)
+
+            args = []
+            args << "min: #{f.min_length}" if Utils.present?(f.min_length)
+            args << "max: #{f.max_length}" if Utils.present?(f.max_length)
+            return if args.empty?
+
+            "length #{args.join(', ')}"
+          end
+
+          def enumeration_macro(enumerations)
+            return nil unless Utils.present?(enumerations)
+
+            "enumeration(#{enumerations.map { |v| literal_for(v) }.join(', ')})"
+          end
+
+          # xs:whiteSpace is a string-only facet; the runtime macro rejects it
+          # on non-string bases. Emit it only for string-derived bases so the
+          # generated code loads.
+          def white_space_macro(white_space)
+            return nil unless string_derived_base? && Utils.present?(white_space)
+
+            "white_space #{white_space.inspect}"
+          end
+
+          # The one renderer for base-typed facet values (bounds, enumeration):
+          # decimal an exact BigDecimal, temporal/boolean/float a cast value
+          # comparable via `<=>`, integer a bare literal, a user-defined base a
+          # `cast` on its generated parent class (in scope as this class's
+          # superclass), and a built-in string base a quoted string.
+          def literal_for(raw)
+            name = base_class_name
+            return %{BigDecimal("#{raw}")} if name == :decimal
+            if (klass = CAST_BASES[name])
+              return "#{klass}.cast(#{raw.to_s.inspect})"
+            end
+            return raw.to_i.to_s if INTEGER_BASES.include?(name)
+            unless XmlCompiler::SupportedDataTypes[name]
+              return "#{Utils.camel_case(name.to_s)}.cast(#{raw.to_s.inspect})"
+            end
+
+            raw.to_s.inspect
+          end
+
+          def string_derived_base?
+            name = base_class_name
+            return false if name == :decimal
+            return false if INTEGER_BASES.include?(name)
+
+            !CAST_BASES.key?(name)
+          end
+
+          def base_class_name
+            @spec.base_class&.to_sym
+          end
+
           def registration_methods
             Registration.methods_block(
               class_name: @spec.class_name,

data/lib/lutaml/model/schema/rng_compiler/define_classifier.rb

@@ -66,7 +66,9 @@ module Lutaml
             Definitions::RestrictedType.new(
               class_name: @class_name,
               parent_class: RngHelpers.parent_class_for(base),
+              base_class: base.to_s,
               facets: RngHelpers.facet_from_data(data),
+              required_files: RngHelpers.required_files_for(base),
             )
           end
 
@@ -77,6 +79,7 @@ module Lutaml
             Definitions::RestrictedType.new(
               class_name: @class_name,
               parent_class: RngHelpers.parent_class_for(:string),
+              base_class: "string",
               facets: RngHelpers.facet_from_values(choice.value),
             )
           end

data/lib/lutaml/model/schema/rng_compiler/rng_helpers.rb

@@ -121,6 +121,12 @@ module Lutaml
             ).to_s
           end
 
+          # A decimal-based restricted type renders `BigDecimal(...)` facet
+          # literals, so the generated file must require bigdecimal to load.
+          def required_files_for(base_symbol)
+            base_symbol == :decimal ? [%(require "bigdecimal")] : []
+          end
+
           def apply_param(facet, name, value)
             case name
             when "minInclusive" then facet.min_inclusive = numeric_or_string(value)
@@ -136,8 +142,10 @@ module Lutaml
 
           def numeric_or_string(value)
             return value.to_i if /\A-?\d+\z/.match?(value)
-            return value.to_f if /\A-?\d+\.\d+\z/.match?(value)
 
+            # Keep a fractional bound as its exact lexical string; casting through
+            # Float would truncate a high-precision decimal before it reaches the
+            # `BigDecimal("...")` facet literal (mirrors the XSD compiler).
             value
           end
 

data/lib/lutaml/model/schema/rng_compiler/value_type_resolver.rb

@@ -75,7 +75,9 @@ module Lutaml
                 @classes, "#{Utils.camel_case(container.attr_name.to_s)}Type"
               ),
               parent_class: RngHelpers.parent_class_for(base),
+              base_class: base.to_s,
               facets: facet,
+              required_files: RngHelpers.required_files_for(base),
             )
           end
 

data/lib/lutaml/model/schema/templates.rb

@@ -111,6 +111,7 @@ module Lutaml
         # Binding: module_opening, module_closing, registration_methods,
         # registration_execution, rendered_class_name, parent_class,
         # xml_namespace_line, restricted_simple_type_required_files,
+        # restricted_simple_type_facet_declarations,
         # restricted_simple_type_cast_body, boilerplate_indent_str.
         RESTRICTED_SIMPLE_TYPE = ERB.new(<<~TMPL, trim_mode: "-")
           # frozen_string_literal: true
@@ -123,6 +124,7 @@ module Lutaml
           <%= boilerplate_indent_str * 2 %><%= xml_namespace_line %>
           <%= boilerplate_indent_str %>end
           <%- end -%>
+          <%= restricted_simple_type_facet_declarations -%>
           <%= boilerplate_indent_str %>def self.cast(value, options = {})
           <%= boilerplate_indent_str * 2 %>return if value.nil?
 

data/lib/lutaml/model/schema/xml_compiler/spec_builder/simple_types.rb

@@ -39,6 +39,7 @@ module Lutaml
               Definitions::RestrictedType.new(
                 class_name: Utils.camel_case(name),
                 parent_class: restricted_parent_class(base),
+                base_class: base,
                 facets: facet,
                 transform_facet: transform,
                 required_files: supported_required_files(base),
@@ -80,6 +81,7 @@ module Lutaml
               Definitions::RestrictedType.new(
                 class_name: Utils.camel_case(name),
                 parent_class: restricted_parent_class(base_class),
+                base_class: base_class,
                 facets: facet,
                 transform_facet: nil,
                 required_files: restricted_required_files(base_class),
@@ -122,28 +124,58 @@ module Lutaml
                 min_length: pick_minmax(restriction.min_length, :max),
                 min_inclusive: pick_minmax(restriction.min_inclusive, :max),
                 max_inclusive: pick_minmax(restriction.max_inclusive, :min),
-                max_exclusive: pick_minmax(restriction.max_exclusive, :max),
-                min_exclusive: pick_minmax(restriction.min_exclusive, :min),
-                length: restriction.length&.any? ? restriction_length(restriction.length) : nil,
+                max_exclusive: pick_minmax(restriction.max_exclusive, :min),
+                min_exclusive: pick_minmax(restriction.min_exclusive, :max),
+                length: pick_minmax(restriction.length, :min),
                 pattern: build_pattern(restriction.pattern),
                 enumerations: restriction.enumeration&.any? ? restriction.enumeration.map(&:value) : nil,
+                white_space: single_facet(restriction.white_space, &:to_sym),
+                total_digits: single_facet(restriction.total_digits, &:to_i),
+                fraction_digits: single_facet(restriction.fraction_digits, &:to_i),
               )
             end
 
+            # Pick the tightest bound as its exact lexical string. A single
+            # value (the only schema-valid case) is returned verbatim so a
+            # decimal keeps its precision; a repeated bound is ordered by
+            # numeric magnitude (not lexical order, under which "5" > "10"),
+            # falling back to lexical order for non-numeric temporal bounds.
             def pick_minmax(field_value, method)
               return nil unless field_value&.any?
 
-              field_value.map(&:value).public_send(method).to_s
+              values = field_value.map(&:value)
+              return values.first if values.one?
+
+              values.public_send(:"#{method}_by") { |v| comparable_bound(v) }
+            end
+
+            # Lazy, guarded require (mirrors Type::Decimal) so this Opal-booted
+            # file has no load-time bigdecimal dependency; the XSD compiler is a
+            # native-only path, so this only runs under MRI.
+            def comparable_bound(value)
+              require "bigdecimal" unless defined?(BigDecimal)
+              BigDecimal(value.to_s)
+            rescue ArgumentError
+              value.to_s
             end
 
-            def restriction_length(lengths)
-              lengths.map { |l| { value: l.value, fixed: l.fixed } }
+            # Carry a single-valued facet (whiteSpace/totalDigits/
+            # fractionDigits), normalizing its lexical value through the block.
+            def single_facet(field_value)
+              return nil unless field_value&.any?
+
+              yield(field_value.first.value)
             end
 
+            # Multiple <xsd:pattern> in one restriction are alternatives (OR),
+            # each grouped so a `|` inside one does not leak across; a single
+            # pattern needs no grouping and is carried verbatim so it round-trips
+            # exactly (and keeps any live `#{...}` interpolation, e.g. anyURI).
             def build_pattern(patterns)
               return nil if Utils.blank?(patterns)
 
-              patterns.map { |p| "(#{p.value})" }.join("|")
+              values = patterns.map(&:value)
+              values.one? ? values.first : values.map { |v| "(#{v})" }.join("|")
             end
           end
         end

data/lib/lutaml/model/schema/xml_compiler/supported_data_types.rb

@@ -33,10 +33,13 @@ module Lutaml
             language: { skippable: false, class_name: TC[:string],
                         validations: { pattern: /\A[a-zA-Z]{1,8}(-[a-zA-Z0-9]{1,8})*\z/ } },
             dateTime: { skippable: true, class_name: TC[:date_time] },
+            date: { skippable: true, class_name: TC[:date] },
+            time: { skippable: true, class_name: TC[:time] },
             boolean: { skippable: true, class_name: TC[:boolean] },
             integer: { skippable: true, class_name: TC[:integer] },
             decimal: { skippable: true, class_name: TC[:decimal] },
             string: { skippable: true, class_name: TC[:string] },
+            float: { skippable: true, class_name: TC[:float] },
             double: { skippable: true, class_name: TC[:float] },
             NCName: { skippable: false, class_name: TC[:string],
                       validations: { pattern: /\A[a-zA-Z_][\w.-]*\z/ } },

data/lib/lutaml/model/serialize/attribute_definition.rb

@@ -27,8 +27,11 @@ module Lutaml
             unless method_defined?(name, false)
               define_method(name) do
                 value = public_send(attr.method_name)
-                # Cast the derived value to the specified type
-                attr.cast_element(value, register_id)
+                # Cast the derived value to the specified type. cast_derived,
+                # not cast_element: this reader is its own casting entry point,
+                # so it needs the same "nothing arrived, nothing to cast" rule
+                # the writers get, and a collection has to come back as one.
+                attr.cast_derived(value, register_id)
               end
             end
           elsif attr.unresolved_type == Lutaml::Model::Type::Reference
@@ -64,14 +67,22 @@ module Lutaml
           unless method_defined?(:"#{name}_#{key_method_name}", false)
             define_method("#{name}_#{key_method_name}") do
               ref = instance_variable_get(:"@#{name}_ref")
-              resolve_reference_key(ref)
+              # attr.reference_key first: once a collection reader has stored
+              # its resolved objects, the key has to come back off the object.
+              resolve_reference_key(attr.reference_key(ref))
             end
           end
 
           unless method_defined?(name, false)
-            define_method(name) do
-              ref = instance_variable_get(:"@#{name}_ref")
-              resolve_reference_value(ref)
+            if attr.options[:collection]
+              define_method(name) do
+                materialize_reference_collection(name)
+              end
+            else
+              define_method(name) do
+                ref = instance_variable_get(:"@#{name}_ref")
+                resolve_reference_value(ref)
+              end
             end
           end
 
@@ -101,7 +112,7 @@ module Lutaml
           if attr.collection?
             define_method(name) do |*args|
               if args.empty?
-                instance_variable_get(:"@#{name}")
+                materialize_lazy_collection(name)
               else
                 # Builder-style: g.member(item) appends to collection
                 value = args.first

data/lib/lutaml/model/serialize/builder.rb

@@ -75,11 +75,10 @@ module Lutaml
           mapping&.ordered? || false
         end
 
-        # Whether this instance was constructed via a builder block and
-        # therefore records mutations into element_order. Parsed models
-        # and instances constructed without a block do not track; their
-        # element_order (if any) comes from the parser and is treated as
-        # the complete source of truth by the serializer.
+        # Whether this instance was constructed via a builder block and so
+        # records one element_order entry per mutation. A parsed instance
+        # does not: its order comes from the document, where one entry can
+        # stand for several rules that share an element name.
         # @return [Boolean]
         def order_tracking_enabled?
           @__order_tracking__ ? true : false

data/lib/lutaml/model/serialize/conversion_caching.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+Lutaml::Model::RuntimeCompatibility.require_native("digest")
+
+module Lutaml
+  module Model
+    module Serialize
+      # Opt-in caching of format conversions in both directions:
+      # deserialized whole objects and serialized output strings
+      # (issue #267).
+      #
+      # A class declares `cache_conversions`; plain `from_<format>` and
+      # `to_<format>` calls are then served from the store configured via
+      # `Config.conversion_cache`. The store is duck-typed — anything
+      # responding to `get(key)` and `set(key, value)` works.
+      # `Lutaml::Store::BasicStore` (lutaml-store gem) is the recommended
+      # backend; TTL, eviction, persistence and clearing are the store's
+      # concern, and store exceptions propagate unchanged. Cache hits do
+      # not emit Instrumentation events — the work did not happen.
+      #
+      # Semantics (deliberate):
+      # - `from_*` hits return the same cached instance for identical
+      #   input — across callers and threads. Treat results as read-only;
+      #   classes whose callers mutate parse results must not opt in.
+      # - Keys digest everything that determines the result: the input
+      #   string (:from) or instance (:to), plus all options except
+      #   :register (folded into the key as a resolved id). What cannot
+      #   be digested bypasses instead of risking a wrong hit: non-String
+      #   inputs (Pathname/IO — content lives elsewhere), non-Hash
+      #   options (Psych/JSON generator protocol objects), and graphs
+      #   Marshal refuses — e.g. instances parsed from XML hold native
+      #   parser nodes for round-trip fidelity, so :to caching engages
+      #   for programmatically built instances.
+      # - Structural invalidation is not propagated: mutating a register's
+      #   mappings or calling GlobalContext.clear_caches does not touch
+      #   the store — clear or replace the store after such mutations.
+      # - A hit returns before the wrapped body runs, so option-hash
+      #   mutations the body performs on a miss (e.g. consuming :adapter)
+      #   do not happen on a hit.
+      # - Caching is disabled under Opal: keys need native Marshal/Digest.
+      module ConversionCaching
+        NATIVE_RUNTIME = !Lutaml::Model::RuntimeCompatibility.opal?
+
+        UNMARSHALABLE_IVAR = :@__lutaml_conversion_cache_unmarshalable
+
+        def cache_conversions
+          define_singleton_method(:conversion_caching_enabled?) { true }
+        end
+
+        def conversion_caching_enabled?
+          false
+        end
+
+        private
+
+        def with_conversion_cache(kind, format, source, options)
+          store = conversion_cache_store(options)
+          return yield unless store
+
+          payload = conversion_cache_payload(kind, source, options)
+          return yield unless payload
+
+          key = conversion_cache_key(kind, format, payload, options)
+          cached = store.get(key)
+          return cached if cacheable_value?(kind, cached)
+
+          result = yield
+          store.set(key, result) if cacheable_value?(kind, result)
+          result
+        end
+
+        def conversion_cache_store(options)
+          unless NATIVE_RUNTIME && conversion_caching_enabled? &&
+              options.is_a?(::Hash)
+            return
+          end
+
+          Config.conversion_cache
+        end
+
+        # A :to source whose graph Marshal refuses (native parser nodes,
+        # IO, procs, ...) costs an O(graph) traversal to fail — ~749 ms at
+        # 50k objects, repeated on every call for zero benefit. The first
+        # failure is remembered on the instance so later calls bypass
+        # straight to yield. The frozen guard preserves today's graceful
+        # bypass (instance_variable_set would raise on a frozen source).
+        # The flag is sticky: an instance later mutated back to marshalable
+        # keeps bypassing the cache — a missed hit, never a wrong result.
+        def conversion_cache_payload(kind, source, options)
+          return if kind == :from && !source.is_a?(::String)
+          return if kind == :to && source.instance_variable_defined?(UNMARSHALABLE_IVAR)
+
+          ::Marshal.dump([source, options.except(:register)])
+        rescue ::TypeError
+          if kind == :to && !source.frozen?
+            source.instance_variable_set(UNMARSHALABLE_IVAR, true)
+          end
+          nil
+        end
+
+        # The key pins everything the payload digest does not: direction,
+        # class identity (name plus object_id — same-named classes can
+        # coexist, see TransformationRegistry's keys), format, register,
+        # and resolved adapter.
+        def conversion_cache_key(kind, format, payload, options)
+          register = extract_register_id(options[:register])
+          adapter = AdapterResolver.adapter_for(format)
+          digest = ::Digest::SHA256.hexdigest(payload)
+
+          "#{kind}:#{name}/#{object_id}:#{format}:#{register}:#{adapter}:#{digest}"
+        end
+
+        # Gate for both serving and admitting cache values: a :from value
+        # must be an instance of this model, a :to value a serialized
+        # String. Anything else — a store that JSON-marshals values back
+        # into hashes, Array results from multi-document formats, nil —
+        # is neither served nor stored.
+        def cacheable_value?(kind, value)
+          kind == :from ? value.is_a?(self) : value.is_a?(::String)
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/serialize/enum_handling.rb

@@ -49,15 +49,18 @@ module Lutaml
               value_set_for(enum_name)
               enum_vals = public_send(:"#{enum_name}")
 
+              # `+` and `-` rather than `<<` and `delete`. The reader hands
+              # back the stored Array now, so mutating it here would reach an
+              # Array a caller already holds — and would land even when the
+              # store below raises on a frozen model.
               enum_vals = if !!val
                             if collection
-                              enum_vals << value
+                              enum_vals.include?(value) ? enum_vals : enum_vals + [value]
                             else
                               [value]
                             end
                           elsif collection
-                            enum_vals.delete(value)
-                            enum_vals
+                            enum_vals - [value]
                           else
                             instance_variable_get(:"@#{enum_name}") - [value]
                           end
@@ -80,15 +83,46 @@ module Lutaml
           Utils.add_method_if_not_defined(klass, enum_name) do
             i = instance_variable_get(:"@#{enum_name}") || []
 
-            if !collection && i.is_a?(Array)
-              # A singular enum stores its one value as a one-element array.
-              # Several values is a cardinality violation, so hand the array
-              # on instead of collapsing it — #validate reads through here and
-              # would otherwise never see the over-count.
-              i.size > 1 ? i : i.first
-            else
-              i.uniq
+            # A singular enum stores its one value as a one-element array.
+            # Several values is a cardinality violation, so hand the array
+            # on instead of collapsing it — #validate reads through here and
+            # would otherwise never see the over-count. Collections fall
+            # through to the liveness path so pushes reach the model.
+            next(i.size > 1 ? i : i.first) if !collection && i.is_a?(Array)
+
+            current = materialize_lazy_collection(enum_name)
+
+            # An enum collection reads as an Array even when nothing was
+            # stored — the old `(ivar || []).uniq` never returned nil — so
+            # unlike a regular collection this one materializes nil too, and
+            # stores what it materialized so a push reaches the model.
+            if current.nil?
+              next [] if frozen?
+
+              next instance_variable_set(:"@#{enum_name}", [])
             end
+
+            # Not an Array, which means a model-defined writer stored
+            # something else. Read it the way the old reader did and leave
+            # what it stored alone — replacing it here would discard data.
+            next current.uniq unless current.is_a?(::Array)
+
+            # A frozen Array cannot be deduped in place, and handing back a
+            # copy would lose the shared sentinel's identity, so only copy
+            # when there is actually something to remove.
+            if current.frozen?
+              deduped = current.uniq
+              next deduped.size == current.size ? current : deduped
+            end
+
+            # Hand back the stored Array, not a copy. This used to be
+            # `i.uniq`, a fresh Array on every read, so `model.roles << "b"`
+            # pushed onto a throwaway and the value never reached the model —
+            # no error, no warning, the item simply never showed up in the
+            # document. It still has to read unique, which is what that `uniq`
+            # guaranteed, so dedupe in place rather than into a copy.
+            current.uniq!
+            current
           end
         end
 
@@ -109,6 +143,11 @@ module Lutaml
             if collection
               curr_value = public_send(:"#{enum_name}")
 
+              # Build a new Array rather than appending into the stored one.
+              # The reader hands back the real Array now, so `curr_value` may
+              # be this model's own collection — or, when the model defines
+              # its own reader, something shared between instances or not an
+              # Array at all. Duplicates are the reader's job either way.
               instance_variable_set(:"@#{enum_name}", curr_value + value)
             else
               instance_variable_set(:"@#{enum_name}", value)