hecks 1.3.0 → 1.5.0

data/lib/hecks/runtime/caller.rb

@@ -1,9 +1,9 @@
 module Hecks
   module Runtime
-    # WHO IS DISPATCHING, bound for the duration of a block — the ambient
+    # Who is dispatching, bound for the duration of a block — the ambient
     # counterpart to `Runtime.with_registry`, but `Thread.current`-backed
-    # rather than a plain module ivar: registry-binding happens at BOOT
-    # time (single-threaded by construction), this happens at DISPATCH
+    # rather than a plain module ivar: registry-binding happens at boot
+    # time (single-threaded by construction), this happens at dispatch
     # time, which a future per-request caller (docs/rails-integration.md's
     # still-unbuilt `WebDoor`) needs to bind safely under concurrency.
     #
@@ -12,15 +12,15 @@ module Hecks
     # worker thread mid-dispatch today, so this is a fact worth naming
     # rather than a gap worth solving.
     module Caller
-      # `actor_id` is OPTIONAL, on top of the role that has always been
+      # `actor_id` is optional, on top of the role that has always been
       # here — a caller that states only a role (every caller before this)
       # is checked the way it always was, string equality against the
-      # command's own `role`. A caller that also names WHO it is lets
+      # command's own `role`. A caller that also names who it is lets
       # `CommandRules::Authorization` check a real Governance
       # `RoleAssignment` instead, once the command's domain has Governance
       # attached — see that module's own header for the full split.
       #
-      # `as_of` and `scope` are BOTH optional too, and both self-asserted
+      # `as_of` and `scope` are both optional too, and both self-asserted
       # by the caller rather than derived from the command — deliberately:
       # `as_of` is filled at the door from `Ports::Clock.now`, never
       # inside the interpreter (see `Ports::Clock`'s own header), so
@@ -31,14 +31,40 @@ module Hecks
       # keeps it an application-boundary fact instead, the same shape
       # `role`/`actor_id` already are. The tradeoff: a caller states what
       # scope it is acting in, and `holds_role?` verifies a live grant
-      # exists for THAT scope — it does not independently confirm the
+      # exists for that scope — it does not independently confirm the
       # scope matches whatever the command's own target data belongs to.
       Current = Struct.new(:role, :actor_id, :as_of, :scope, keyword_init: true)
 
       module_function
 
+      # The ambient caller bound by the innermost enclosing `as` block on this thread.
+      #
+      # @return [Runtime::Caller::Current, nil] the bound caller, or nil when no `as`
+      #   block is on the stack for this thread
       def current = Thread.current[:hecks_caller]
 
