hecks 1.2.0 → 1.4.0

data/lib/hecks/runtime/entity_element.rb

@@ -4,13 +4,14 @@ require_relative "value"
 require_relative "refusal_wording"
 require_relative "errors"
 require_relative "identity"
+require_relative "instance"
 
 module Hecks
   module Runtime
-    # ONE ENTITY ELEMENT, LOCATED AND MUTATED — the walk-and-write half of
+    # **One entity element, located and mutated** — the walk-and-write half of
     # dispatching into a piece an aggregate holds, factored out of
-    # `EntityInterpreter` so a SECOND caller (`CommandInterpreter`'s own
-    # `delegate_to_entity` step) can locate and mutate the SAME element the
+    # `EntityInterpreter` so a second caller (`CommandInterpreter`'s own
+    # `delegate_to_entity` step) can locate and mutate the same element the
     # same way, against an aggregate record it already holds in memory
     # rather than one freshly loaded from a repository. `EntityInterpreter`
     # keeps its own dispatch order and Context; this is the part underneath
@@ -24,13 +25,21 @@ module Hecks
     module EntityElement
       module_function
 
-      # ONE HOP PER CHAIN ENTRY. `container` starts as `instance` (the root
+      # BUG#3 — an addressing value that can never match a stored element,
+      # returned from `element_of`'s own `wants` coercion in place of a real
+      # `Value` (below). A unique object, never `nil`: a stored, optional
+      # element field really can hold `nil`, and comparing that against a
+      # bare `nil` sentinel would accidentally "match" it.
+      UNMATCHABLE = Object.new.freeze
+      private_constant :UNMATCHABLE
+
+      # **One hop per chain entry**. `container` starts as `instance` (the root
       # aggregate record) and becomes each just-located element in turn —
-      # Dispatch's own element is found INSIDE the Handler element
+      # Dispatch's own element is found inside the Handler element
       # `locate_chain` located the step before, never inside `instance`
-      # directly. `owner` is whichever construct's OWN attribute declares
+      # directly. `owner` is whichever construct's own attribute declares
       # the list being searched (Handler declares `dispatches` ; the root
-      # aggregate declares `handlers`) — `root_aggregate` stays the ROOT
+      # aggregate declares `handlers`) — `root_aggregate` stays the root
       # the whole way through instead, passed to `element_of` separately,
       # because coercion (`Value.for_attribute`) resolves value objects
       # against the root's own namespace only ; an entity must never
@@ -54,7 +63,7 @@ module Hecks
         container
       end
 
-      # ONE ELEMENT, MATCHED ON EVERY PART OF ITS IDENTITY — not just the first.
+      # One element, matched on every part of its identity — not just the first.
       # A piece's identity may be several paths, the same shape a head's can be,
       # so a dispatch that names the element has to supply every part and every
       # part has to agree with the stored one. `routed_identity`, when given,
@@ -63,29 +72,58 @@ module Hecks
       # which element it means, so re-deriving `wants` from `args` would be
       # redundant at best and wrong if `args` no longer carries that identity
       # at all.
-      # Locate, then copy-before-mutate, in that order — see the "ONE
-      # LEVEL DEEPER" comment below on why the copy has to happen exactly
+      # Locate, then copy-before-mutate, in that order — see the "one
+      # level deeper" comment below on why the copy has to happen exactly
       # where it does (aliasing the adapter's own record otherwise).
       # Splitting resolution from the copy/write-back would separate two
       # halves of one aliasing-safety invariant across method boundaries.
       # rubocop:disable-next Metrics/AbcSize
       # rubocop:disable-next Metrics/CyclomaticComplexity
       # rubocop:disable-next Metrics/PerceivedComplexity
+      # rubocop:disable-next Metrics/MethodLength
       def element_of(root_aggregate, owner, entity, command_name, container, args, routed_identity = nil)
         entity_name = entity.hecks_name
         list_attr = owner.attributes.find { |a| a.list? && a.type.to_s == entity_name } ||
