hecks 2.8.0 → 3.0.0

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

@@ -5,38 +5,11 @@ require_relative "../../rendering"
 module Hecks
   module Runtime
     class Value
-      # How a `list_of` attribute's own elements GET hydrated — entity-typed
-      # and value-object-typed alike — split out of `Coercion` (this file's
-      # sibling, extended into `Value` alongside it exactly the way
-      # `Admission` already is) once `Coercion` itself grew past
-      # `Metrics/ModuleLength`'s budget from two, unrelated fixes landing in
-      # the same method the same week (BUG#32's own `hydrate_entity_identity`
-      # and BUG#33's own `check_entity_list_identities` — see each method's
-      # own header, and this repo's `.rubocop_todo.yml` for the merge that
-      # made the split necessary). Cross-calls into `Coercion`'s own
-      # `for_attribute`/`build`/`fields_for`/`value_object_for`/
-      # `trusting_stored_state?` work unqualified here, exactly as they do
-      # within `Coercion` itself, because both modules land on the same
-      # `Value` singleton class once extended — `self` never has to know
-      # which file a sibling method actually lives in.
+      # Hydrates a `list_of` attribute's own elements, entity-typed and
+      # value-object-typed alike; extended into `Value` alongside `Coercion`.
       module EntityListCoercion
-        # S17, ADR 0026 — searches the whole entity tree, not only the
-        # root's own direct children. `aggregate` here is always the
-        # root aggregate — `for_attribute`'s own `aggregate` argument is
-        # never reassigned as hydration recurses into a nested element,
-        # because coercion has to resolve value objects, and only the
-        # root answers `.value_object` at all (Entity's own header
-        # comment: an entity must not answer to it, or `Value.
-        # for_attribute` could not tell a piece from a head). So
-        # a nested entity — Dispatch, inside Handler — is not a direct
-        # child of the root the way Handler itself is, and a plain
-        # `aggregate.entities.find` stops one level short of it.
-        #
-        # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct to
-        #   search, and every entity nested under it
-        # @param name [String] the entity's declared `hecks_name` to find
-        # @return [Bluebook::Entity, nil] the matching entity anywhere in the tree, or
-        #   nil if none matches
+        # Searches the whole entity tree, not just the root's direct
+        # children; `aggregate` here is always the root aggregate. (ADR 0026)
         def find_entity(construct, name)
           construct.entities.each do |candidate|
             return candidate if candidate.hecks_name == name
@@ -47,54 +20,12 @@ module Hecks
           nil
         end
 
-        # Hydrates a `list_of` attribute's offered value — each element of a
-        # whole-list offering, or a single remove-target value, depending on
-        # `attribute.type` and `value`'s own shape.
-        #
-        # Frozen through: a list read back out of the store is an answer,
-        # not a handle on what is stored.
+        # Hydrates a `list_of` attribute's offered value: each element of a
+        # whole-list Array, or a single remove-target value.
         #