+      # Binds the ambient caller for the duration of the block, restoring whatever
+      # caller (if any) was bound before, even if the block raises.
+      #
+      # `actor_id`, `as_of` and `scope` are each optional, self-asserted facts about
+      # the caller rather than derived from the command — see `Current`'s own header
+      # above for why each stays here instead of becoming a command-level DSL
+      # construct.
+      #
+      # @param role [String] the role the caller states it holds, checked by string
+      #   equality against the command's declared `role`
+      # @param actor_id [String, nil] who the caller is; when given, lets
+      #   `CommandRules::Authorization` check a real Governance `RoleAssignment`
+      #   instead of the bare role-string comparison
+      # @param as_of [Integer, nil] Unix epoch seconds the caller asserts as "now",
+      #   filled at the door from `Ports::Clock.now`; nil leaves a `RoleAssignment`'s
+      #   `starts_at` unchecked
+      # @param scope [String, nil] the scope the caller states it is acting in,
+      #   checked against the matching `RoleAssignment`'s own `scope`; nil skips
+      #   that check
+      # @yield the code that should see `role`/`actor_id`/`as_of`/`scope` as the
+      #   ambient caller
+      # @return [Object] the block's result
       def as(role:, actor_id: nil, as_of: nil, scope: nil)
         previous = Thread.current[:hecks_caller]
         Thread.current[:hecks_caller] = Current.new(
@@ -49,11 +75,17 @@ module Hecks
         Thread.current[:hecks_caller] = previous
       end
 
-      # A REACTION IS THE SYSTEM ACTING, not the caller who happened to be
+      # Clears the ambient caller for the duration of the block, restoring
+      # whatever caller (if any) was bound before, even if the block raises.
+      #
+      # A reaction is the system acting, not the caller who happened to be
       # on the stack when the triggering command ran — `Dispatcher#reenter`
       # clears the ambient caller around a reaction's own dispatch so a
       # triggering caller's role can neither satisfy nor block a reaction
       # command it has nothing to do with.
+      #
+      # @yield the code that should see no ambient caller bound
+      # @return [Object] the block's result
       def without
         previous = Thread.current[:hecks_caller]
         Thread.current[:hecks_caller] = nil

data/lib/hecks/runtime/capability_graph.rb

@@ -1,12 +1,12 @@
 module Hecks
   module Runtime
-    # WHICH PORTS A BOOT CAN ACTUALLY FULFILL, read off the registry it already
+    # Which ports a boot can actually fulfill, read off the registry it already
     # holds. `registry.ports` names every port a domain declared a dependency
     # on ; `registry.adapters` names every adapter wired to implement one — the
     # same `adapter.port == port.name` match `Ports::Extraction` and
     # `Ports::IdentityGeneration` already make for themselves, one at a time,
     # each time they resolve. This is that same question asked once, for
-    # every port at once, so a gap in the wiring is something a caller can ASK
+    # every port at once, so a gap in the wiring is something a caller can ask
     # about rather than something a live dispatch discovers by refusing.
     #
     # `cycles` answers `[]`, always, and honestly: nothing in this port model
@@ -14,6 +14,8 @@ module Hecks
     # adapter names the port it implements, and neither can point at a third
     # port. There is no edge for a cycle to be made of.
     class CapabilityGraph
+      # @param registry [Runtime::Registry] the booted registry to read ports and adapters from
+      # @return [void]
       def initialize(registry)
         @registry = registry
       end
@@ -21,6 +23,9 @@ module Hecks
       # { port name => [adapter name, ...] }, for every port the registry
       # declares — including the ports nothing implements, so a caller can
       # tell "declared, unfulfilled" from "never declared at all".
+      #
+      # @return [Hash{String => Array<String>}] each declared port's name mapped to the names
+      #   of every adapter bound to it (empty when none are)
       def fulfillments
         @fulfillments ||= @registry.ports.each_key.to_h { |name| [name, adapters_for(name)] }
       end
@@ -28,10 +33,16 @@ module Hecks
       # The ports with zero adapters bound — the gap `Runtime::WiringError`
       # would otherwise only surface at the moment something tries to dispatch
       # through one.
+      #
+      # @return [Array<String>] the names of every declared port with no adapter bound to it
       def unfulfilled
         fulfillments.select { |_, adapters| adapters.empty? }.keys
       end
 
+      # Reports the port-dependency cycles this registry has — always none; see the module
+      # header for why no port model here can express one.
+      #
+      # @return [Array] always empty
       def cycles = []
 
       private

data/lib/hecks/runtime/command_interpreter/argument_gate.rb

@@ -10,19 +10,19 @@ module Hecks
       module ArgumentGate
         private
 
-        # Anything else used to ride along in the payload untouched —
-        # normalize_args walks the DECLARED attributes, so a name the command
-        # never had was simply never looked at. A misspelled argument did
-        # nothing, in silence.
+        # Without this check, anything else would ride along in the payload
+        # untouched — normalize_args walks only the declared attributes, so
+        # a name the command never had is simply never looked at, and a
+        # misspelled argument would do nothing, in silence.
         #
-        # The keys that are legitimately not attributes are the ones that ADDRESS
+        # The keys that are legitimately not attributes are the ones that address
         # the aggregate rather than describe it : `id`, whatever the aggregate is
         # identified by, and the reference key of the root a command reaches
         # through. Refusing those would refuse every dispatch there is.
         #
         # `extra_identity_heads:` — EntityInterpreter's own callers only. An
         # entity dispatch addresses not just the root aggregate but every
-        # entity ALONG THE CHAIN it walks to reach the piece the command
+        # entity along the chain it walks to reach the piece the command
         # actually belongs to (`Handler.Dispatch.Bind` is two hops), and each
         # hop's own `identity_heads` is addressing the same way the root's
         # are — `element_of` (entity_element.rb) reads them straight out of
@@ -33,66 +33,68 @@ module Hecks
           addressing = [:id, *aggregate.identity_heads, *extra_identity_heads, reference_key(command)] +
                        correlation_keys(domain)
           known      = (command.attributes.map(&:name) + addressing).compact.map(&:to_sym)
-          # SORTED. Payload order is whatever the caller happened to write, and
+          # Sorted. Payload order is whatever the caller happened to write, and
           # refusal wording is contract — pinned byte-for-byte by the corpus, so
           # it cannot depend on hash iteration order.
           unknown = (args.keys.map(&:to_sym) - known).sort
           return if unknown.empty?
 
           raise UnknownArgument,
-                RefusalWording.render("UnknownArgument", "unknown_args",
-                                      command: command.hecks_name, unknown: unknown.join(", "),
-                                      declared: declared_reading(command))
+                RefusalWording.render_site("UnknownArgument", "unknown_args",
+                                           command: command.hecks_name, unknown: unknown,
+                                           declared: declared_names(command))
         end
 
-        # And it takes ALL of them. The other half of the same sentence, missing
+        # And it takes all of them. The other half of the same sentence, missing
         # until fuzz went looking : a name the command never declared was refused,
-        # while a name it DID declare could simply be left out.
+        # while a name it did declare could simply be left out.
         #
-        # `Customer.Register` without its `name` used to be refused — but by
-        # ACCIDENT, and with a lie for a message. `then_set :name, to: :name` found
-        # nothing to resolve, passed the literal symbol on, and coercion reported
-        # `name is a PersonName — pass its fields as an object`, which describes a
-        # mistake the caller did not make. The real mistake — an argument simply
-        # missing — was never the one named, and nothing refused it on purpose.
+        # Refusing `Customer.Register` for a missing `name` needs to be
+        # deliberate, not an accident with a lie for a message. Without this
+        # check, `then_set :name, to: :name` finds nothing to resolve, passes
+        # the literal symbol on, and coercion reports `name is a PersonName —
+        # pass its fields as an object`, which describes a mistake the caller
+        # did not make. The real mistake — an argument simply missing — is
+        # never the one named unless this refuses it on purpose.
         #
         # No command attribute anywhere in the corpus carries a default — checked,
         # all eight chapters, zero — so there is no optional argument for this to
         # step on. Every declared attribute is a fact the command needs.
         #
-        # `aggregate:` — PRESENT ONLY FOR A PORT OPERATION. An aggregate
+        # `aggregate:` — present only for a port operation. An aggregate
         # command's own self-address never reaches this list at all
         # (`CommandBuilder#reference_to`'s bare self-reference mints no
         # attribute to be absent) — but `PortOperationBuilder#reference_to`
-        # ALWAYS mints one (this file's own header on `PortOperation`: "no
-        # creates?/acts_on distinction to protect"), because an operation
-        # historically had no OTHER way to say which record it addressed.
-        # `to:` is that other way now (`Dispatcher#port_invocation`
-        # promotes the identity attribute's own value out of the payload
-        # and into routing) — which left the attribute still DECLARED,
-        # still non-optional, and now never present in `args` at all: every
-        # operation with an identity attribute refused its own well-formed
-        # calls, dispatched exactly the way `to:` intends. Exempted here on
-        # the same terms an aggregate command's self-address always was —
-        # an address, not a fact the operation still needs handed back.
+        # always mints one (this file's own header on `PortOperation`: "no
+        # creates?/acts_on distinction to protect"), because an operation had
+        # no other way to say which record it addressed before `to:` existed.
+        # `to:` is that way now (`Dispatcher#port_invocation` promotes the
+        # identity attribute's own value out of the payload and into
+        # routing) — which leaves the attribute still declared, still
+        # non-optional, and never present in `args` at all: without this
+        # exemption, every operation with an identity attribute would refuse
+        # its own well-formed calls, dispatched exactly the way `to:`
+        # intends. Exempted here on the same terms an aggregate command's
+        # self-address always was — an address, not a fact the operation
+        # still needs handed back.
         def refuse_absent_arguments(command, args, aggregate: nil)
           given    = args.keys.map(&:to_sym)
           exempt   = aggregate && command.respond_to?(:identity_attribute) &&
                      command.identity_attribute(aggregate.hecks_name)&.name
           required = command.attributes.reject(&:optional?).map { |attribute| attribute.name.to_sym } - [exempt]
-          # SORTED, for the same reason the unknown list is : refusal wording is
+          # Sorted, for the same reason the unknown list is : refusal wording is
           # contract, and a pinned wording cannot depend on the order a set
           # difference happens to be computed in.
           absent = (required - given).sort
           return if absent.empty?
 
           raise AbsentArgument,
-                RefusalWording.render("AbsentArgument", "absent_args",
-                                      command: command.hecks_name, absent: absent.join(", "),
-                                      declared: declared_reading(command))
+                RefusalWording.render_site("AbsentArgument", "absent_args",
+                                           command: command.hecks_name, absent: absent,
+                                           declared: declared_names(command))
         end
 
-        # A COMMAND THAT DECLARES NOTHING STILL HAS TO SAY SO. `Account
+        # A command that declares nothing still has to say so. `Account
         # .Freeze` is `reference_to Account` and no attributes at all, so
         # `{declared}` rendered empty and the sentence trailed off mid-
         # clause : "Freeze does not declare standing — it takes ". Read
@@ -104,17 +106,14 @@ module Hecks
         # one attribute renders exactly as it did before, because refusal
         # wording is contract and pinned byte-for-byte by the corpus (see
         # `refuse_unknown_arguments`' own note on sorting for why).
-        def declared_reading(command)
-          declared = command.attributes.map(&:name)
-          declared.empty? ? "none" : declared.join(", ")
-        end
+        def declared_names(command) = command.attributes.map(&:name)
 
-        # What a process manager correlates by is ROUTING, not description. A saga
+        # What a process manager correlates by is routing, not description. A saga
         # threads its correlation key through every leg it dispatches so the event
         # each leg emits carries it and the next step can be correlated — so the key
         # arrives on commands that never declare it, and legitimately.
         #
-        # This is the weakest part of the gate. Correlation is the SAGA's business,
+        # This is the weakest part of the gate. Correlation is the saga's business,
         # and the better shape is for the saga to stamp its own key onto the event
         # it caused rather than smuggle it through the command's payload. Until it
         # does, refusing the key here would break every saga in the corpus.

data/lib/hecks/runtime/command_interpreter/mutation_applier.rb

@@ -19,19 +19,19 @@ module Hecks
           end
         end
 
-        # A CASE STATEMENT OVER A CLOSED, DECLARED SET — every mutation op
+        # A case statement over a closed, declared set — every mutation op
         # the grammar can emit gets its own branch, including the `else`
         # backstop for the day a new op reaches this method undeclared (see
         # its own comment). Splitting each branch into its own method would
         # not reduce what a reader has to hold at once (each op's own
-        # comment already explains why IT is shaped the way it is) and
+        # comment already explains why it is shaped the way it is) and
         # would obscure that the set is closed and exhaustive.
         # rubocop:disable Lint/DuplicateBranch -- :delegate and :corrects
         # both no-op here, for two unrelated documented reasons (see each
         # branch's own comment below); merging would blur that distinction.
         # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
         #
-        # `pre` — THE PRE-DISPATCH STATE (C4.2): every source below reads
+        # `pre` — the pre-dispatch state (C4.2): every source below reads
         # it, every target is written to `instance`. A command's effects
         # are one update set; declaration order carries no meaning, and
         # build refuses a field written twice (`CommandBuilder#
@@ -54,7 +54,7 @@ module Hecks
             current   = pre[mutation.target]
             # Vendored fix, not (yet) upstream hecks (migration plan
             # task 9): see #rewrap_arithmetic_result's own comment below
-            # -- `amount` is wrapped ONLY when `current` already is, not
+            # -- `amount` is wrapped only when `current` already is, not
             # merely because the target attribute exists.
             amount = Value.for_attribute(aggregate, attribute, amount) if attribute && current.is_a?(Value)
             result = @rules.arithmetic(current, amount, mutation.target, @rules.sign_of(mutation.op))
@@ -86,22 +86,22 @@ module Hecks
           when :clamp
             instance[mutation.target] = @rules.clamp(pre[mutation.target], mutation.source, mutation.target)
           # `delegates_to` — CommandBuilder#delegates_to's own comment gives
-          # the full reasoning for storing it as a mutation at all. A REAL
-          # no-op here, not a gap: it targets no field on THIS instance —
-          # `CommandInterpreter#step_delegate_to_entity`, a LATER step in
+          # the full reasoning for storing it as a mutation at all. A real
+          # no-op here, not a gap: it targets no field on this instance —
+          # `CommandInterpreter#step_delegate_to_entity`, a later step in
           # the same dispatch, is what actually applies it, against the
           # target entity element `EntityElement.apply_to_element` reaches,
           # never through this method.
           when :delegate
             nil
           # `corrects` — CommandBuilder#corrects_impl's own comment gives
-          # the full reasoning for storing it as a mutation at all. A REAL
-          # no-op here too: it targets no field on THIS instance either —
-          # its own event name, and whether THIS record has actually
+          # the full reasoning for storing it as a mutation at all. A real
+          # no-op here too: it targets no field on this instance either —
+          # its own event name, and whether this record has actually
           # emitted it, is checked once, up front, by
           # CommandRules::Admissibility#enforce_correction_target, not
           # here. Whatever field this correction actually changes is an
-          # ORDINARY declared (or, for `reverses: true`, derived — see
+          # ordinary declared (or, for `reverses: true`, derived — see
           # AggregateBuilder#seal_correction_targets) mutation of its own,
           # applied by one of the branches above like any other.
           when :corrects
@@ -120,9 +120,9 @@ module Hecks
         # rubocop:enable Lint/DuplicateBranch
         # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
 
-        # A CALLER-SUPPLIED ARG, FIRST -- an append's own field can also
-        # name something the SUBJECT ALREADY KNOWS about itself, falling
-        # back to the AGGREGATE'S OWN CURRENT FIELD when it isn't one — a
+        # A caller-supplied arg, first -- an append's own field can also
+        # name something the subject already knows about itself, falling
+        # back to the aggregate's own current field when it isn't one — a
         # caller appending at the end without computing or supplying a
         # position (`position: :next_position`, a field the command never
         # declares as an argument at all). `args.key?`, not a truthiness
@@ -149,9 +149,9 @@ module Hecks
           value_object = aggregate.value_object(element_type)
           value_object&.attributes&.each do |attribute|
             held = fields[attribute.name]
-            # A SINGLE-FIELD VALUE unwraps to its scalar so it bridges
+            # A single-field value unwraps to its scalar so it bridges
             # into the element's own (differently named) wrapper; a
-            # MULTI-FIELD one (a `state(:en_passant_square)` Square
+            # multi-field one (a `state(:en_passant_square)` Square
             # copied off the record) has no scalar to stand in for it
             # and is handed across whole — `Value.for_attribute` keeps a
             # value of the element field's own type as it is.
@@ -165,24 +165,24 @@ module Hecks
                                      fields)
                     end
 
