hecks 1.2.0 → 1.4.0

data/lib/hecks/router/namespace_installer.rb

@@ -77,16 +77,16 @@ module Hecks
         end
       end
 
-      # `.find`/`.all`/`.count`/`.events`/`.repository` — the SAME read/CRUD
+      # `.find`/`.all`/`.count`/`.events`/`.repository` — the same read/CRUD
       # surface `Facade::Surface::AggregateDoor` gives a plain `Hecks
       # .boot`, missing here until now: `install_namespace_entry` above
-      # installs ONE method per declared VERB, so an aggregate with no
+      # installs one method per declared verb, so an aggregate with no
       # commands or queries of its own shape (or simply never asked for
       # a `find`-shaped query) had no way to look up one record by id
       # through the router surface at all — real gap, hit live building
       # a `List` aggregate meant to be read this way. Grouped by
       # (realm, domain, aggregate) rather than installed per-verb,
-      # because unlike a command or query this is the SAME five methods
+      # because unlike a command or query this is the same five methods
       # regardless of which verb happened to trigger this aggregate's
       # own namespace module into existing.
       def install_aggregate_doors!

data/lib/hecks/router.rb

@@ -47,7 +47,7 @@ module Hecks
       entry = resolve(address)
       raise WrongVerbKind, "#{address.inspect} names a query; use #query" unless entry.command?
 
-      entry.dispatcher.dispatch(local_verb(entry), **args)
+      entry.dispatcher.dispatch_flat(local_verb(entry), args)
     end
 
     def query(address, **args)

data/lib/hecks/runtime/aggregate_lock.rb

@@ -1,28 +1,28 @@
 module Hecks
   module Runtime
-    # A PROCESS-WIDE, STRIPED MUTEX REGISTRY — the concurrency-control
-    # mechanism for every adapter that does NOT declare
+    # **A process-wide, striped mutex registry** — the concurrency-control
+    # mechanism for every adapter that does not declare
     # `:optimistic_concurrency` (Heki, Memory today; see
     # `CommandInterpreter#call`/`EntityInterpreter#call`, which choose
     # between this and Postgres's CAS+retry purely off
     # `repository.capabilities`).
     #
-    # WHY A LOCK SUFFICES HERE AND CAS IS NOT NEEDED: both adapters hold
+    # Why a lock suffices here and CAS is not needed: both adapters hold
     # process-local data. `Adapters::Memory.tenant_capable?`'s own comment
     # states the confirmed fact this relies on — two `Runtime.boot` calls
-    # get two entirely separate adapter instances; there is never a SECOND
-    # PROCESS writing the same Heki file or the same Memory Hash, only
-    # possibly other THREADS within this one process. A `Mutex` held for
+    # get two entirely separate adapter instances; there is never a second
+    # process writing the same Heki file or the same Memory Hash, only
+    # possibly other threads within this one process. A `Mutex` held for
     # the full hydrate-through-save critical section closes the identical
     # lost-update gap CAS closes for Postgres, with no schema, no version
     # column, and no retry loop — the second thread simply doesn't start
     # its own hydrate until the first thread's save has landed.
     #
-    # STRIPED, NOT ONE GLOBAL LOCK: keyed by `[domain, aggregate.hecks_name,
-    # id]`, so two dispatches against two DIFFERENT records never block
+    # **Striped, not one global lock**: keyed by `[domain, aggregate.hecks_name,
+    # id]`, so two dispatches against two different records never block
     # each other. The registry Hash itself is guarded by its own top-level
     # Mutex only for the moment a new per-key Mutex is created — two
-    # threads locking DIFFERENT keys for the first time never wait on one
+    # threads locking different keys for the first time never wait on one
     # another beyond that brief creation window.
     module AggregateLock
       @registry_lock = Mutex.new
@@ -31,9 +31,9 @@ module Hecks
       class << self
         # `AggregateLock.for(domain, aggregate, id).synchronize { ... }`
         # `id: nil` — identity could not be resolved yet (see
-        # `Identity.best_effort`) — locks by aggregate TYPE alone, coarser
+        # `Identity.best_effort`) — locks by aggregate type alone, coarser
         # (every record of this aggregate serializes against every other)
-        # but still correct: it can only ever make dispatch MORE
+        # but still correct: it can only ever make dispatch more
         # conservative than a resolved id would.
         def for(domain, aggregate, id = nil)
           key = id.nil? ? [domain.to_s, aggregate.hecks_name] : [domain.to_s, aggregate.hecks_name, id.to_s]

data/lib/hecks/runtime/boot_gates.rb

