hecks 3.4.2 → 3.6.0

data/lib/hecks/runtime/value/coercion.rb

@@ -48,56 +48,10 @@ module Hecks
         # @raise [Runtime::InvariantViolation] if a coerced value object breaks an invariant
         def for_attribute(aggregate, attribute, value, boundary: true, argument: false)
           return nil_or_missing(aggregate, attribute, value, argument) if attribute.nil? || value.nil?
-          return reference_list(attribute, value) if attribute.list? && attribute.reference?
-          return reference_identity(attribute, value) if attribute.reference?
-          return hydrate_entity_list(aggregate, attribute, value) if attribute.list? # :list
+          return reference_or_list(aggregate, attribute, value) if attribute.list? || attribute.reference?
           return value unless aggregate.respond_to?(:value_object)
 
-          # `admits:` is checked here, where the attribute is known — `build` only
-          # sees the value object. Checked after coercion: a scalar arrives wrapped
-          # in its type's own holder, and checking the raw payload would be wrong.
-          value_object = value_object_for(aggregate, attribute.type)
-          return bare_primitive(aggregate, attribute, value, boundary) if value_object.nil?
-
-          coerced = if value.is_a?(self) && value.type_name == value_object.hecks_name
-                      value
-                    else
-                      build(value_object, fields_for(value_object, attribute.name, value), aggregate)
-                    end
-
-          admit_declared_set(aggregate, attribute, coerced)
-          coerced
-        end
-
-        # A required argument's nil is refused (C3.7); state assembly, hydration
-        # and query nils pass through unchanged. Lists/references keep their own
-        # nil passthrough regardless of `argument`.
-        private def nil_or_missing(aggregate, attribute, value, argument)
-          return value if attribute.nil? || !value.nil?
-
-          argument ? nil_argument(aggregate, attribute) : value
-        end
-
-        private def nil_argument(aggregate, attribute)
-          return nil if attribute.optional? || trusting_stored_state?
-          return nil if attribute.list? || attribute.reference?
-
-          value_object = aggregate.respond_to?(:value_object) ? value_object_for(aggregate, attribute.type) : nil
-          return build(value_object, {}, aggregate) if value_object
-
-          raise TypeMismatch,
-                RefusalWording.render_site("TypeMismatch", "numeric_field",
-                                           type: aggregate.hecks_name, field: attribute.name,
-                                           expected: attribute.type, offered: "nil")
-        end
-
-        # A bare primitive is boundary-checked too (C3.8) — wrong-typed input
-        # refuses here as a TypeMismatch, never later as a broken predicate.
-        # Its `admits:` set is still checked, exactly as a value object's is.
-        private def bare_primitive(aggregate, attribute, value, boundary)
-          check_bare_primitive(aggregate, attribute, value) if boundary
-          admit_declared_set(aggregate, attribute, value)
-          value
+          coerce_scalar(aggregate, attribute, value, boundary)
         end
 
         # Resolves the value-object class `type` names: `aggregate`'s own
@@ -113,99 +67,7 @@ module Hecks
           chapter = aggregate.respond_to?(:hecks_owner) ? aggregate.hecks_owner : nil
           return nil unless chapter.respond_to?(:aggregates)
 