-        # ADR 0047 — bailing (`return value unless entity`) the moment
-        # `attribute.type` names a value object rather than an entity would
-        # hand back the raw, un-hydrated argument untouched. A `sets :field`
-        # mutation sourced from a whole-array argument (as opposed to
-        # element-by-element `append:`) goes straight through
-        # `for_attribute`'s `:list` branch, so `Banking::CardPayment.
-        # Authorize`'s own `sets :tags` (`list_of(Tag)`) would store plain
-        # Ruby Hashes as its `tags` elements forever — never a real
-        # `Value`, never through `Tag`'s own `pattern:`/`invariant`
-        # checks. `remove:`'s `==` comparison (a real `Value` against a
-        # raw `Hash`) would then always fail, since `Hash#==` refuses
-        # anything that isn't itself a compatible Hash — the bug ADR 0047
-        # traces in full. Delegating to `hydrate_value_object_list` below
-        # closes that gap the same way the entity branch already works:
-        # build a real, validated `Value` per element, reusing
-        # `for_attribute`'s own composite-construction path rather than
-        # inventing a second one.
-        # BUG#32 (QualityControl ledger) — without this, `remove:`'s own
-        # single-target value would fall straight into
-        # `Array(value).map { ... }` below unguarded, unlike this method's
-        # own delegated `hydrate_value_object_list` sibling, whose
-        # `value.is_a?(Array)` check exists for exactly this shape (see
-        # that method's own comment). For an entity-typed list, `remove:`'s
-        # scalar target (`Ledger.Void`'s `sequence: EntrySequence`) is
-        # never a Hash, so `Array(2)` would merely wrap it as `[2]` rather
-        # than shredding it — but the wrapping itself would still be wrong:
-        # `MutationApplier#removed`'s `element == value` would then compare
-        # a stored `Entry` Hash against a one-element Array, which can
-        # never be `==` a Hash, so nothing would ever be removed and
-        # nothing would ever refuse either. Routed to `hydrate_entity_identity`
-        # instead, below.
-        #
-        # @param aggregate [Bluebook::Aggregate] the root aggregate `attribute` is
-        #   declared on
-        # @param attribute [Bluebook::Attribute] the `list_of` attribute being hydrated
-        # @param value [Array<Hash, Object>, Object] the offered value: a whole-list
-        #   Array (a `sets`/hydrate load) or a single remove-target value
-        # @return [Object] a frozen Array of hydrated elements when `value` is a
-        #   whole-list Array and `attribute.type` names an entity; otherwise whatever
-        #   `hydrate_entity_identity` (a non-Array value naming an entity) or
-        #   `hydrate_value_object_list` (`attribute.type` naming no entity) returns
+        # Delegates non-entity types to `hydrate_value_object_list` so
+        # elements get the same `pattern:`/invariant checks other
+        # composites get. (ADR 0047)
         def hydrate_entity_list(aggregate, attribute, value)
           entity = find_entity(aggregate, attribute.type.to_s)
           return hydrate_value_object_list(aggregate, attribute, value) unless entity
@@ -110,61 +41,16 @@ module Hecks
               acc[key] = field ? for_attribute(aggregate, field, field_value) : field_value
             end
           end
-          # BUG#33 — only a genuine whole-list offering (`value.is_a?(Array)`)
-          # is a caller naming every element's own identity at once; the
-          # single-target shape this same method also hydrates (a `remove:`
-          # target, wrapped one level up by `Array()`) never reaches this
-          # check, and never should — see `check_entity_list_identities`'s
-          # own comment.
+          # 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)
           Freezer.deep(hydrated)
         end
 
-        # `MutationApplier#check_entity_collision`'s own guard
-        # (mutation_applier.rb), extended from a single caller-supplied
-        # append (BUG#13) to a whole-list replace — `sets :entries` bare
-        # (`Ledger.ReplaceEntries`, the corpus's first `list_of(ENTITY)`
-        # command argument/mutation, qa/stress_domains/corrections). The
-        # array branch above rebuilds each offered element's own declared
-        # fields but never checked the offered list itself for either way
-        # it can misname its own entities:
-        #
-        #   - two elements sharing one identity — the same silent-duplicate
-        #     hazard BUG#13's own comment describes: `EntityInterpreter#
-        #     element_of`'s own `find_index` always matches the first
-        #     match, so the second becomes permanently unaddressable by any
-        #     later command.
-        #   - an element missing its identity altogether — there is no
-        #     auto-mint for a whole-list replace the way `MutationApplier#
-        #     entity_element` mints one for a single append (which element
-        #     would it mint for? every element here is the caller's own
-        #     whole state, offered at once), so an absent identity is
-        #     refused rather than guessed.
-        #
-        # Non-composite identities only, exactly BUG#13's own scope
-        # (`entity.identified_by` answers a single Symbol only when
-        # `identity_heads.size == 1`, `Behaviour::Traits#derive_identity`) —
-        # a composite identity's own duplicate/missing question is the
-        # same pre-existing, narrower gap BUG#13 documented and left open,
-        # not widened here.
-        #
-        # Refuses a whole-list offering that misnames its own entities' identities —
-        # a duplicate identity across two elements, or an element missing one.
-        #
-        # Skipped under `trusting_stored_state?`, the same guard `validate!`
-        # already gives every value object (C6.3): a record already
-        # written is trusted as it was, so tightening this check can never
-        # make an old, already-persisted record unreadable.
-        #
-        # @param aggregate [Bluebook::Aggregate] the aggregate `entity` belongs to,
-        #   named in a refusal
-        # @param entity [Bluebook::Entity] the entity type `elements` are shaped as
-        # @param elements [Array<Hash, Object>] the hydrated whole-list offering; a
-        #   non-Hash element is skipped, not checked
-        # @return [void]
-        # @raise [Runtime::TypeMismatch] if `entity` declares a single-field identity
-        #   and an element offers no value for it
-        # @raise [Runtime::AlreadyExists] if two elements offer the same identity value
+        # Refuses a whole-list offering that misnames its own entities: a
+        # duplicate identity across two elements, or an element missing
+        # one. Single-field identities only; skipped once
+        # `trusting_stored_state?`.
         def check_entity_list_identities(aggregate, entity, elements)
           identity = entity.identified_by
           return unless identity