-          # FROZEN, like every other value the domain hands back. An
-          # appended list used to come back mutable, so a caller could
-          # push straight into an aggregate's own state after the
+          # Frozen, like every other value the domain hands back — without
+          # this, an appended list would come back mutable, letting a
+          # caller push straight into an aggregate's own state after the
           # dispatch had finished.
           Freezer.deep(Array(instance[mutation.target]) + [element])
         end
 
         # Vendored addition, not (yet) upstream hecks (migration plan
         # task 4): the removal counterpart to #appended -- matches by
-        # VALUE EQUALITY, element-wise, no read-modify-write (plan.
+        # value equality, element-wise, no read-modify-write (plan.
         # bluebook's own words: "so a concurrent Add can never be lost")
-        # -- UNLESS the target list is itself entity-typed (BUG#32,
+        # -- unless the target list is itself entity-typed (BUG#32,
         # QualityControl ledger), in which case `EntityElement.
-        # list_element_match?` matches by the entity's own IDENTITY
+        # list_element_match?` matches by the entity's own identity
         # field instead -- see that method's own comment for the full
         # "why identity, not whole-value equality" reasoning. `mutation.
         # source` is a single field reference (`:dependency`), unlike
-        # append's field-map -- resolved and Value-coerced the SAME way
+        # append's field-map -- resolved and Value-coerced the same way
         # increment/decrement already coerce their own amount, so the
         # comparison is against a like-shaped Value, not a raw scalar
         # against a wrapped one.