-                    raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_holds_no_list",
-                                                             aggregate: owner.hecks_name, entity: entity_name))
+                    raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_holds_no_list",
+                                                                  aggregate: owner.hecks_name, entity: entity_name))
 
         wants = unless routed_identity
                   entity.identity_paths.map do |path|
                     head = path.to_s.split(".").first.to_sym
                     raw  = args[head] ||
-                           raise(NotFound, RefusalWording.render("NotFound", "entity_element_no_identity",
-                                                                 command: command_name, entity: entity_name,
-                                                                 identity: Identity.reading(entity)))
+                           raise(NotFound, RefusalWording.render_site("NotFound", "entity_element_no_identity",
+                                                                      command: command_name, entity: entity_name,
+                                                                      identity: Identity.reading(entity)))
+
+                    # An identity offered for addressing, not for storage
+                    # (BUG#3, found live by `bin/qa_sweep` — banking fuzz seed
+                    # 23, `LedgerEntry.Amend sequence: { value: 0 }` against an
+                    # entry-less ledger). Coercing it all the way to a typed
+                    # `Value` here ran that type's own invariant before this
+                    # method ever checks whether any element matches — a
+                    # `sequence: 0` against `LedgerSequence`'s own "a ledger
+                    # sequence is positive" invariant raised InvariantViolation,
+                    # not NotFound, even when (as here) nothing was ever posted
+                    # at all. Every element actually in the list already
+                    # satisfied its own type's invariant the moment it was
+                    # created, so a value that fails it can never equal one —
+                    # degrading to `UNMATCHABLE` here, instead of propagating,
+                    # is exactly as safe as the ordinary "no match found" case
+                    # below, and lines this addressing path up with the two
+                    # conventions it already disagreed with: Rust's own
+                    # `extract_id`/`extract_wants` (a raw scalar read, never a
+                    # typed rebuild — rust/src/generated/*/*.rs) and
+                    # `Identity.from`'s own raw-comparison convention for a
+                    # root aggregate's identity (this file's sibling,
+                    # `identity.rb`). `raw` rides alongside `want` so the
+                    # eventual NotFound below can still quote what was offered.
+                    want = begin
+                      Value.for_attribute(root_aggregate, entity.attribute(head), raw)
+                    rescue InvariantViolation
+                      UNMATCHABLE
+                    end
 
-                    [head, path, Value.for_attribute(root_aggregate, entity.attribute(head), raw)]
+                    [head, path, want, raw]
                   end
                 end
 
@@ -93,29 +131,31 @@ module Hecks
         position = if routed_identity
                      original.find_index { |element| element_identity(entity, element).to_s == routed_identity.to_s }
                    else
-                     original.find_index { |el| wants.all? { |head, _path, want| el[head] == want } }
+                     original.find_index do |el|
+                       wants.all? { |head, _path, want, _raw| want != UNMATCHABLE && el[head] == want }
+                     end
                    end
         unless position
