hecks 1.1.0 → 1.3.0

data/lib/hecks/projections/glossary.rb

@@ -0,0 +1,302 @@
+require_relative "../projector"
+require_relative "../naming"
+require_relative "statements"
+require_relative "glossary/sections"
+require_relative "glossary/sentences"
+require_relative "glossary/mermaid"
+require_relative "glossary/markdown"
+require_relative "glossary/html"
+
+module Hecks
+  module Projections
+    # A CHAPTER, PROJECTED AS ITS UBIQUITOUS LANGUAGE — a glossary for the
+    # whole team, in the sense Evans meant (DDD ch. 2): ONE language,
+    # shared by domain experts and developers, written the same way in
+    # conversation, diagrams, documents and code, so that a subject-matter
+    # expert can read the model and say "yes, that's how it works" or
+    # "no, that's wrong". A banker, a support rep, the CEO and an engineer
+    # read the same page.
+    #
+    # THREE THINGS FOLLOW FROM THAT AUDIENCE. First, no type jargon: a
+    # term is a term, not "an Aggregate" or "a Value Object", and every
+    # identifier is spelled as a person says it (`Naming.words`: `ATMCard`
+    # is "ATM card"). Second, nothing invented: every sentence is either
+    # the domain author's own words (a `description`, a `goal`, an
+    # invariant) or built mechanically from a declared fact ("Recorded
+    # after Freeze account") — the same discipline `DocsProjector` holds
+    # to; a wrong sentence is worse than a missing one. Third, grouped
+    # under the aggregate each term belongs to, A to Z within it — a
+    # reader thinks "what does Account mean" before "what starts with A",
+    # and once there reads the way a dictionary reads.
+    #
+    # TWO FILES FROM ONE SOURCE. `glossary.md` is the document — every
+    # construct in it renders on GitHub as-is (headings, blockquotes,
+    # ```mermaid fences, lists, in-page links). `html/index.html` is that
+    # exact Markdown string rendered into a page with a navigation rail;
+    # it is built FROM the Markdown, not beside it, so the two cannot
+    # drift. `bin/project_glossary` writes both to `<domain>/glossary/` beside
+    # the bluebook (examples/banking, examples/pizzas, and the QA ledger in qa/).
+    #
+    #   Projector.call(:glossary, bluebook: <the Bluebook chapter>)
+    #   # => { "glossary.md" => "...", "html/index.html" => "..." }
+    module Glossary
+      extend Projector::Target
+
+      projects_as :glossary, emits: :files
+
+      # One term. `kind` is a Symbol the renderers never print; `facts`
+      # carries the declaration objects the sentence is built from;
+      # `headword` and `slug` are assigned once the document's order is
+      # known (a headword may need qualifying, a slug depends on what
+      # came before it).
+      Entry = Struct.new(:name, :kind, :within, :section, :facts, :headword, :slug, keyword_init: true)
+
+      # One `##` of the document: an aggregate (with its own object, for
+      # the lede and diagrams) or one of the three trailing groups.
+      Section = Struct.new(:name, :title, :aggregate, :terms, :slug, keyword_init: true)
+
+      Document = Struct.new(:bluebook, :sections, :index, keyword_init: true)
+
+      module_function
+
+      def call(bluebook:, options: {})
+        markdown = Markdown.render(document(bluebook))
+        { "glossary.md" => markdown, "html/index.html" => Html.render(markdown) }
+      end
+
+      # ── the document ─────────────────────────────────────────────────
+
+      def document(bluebook)
+        sections = sections(bluebook, entries(bluebook))
+        Slugs.assign!(bluebook, sections)
+        Document.new(bluebook: bluebook, sections: sections, index: Index.new(sections))
+      end
+
+      # AGGREGATES FIRST, A TO Z BY THEIR SPOKEN NAME ("Account" before
+      # "ATM card"), then the three groups nothing homes to one aggregate.
+      def sections(bluebook, entries)
+        grouped = entries.group_by(&:section)
+        list = bluebook.aggregates.sort_by { |aggregate| Naming.words(aggregate.hecks_name).downcase }.map do |aggregate|
+          Section.new(name: aggregate.hecks_name, title: Naming.words(aggregate.hecks_name), aggregate: aggregate,
+                      terms: with_headwords(grouped.fetch(aggregate.hecks_name, []), aggregate.hecks_name))
+        end
+        [ROLES, READ_MODELS, REACTIONS].each do |name|
+          held = grouped[name == REACTIONS ? nil : name]
+          list << Section.new(name: name, title: name, terms: with_headwords(held, name)) if held
+        end
+        list
+      end
+
+      # A HEADWORD IS QUALIFIED ONLY WHEN IT WOULD REPEAT within its own
+      # section — "Open" the action and "Open (the list)" the question;
+      # "Return (key issuance)" beside another Return — never numbered
+      # (Chicago 18.9, MDN's disambiguation pages: qualify the headword).
+      def with_headwords(entries, section_name)
+        entries.each { |entry| entry.headword = Naming.words(entry.name) }
+        entries.group_by(&:headword).each_value do |group|
+          next if group.size == 1
+
+          group.each { |entry| entry.headword = qualified(entry, group, section_name) }
+        end
+        entries.sort_by { |entry| [entry.headword.downcase, entry.kind.to_s] }
+      end
+
+      def qualified(entry, group, section_name)
+        base = Naming.words(entry.name)
+        return "#{base} (the list)" if entry.kind == :query && group.any? { |other| other.kind == :command }
+        return "#{base} (#{Naming.words(entry.within).downcase})" if entry.within && entry.within != section_name
+
+        base
+      end
+
+      # ── gathering ────────────────────────────────────────────────────
+
+      # AN ENTITY CAN CARRY ITS OWN COMMANDS AND QUERIES TOO — walked the
+      # same one level down `DocsProjector` and `Projections::Diagrams`
+      # already walk it.
+      def holders(bluebook)
+        bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
+      end
+
+      # EVERY HOLDER'S OWN AGGREGATE, ONE HOP OR ZERO — an aggregate maps
+      # to itself, an entity to whichever aggregate declared it. The one
+      # fact the grouping is built on.
+      def holder_aggregate(bluebook)
+        bluebook.aggregates.each_with_object({}) do |aggregate, map|
+          map[aggregate.hecks_name] = aggregate.hecks_name
+          aggregate.entities.each { |entity| map[entity.hecks_name] = aggregate.hecks_name }
+        end
+      end
+
+      # EVERY EVENT'S RAISERS — an event is never declared, only emitted,
+      # so its home is whichever aggregate the FIRST command that raises
+      # it belongs to; a policy or saga reacting to it inherits that home.
+      def event_raisers(bluebook)
+        holders(bluebook).each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |holder, map|
+          holder.commands.each { |command| command.emits.each { |event| map[event] << [holder, command] } }
+        end
+      end
+
+      def bare(qualified) = qualified.to_s.split(".").last
+
+      def entries(bluebook)
+        homes   = holder_aggregate(bluebook)
+        raisers = event_raisers(bluebook)
+        home_of = ->(event) { raisers.key?(event) ? homes[raisers[event].first.first.hecks_name] : nil }
+
+        entries = []
+        entries += entity_entries(bluebook)
+        entries += value_object_entries(bluebook)
+        entries += verb_entries(bluebook, homes)
+        entries += event_entries(bluebook, raisers, home_of)
+        entries += policy_entries(bluebook, home_of)
+        entries += saga_entries(bluebook, home_of)
+        entries += role_entries(bluebook)
+        entries += read_model_entries(bluebook)
+        entries
+      end
+
+      def entity_entries(bluebook)
+        bluebook.aggregates.flat_map do |aggregate|
+          aggregate.entities.map do |entity|
+            Entry.new(name: entity.hecks_name, kind: :entity, within: aggregate.hecks_name,
+                      section: aggregate.hecks_name, facts: { entity: entity })
+          end
+        end
+      end
+
+      # AGGREGATES ONLY — an entity declares no value objects of its own
+      # (`Bluebook::Entity` deliberately does not answer `value_objects`).
+      def value_object_entries(bluebook)
+        bluebook.aggregates.flat_map do |aggregate|
+          aggregate.value_objects.map do |value_object|
+            Entry.new(name: value_object.hecks_name, kind: :value_object, within: aggregate.hecks_name,
+                      section: aggregate.hecks_name, facts: { value_object: value_object })
+          end
+        end
+      end
+
+      def verb_entries(bluebook, homes)
+        holders(bluebook).flat_map do |holder|
+          commands = holder.commands.map do |command|
+            Entry.new(name: command.hecks_name, kind: :command, within: holder.hecks_name,
+                      section: homes[holder.hecks_name], facts: { command: command, holder: holder })
+          end
+          queries = holder.queries.map do |query|
+            Entry.new(name: query.hecks_name, kind: :query, within: holder.hecks_name,
+                      section: homes[holder.hecks_name], facts: { query: query })
+          end
+          commands + queries
+        end
+      end
+
+      def event_entries(bluebook, raisers, home_of)
+        raisers.map do |event, raised_by|
+          reactions = bluebook.policies.select { |policy| bare(policy.on_event) == event }
+          Entry.new(name: event, kind: :event, section: home_of.call(event),
+                    facts: { event: event, raised_by: raised_by, policies: reactions })
+        end
+      end
+
+      def policy_entries(bluebook, home_of)
+        bluebook.policies.map do |policy|
+          Entry.new(name: policy.name, kind: :policy, section: home_of.call(bare(policy.on_event)),
+                    facts: { policy: policy })
+        end
+      end
+
+      def saga_entries(bluebook, home_of)
+        bluebook.process_managers.map do |saga|
+          shape = saga.to_h
+          Entry.new(name: shape[:name], kind: :saga, section: home_of.call(bare(shape[:starts_on])),
+                    facts: { saga: shape })
+        end
+      end
+
+      # CROSS-CUTTING BY NATURE — `System` and `Customer` issue commands
+      # across half the aggregates here — so a role belongs to no single
+      # one and gets its own section.
+      def role_entries(bluebook)
+        by_role = Hash.new { |hash, key| hash[key] = [] }
+        holders(bluebook).each do |holder|
+          holder.commands.select(&:role).each { |command| by_role[command.role] << [holder, command] }
+        end
+        by_role.map do |role, issues|
+          Entry.new(name: role, kind: :role, section: ROLES, facts: { role: role, commands: issues })
+        end
+      end
+
+      # A read model joins heads from more than one aggregate — its own
+      # header says so — so it belongs to none of them.
+      def read_model_entries(bluebook)
+        bluebook.read_models.map do |read_model|
+          Entry.new(name: read_model.name, kind: :read_model, section: READ_MODELS, facts: { read_model: read_model })
+        end
+      end
+
+      # ── anchors ──────────────────────────────────────────────────────
+
+      # GITHUB'S OWN HEADING SLUGS, REPRODUCED — lowercase, punctuation
+      # dropped, spaces to hyphens, a repeat gets "-1", "-2" in document
+      # order. Computed here, once, in the order the headings will appear,
+      # so a link written into the Markdown lands on the same heading
+      # whether GitHub renders the `.md` or `Html` renders the page.
+      module Slugs
+        module_function
+
+        def github(text) = text.to_s.downcase.gsub(/[^\p{Word}\- ]/, "").tr(" ", "-")
+
+        def assign!(bluebook, sections)
+          seen = Hash.new(0)
+          take = lambda do |text|
+            base = github(text)
+            seen[base] += 1
+            seen[base] == 1 ? base : "#{base}-#{seen[base] - 1}"
+          end
+          take.call(Markdown.title(bluebook))
+          sections.each do |section|
+            section.slug = take.call(section.title)
+            section.terms.each { |entry| entry.slug = take.call(entry.headword) }
+          end
+        end
+      end
+
+      # WHERE A DECLARED REFERENCE POINTS — keyed structurally (a command
+      # by its holder AND name, an event by its bare name), never by
+      # searching prose for a matching word. Anything not declared here
+      # (a cross-domain command like `Notifications.Send`) answers nil,
+      # and the sentence says it in words with no link.
+      class Index
+        def initialize(sections)
+          @by_key = {}
+          sections.each do |section|
+            @by_key[[:aggregate, section.name]] = section if section.aggregate
+            section.terms.each { |entry| @by_key[key_of(entry)] = entry }
+          end
+        end
+
+        def key_of(entry)
+          case entry.kind
+          when :command, :query, :value_object then [entry.kind, entry.within, entry.name]
+          else [entry.kind, entry.name]
+          end
+        end
+
+        def [](kind, name, within: nil)
+          @by_key[within ? [kind, within, name] : [kind, name]]
+        end
+
+        # A Markdown link to a term's own heading, or the plain words when
+        # the chapter declares no such term. `label:` overrides the link
+        # text for a sentence that has to tell two same-named terms apart.
+        def link(kind, name, within: nil, label: nil)
+          target = self[kind, name, within: within]
+          return label || Naming.words(name) unless target
+
+          text = label || (target.is_a?(Section) ? target.title : target.headword)
+          "[#{text}](##{target.slug})"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections.rb