-          matches = chapter.aggregates.filter_map { |candidate| candidate.value_object(type) }
-          shapes = matches.group_by do |shape|
-            shape.attributes.map { |field| [field.name, field.type.to_s, field.list?, field.optional?] }
-          end
-          shapes.size == 1 ? matches.first : nil
-        end
-
-        # Coerces a reference-typed attribute's offered value into the target's own
-        # canonical identity string.
-        #
-        # @param attribute [Bluebook::Attribute] the reference-typed attribute
-        # @param value [Object] a bare scalar identity, a `Runtime::Value`, or a Hash
-        #   naming the target's own identity fields
-        # @return [String, Object] the joined identity String, or `value` unchanged
-        #   when it cannot be resolved
-        def reference_identity(attribute, value)
-          return value unless value.is_a?(self) || value.is_a?(Hash)
-
-          target = attribute.type.resolve
-          return value unless target
-
-          materialized = materialize(value)
-          paths = target.identity_paths
-          return value if paths.empty?
-
-          direct_head = direct_identity_head(value, target)
-          parts = paths.map { |path| identity_part(materialized, path, direct_head) }
-          if parts.any? { |part| part.nil? || (part.respond_to?(:empty?) && part.empty?) }
-            return sole_scalar_identity(value, paths) || value
-          end
-
-          Naming.identity(parts)
-        end
-
-        # Unwraps `value` to a bare scalar when `paths` names exactly one identity
-        # field and `value` is itself a single-attribute value object — the only
-        # case where unwrapping cannot be ambiguous.
-        #
-        # @param value [Object] the offered reference value to unwrap
-        # @param paths [Array<String>] the target's own declared identity paths
-        # @return [Object, nil] the unwrapped scalar, or nil if it does not apply
-        def sole_scalar_identity(value, paths)
-          return nil unless value.is_a?(self) && paths.one?
-          return nil unless value.value_object.sole_attribute
-
-          materialize_unwrapped(value)
-        end
-
-        # Whether `value` is itself the target's own single identity value object.
-        #
-        # @param value [Object] the offered reference value to check
-        # @param target [Bluebook::Aggregate] the reference's own resolved target
-        # @return [String, nil] the target's identity head name, or nil
-        def direct_identity_head(value, target)
-          return nil unless value.is_a?(self) && target.identity_heads.one?
-
-          head = target.identity_heads.first
-          target.attribute(head)&.type.to_s == value.type_name ? head.to_s : nil
-        end
-
-        # One identity path's own value out of the materialized hash, stripping a
-        # leading segment already covered by `direct_identity_head`.
-        #
-        # @param materialized [Hash, Object] the offered reference value as a Hash
-        # @param path [String, Symbol] one dotted identity path to dig
-        # @param direct_head [String, nil] leading segment to strip, if present
-        # @return [Object, nil] the value found by walking `path`, or nil if missing
-        def identity_part(materialized, path, direct_head)
-          segments = path.to_s.split(".")
-          segments.shift if direct_head && segments.first == direct_head
-          segments.reduce(materialized) do |held, segment|
-            next nil unless held.is_a?(Hash)
-
-            # `key?` decides which spelling answers — a genuinely-held `false`
-            # must not fall through to the other spelling and read as `nil`.
-            sym = segment.to_sym
-            held.key?(sym) ? held[sym] : held[segment]
-          end
-        end
-
-        # Coerces a `has_many` reference-typed attribute's offered value.
-        #
-        # @param attribute [Bluebook::Attribute] the `has_many` reference attribute
-        # @param value [Object] the offered value; must be an Array
-        # @return [Array] `value`, deep-frozen and duped
-        # @raise [Runtime::TypeMismatch] if `value` is not an Array
-        def reference_list(attribute, value)
-          unless value.is_a?(Array)
-            raise TypeMismatch,
-                  "#{attribute.name} is a has_many relationship — pass a list of identities"
-          end
-
-          Freezer.deep(value.dup)
+          agreed_value_object(chapter, type)
         end
 
         # Normalizes an offered value into `value_object`'s own field Hash, before
@@ -235,94 +97,6 @@ module Hecks
                                            offered: Rendering.describe(value))
         end
 