@@ -197,26 +197,26 @@ module Hecks
 
         # Vendored fix, not (yet) upstream hecks (migration plan
         # task 9): #apply's `:increment`/`:decrement`/`:multiply`
-        # branches used to wrap `amount` into a `Value` unconditionally
+        # branches wrapping `amount` into a `Value` unconditionally
         # whenever the target attribute existed, never checking whether
-        # `current` (the field's OWN existing value, read straight off
-        # `instance[mutation.target]`) was ALSO wrapped -- the two sides
-        # of the same arithmetic call could disagree on Value-ness. On a
-        # PHANTOM-CREATED field this is the common case, not an edge
+        # `current` (the field's own existing value, read straight off
+        # `instance[mutation.target]`) was also wrapped, would let the two
+        # sides of the same arithmetic call disagree on Value-ness. On a
+        # phantom-created field this is the common case, not an edge
         # one: `Instance.defaults`/`#default_for` leaves a VO-typed
         # attribute with no declared `default:` genuinely absent (nil),
         # and `CommandRules::Arithmetic#arithmetic`/`#multiply`'s own
-        # `current ||= 0` then turns that nil into a RAW, unwrapped
+        # `current ||= 0` then turns that nil into a raw, unwrapped
         # Integer `0` -- so `current.is_a?(Value) && amount.is_a?(Value)`
         # read false even though `amount` (correctly wrapped by the old
         # unconditional line) genuinely held a valid, correctly-typed
         # number, and the primitive path's `unless amount.is_a?(Numeric)`