-          raise NotFound, RefusalWording.render(
+          raise NotFound, RefusalWording.render_site(
             "NotFound", "entity_element_missing",
             entity: entity_name, identity: Identity.reading(entity),
-            wants: wants&.map { |_h, path, want| Identity.scalar(path, want) }&.join(", "),
+            wants: wants&.map { |_h, path, _want, raw| Identity.scalar(path, raw) }&.join(", "),
             aggregate: owner.hecks_name,
             parent_id: container.respond_to?(:id) ? container.id.inspect : Rendering.describe(container)
           )
         end
 
-        # ONE LEVEL DEEPER THAN Instance#dup, for the same reason: a list
+        # One level deeper than Instance#dup, for the same reason: a list
         # attribute holds Hashes, and `apply_to_element` mutates the found
-        # one IN PLACE — the update mechanism for an entity, not a bug. But
+        # one in place — the update mechanism for an entity, not a bug. But
         # in place means aliased with the adapter's own record until this
         # copies the array and the target element before handing either
         # back, and writes the fresh array into `container` so the copy is
-        # what persists on success and NOTHING aliased survives a refusal.
+        # what persists on success and nothing aliased survives a refusal.
         # `container[list_attr.name] = copied` reaches `instance` itself
-        # when this is the FIRST hop, and reaches the (already copied)
-        # PARENT element when it is a later one — either way it is the
-        # SAME already-fresh object `locate_chain` is about to hand back
+        # when this is the first hop, and reaches the (already copied)
+        # parent element when it is a later one — either way it is the
+        # same already-fresh object `locate_chain` is about to hand back
         # as `container` for the next hop, so nothing further has to
         # propagate a write back up the chain by hand.
         copied  = original.dup
@@ -125,9 +165,9 @@ module Hecks
         element
       end
 
-      # THE ELEMENT'S OWN IDENTITY, joined from its parts — the entity-level
-      # twin of `Identity.of`, reading off the STORED ELEMENT (a Hash) rather
-      # than a dispatch payload. An id is a SCALAR, and the PATH is how it is
+      # The element's own identity, joined from its parts — the entity-level
+      # twin of `Identity.of`, reading off the stored element (a Hash) rather
+      # than a dispatch payload. An id is a scalar, and the path is how it is
       # reached — never by opening a value object and taking whatever single
       # field is inside. That unwrapping is gone from the language: a piece
       # that does not name its fields is refused when the bluebook loads ("an
@@ -151,10 +191,10 @@ module Hecks
       # refuses what it cannot check applying nothing instead. `Member`/
       # `Dispatch` (S17) are the first real callers: both need to
       # append a value-object-typed element (`Pair`/`Binding`) onto a
-      # list attribute THEY OWN, once they become entities of
+      # list attribute they own, once they become entities of
       # `ValueObject`/`ProcessManager` rather than separate aggregates.
       #
-      # `:increment`/`:decrement`/`:multiply` ALSO fixed here, found
+      # `:increment`/`:decrement`/`:multiply` also fixed here, found
       # while proving this method against a real fixture: they wrapped
       # `amount` unconditionally whenever `attribute` existed, the same
       # asymmetric-wrapping shape `MutationApplier#rewrap_arithmetic_
@@ -174,7 +214,7 @@ module Hecks
       # shape here without doing the same there would break that
       # intentional mirroring, which is what lets the two be diffed
       # against each other when one gets a fix the other needs too.
-      # rubocop:disable-next Metrics/AbcSize
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity
       # `pre` — the element as it was before this command (C4.2): every
       # read below goes through it, every write lands on `element`.
       def apply_to_element(rules, aggregate, entity, element, mutation, args, pre = element)
@@ -203,6 +243,22 @@ module Hecks
           element[mutation.target] = rewrap_arithmetic_result(aggregate, attribute, current, result)
         when :clamp
           element[mutation.target] = rules.clamp(pre[mutation.target], mutation.source, mutation.target)
+        # `corrects` — BUG#30. `MutationApplier#apply`'s own aggregate-
+        # level `:corrects` branch's own comment gives the full reasoning;
+        # the same one applies here unchanged: this mutation targets no
+        # field on this element at all — its own event name, and whether
+        # the owning record has actually emitted it, was already checked
+        # once, up front, by `EntityInterpreter#step_enforce_givens`
+        # (`CommandRules::Admissibility#enforce_correction_target`, called
+        # there against the parent record/root aggregate — see that
+        # step's own comment for exactly why). Whatever field a correction
+        # actually changes is an ordinary declared `sets`/`increment`/etc.
+        # mutation of its own, applied by one of the branches above like
+        # any other — `qa/stress_domains/corrections`' own `Entry.Amend`
+        # pairs `corrects "EntryRecorded", ...` with a separate `sets
+        # :amount`, exactly this shape.
+        when :corrects
+          nil
         else
           # The aggregate-level twin's own backstop
           # (MutationApplier#apply), for the same reason: applying
@@ -226,8 +282,8 @@ module Hecks
       end
 
       # `MutationApplier#resolve_append_source`'s own entity-scoped
-      # twin — a caller-supplied ARG first, falling back to the
-      # ELEMENT's own current field (never the parent instance's) when
+      # twin — a caller-supplied arg first, falling back to the
+      # element's own current field (never the parent instance's) when
       # it isn't one.
       def resolve_element_append_source(source, element, args)
         return source unless source.is_a?(Symbol)
@@ -236,17 +292,28 @@ module Hecks
         element[source]
       end
 
-      # `MutationApplier#appended`'s own entity-scoped twin. VALUE-
-      # OBJECT elements only — an entity's own list, appended to by an
+      # `MutationApplier#appended`'s own entity-scoped twin. Usually a
+      # value object element — an entity's own list, appended to by an
       # entity-owned command, holds a value object (`Member.pairs`'
       # own `Pair`, `Dispatch.with_spec`'s own `Binding`) the same way
-      # every real corpus append does; entity-in-entity nesting (a
-      # list of ANOTHER entity, owned by this one) is out of scope —
-      # `MutationApplier#entity_element`'s own fallback is deliberately
-      # not mirrored here, since nothing in this language's own
-      # `EntityBuilder` can declare a nested entity to need it (see
-      # S17's own scoping note on why Dispatch flattens under
-      # ProcessManager instead of nesting under Handler).
+      # most real corpus appends do — but entity-in-entity nesting (a
+      # list of another entity, owned by this one) is real now too:
+      # `qa/stress_domains/nested_pieces` (`Board.AddCard`, appending a
+      # `Card` onto `Board`'s own `cards`) is the first corpus member to
+      # do it, the comment this replaces having been written before that
+      # domain existed. `element_type` naming an entity rather than a
+      # value object falls through to `fields` unchanged, same as
+      # before — `MutationApplier#entity_element`'s own identity-minting
+      # fallback still isn't mirrored here (nothing in this corpus needs
+      # auto-minting at this depth — Card supplies its own identity in
+      # the append mapping) — but its collision-checking fallback now is
+      # (BUG#145, `check_entity_collision`, below — see its own call
+      # site's comment for why "collision-checking a nested entity is its
+      # own separate, unfixed question," this comment's own prior wording,
+      # stopped being true). BUG#12's fix (below) is likewise shared:
+      # every declared attribute the append mapping doesn't name gets its
+      # own default the same way a fresh aggregate's own attributes
+      # already do (`Instance.defaults`), whichever branch built `fields`.
       def appended_to_element(aggregate, entity, element, mutation, args)
         fields       = mutation.source.transform_values { |source| resolve_element_append_source(source, element, args) }
         element_type = entity.attribute(mutation.target)&.type
@@ -254,18 +321,187 @@ module Hecks
         value_object&.attributes&.each do |attribute|
           fields[attribute.name] = Value.scalar(fields[attribute.name]) if fields[attribute.name].is_a?(Value)
         end
-        appended = value_object ? Value.build(value_object, fields, aggregate) : fields
+        appended =
+          if value_object
+            Value.build(value_object, fields, aggregate)
+          else
+            # `entity.entities`, not `aggregate.entities` — a piece
+            # nested inside a piece is a child of the owning entity
+            # (`Card` is `Board.entities`, never `Workspace.entities`;
+            # `Behaviour::Entity#entities` answers direct children only,
+            # by design — see its own comment), the same lexical-nesting
+            # rule `EntityBuilder#entity_impl` builds the tree with in
+            # the first place.
+            nested_entity = entity.entities.find { |piece| piece.hecks_name == element_type.to_s }
+            if nested_entity
+              # BUG#145 — `MutationApplier#entity_element`'s own
+              # `check_entity_collision` call (one hop up, an aggregate's
+              # own entity list) never had a twin here: a nested entity's
+              # own identity is always caller-supplied at this depth
+              # (`Card.sequence` rides the append mapping directly — no
+              # nested-entity auto-mint exists anywhere in this corpus,
+              # see this method's own header), so this is unconditional,
+              # unlike `#entity_element`'s own auto-mint/collision `if`/
+              # `else` split — there is no auto-mint branch here to skip.
+              # Found live: `qa/stress_domains/nested_pieces`'s own
+              # differential sweep, `Board.AddCard` dispatched twice under
+              # the same `sequence` — Ruby silently appended a second
+              # `Card`, Rust's generated code (`rust/project/mutations.rb`'s
+              # `emit_mutation_line_body`, which never splits an
+              # aggregate-owned append from an entity-owned one the way
+              # this runtime's two separate methods do) already refused
+              # `AlreadyExists` for both depths.
+              # `entity` (the owner — `Board`), not `aggregate` (the root
+              # — `Workspace`), is what the refusal names as "on {…}" —
+              # `check_entity_collision`'s first argument is only ever
+              # used for that one naming purpose (`owner.hecks_name`,
+              # below), matching Rust's own generated wording exactly
+              # (`rust/project/mutations.rb`'s own `collision_guard`
+              # passes the entity's declaring construct's name the same
+              # way — "a Card already exists on Board", never "…on
+              # Workspace").
+              check_entity_collision(entity, nested_entity, element[mutation.target], fields)
+              fill_declared_defaults(aggregate, nested_entity, fields)
+            else
+              fields
+            end
+          end
         Freezer.deep(Array(element[mutation.target]) + [appended])
       end
 
+      # BUG#12 — an entity created via `sets :list, append: {...}` used
+      # to leave any of its own declared attributes the append mapping
+      # simply didn't name (an optional field a later, separate command
+      # sets — `Board.label`, `Card.note`) absent from the stored hash
+      # entirely, not even a `nil` placeholder, until that later command
+      # actually ran. `rust/project/json_codec.rb#emit_to_json_flat`'s
+      # own header comment documents the opposite as the intended
+      # contract for a persisted record: every declared field present,
+      # `null` when unset, "because Ruby's own `JSON.generate(state)`
+      # round-trip this mirrors does the same" — true for a freshly
+      # created aggregate (`Instance.defaults` already fills one key per
+      # declared attribute, `default_for` per attribute), never true for
+      # an entity minted by an append. This closes that gap the same
+      # way: `Instance.default_for` is the same per-attribute default
+      # rule (nil with no declared `default:`, a fully-defaulted value
+      # object when every one of its own fields has one), reused rather
+      # than reimplemented so the two creation paths can never drift on
+      # what "the default" means. Additive only — a key `fields` already
+      # holds (the append mapping, an auto-minted identity, a lifecycle
+      # default) is never overwritten.
+      def fill_declared_defaults(aggregate, entity, fields)
+        entity.attributes.each do |attribute|
+          next if fields.key?(attribute.name)
+
+          fields[attribute.name] = attribute.list? ? Freezer.deep([]) : Instance.default_for(aggregate, attribute)
+        end
+        fields
+      end
+
       # `MutationApplier#removed`'s own entity-scoped twin — matches by
-      # VALUE EQUALITY, element-wise, the same "so a concurrent Add can
-      # never be lost" reasoning that method's own comment gives.
+      # value equality, element-wise, the same "so a concurrent Add can
+      # never be lost" reasoning that method's own comment gives, unless
+      # the list this targets is itself entity-typed — see
+      # `list_element_match?`, below, which both this and
+      # `MutationApplier#removed` now share.
       def removed_from_element(rules, aggregate, entity, element, mutation, args)
         value     = rules.resolve_source(mutation.source, args)
         attribute = entity.attribute(mutation.target)
         value     = Value.for_attribute(aggregate, attribute, value) if attribute
-        Array(element[mutation.target]).reject { |candidate| candidate == value }
+        Array(element[mutation.target]).reject { |candidate| list_element_match?(aggregate, attribute, candidate, value) }
+      end
+
+      # BUG#32 (QualityControl ledger) — the match rule `remove:` uses
+      # against one stored list element. Value equality for a
+      # value-object-typed list stays exactly what it always was — an
+      # element and `value` are both real `Value`s there, so `==` already
+      # compares every field, the "concurrent Add can never be lost"
+      # shape `removed`/`removed_from_element`'s own headers describe.
+      # An entity-typed list is different in kind, not just in type: a
+      # stored element is a plain Hash, never a `Value` (`Entity`'s own
+      # header — "an entity must never answer .value_object"), so there
+      # is no whole-value shape to compare against at all — only the
+      # entity's own identity field, the same field a caller already has
+      # to name to address that element any other way
+      # (`element_of`'s own `wants`, above). `value` arrives here already
+      # coerced against that identity field's declared type
+      # (`Coercion#hydrate_entity_identity`, run underneath
+      # `Value.for_attribute` before either caller above ever sees it),
+      # so this only has to know which field to read off the stored
+      # element — `entity.identity_heads`'s own single head, when there
+      # is exactly one. A composite identity (more than one head, or
+      # none) has no single field a bare `remove:` target could mean —
+      # this returns `false` (never a match, the same documented no-op
+      # `hydrate_entity_identity`'s own header already commits to) rather
+      # than guessing which head, matching the narrow, honest boundary
+      # `MutationApplier#check_entity_collision`'s own header draws for
+      # entity identity elsewhere in this runtime.
+      #
+      # Shared by `MutationApplier#removed` (an aggregate's own list) and
+      # `#removed_from_element` (a list an entity owns), so the two
+      # `remove:` call sites can never quietly disagree on what
+      # "matches" means — the same reasoning this file's own header
+      # gives for centralizing `locate_chain`/`element_of` once rather
+      # than twice.
+      def list_element_match?(aggregate, attribute, element, value)
+        entity = attribute&.list? ? Value.find_entity(aggregate, attribute.type.to_s) : nil
+        return element == value unless entity
+
+        head = entity.identity_heads.one? ? entity.identity_heads.first : nil
+        return false unless head
+
+        element.is_a?(Hash) && element[head] == value
+      end
+
+      # BUG#13 (PR #549) — the same check #hydrate gives every creating
+      # aggregate command (`repository.find(id)`,
+      # `command_interpreter.rb`), one level down. Originally lived in
+      # `MutationApplier` (mutation_applier.rb), called only from
+      # `#entity_element` — an aggregate's own entity list (`Workspace.
+      # boards`, `Ledger.entries`). Moved here (BUG#145) so `#appended_
+      # to_element`, above — an entity's own nested entity list one hop
+      # further in (`Board.cards`) — can share it too, rather than
+      # reimplementing it a second time the same way `#list_element_
+      # match?` already avoids that split for `remove:`.
+      #
+      # Reached, at the aggregate-owned call site, only on the two
+      # branches that do not auto-mint: a caller-supplied identity (the
+      # field is already in the append's own field map) or a composite
+      # one (`entity.identified_by` is nil for those — Runtime::
+      # Identified#derive_identity). Neither used to check the sibling
+      # list at all: a second LogVisit with the same date+sequence, or a
+      # second IssueKey with the same serial, appended a silent
+      # duplicate — worse than an ordinary duplicate row, because
+      # `EntityElement#element_of`'s own `find_index` always matches the
+      # first match, so the second becomes permanently unaddressable by
+      # any later command. At the entity-owned call site (`#appended_to_
+      # element`), there is no auto-mint branch at all — every caller
+      # reaches this unconditionally, since a nested entity's own
+      # identity is always caller-supplied in this corpus.
+      #
+      # Auto-minted (aggregate-owned) entities never reach here —
+      # `identity_heads` for them is still checked at mint time by
+      # construction (`current.size + 1` can only repeat if something
+      # `remove:`s from the list between mints, which no real domain does
+      # today), so they can't be flagged by mistake.
+      # `owner` — the declaring construct named in the "…already exists on
+      # {owner}" wording: the root aggregate at the aggregate-owned call
+      # site (`Workspace`, `Ledger`), the immediately-enclosing entity at
+      # the entity-owned one (`Board` — never the root `Workspace` two
+      # hops up). Used for that naming purpose only (`owner.hecks_name`) —
+      # never for `Value`/namespace resolution, which is why an `Entity`
+      # (not just an `Aggregate`) is a valid thing to pass here.
+      def check_entity_collision(owner, entity, current, fields)
+        heads = entity.identity_heads
+        return if heads.empty?
+
+        collision = Array(current).find { |element| heads.all? { |head| element[head] == fields[head] } }
+        return unless collision
+
+        raise(AlreadyExists, RefusalWording.render_site("AlreadyExists", "entity_duplicate",
+                                                        entity: entity.hecks_name, aggregate: owner.hecks_name,
+                                                        identity: Identity.reading(entity),
+                                                        offered: heads.map { |head| Rendering.describe(fields[head]) }))
       end
     end
   end