-        # `build`'s own recursive twin of `for_attribute`, normalizing a value
-        # object's own composite-typed fields into their declared shape.
-        #
-        # Stays a plain Hash, never a nested `Value` — `Value#with` depends on that.
-        #
-        # @param aggregate [Bluebook::Aggregate, Entity, nil] nested-type lookup scope
-        # @param value_object [Class] the value object `fields` belongs to
-        # @param fields [Hash{Symbol => Object}] the outer fields, already defaulted
-        # @return [Hash{Symbol => Object}] `fields` with composite fields normalized
-        # @raise [Runtime::TypeMismatch] if a nested field cannot be coerced
-        # @raise [Runtime::UnknownArgument] if a nested field names an undeclared key
-        # @raise [Runtime::InvariantViolation] if a nested field breaks its own invariant
-        def normalize_composite_fields(aggregate, value_object, fields)
-          return fields unless aggregate.respond_to?(:value_object)
-
-          value_object.attributes.each do |attribute|
-            next unless fields.key?(attribute.name)
-
-            # A list member hydrates the same as a top-level list, so a value
-            # read back from the store matches the shape a live dispatch wrote.
-            # Load door only — an input list member is left as offered.
-            if attribute.list?
-              fields[attribute.name] = for_attribute(aggregate, attribute, fields[attribute.name]) if trusting_stored_state?
-              next
-            end
-
-            raw = fields[attribute.name]
-            next if raw.nil? || raw.is_a?(self)
-
-            nested = value_object_for(aggregate, attribute.type)
-            next unless nested
-
-            nested_fields = apply_defaults(nested, fields_for(nested, attribute.name, raw))
-            nested_fields = normalize_composite_fields(aggregate, nested, nested_fields)
-            validate!(nested, nested_fields)
-            fields[attribute.name] = nested_fields
-          end
-
-          fields
-        end
-
-        # Fills every declared attribute `fields` lacks with its own `default:`.
-        #
-        # @param value_object [Class] the `Bluebook::ValueObject` subclass whose
-        #   declared defaults are read
-        # @param fields [Hash{Symbol => Object}] the offered fields; written in place
-        # @return [Hash{Symbol => Object}] `fields`, with defaults filled in
-        def apply_defaults(value_object, fields)
-          value_object.attributes.each_with_object(fields) do |attribute, completed|
-            completed[attribute.name] = attribute.default unless completed.key?(attribute.name) || attribute.default.nil?
-          end
-        end
-
-        # The full door a value object's own fields pass through — shared by
-        # `build` and `normalize_composite_fields`, so a nested field refuses
-        # exactly like the same type declared directly on a command.
-        #
-        # @param value_object [Class] the `Bluebook::ValueObject` subclass to
-        #   validate `fields` against
-        # @param fields [Hash{Symbol => Object}] already-defaulted, nested-normalized fields
-        # @return [void]
-        # @raise [Runtime::UnknownArgument] if `fields` names an undeclared key
-        # @raise [Runtime::TypeMismatch] if a required field is missing or wrong-shaped
-        # @raise [Runtime::InvariantViolation] if `fields` breaks a declared invariant
-        def validate!(value_object, fields)
-          # C6.3 — a value object validates on construction from input only; state
-          # read back from the store is trusted as written, so tightening an
-          # invariant never makes an old record unreadable. `hydrate` sets this flag.
-          return if trusting_stored_state?
-
-          check_unknown_fields(value_object, fields)
-          check_required_fields(value_object, fields)
-          admit_member(value_object, fields)
-          check_admitted(value_object, fields)
-          check_list_shapes(value_object, fields)
-          check_numeric_fields(value_object, fields)
-          check_scalar_shapes(value_object, fields)
-          check_patterns(value_object, fields)
-          value_object.invariants.each do |invariant|
-            next if Bluebook::Expression::Evaluator.call_rule(invariant, fields)
-
-            raise InvariantViolation,
-                  RefusalWording.render_site("InvariantViolation", "value_object_invariant",
-                                             name: value_object.hecks_name, description: invariant.description,
-                                             offered: canonical_fields(fields))
-          end
-        end
-
         # Builds one validated `Value` of `value_object`'s own type: defaults filled,
         # nested fields normalized and validated, then the whole thing checked.
         #
@@ -353,12 +127,7 @@ module Hecks
         # @return [Hash{Symbol => Object}] `state`, coerced through each declared attribute
         # @raise [Runtime::WiringError] if `state` holds any non-Symbol key
         def hydrate(aggregate, state)
-          undecoded = state.keys.grep_v(Symbol)
-          unless undecoded.empty?
-            raise WiringError,
-                  "#{aggregate.name} state reached hydration with non-Symbol keys #{undecoded.inspect} — " \
-                  "decode stored state through Hecks::Ports::Persistence::StateCodec.decode first"
-          end
+          refuse_undecoded_keys!(aggregate, state)
 
           trusting_stored_state do
             state.each_with_object({}) do |(key, value), hydrated|
@@ -368,195 +137,77 @@ module Hecks
           end
         end
 
-        TRUSTED_LOAD_KEY = :hecks_trusting_stored_state
+        private
 
-        # Marks the block as loading trusted, already-validated stored state, so
-        # `validate!` skips its own checks for the block's duration.
-        #
-        # Thread-local, not a plain ivar, so two threads hydrating concurrently
-        # never see or clear each other's flag.
-        #
-        # @yield the code that should see `trusting_stored_state?` true
-        # @return [Object] the block's result
-        def trusting_stored_state
-          previous = Thread.current[TRUSTED_LOAD_KEY]
-          Thread.current[TRUSTED_LOAD_KEY] = true
-          yield
-        ensure
-          Thread.current[TRUSTED_LOAD_KEY] = previous
-        end
-
-        # Whether the current thread is inside a `trusting_stored_state` block.
-        #
-        # @return [Boolean] true if on this thread's own call stack
-        def trusting_stored_state? = Thread.current[TRUSTED_LOAD_KEY] == true
-
-        # `MetaValidator::Judge#send_to` walks a bluebook's own declarations through
-        # the self-hosted "Bluebook" meta-domain, and its generic append handling
-        # keys off a field's name ("position") rather than its declared type — so
-        # the language's own grammar can hand this a raw Integer for a String-typed
-        # meta field on every domain's first boot. This flag loosens
-        # `check_scalar_shapes`'s String check only for that one caller; composite
-        # shapes (Array/Hash) stay refused unconditionally, bootstrap or not, and no
-        # real domain's own declared value objects are affected.
-        BOOTSTRAP_KEY = :hecks_judge_bootstrapping
+        # A list or a reference: each has its own coercion.
+        def reference_or_list(aggregate, attribute, value)
+          return reference_list(attribute, value) if attribute.list? && attribute.reference?
+          return reference_identity(attribute, value) if attribute.reference?
 