@@ -194,43 +80,10 @@ module Hecks
           end
         end
 
-        # BUG#32 — `remove:`'s own single-target value against an
-        # entity-typed list. An entity is never offered to `remove:`
-        # whole the way a value object is (`hydrate_value_object_list`'s
-        # own `element == value` full-value-equality shape) — an entity
-        # must never answer `.value_object` at all (`Entity`'s own header
-        # comment), so there is no whole-value shape here to rebuild in
-        # the first place, only the one field a caller would otherwise
-        # have to name to address that element any other way
-        # (`EntityElement#element_of`'s own `wants`). So this coerces the
-        # offered scalar against the entity's own identity field's
-        # declared type — not the entity's full shape — and hands back a
-        # real, correctly-typed `Value` ready to compare against each
-        # stored element's own identity field
-        # (`EntityElement.list_element_match?`, the shared rule both
-        # `MutationApplier#removed` and `EntityElement#
-        # removed_from_element` match against).
-        #
-        # A composite identity (more than one head) has no single field a
-        # bare `remove:` target could mean, so this passes the value
-        # through uncoerced rather than guessing which head — the same
-        # "nothing in this corpus needs it yet" boundary
-        # `MutationApplier#check_entity_collision`'s own header already
-        # draws for entity identity elsewhere in this runtime.
-        # Coerces a `remove:` target against an entity's own single-field
-        # identity type, rather than the entity's full shape.
-        #
-        # `list_element_match?` treats an uncoerced value the same way
-        # it always treated the pre-fix wrapped Array: never a match, a
-        # documented no-op rather than a crash.
-        #
-        # @param aggregate [Bluebook::Aggregate] the aggregate `entity` belongs to
-        # @param entity [Bluebook::Entity] the entity type `value` addresses
-        # @param value [Object] the offered remove-target value
-        # @return [Runtime::Value, Object] `value` already coerced (returned unchanged);
-        #   the value coerced against the identity field's declared type when `entity`
-        #   has a single identity head and a matching attribute; `value` unchanged
-        #   otherwise (no identity head, a composite identity, or no matching attribute)
+        # Coerces a `remove:` target against an entity's single-field
+        # identity type, rather than the entity's full shape. Passed
+        # through unchanged for a composite identity (more than one head)
+        # rather than guessing which head it means.
         def hydrate_entity_identity(aggregate, entity, value)
           return value if value.is_a?(self)
 
@@ -243,47 +96,12 @@ module Hecks
           for_attribute(aggregate, field, value)
         end
 
-        # Hydrates a `list_of` attribute's offered value when `attribute.type`
-        # names a value object rather than an entity.
+        # Hydrates a `list_of` attribute's offered value when
+        # `attribute.type` names a value object rather than an entity.
         #
