hecks 1.3.0 → 1.4.0

data/lib/hecks/runtime/entity_element.rb

@@ -8,10 +8,10 @@ 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
@@ -27,19 +27,19 @@ module Hecks
 
       # 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
+      # `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
+      # **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
@@ -63,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,
@@ -72,8 +72,8 @@ 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.
@@ -84,27 +84,27 @@ module Hecks
       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
+                    # 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
+                    # `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
+                    # 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,
@@ -114,7 +114,7 @@ module Hecks
                     # `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,
+                    # 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
@@ -136,7 +136,7 @@ module Hecks
                      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, raw| Identity.scalar(path, raw) }&.join(", "),
@@ -145,17 +145,17 @@ module Hecks
           )
         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
@@ -165,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
@@ -191,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_
@@ -246,13 +246,13 @@ module Hecks
         # `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
+        # 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
+        # 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.
+        # 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
@@ -282,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)
@@ -293,25 +293,27 @@ module Hecks
       end
 
       # `MutationApplier#appended`'s own entity-scoped twin. Usually a
-      # VALUE OBJECT element — an entity's own list, appended to by an
+      # 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
       # most real corpus appends do — but entity-in-entity nesting (a
-      # list of ANOTHER entity, owned by this one) is real now too:
+      # 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/
-      # collision-checking 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 — and collision-checking
-      # a nested entity is its own separate, unfixed question) — but
-      # BUG#12's fix (below) is: 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`.
+      # 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
@@ -323,22 +325,53 @@ module Hecks
           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
+            # `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 }
-            nested_entity ? fill_declared_defaults(aggregate, nested_entity, fields) : fields
+            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
+      # 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
@@ -346,12 +379,12 @@ module Hecks
       # 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
+      # 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
+      # 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
+      # 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
@@ -366,8 +399,8 @@ module Hecks
       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, UNLESS
+      # 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.
@@ -378,23 +411,23 @@ module Hecks
         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
+      # 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
+      # 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
+      # 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
+      # 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 —
@@ -405,7 +438,7 @@ module Hecks
       # 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
+      # `#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
@@ -419,6 +452,57 @@ module Hecks
 
         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
 end