-        # Marks the block as `MetaValidator::Judge#send_to`'s self-hosted bootstrap
-        # dispatch, so `check_scalar_shapes` loosens its `String` check for the
-        # block's duration.
-        #
-        # Thread-local, not a plain ivar, so two threads bootstrapping concurrently
-        # never see or clear each other's flag.
-        #
-        # @yield the code that should see `judge_bootstrapping?` true
-        # @return [Object] the block's result
-        def judge_bootstrapping
-          previous = Thread.current[BOOTSTRAP_KEY]
-          Thread.current[BOOTSTRAP_KEY] = true
-          yield
-        ensure
-          Thread.current[BOOTSTRAP_KEY] = previous
+          hydrate_entity_list(aggregate, attribute, value)
         end
 
-        # Whether the current thread is inside a `judge_bootstrapping` block.
-        #
-        # @return [Boolean] true if on this thread's own call stack
-        def judge_bootstrapping? = Thread.current[BOOTSTRAP_KEY] == true
-
-        # A reference is an ID; refused at the payload gate if it arrives as a
-        # Hash or `Runtime::Value` instead. `nil` stays legitimate for an optional
-        # reference — a required reference's own `nil` is refused elsewhere (C3.7).
-        #
-        # @param command [Class] the command `attribute` is declared on, named in a refusal
-        # @param attribute [Bluebook::Attribute] the attribute to check; a no-op unless
-        #   reference-typed
-        # @param value [Object] the offered value
-        # @return [void]
-        # @raise [Runtime::TypeMismatch] if `value` (or an element, for `has_many`) is a
-        #   Hash or `Runtime::Value` rather than a plain identity
-        def refuse_object_reference(command, attribute, value)
-          return unless attribute.reference?
-
-          if attribute.list?
-            offered = Array(value).find { |item| item.is_a?(Hash) || item.is_a?(self) }
-            return unless offered
-          else
-            return if value.nil? && attribute.optional?
-            return if value.is_a?(String)
-
-            offered = value
-          end
-
-          raise TypeMismatch,
-                RefusalWording.render_site("TypeMismatch", "reference_wrong_shape",
-                                           command: command.hecks_name, attribute: attribute.name,
-                                           offered: reference_shape_description(offered),
-                                           known_by: known_by(attribute))
-        end
+        # A bare scalar or a value object. `admits:` is checked here, where the attribute is
+        # known — `build` only sees the value object. Checked after coercion: a scalar arrives
+        # wrapped in its type's own holder, and checking the raw payload would be wrong.
+        def coerce_scalar(aggregate, attribute, value, boundary)
+          value_object = value_object_for(aggregate, attribute.type)
+          return bare_primitive(aggregate, attribute, value, boundary) if value_object.nil?
 
-        # A list argument is an Array whatever its element type, so a lone scalar offered for
-        # it is refused; nil stays legitimate, as for any optional argument. The single-element
-        # form belongs to the `append`/`remove` effects, which take one element and are
-        # coerced against the aggregate's own list, never through this gate.
-        #
-        # @param command [#hecks_name] what `attribute` is declared on, named in a refusal
-        # @param attribute [Bluebook::Attribute] the attribute to check; a no-op unless list-typed
-        #   (a `has_many` reference list has its own refusal)
-        # @param value [Object] the offered value
-        # @return [void]
-        # @raise [Runtime::TypeMismatch] if `value` is neither nil nor an Array
-        def refuse_scalar_list(command, attribute, value)
-          return unless attribute.list? && !attribute.reference? && !value.nil? && !value.is_a?(Array)
+          coerced = if value.is_a?(self) && value.type_name == value_object.hecks_name
+                      value
+                    else
+                      build(value_object, fields_for(value_object, attribute.name, value), aggregate)
+                    end
 