-        # The value-object sibling of the entity branch above: an element
-        # already shaped like the target `Value` (or a `Hash`/scalar that
-        # `fields_for` can still open) is rebuilt through the same `build`
-        # a scalar composite attribute already uses (`for_attribute`'s own
-        # `coerced = ... build(value_object, fields_for(...), aggregate)`
-        # line) — same defaults, same `pattern:`/`admits:`/invariant
-        # checks, same `trusting_stored_state?` bypass on a trusted load.
-        # `attribute.type` naming neither an entity nor a value object
-        # (a `list_of(String)`, say) has no shape to rebuild into, so the
-        # element passes through unchanged, exactly as the entity branch's
-        # own non-Hash elements do.
-        #
-        # Not `Array(value).map` (unlike the entity branch above) — `value`
-        # here is not always genuinely list-shaped. `MutationApplier#
-        # removed`'s own `Value.for_attribute(aggregate, attribute, value)`
-        # call (`attribute` = the list attribute, `mutation.target`; `value`
-        # = the single remove-target argument, already a real `Value` by
-        # the time it gets here) reuses this exact branch — for `remove:`,
-        # not for a whole-list `sets`. `Array(a_real_Value)` alone would be
-        # harmless (`Value` defines neither `to_a` nor `to_ary`, so Kernel
-        # wraps it `[value]`), but `Array(a_Hash)` is not harmless: Ruby's
-        # `Array()` opens a bare Hash into its own `[[k, v], ...]` pairs,
-        # not `[hash]` — silently shredding a single-element Hash-shaped
-        # target into garbage instead of hydrating it. Branching on
-        # `value.is_a?(Array)` up front (true only for a genuine whole-list
-        # `sets`/hydrate load) keeps the single-target shape a single
-        # target, hydrated the same way, never listified.
-        #
-        # @param aggregate [Bluebook::Aggregate] the aggregate `attribute` is declared
-        #   on, or a construct that does not respond to `value_object` (an entity), in
-        #   which case `value` passes through unchanged
-        # @param attribute [Bluebook::Attribute] the `list_of` attribute being hydrated
-        # @param value [Array<Hash, Object>, Object] the offered value: a whole-list
-        #   Array, or a single remove-target value
-        # @return [Object] `value` unchanged when `aggregate` does not respond to
-        #   `value_object`, or `attribute.type` names no value object; otherwise a
-        #   frozen Array of built `Value`s for a whole-list Array, or a single built
-        #   `Value` (via `hydrate_value_object_element`) otherwise
+        # Branches on `value.is_a?(Array)` rather than `Array(value)`: a
+        # bare Hash-shaped single target would otherwise be shredded into
+        # its own `[[k, v], ...]` pairs instead of hydrated whole.
         def hydrate_value_object_list(aggregate, attribute, value)
           return value unless aggregate.respond_to?(:value_object)
 
@@ -296,19 +114,8 @@ module Hecks
           Freezer.deep(hydrated)
         end
 
-        # Rebuilds one `list_of` element into a real, validated `Value`, unless it
-        # already is one of `value_object`'s own type.
-        #
-        # @param aggregate [Bluebook::Aggregate] the aggregate `value_object` is
-        #   resolved against
-        # @param attribute [Bluebook::Attribute] the `list_of` attribute `element`
-        #   belongs to
-        # @param value_object [Class] the `Bluebook::ValueObject` subclass `element`
-        #   is built as
-        # @param element [Object] the raw element to build: a Hash of fields, a scalar
-        #   `fields_for` can still open, or an already-built `Value`
-        # @return [Runtime::Value] `element` unchanged if it is already a `Value` of
-        #   `value_object`'s own type; otherwise a freshly built one
+        # Rebuilds one `list_of` element into a real, validated `Value`,
+        # unless it already is one of `value_object`'s own type.
         def hydrate_value_object_element(aggregate, attribute, value_object, element)
           return element if element.is_a?(self) && element.type_name == value_object.hecks_name
 

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