@@ -30,3 +30,4 @@ require_relative "projections/reference"
 require_relative "projections/model"
 require_relative "projections/diagrams"
 require_relative "projections/statements"
+require_relative "projections/glossary"

data/lib/hecks/projector/cli_projector.rb

@@ -156,6 +156,33 @@ module Hecks
          entity ? "#{entity.hecks_name}." : "", verb.hecks_name].join
       end
 
+      # THE ARGUMENTS A RECEIVER ADDS, BEFORE ANY VERB-SPECIFIC ONE. Shared by
+      # `command_spec` and `port_spec` — a port operation always addresses an
+      # aggregate record (`port_spec` passes `receiver: :aggregate`, never
+      # `:entity` or `nil`, because a port is declared on an aggregate, never
+      # an entity), and this is exactly the same "how do I name the record"
+      # question a command with a receiver already answers, so it is answered
+      # once, here, rather than duplicated.
+      #
+      # `nil` — a creating command — takes none: there is no existing record
+      # yet for `to=` to name.
+      def receiver_options(receiver, aggregate, entity)
+        case receiver
+        when :entity
+          [
+            { path: "to.aggregate", type: "String", required: true,
+              note: "id of the #{aggregate.hecks_name} holding the #{entity.hecks_name}" },
+            { path: "to.entity", type: "String", required: true,
+              note: "id of the #{entity.hecks_name} to act on" }
+          ]
+        when :aggregate
+          [{ path: "to", type: "String", required: true,
+             note: "id of the #{aggregate.hecks_name} to act on" }]
+        else
+          []
+        end
+      end
+
       # ── one verb ──────────────────────────────────────────────────────
 
       def command_spec(bluebook, aggregate, entity, command)
