hecks 1.2.0 → 1.4.0

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

@@ -0,0 +1,248 @@
+require_relative "../errors"
+require_relative "../refusal_wording"
+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 did
+      # before the split, 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.
+      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 no longer 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.
+        def find_entity(construct, name)
+          construct.entities.each do |candidate|
+            return candidate if candidate.hecks_name == name
+
+            found = find_entity(candidate, name)
+            return found if found
+          end
+          nil
+        end
+
+        # Frozen through: a list read back out of the store is an answer,
+        # not a handle on what is stored.
+        #
+        # ADR 0047 — this used to bail (`return value unless entity`) the
+        # moment `attribute.type` named a value object rather than an
+        # entity, handing back the raw, un-hydrated argument untouched.
+        # A `sets :field` mutation sourced from a whole-array argument (as
+        # opposed to element-by-element `append:`) went straight through
+        # `for_attribute`'s `:list` branch, so `Banking::CardPayment.
+        # Authorize`'s own `sets :tags` (`list_of(Tag)`) stored 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`) then always failed, 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 worked: 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) — `remove:`'s own single-target
+        # value used to 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)` merely wrapped it as `[2]` rather than shredding it —
+        # but the wrapping itself was still wrong: `MutationApplier#
+        # removed`'s `element == value` then compared a stored `Entry`
+        # Hash against a one-element Array, which can never be `==` a
+        # Hash, so nothing was ever removed and nothing ever refused
+        # either. Routed to `hydrate_entity_identity` instead, below.
+        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
+
+          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
+          # 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.
+          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.
+        #
+        # 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.
+        def check_entity_list_identities(aggregate, entity, elements)
+          identity = entity.identified_by
+          return unless identity
+          return if trusting_stored_state?
+
+          field = entity.attribute(identity)
+          seen  = []
+          elements.each do |fields|
+            next unless fields.is_a?(Hash)
+
+            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
+            seen << offered
+          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.
+        # `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.
+        def hydrate_entity_identity(aggregate, entity, value)
+          return value if value.is_a?(self)
+
+          heads = entity.identity_heads
+          return value unless heads.one?
+
+          field = entity.attribute(heads.first)
+          return value unless field
+
+          for_attribute(aggregate, field, value)
+        end
+
+        # 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.
+        def hydrate_value_object_list(aggregate, attribute, value)
+          return value unless aggregate.respond_to?(:value_object)
+
+          value_object = value_object_for(aggregate, attribute.type)
+          return value unless value_object
+
+          return hydrate_value_object_element(aggregate, attribute, value_object, value) unless value.is_a?(Array)
+
+          hydrated = value.map { |element| hydrate_value_object_element(aggregate, attribute, value_object, element) }
+          Freezer.deep(hydrated)
+        end
+
+        def hydrate_value_object_element(aggregate, attribute, value_object, element)
+          return element if element.is_a?(self) && element.type_name == value_object.hecks_name
+
+          build(value_object, fields_for(value_object, attribute.name, element), aggregate)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/value.rb

@@ -2,25 +2,30 @@ require "json"
 require_relative "../rendering"
 require_relative "value/invariant_violation"
 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
+    # 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 and value/admission.rb, extended here so the door
-    # stays where it always was: `Value.for`, `Value.build`.
+    # 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`.
     class Value
       extend Coercion
+      extend EntityListCoercion
       extend Admission
 
       attr_reader :value_object
 
-      # FROZEN THROUGH, not just on top.
+      # 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
+      # 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
@@ -28,7 +33,7 @@ module Hecks
       # 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
+      # identity to change over — `with` already answers a new one rather
       # than mutating — so freezing it through is what it always claimed
       # to be.
       def initialize(value_object, fields)
@@ -63,13 +68,13 @@ module Hecks
       # `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
+      # 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
+      # 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.
       def self.materialize_unwrapped(value)
@@ -78,12 +83,12 @@ 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
+          # 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.
+          # happens through this method the whole way down.
           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) }
@@ -91,17 +96,17 @@ module Hecks
         end
       end
 
-      # REDUCES AN APPEND-ONLY SUB-LOG TO ITS CURRENT STATE — the same
+      # 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
+      # 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
+      # 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,"
+      # **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
@@ -114,17 +119,17 @@ module Hecks
       def method_missing(name, *args)
         return @fields[name] if @fields.key?(name)
 
-        # THE LANGUAGE RULE, not a convenience: ANY value object with
+        # 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
+        # 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
+        # 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
+        # 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
@@ -146,15 +151,15 @@ module Hecks
 
       private
 
-      # THE `.value` ALIAS FOR INDEXED ACCESS — the same language rule
+      # **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
+      # 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
+      # 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

data/lib/hecks/runtime.rb

@@ -6,24 +6,24 @@
 # declaration is being collected into — sat on the top-level Hecks module
 # beside the DSL words.
 #
-# What lives here is what RUNS a domain :
+# What lives here is what runs a domain :
 #
 #   Runtime.boot(path)          load a directory and return its Dispatcher
 #   Runtime.with_registry(r)    bind the ambient registry for the duration of a load
 #   Runtime.current_registry    the registry a declaration is landing in, or nil
 #
-# What does NOT live here is what DECLARES one — `Hecks.bluebook`,
+# What does not live here is what declares one — `Hecks.bluebook`,
 # `.hecksagon`, `.port`, `.adapter`, `.world` are loading words and stay on the
 # top-level module, which now reads as a facade over this.
 #
 #   runtime = Hecks::Runtime.boot("examples/pizzas/bluebook")
 #   runtime.dispatch("Pizzas::Pizza.CreatePizza", name: "Margherita")
 #
-# NOTE, and it is the reason this file exists : `current_registry` is still
+# Note, and it is the reason this file exists : `current_registry` is still
 # process-global. Each boot builds a fresh Registry, and `Loader.bind_runtime`
-# installs a fresh facade door whose modules close over THAT boot's dispatcher
+# installs a fresh facade door whose modules close over that boot's dispatcher
 # — no class-level runtime binding remains, so two boots in one process no
-# longer share dispatch state, only the top-level NAME (the last-bound door
+# longer share dispatch state, only the top-level name (the last-bound door
 # wins the constant, which is what per-boot install means). Owning the state
 # here was the first move ; the dispatcher reachable per-runtime rather than
 # through a constant was the second, and it is done — the door is the only
@@ -91,7 +91,7 @@ module Hecks
       # the block — who a command's declared `role`, if any, is checked
       # against.
       #
-      # `as_of:` is OPTIONAL, same opt-in shape as `actor_id:` — a caller
+      # `as_of:` is optional, same opt-in shape as `actor_id:` — a caller
       # that wants a Governance `RoleAssignment`'s `starts_at` enforced
       # passes `as_of: Ports::Clock.now(registry)` here, at the door,
       # exactly where `cli_runner.rb` already merges `Clock.now` into a
@@ -99,7 +99,7 @@ module Hecks
       # itself — see `Ports::Clock`'s own header for why — so an unbound
       # `as_of` leaves `starts_at` unchecked, exactly as before.
       #
-      # `scope:` is OPTIONAL too — a caller that states which scope it is
+      # `scope:` is optional too — a caller that states which scope it is
       # acting in gets that scope checked against the matching
       # `RoleAssignment`'s own `scope`, not just its `role_name`. See
       # `Runtime::Caller::Current`'s own header for why this lives here