@@ -0,0 +1,172 @@
+require_relative "../errors"
+require_relative "../refusal_wording"
+require_relative "../../rendering"
+
+module Hecks
+  module Runtime
+    class Value
+      # Boundary checks that refuse a mistyped, unknown, missing or malformed field before an
+      # invariant reads it; extended into `Value` alongside `Coercion`, which calls them.
+      module FieldChecks
+        # C3.8 boundary check — refuses a mistyped argument before it breaks a predicate.
+        private def check_bare_primitive(owner, attribute, value)
+          type = attribute.type.to_s
+          expected = NUMERIC[type]
+          mistyped = if expected
+                       !value.is_a?(expected)
+                     elsif NON_NUMERIC_SCALARS.include?(type)
+                       COMPOSITE_SHAPES.any? { |shape| value.is_a?(shape) }
+                     else
+                       false
+                     end
+          if mistyped
+            raise TypeMismatch,
+                  RefusalWording.render_site("TypeMismatch", "numeric_field",
+                                             type: owner.hecks_name, field: attribute.name,
+                                             expected: type, offered: Rendering.describe(value))
+          end
+
+          check_numeric_bounds(owner.hecks_name, attribute.name, value)
+        end
+
+        # C3.3/C3.4 — value bounds enforced at every boundary: an Integer must fit
+        # signed 64 bits, a Float must be finite.
+        INT64_RANGE = (-(2**63))..((2**63) - 1)
+
+        private def check_numeric_bounds(type_name, field_name, given)
+          if given.is_a?(Integer) && !INT64_RANGE.cover?(given)
+            raise TypeMismatch,
+                  RefusalWording.render_site("TypeMismatch", "integer_range",
+                                             type: type_name, field: field_name, offered: Rendering.describe(given))
+          end
+          return unless given.is_a?(Float) && !given.finite?
+
+          raise TypeMismatch,
+                RefusalWording.render_site("TypeMismatch", "non_finite_field",
+                                           type: type_name, field: field_name, offered: Rendering.describe(given))
+        end
+
+        # A value object refuses an undeclared key the same way a command's own
+        # payload does, checked before any other field-content check.
+        private def check_unknown_fields(value_object, fields)
+          known   = value_object.attributes.map { |attribute| attribute.name.to_sym }
+          unknown = (fields.keys.map(&:to_sym) - known).sort
+          return if unknown.empty?
+
+          declared = value_object.attributes.map(&:name)
+          raise UnknownArgument,
+                RefusalWording.render_site("UnknownArgument", "unknown_args",
+                                           command: value_object.hecks_name, unknown: unknown,
+                                           declared: declared)
+        end
+
+        # C3.7 — every non-optional, non-list field must arrive (or construction
+        # refuses); a `default:` has already been filled in by `apply_defaults`.
+        private def check_required_fields(value_object, fields)
+          value_object.attributes.each do |attribute|
+            next if attribute.optional? || attribute.list?
+            next unless fields[attribute.name].nil?
+
+            raise TypeMismatch,
+                  RefusalWording.render_site("TypeMismatch", "numeric_field",
+                                             type: value_object.hecks_name, field: attribute.name,
+                                             expected: attribute.type, offered: "nil")
+          end
+        end
+
+        # Checked before invariants, because an invariant reading a mistyped field
+        # is exactly the thing that would otherwise explode.
+        NUMERIC = { "Integer" => Integer, "Float" => Numeric }.freeze
+        private def check_numeric_fields(value_object, fields)
+          value_object.attributes.each do |attribute|
+            expected = NUMERIC[attribute.type.to_s]
+            next unless expected
+
+            given = fields[attribute.name]
+            next if given.nil?
+
+            offered_items(attribute, given).each do |item|
+              unless item.is_a?(expected)
+                raise TypeMismatch,
+                      RefusalWording.render_site("TypeMismatch", "numeric_field",
+                                                 type: value_object.hecks_name, field: attribute.name,
+                                                 expected: attribute.type, offered: Rendering.describe(item))
+              end
+
+              # `is_a?(expected)` alone waves NaN/Infinity through — both are real
+              # Floats. `-0.0` is deliberately left unchecked: finite and legitimate.
+              check_numeric_bounds(value_object.hecks_name, attribute.name, item)
+            end
+          end
+        end
+
+        # A `list_of` field holds an Array whatever its element type, so a lone scalar
+        # offered for it is refused; nil stays legitimate, as it is for any optional field.
+        private def check_list_shapes(value_object, fields)
+          value_object.attributes.each do |attribute|
+            given = fields[attribute.name]
+            next unless attribute.list? && !given.nil? && !given.is_a?(Array)
+
+            raise TypeMismatch, RefusalWording.render_site(
+              "TypeMismatch", "numeric_field", type: value_object.hecks_name, field: attribute.name,
+              expected: "list_of(#{attribute.type})", offered: Rendering.describe(given)
+            )
+          end
+        end
+
+        # The values a field's element-level checks apply to: each element of a list, or the
+        # one value of a scalar field.
+        private def offered_items(attribute, given) = attribute.list? && given.is_a?(Array) ? given : [given]
+
+        # A scalar field (String, or a boolean) must not arrive as a composite
+        # (Array/Hash) standing in for a leaf value. A String field additionally
+        # must not arrive as any other scalar, except inside `judge_bootstrapping?`.
+        COMPOSITE_SHAPES = [Array, ::Hash].freeze
+        NON_NUMERIC_SCALARS = %w[String TrueClass FalseClass].freeze
+        private def check_scalar_shapes(value_object, fields)
+          value_object.attributes.each do |attribute|
+            type = attribute.type.to_s
+            next unless NON_NUMERIC_SCALARS.include?(type)
+
+            given = fields[attribute.name]
+            next if given.nil?
+
+            offered_items(attribute, given).each do |item|
+              composite = COMPOSITE_SHAPES.any? { |shape| item.is_a?(shape) }
+              non_string_scalar = type == "String" && !composite && !item.is_a?(String) && !judge_bootstrapping?
+              next unless composite || non_string_scalar
+
+              raise TypeMismatch,
+                    RefusalWording.render_site("TypeMismatch", "numeric_field",
+                                               type: value_object.hecks_name, field: attribute.name,
+                                               expected: attribute.type, offered: Rendering.describe(item))
+            end
+          end
+        end
+
+        # A field declared with a pattern must match it, refused as a TypeMismatch
+        # rather than surfacing later as a broken predicate. The pattern itself is
+        # already vetted by PatternSubset when the bluebook is declared. `^` and `$` match the
+        # whole value, as in Rust, so a newline cannot smuggle text past an anchored pattern.
+        private def check_patterns(value_object, fields)
+          value_object.attributes.each do |attribute|
+            pattern = attribute.pattern
+            next unless pattern
+
+            given = fields[attribute.name]
+            next if given.nil?
+
+            offered_items(attribute, given).each do |item|
+              next if item.is_a?(String) && Regexp.new(Hecks::Bluebook::PatternSubset.whole_string(pattern)).match?(item)
+
+              raise TypeMismatch,
+                    RefusalWording.render_site("TypeMismatch", "pattern_mismatch",
+                                               type: value_object.hecks_name, field: attribute.name,
+                                               pattern: pattern, offered: Rendering.describe(item))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/value.rb