@@ -166,7 +193,6 @@ module Hecks
                     else
                       (command.creates? ? nil : :aggregate)
                     end
-        legacy_arguments = []
 
         # THE RECEIVER IS NOT A COMMAND ARGUMENT. An aggregate command names
         # its record through to; an entity command needs both the aggregate
@@ -178,18 +204,8 @@ module Hecks
         # Existing aggregate scripts may still spell the receiver id=... .
         # That alias is deliberately hidden from help and recorded separately
         # as legacy_arguments; new help and examples teach only to=... .
-        if entity
-          arguments = [
-            { path: "to.aggregate", type: "String", required: true,
-              note: "id of the #{aggregate.hecks_name} holding the #{entity.hecks_name}" },
-            { path: "to.entity", type: "String", required: true,
-              note: "id of the #{entity.hecks_name} to act on" }
-          ] + arguments
-        elsif receiver == :aggregate
-          arguments = [{ path: "to", type: "String", required: true,
-                         note: "id of the #{aggregate.hecks_name} to act on" }] + arguments
-          legacy_arguments = [{ path: "id", type: "String", required: true }]
-        end
+        arguments = receiver_options(receiver, aggregate, entity) + arguments
+        legacy_arguments = receiver == :aggregate ? [{ path: "id", type: "String", required: true }] : []
 
         { verb: fqn(bluebook, aggregate, command, entity), kind: :command,
           summary: command.goal, role: command.role, role_gated: !command.role.to_s.empty?,

data/lib/hecks/projector/exporter.rb

@@ -54,6 +54,30 @@ module Hecks
         { capable_aggregates: capable.map { |aggregate| { name: aggregate.name, storage_name: aggregate.storage_name } } }
       end
 
+      # A BINDING fact, same shape/reasoning as `lineage` above: every
+      # aggregate's DECLARED persistence adapter name (`persisted_by`),
+      # not part of the canonical bluebook shape `call` exports (ADR
+      # 0001 — the IR describes what's declared, never which adapter a
+      # deployment binds it to). Unlike `lineage`, this needs no era
+      # plugin — `BindingPolicy` is core, always loaded — and covers
+      # EVERY aggregate, not just lineage-capable ones: `rust/host`
+      # (`ir.rs`'s own `refuse_unsupported_persistence_adapters`) reads
+      # this to refuse loudly, at boot, against a domain bound to an
+      # adapter it has no backend for (Heki, Memory, Sqlite, D1,
+      # LocalStorage — `rust/host` understands only Postgres/PostgresEra
+      # today), rather than silently building up a second, disjoint
+      # history nothing but Rust ever reads while the real state stays
+      # wherever its own adapter actually wrote it.
+      def persistence(registry, domain_name)
+        bluebook = registry.bluebooks.fetch(domain_name)
+        aggregates = bluebook.aggregates.map do |aggregate|
+          adapter = Ports::Persistence::BindingPolicy.resolve(registry, domain_name, aggregate).adapter
+          { name: aggregate.name, storage_name: aggregate.storage_name, adapter: adapter }
+        end
+
+        { aggregates: aggregates }
+      end
+
       # Translation IR, always as an array, WITH each aggregate's
       # precompiled SQL attached (`compiled_translation_aggregate`) —
       # this is the export a consumer embeds (`ir.json`'s `translations`

data/lib/hecks/projector/narrate_projector.rb

@@ -284,18 +284,11 @@ module Hecks
 
       # ── small sentence carpentry ──────────────────────────────────────
 
-      def to_sentence_list(items, conj: "and")
-        case items.size
-        when 0 then ""
-        when 1 then items[0].to_s
-        when 2 then "#{items[0]} #{conj} #{items[1]}"
-        else "#{items[0..-2].join(', ')}, #{conj} #{items[-1]}"
-        end
-      end
+      # Both now live in `Naming` (a second projection, the glossary,
+      # needed them); kept here as names so this file reads as it did.
+      def to_sentence_list(items, conj: "and") = Naming.to_sentence_list(items, conj: conj)
 
-      def a_or_an(word)
-        %w[a e i o u].include?(word.to_s[0].to_s.downcase) ? "an" : "a"
-      end
+      def a_or_an(word) = Naming.a_or_an(word)
     end
   end
 end

data/lib/hecks/query_specification/common/comparison.rb

@@ -165,7 +165,33 @@ module Hecks
           record = registry.repository(target_domain, target_ir).find(held)
           return true unless record
 
-          comparable(record.state[:state]) != state
+          # THE FIELD A STATE LIVES ON, READ FROM THE TARGET'S OWN
+          # DECLARATION — not assumed to be literally named `state`. Every
+          # `none_in_state` fixture this comparator originally shipped
+          # with (spec/query_none_in_state_*_spec.rb) happens to declare a
+          # plain `attribute :state, ...` rather than a real `lifecycle`,
+          # which is how the previous hardcoded `record.state[:state]`
+          # passed every one of them while being wrong for the shape this
+          # whole comparator exists to answer about: a real state MACHINE.
+          # `lifecycle :field, default: ... do ... end` stores its state
+          # under `field` (`Instance#assign_creation_attributes`'s own
+          # `state[aggregate.lifecycle.field.to_sym] = ...`), and this
+          # codebase's own convention overwhelmingly names that field
+          # `status`, not `state` (`QualityControl::Clearance`'s own
+          # `lifecycle :status` among many others) — so the hardcoded key
+          # silently read `nil` from every real lifecycle-backed target,
+          # comparable(nil) != state was true unconditionally, and
+          # `none_in_state` against ANY lifecycle aggregate answered
+          # "not excluded" for every row, always, no matter its actual
+          # state. Found chasing `QualityControl::Bug.AwaitingClearance`
+          # (qa/bluebook/quality_control.bluebook), which is exactly this
+          # shape: `Clearance:green`/`Clearance:red` against a `lifecycle
+          # :status` aggregate. Falls back to `:state` when the target
+          # declares no lifecycle at all, so every existing fixture (a
+          # plain attribute literally named `state`) keeps answering
+          # exactly as before.
+          field = target_ir.lifecycle&.field || :state
+          comparable(record.state[field]) != state
         end
 
         def find_aggregate_by_name(registry, name)

data/lib/hecks/query_specification/common/limit_spec.rb

@@ -1,8 +1,15 @@
 module Hecks
   module QuerySpecification
     module Common
-      LimitSpec = Struct.new(:value, keyword_init: true) do
-        def to_h = { value: QuerySpecification.render_value(value) }
+      # `target` — see `WhereClause`'s own header (ADR 0055): which
+      # many-side `include`d aggregate this `limit` applies to, on a
+      # `read_model` declaring more than one. `nil` for a plain `Query`,
+      # and for a `read_model` with a single many-side head.
+      LimitSpec = Struct.new(:value, :target, keyword_init: true) do
+        def to_h
+          base = { value: QuerySpecification.render_value(value) }
+          target ? base.merge(target: target.to_s) : base
+        end
       end
     end
   end

data/lib/hecks/query_specification/common/offset_spec.rb

@@ -1,8 +1,15 @@
 module Hecks
   module QuerySpecification
     module Common
-      OffsetSpec = Struct.new(:value, keyword_init: true) do
-        def to_h = { value: QuerySpecification.render_value(value) }
+      # `target` — see `WhereClause`'s own header (ADR 0055): which
+      # many-side `include`d aggregate this `offset` applies to, on a
+      # `read_model` declaring more than one. `nil` for a plain `Query`,
+      # and for a `read_model` with a single many-side head.
+      OffsetSpec = Struct.new(:value, :target, keyword_init: true) do
+        def to_h
+          base = { value: QuerySpecification.render_value(value) }
+          target ? base.merge(target: target.to_s) : base
+        end
       end
     end
   end

data/lib/hecks/query_specification/common/order_by.rb

@@ -1,8 +1,15 @@
 module Hecks
   module QuerySpecification
     module Common
-      OrderBy = Struct.new(:field, :direction, keyword_init: true) do
-        def to_h = { field: field.to_s, direction: direction.to_s }
+      # `target` — see `WhereClause`'s own header (ADR 0055): which
+      # many-side `include`d aggregate this `order_by` applies to, on a
+      # `read_model` declaring more than one. `nil` for a plain `Query`,
+      # and for a `read_model` with a single many-side head.
+      OrderBy = Struct.new(:field, :direction, :target, keyword_init: true) do
+        def to_h
+          base = { field: field.to_s, direction: direction.to_s }
+          target ? base.merge(target: target.to_s) : base
+        end
       end
     end
   end

data/lib/hecks/query_specification/common/where_clause.rb

@@ -1,8 +1,21 @@
 module Hecks
   module QuerySpecification
     module Common
-      WhereClause = Struct.new(:field, :op, :value, keyword_init: true) do
-        def to_h = { field: field.to_s, op: op.to_s, value: QuerySpecification.render_value(value) }
+      # `target` — which many-side `include`d aggregate this clause applies
+      # to on a `read_model` with more than one (ADR 0055's own `on:`,
+      # `ReadModelBuilder#where_impl`). Always `nil` for a plain `Query`'s
+      # own `where` (that builder never overrides `where_impl` to accept
+      # `on:`), and `nil` for a `read_model` with a single many-side head,
+      # where naming one is unnecessary. `to_h` omits the key entirely
+      # rather than emitting `target: nil` — the same "absent, not null"
+      # convention `count`/`median_field` already established
+      # (`lib/hecks/bluebook/read_model.rb`), so every read model that
+      # never uses `on:` keeps its existing wire shape byte-identical.
+      WhereClause = Struct.new(:field, :op, :value, :target, keyword_init: true) do
+        def to_h
+          base = { field: field.to_s, op: op.to_s, value: QuerySpecification.render_value(value) }
+          target ? base.merge(target: target.to_s) : base
+        end
       end
     end
   end

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

@@ -1,4 +1,5 @@
 require_relative "../value"
+require_relative "../entity_element"
 
 module Hecks
   module Runtime
@@ -174,17 +175,24 @@ 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.
+        # 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
@@ -246,7 +254,17 @@ module Hecks
             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