-          raise TypeMismatch, RefusalWording.render_site(
-            "TypeMismatch", "numeric_field", type: command.hecks_name, field: attribute.name,
-            expected: "list_of(#{attribute.type})", offered: Rendering.describe(value)
-          )
+          admit_declared_set(aggregate, attribute, coerced)
+          coerced
         end
 
-        # "an object" for the Hash/Value shape; `Rendering.describe` otherwise —
-        # the same rendering every other TypeMismatch in this file uses.
-        #
-        # @param value [Object] the wrongly-shaped offered value to describe
-        # @return [String] `"an object"` for a Hash or `Runtime::Value`; otherwise
-        #   `Rendering.describe(value)`
-        def reference_shape_description(value)
-          return "an object" if value.is_a?(Hash) || value.is_a?(self)
-
-          Rendering.describe(value)
+        # The one value object every aggregate of the chapter that declares `type` agrees on.
+        def agreed_value_object(chapter, type)
+          matches = chapter.aggregates.filter_map { |candidate| candidate.value_object(type) }
+          shapes = matches.group_by do |shape|
+            shape.attributes.map { |field| [field.name, field.type.to_s, field.list?, field.optional?] }
+          end
+          shapes.size == 1 ? matches.first : nil
         end
 
-        # "(Account is known by number)" — what to send instead. No article, since
-        # "an Account" vs "a Customer" would make a pinned refusal hinge on spelling.
-        #
-        # @param attribute [Bluebook::Attribute] the reference-typed attribute to
-        #   describe the target's identity heads for
-        # @return [String] `" (Target is known by head1, head2)"`, or `""` if the
-        #   target or its identity heads cannot be resolved
-        def known_by(attribute)
-          heads = Array(attribute.type.resolve&.identity_heads)
-          return "" if heads.empty?
+        # A required argument's nil is refused (C3.7); state assembly, hydration
+        # and query nils pass through unchanged. Lists/references keep their own
+        # nil passthrough regardless of `argument`.
+        def nil_or_missing(aggregate, attribute, value, argument)
+          return value if attribute.nil? || !value.nil?
 
-          " (#{attribute.type.target_name} is known by #{heads.join(', ')})"
+          argument ? nil_argument(aggregate, attribute) : value
         end
 
-        # Renders a value object into the bare scalar its one field holds — for a
-        # column or a message, where there is no path to consult.
-        #
-        # @param value [Object] the value to render; passed through unless a `Runtime::Value`
-        # @return [Object] `value` unchanged, or its one field's own value
-        # @raise [Runtime::TypeMismatch] if `value` has more than one field
-        def scalar(value)
-          return value unless value.is_a?(self)
+        def nil_argument(aggregate, attribute)
+          return nil if attribute.optional? || trusting_stored_state?
+          return nil if attribute.list? || attribute.reference?
 
-          fields = value.to_h
-          return fields.values.first if fields.size == 1
+          value_object = aggregate.respond_to?(:value_object) ? value_object_for(aggregate, attribute.type) : nil
+          return build(value_object, {}, aggregate) if value_object
 
-          raise TypeMismatch, RefusalWording.render_site("TypeMismatch", "multi_field_scalar", type: value.type_name)
+          numeric_field_mismatch!(aggregate.hecks_name, attribute.name, attribute.type, "nil")
         end
 
-        # Coerces a derived identity string back into `attribute`'s own declared type.
-        #
-        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] construct
-        #   `attribute` is declared on
-        # @param attribute [Bluebook::Attribute] the identity attribute to coerce for
-        # @param identifier [String, Object] the derived identity
-        # @return [Runtime::Value, String, Object] a built value object for a
-        #   single-field value-object type; `identifier` unchanged otherwise
-        # @raise [Runtime::TypeMismatch] if the type names a multi-field value object
-        def from_identifier(aggregate, attribute, identifier)
-          value_object = value_object_for(aggregate, attribute.type)
-          return identifier unless value_object
-
-          fields = value_object.attributes
-          if fields.size == 1
-            field = fields.first
-            return build(value_object, { field.name => coerce_identifier(field, identifier) })
-          end
-
-          raise TypeMismatch, RefusalWording.render_site("TypeMismatch", "composite_identity", type: value_object.hecks_name)
+        # A bare primitive is boundary-checked too (C3.8) — wrong-typed input
+        # refuses here as a TypeMismatch, never later as a broken predicate.
+        # Its `admits:` set is still checked, exactly as a value object's is.
+        def bare_primitive(aggregate, attribute, value, boundary)
+          check_bare_primitive(aggregate, attribute, value) if boundary
+          admit_declared_set(aggregate, attribute, value)
+          value
         end
 