@@ -1,41 +1,25 @@
 require "json"
 require_relative "../rendering"
 require_relative "value/invariant_violation"
+require_relative "value/field_checks"
 require_relative "value/coercion"
 require_relative "value/entity_list_coercion"
 require_relative "value/admission"
 
 module Hecks
   module Runtime
-    # A typed value object in hand: frozen fields, read by name. How one is
-    # made — coerced from a raw argument, checked against its declared
-    # numeric types, patterns and closed sets — is the class-side engine in
-    # value/coercion.rb, value/entity_list_coercion.rb (a `list_of`
-    # attribute's own elements — split out once growing Coercion tripped
-    # Metrics/ModuleLength, see that file's own header), and
-    # value/admission.rb, extended here so the door stays where it always
-    # was: `Value.for`, `Value.build`.
+    # A typed value object: frozen fields, read by name.
+    # Construction lives in value/coercion.rb, field_checks.rb, entity_list_coercion.rb and
+    # admission.rb.
     class Value
+      extend FieldChecks
       extend Coercion
       extend EntityListCoercion
       extend Admission
 
       attr_reader :value_object
 
-      # Frozen through, not just on top.
-      #
-      # `@fields.freeze` alone stops a key being added or removed and
-      # nothing else: the String, Array or Hash a field holds stays
-      # mutable, so `vo[:value] << "!"` edits a value object in place —
-      # demonstrated on a real dispatch before this was written, not
-      # supposed. Same shape as the three freezing bugs already fixed
-      # (list attributes, the event log, query rows), where the container
-      # was frozen and the contents were not.
-      #
-      # A value object is the one thing in the domain that has no
-      # identity to change over — `with` already answers a new one rather
-      # than mutating — so freezing it through is what it always claimed
-      # to be.
+      # Deep-freezes the fields so a held String, Array or Hash cannot be mutated in place.
       #
       # @param value_object [Bluebook::ValueObject] the declared type this instance is one of
       # @param fields [Hash] the type's fields, keyed by name (String or Symbol); deep-frozen
@@ -103,18 +87,8 @@ module Hecks
         end
       end
 
-      # `materialize`, but a single-attribute value object (`sole_attribute`
-      # — [[feedback_name_the_scalar_field]]) recurses into its own bare
-      # field instead of building `{field: ...}` — a Board's own `label`
-      # unwraps to `"Kanban"`, not `{value: "Kanban"}`. Not a replacement
-      # for `materialize` itself: every existing report/query/command
-      # caller keeps the wrapped shape it already depends on (Banking's
-      # own `CustomerPortfolio` reads `payment[:amount][:cents]`, and
-      # changing that out from under it would be a real breaking change,
-      # not a bug fix). This is read_model_interpreter.rb's own opt-in,
-      # used only for a `group_by`-declared head's own rows — grouping
-      # needs a real scalar to key by regardless, so a report already
-      # asking for that gets the unwrap for free.
+      # `materialize`, but a single-attribute value object unwraps to its bare field.
+      # Opt-in for `group_by` rows; `materialize` keeps the wrapped shape callers depend on.
       #
       # @param value [Object] the value to materialize; anything that is not a `Runtime::Value`,
       #   Array or Hash passes through unchanged