-        # guard refused it as a TYPE MISMATCH the caller never made --
+        # guard refused it as a type mismatch the caller never made --
         # an artifact of this method's own asymmetric wrapping, not bad
         # input.
         #
-        # Fixed at the call site (above) by wrapping `amount` ONLY when
-        # `current` is ALREADY a `Value` -- so an established VO-typed
+        # Fixed at the call site (above) by wrapping `amount` only when
+        # `current` is already a `Value` -- so an established VO-typed
         # field (a multi-field Money balance, say, already hydrated from
         # a prior save) keeps going through
         # `Arithmetic#arithmetic_value_object` exactly as before (the
@@ -225,7 +225,7 @@ module Hecks
         # `current` and raw `amount` both take the plain-Numeric path
         # together. This method closes the other half: the plain-Numeric
         # path returns a bare Ruby number, and if the attribute is
-        # itself VO-typed (the norm), that raw result needs the SAME
+        # itself VO-typed (the norm), that raw result needs the same
         # wrap `:set` already gives its own resolved value (`Value.for`)
         # before it's stored, so a field's stored shape doesn't depend
         # on which dispatch happened to mutate it first. A no-op
@@ -251,10 +251,10 @@ module Hecks
             attribute = entity.attribute(entity.identified_by)
             fields[entity.identified_by] = Value.from_identifier(aggregate, attribute, next_identity(current, entity))
           else