@@ -1,8 +1,8 @@
 module Hecks
   module Runtime
     # A boot's own small set of phase-tagged, conditionally-present gates —
-    # ADR 0031. Registration is instance-scoped, ONE PER `Loader.boot`
-    # CALL, never a module-level singleton: a process that boots more than
+    # ADR 0031. Registration is instance-scoped, one per `Loader.boot`
+    # call, never a module-level singleton: a process that boots more than
     # one registry in its lifetime (every spec suite does) must never let
     # one boot's capability profile leak into the next boot's gate list.
     #
@@ -13,7 +13,7 @@ module Hecks
     # order — today exactly one gate per phase, so ordering among
     # same-phase gates has never been exercised.
     #
-    # This is deliberately NOT the same registry `Hecks::Projector` uses
+    # This is deliberately not the same registry `Hecks::Projector` uses
     # (ADR 0027) — that one is a process-wide, static IR-in/artifact-out
     # registry with no bindings and no live-state mutation; this one is
     # per-boot and gates real I/O (a Postgres mint, a saga-store read).

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,7 +31,7 @@ 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)
 
@@ -49,7 +49,7 @@ module Hecks
         Thread.current[:hecks_caller] = previous
       end
 
-      # A REACTION IS THE SYSTEM ACTING, not the caller who happened to be
+      # 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

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

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

@@ -11,18 +11,18 @@ module Hecks
         private
 
         # Anything else used to ride along in the payload untouched —
-        # normalize_args walks the DECLARED attributes, so a name the command
+        # 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.
         #
-        # 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,24 +33,24 @@ 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
+        # 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
@@ -60,16 +60,16 @@ module Hecks
         # 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
+        # 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.
+        # 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,
+        # 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
@@ -80,19 +80,19 @@ module Hecks
           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 +104,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

@@ -1,4 +1,5 @@
 require_relative "../value"
+require_relative "../entity_element"
 
 module Hecks
   module Runtime
@@ -18,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#
@@ -53,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))
@@ -85,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
@@ -119,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
@@ -148,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.
@@ -164,7 +165,7 @@ module Hecks
                                      fields)
                     end
 
-          # FROZEN, like every other value the domain hands back. An
+          # 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
           # dispatch had finished.
@@ -173,42 +174,49 @@ module Hecks
 
         # 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.
-        # bluebook's own words: "so a concurrent Add can never be lost").
-        # `mutation.source` is a single field reference (`:dependency`),
-        # unlike 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.
+        # 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,
+        # QualityControl ledger), in which case `EntityElement.
+        # 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
+        # increment/decrement already coerce their own amount, so the
+        # comparison is against a like-shaped Value, not a raw scalar
+        # against a wrapped one.
         def removed(instance, aggregate, mutation, args)
           value     = @rules.resolve_source(mutation.source, args)
           attribute = aggregate.attribute(mutation.target)
           value     = Value.for_attribute(aggregate, attribute, value) if attribute
-          Array(instance[mutation.target]).reject { |element| element == value }
+          Array(instance[mutation.target]).reject do |element|
+            EntityElement.list_element_match?(aggregate, attribute, element, value)
+          end
         end
 
         # Vendored fix, not (yet) upstream hecks (migration plan
         # task 9): #apply's `:increment`/`:decrement`/`:multiply`
         # branches used to wrap `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
+        # `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
+        # 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
@@ -217,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
@@ -243,13 +251,23 @@ 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
-          fields
+          # 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
+          # (`Instance.defaults`) — see `EntityElement#
+          # fill_declared_defaults`'s own comment for the full reasoning;
+          # shared rather than reimplemented so this aggregate-level
+          # entity creation and `EntityElement#appended_to_element`'s
+          # entity-nested-in-entity one can never drift on what "the
+          # default" means.
+          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.
@@ -258,37 +276,16 @@ 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
+        # Moved to `EntityElement.check_entity_collision` (entity_element.rb)
+        # — BUG#145. Used to live here, called only from `#entity_element`
+        # above (an aggregate's own entity list, e.g. `Workspace.boards`).
+        # `EntityElement#appended_to_element`'s own nested-entity branch (an
+        # entity's own entity list one hop further in, e.g. `Board.cards`)
+        # needs the exact same guard — see that method's own call site and
+        # comment for why a caller-supplied nested identity was silently
+        # duplicating before this moved. Pure relocation, not a behavior
+        # change here: the check's own doc comment (heads/composite/
+        # auto-mint reasoning) now lives with the code, in entity_element.rb.
       end
     end
   end