-        # Converts a derived numeric identity string back before `check_numeric_fields` runs.
-        private def coerce_identifier(field, identifier)
-          return identifier unless identifier.is_a?(String) && FieldChecks::NUMERIC.key?(field.type.to_s)
-
-          case field.type.to_s
-          when "Integer" then Integer(identifier)
-          when "Float"   then Float(identifier)
-          else identifier
-          end
-        rescue ArgumentError
-          identifier
-        end
+        def refuse_undecoded_keys!(aggregate, state)
+          undecoded = state.keys.grep_v(Symbol)
+          return if undecoded.empty?
 
-        # Renders a value object's fields as a canonical JSON string, for an
-        # invariant refusal to quote.
-        #
-        # @param fields [Hash{Symbol, String => Object}] the field values to render
-        # @return [String] `fields`, sorted by key name and JSON-encoded
-        def canonical_fields(fields)
-          JSON.generate(fields.sort_by { |name, _| name.to_s }.to_h)
+          raise WiringError,
+                "#{aggregate.name} state reached hydration with non-Symbol keys #{undecoded.inspect} — " \
+                "decode stored state through Hecks::Ports::Persistence::StateCodec.decode first"
         end
       end
     end

data/lib/hecks/runtime/value/entity_list_coercion.rb

@@ -32,18 +32,10 @@ module Hecks
 
           return hydrate_entity_identity(aggregate, entity, value) unless value.is_a?(Array)
 
-          hydrated = value.map do |element|
-            next element unless element.is_a?(Hash)
-
-            element.each_with_object({}) do |(name, field_value), acc|
-              key = name.to_sym
-              field = entity.attribute(key)
-              acc[key] = field ? for_attribute(aggregate, field, field_value) : field_value
-            end
-          end
+          hydrated = value.map { |element| hydrate_entity_element(aggregate, entity, element) }
           # Only a genuine whole-list offering names every element's own
           # identity at once; a single `remove:` target never reaches this.
-          check_entity_list_identities(aggregate, entity, hydrated) if value.is_a?(Array)
+          check_entity_list_identities(aggregate, entity, hydrated)
           Freezer.deep(hydrated)
         end
 
@@ -56,26 +48,11 @@ module Hecks
           return unless identity
           return if trusting_stored_state?
 
-          field = entity.attribute(identity)
-          seen  = []
-          elements.each do |fields|
-            next unless fields.is_a?(Hash)
-
+          seen = []
+          elements.grep(Hash).each do |fields|
             offered = fields[identity]
-            if offered.nil?
-              raise TypeMismatch,
-                    RefusalWording.render_site("TypeMismatch", "numeric_field",
-                                               type: entity.hecks_name, field: identity,
-                                               expected: field&.type, offered: "nil")
-            end
-
-            if seen.include?(offered)
-              raise AlreadyExists,
-                    RefusalWording.render_site("AlreadyExists", "entity_duplicate",
-                                               entity: entity.hecks_name, aggregate: aggregate.hecks_name,
-                                               identity: entity.identity_paths.join(", "),
-                                               offered: [Rendering.describe(offered)])
-            end
+            numeric_field_mismatch!(entity.hecks_name, identity, entity.attribute(identity)&.type, "nil") if offered.nil?
+            refuse_duplicate_identity!(aggregate, entity, offered) if seen.include?(offered)
             seen << offered
           end
         end
@@ -121,6 +98,27 @@ module Hecks
 
           build(value_object, fields_for(value_object, attribute.name, element), aggregate)
         end
+
+        private
+
+        # One element of an entity list, each field coerced through its declared attribute.
+        def hydrate_entity_element(aggregate, entity, element)
+          return element unless element.is_a?(Hash)
+
+          element.each_with_object({}) do |(name, field_value), acc|
+            key = name.to_sym
+            field = entity.attribute(key)
+            acc[key] = field ? for_attribute(aggregate, field, field_value) : field_value
+          end
+        end
+
+        def refuse_duplicate_identity!(aggregate, entity, offered)
+          raise AlreadyExists,
+                RefusalWording.render_site("AlreadyExists", "entity_duplicate",
+                                           entity: entity.hecks_name, aggregate: aggregate.hecks_name,
+                                           identity: entity.identity_paths.join(", "),
+                                           offered: [Rendering.describe(offered)])
+        end
       end
     end
   end