@@ -127,12 +101,7 @@ module Hecks
           sole = value.value_object.sole_attribute
           return materialize_unwrapped(value[sole.name]) if sole
 
-          # Not `value.to_h` — `Value#to_h` materializes each field through
-          # plain `materialize`, so a VO nested inside a multi-attribute VO
-          # would already be a plain Hash by the time this method ever saw
-          # it, and never reach the `when self` branch above. Read each
-          # field straight off `value` instead, so recursion actually
-          # happens through this method the whole way down.
+          # Not `value.to_h`: it materializes nested values to Hashes, ending the recursion.
           value.value_object.attributes.to_h { |attr| [attr.name, materialize_unwrapped(value[attr.name])] }
         when Array then value.map { |item| materialize_unwrapped(item) }
         when Hash then value.transform_values { |item| materialize_unwrapped(item) }
@@ -140,22 +109,8 @@ module Hecks
         end
       end
 
-      # Reduces an append-only sub-log to its current state — the same
-      # "a later fact supersedes an earlier one" reduction this runtime
-      # already performs replaying an aggregate's own command history
-      # into its current attributes, applied here to a single `list_of`
-      # field acting as its own miniature append-only log (a placement
-      # history, a tombstone-style soft-delete list, a versioned
-      # setting). `rows` is what a `list_of` attribute hands back — an
-      # Array of `Value`, in append order — and `key` names the field
-      # that identifies "the same logical thing" across entries.
-      #
-      # **Grouping only, never interpretation**. What counts as "removed,"
-      # how to order what survives — that meaning belongs to whichever
-      # domain declared the field, never here: a generic reduction that
-      # started guessing domain semantics would need to keep guessing
-      # forever, once per shape of "gone" any caller ever invents. The
-      # caller filters and sorts the result; this only groups it.
+      # Reduces an append-only `list_of` sub-log to its current state: the latest row per `key`.
+      # Grouping only; what counts as removed, and the ordering, belong to the caller.
       #
       # @param rows [Array<Runtime::Value>] a `list_of` attribute's own elements, in append order
       # @param key [Symbol] the method to call on each row to find "the same logical thing"
@@ -169,21 +124,8 @@ module Hecks
       def method_missing(name, *args)
         return @fields[name] if @fields.key?(name)
 
-        # The language rule, not a convenience: any value object with
-        # exactly one declared attribute answers `.value`, whatever that
-        # attribute is actually named — a single-attribute value object
-        # is a name for a scalar, not a genuine group
-        # ([[feedback_name_the_scalar_field]], `Behaviour::ValueObject#
-        # sole_attribute`), so `money.value` reads `Money`'s own `amount`
-        # exactly as `label.value` reads a shorthand-declared `value`.
-        # After the real-field lookup above, on purpose: a field
-        # literally named `value` is already answered there (and is the
-        # sole attribute whenever the count is one), so this branch only
-        # ever aliases, never shadows. A multi-attribute value object
-        # keeps its NoMethodError — `sole_attribute` answers nil for it,
-        # and falling through to `super` is exactly the refusal it
-        # always gave: with two or more fields there is no single value
-        # `.value` could honestly mean.
+        # `.value` aliases the sole field of a single-attribute value object; after the real-field
+        # lookup so a field literally named `value` is never shadowed.
         if name == :value
           sole = @value_object.sole_attribute
           return @fields[sole.name] if sole
@@ -201,19 +143,8 @@ module Hecks
 
       private
 
-      # **The `.value` alias for indexed access** — the same language rule
-      # `method_missing` above enforces for method reads, applied to
-      # `[]`/`key?`/`with`: `:value` names a single-attribute value
-      # object's sole field whatever that field is actually called. A
-      # real key always wins first (a field literally named `value` is
-      # its own answer, and is the sole attribute anyway whenever the
-      # count is one), so this only ever resolves a `:value` that would
-      # otherwise miss — it can never redirect a genuine field read.
-      # `with(:value, x)` in particular needs this: merging a literal
-      # `:value` key beside a sole field named `amount` would build a
-      # two-key hash for a one-field shape and be refused (or worse,
-      # stored) downstream — aliasing at the merge is what keeps the
-      # write half of the rule as true as the read half.
+      # Resolves `:value` to the sole field's name so `[]`, `key?`, `with` match `method_missing`.
+      # A real key always wins.
       def resolve_field(field)
         sym = field.to_sym
         return sym if @fields.key?(sym)