-            check_entity_collision(aggregate, entity, current, fields)
+            EntityElement.check_entity_collision(aggregate, entity, current, fields)
           end
           fields[entity.lifecycle.field] ||= entity.lifecycle.default if entity.lifecycle
-          # BUG#12 — every one of THIS entity's own declared attributes
+          # BUG#12 — every one of this entity's own declared attributes
           # the append mapping (and the identity/lifecycle filling just
           # above) didn't already touch gets its own default, the same
           # way a fresh aggregate's own attributes already do
@@ -267,7 +267,7 @@ module Hecks
           EntityElement.fill_declared_defaults(aggregate, entity, fields)
         end
 
-        # THE MINTED IDENTITY IS ONE PAST THE HIGHEST HELD (C4.5) — not
+        # The minted identity is one past the highest held (C4.5) — not
         # `size + 1`, which repeats an identity the moment the list has
         # ever shrunk. One strategy for the language, so the IR declares
         # none; the Rust generators mint by the same rule.
@@ -276,37 +276,15 @@ module Hecks
           held.max.to_i + 1
         end
 
-        # THE SAME CHECK #hydrate GIVES EVERY CREATING AGGREGATE COMMAND
-        # (`repository.find(id)`, above this file in command_interpreter.rb),
-        # one level down. Reached only on the two branches #entity_element
-        # does NOT auto-mint: a CALLER-SUPPLIED identity (the field is
-        # already in the append's own field map, so the `if` above skips
-        # it) or a COMPOSITE one (`entity.identified_by` is nil for those —
-        # Runtime::Identified#derive_identity — so the `if` above is false
-        # unconditionally). 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 EntityInterpreter#element_of's
-        # `find_index` always matches the FIRST match, so the second becomes
-        # permanently unaddressable by any later command.
-        #
-        # Auto-minted 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.
-        def check_entity_collision(aggregate, 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("AlreadyExists", "entity_duplicate",
-                                                     entity: entity.hecks_name, aggregate: aggregate.hecks_name,
-                                                     identity: Identity.reading(entity),
-                                                     offered: heads.map { |head| Rendering.describe(fields[head]) }.join(", ")))
-        end
+        # The entity-collision check lives in `EntityElement.check_entity_collision`
+        # (entity_element.rb) — BUG#145 — shared by both `#entity_element` above
+        # (an aggregate's own entity list, e.g. `Workspace.boards`) and
+        # `EntityElement#appended_to_element`'s own nested-entity branch (an
+        # entity's own entity list one hop further in, e.g. `Board.cards`),
+        # which needs the exact same guard against a caller-supplied nested
+        # identity silently duplicating. See that method's own call site and
+        # comment; the check's own doc comment (heads/composite/auto-mint
+        # reasoning) lives with the code, in entity_element.rb.
       end
     end
   end