hecks 3.4.2 → 3.6.0

data/lib/hecks/bluebook/dsl/bluebook_builder.rb

@@ -1,5 +1,6 @@
 require_relative "word_gate"
 require_relative "bluebook_builder/validation"
+require_relative "bluebook_builder/pending_givens"
 module Hecks
   module Bluebook
     module DSL
@@ -197,16 +198,7 @@ module Hecks
           # The chapter is the top of the construct chain — its constructor stamps every
           # aggregate and read model with itself as owner, so `hecks_fqn` resolves by
           # walking up to it.
-          bluebook = Bluebook::Chapter.new(name: @name, version: @version, vision: @vision,
-                                           aggregates: @aggregates,
-                                           read_models: @read_models,
-                                           policies: @aggregates.flat_map(&:policies) + @policies,
-                                           process_managers: @process_managers,
-                                           classification: @classification,
-                                           formerly_known_as: @formerly_known_as,
-                                           namespace: @namespace,
-                                           attaches_to: @attaches_to || [],
-                                           provides: @provides || [])
+          bluebook = Bluebook::Chapter.new(**chapter_identity, **chapter_constructs)
 
           # A bare chapter-given may still be pending if a file that would resolve it
           # hasn't loaded yet; deferred to `MetaValidator.judge_deferred!`, before
@@ -225,103 +217,6 @@ module Hecks
           MetaValidator.call(bluebook)
         end
 
-        # The other half of a chapter-wide `given` reference — resolves every reference
-        # `AggregateBuilder#pending_chapter_given` deferred, once the chapter's files are loaded.
-        #
-        # Mutates each placeholder `Given` in place, since it's already embedded by Ruby
-        # object reference in the referencing preconditions and commands.
-        #
-        # @return [void]
-        # @raise [Bluebook::DSL::Malformed] if a pending reference's own `description` names no
-        #   precondition any aggregate in this chapter declares, is ambiguous across several
-        #   aggregates with no `declared_by:` to disambiguate, or `declared_by:` names an
-        #   aggregate that does not declare it
-        def resolve_pending_chapter_givens!
-          @chapter_pending_givens.each do |entry|
-            resolved = resolve_pending_chapter_given(entry)
-            entry[:placeholder].description = resolved.description
-            entry[:placeholder].canonical   = resolved.canonical
-            entry[:placeholder].predicate   = resolved.predicate
-            entry[:placeholder].ast         = resolved.ast
-          end
-          @chapter_pending_givens.clear
-        end
-
-        def resolve_pending_chapter_given(entry)
-          description = entry[:description]
-          candidates  = RuleReference.resolve_owner_keyed(@chapter_named_givens, description)
-
-          if entry[:declared_by]
-            candidates[entry[:declared_by]] ||
-              raise(Malformed,
-                    "#{entry[:aggregate]}'s given #{description.inspect} names no precondition " \
-                    "#{entry[:declared_by]} declares in this chapter — #{entry[:declared_by]} " \
-                    "either hasn't declared #{description.inspect}, or declared_by: named the " \
-                    "wrong aggregate")
-          elsif candidates.size == 1
-            candidates.values.first
-          elsif candidates.empty?
-            raise(Malformed,
-                  "#{entry[:aggregate]}'s given #{description.inspect} names no precondition " \
-                  "any aggregate in this chapter ever declares — declare it once with a block " \
-                  "(some aggregate's own given(#{description.inspect}) { ... })")
-          else
-            raise(Malformed,
-                  "#{entry[:aggregate]}'s given #{description.inspect} is ambiguous in this " \
-                  "chapter — #{candidates.keys.join(', ')} each declare a DIFFERENT predicate " \
-                  "under this same description; name which one with declared_by: (e.g. " \
-                  "given(#{description.inspect}, declared_by: #{candidates.keys.first}))")
-          end
-        end
-        private :resolve_pending_chapter_given
-
-        # The entity-scoped analogue of `#resolve_pending_chapter_givens!`, resolved
-        # against `@chapter_entity_named_givens` instead.
-        #
-        # @return [void]
-        # @raise [Bluebook::DSL::Malformed] if a pending reference's own `description` names no
-        #   precondition any piece in this chapter declares, is ambiguous across several pieces
-        #   with no `declared_by:` to disambiguate, or `declared_by:` names a piece that does
-        #   not declare it
-        def resolve_pending_chapter_entity_givens!
-          @chapter_entity_pending_givens.each do |entry|
-            resolved = resolve_pending_chapter_entity_given(entry)
-            entry[:placeholder].description = resolved.description
-            entry[:placeholder].canonical   = resolved.canonical
-            entry[:placeholder].predicate   = resolved.predicate
-            entry[:placeholder].ast         = resolved.ast
-          end
-          @chapter_entity_pending_givens.clear
-        end
-
-        def resolve_pending_chapter_entity_given(entry)
-          description = entry[:description]
-          candidates  = RuleReference.resolve_owner_keyed(@chapter_entity_named_givens, description)
-
-          if entry[:declared_by]
-            candidates[entry[:declared_by]] ||
-              raise(Malformed,
-                    "#{entry[:entity]}'s given #{description.inspect} names no precondition " \
-                    "#{entry[:declared_by]} declares in this chapter — #{entry[:declared_by]} " \
-                    "either hasn't declared #{description.inspect}, or declared_by: named the " \
-                    "wrong piece")
-          elsif candidates.size == 1
-            candidates.values.first
-          elsif candidates.empty?
-            raise(Malformed,
-                  "#{entry[:entity]}'s given #{description.inspect} names no precondition " \
-                  "any piece in this chapter ever declares — declare it once with a block " \
-                  "(some piece's own given(#{description.inspect}) { ... })")
-          else
-            raise(Malformed,
-                  "#{entry[:entity]}'s given #{description.inspect} is ambiguous across the " \
-                  "chapter's own pieces — #{candidates.keys.join(', ')} each declare a DIFFERENT " \
-                  "predicate under this same description; name which one with declared_by: (e.g. " \
-                  "given(#{description.inspect}, declared_by: #{candidates.keys.first.inspect}))")
-          end
-        end
-        private :resolve_pending_chapter_entity_given
-
         # Builds a `Chapter` from a `Hecks.bluebook "Name" do ... end` block, reusing one open
         # builder per chapter name so several files accumulate into it rather than replacing it.
         #
@@ -348,6 +243,22 @@ module Hecks
           ConstShim.with(resolver) { builder.instance_eval(&block) } if block
           builder.build
         end
+
+        private
+
+        # The chapter's own metadata.
+        def chapter_identity
+          { name: @name, version: @version, vision: @vision, classification: @classification,
+            formerly_known_as: @formerly_known_as, namespace: @namespace }
+        end
+
+        # What the chapter declares: its constructs and the contexts and capabilities it names.
+        def chapter_constructs
+          { aggregates: @aggregates, read_models: @read_models,
+            policies: @aggregates.flat_map(&:policies) + @policies,
+            process_managers: @process_managers,
+            attaches_to: @attaches_to || [], provides: @provides || [] }
+        end
       end
     end
   end

data/lib/hecks/bluebook/dsl/command_builder/implicit_attributes.rb

@@ -0,0 +1,132 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class CommandBuilder
+        # Build-time resolution of the attributes a command's mutations imply: `sets :field` alone
+        # imports the owner's attribute of that name, and a mutation source that names nothing
+        # declared is refused.
+        module ImplicitAttributes
+          # For exactly these ops, a bare Symbol source has exactly one legitimate reading —
+          # a declared argument's name — since `append`'s record-state fallback doesn't apply
+          # here; anything else would resolve to nil forever, indistinguishable from an
+          # absent optional argument, unless refused explicitly.
+          CHECKED_SYMBOL_SOURCE_OPS = %i[set increment decrement multiply remove].freeze
+          private_constant :CHECKED_SYMBOL_SOURCE_OPS
+
+          private
+
+          # `sets :field` alone already means the command accepts an argument named `:field` —
+          # when the command hasn't declared its own `:field`, imports the owner's already-built
+          # `Attribute` verbatim instead of requiring a redundant re-declaration (ADR 0025).
+          # Requires the owner's own attributes to already exist by the time `build` runs.
+          def resolve_implicit_attributes!
+            import_implied_attributes!
+            # A second, separate pass: every mutation's own self-referential import must land
+            # before any source is checked against the final `attributes` list, or a legal
+            # declaration order gets refused.
+            refuse_unknown_argument_sources_everywhere!
+          end
+
+          def import_implied_attributes!
+            @mutations.each do |mutation|
+              case mutation.op
+              when :set    then resolve_bare_set!(mutation)
+              when :append then resolve_append_fields!(mutation)
+              end
+              refuse_unknown_state_sources!(mutation)
+            end
+          end
+
+          def refuse_unknown_argument_sources_everywhere!
+            @mutations.each { |mutation| refuse_unknown_argument_sources!(mutation) }
+          end
+
+          # The bare self-referential shape (`source == target`) is `resolve_bare_set!`'s
+          # own territory — skipped here so an undeclared field is refused as a target
+          # problem, not misreported as a source problem.
+          def refuse_unknown_argument_sources!(mutation)
+            return unless undeclared_argument_source?(mutation)
+
+            raise Malformed,
+                  "#{@name}'s sets :#{mutation.target} resolves :#{mutation.source} from its " \
+                  "arguments, but #{@name} declares no #{mutation.source} attribute — an " \
+                  "argument that does not exist resolves to nil, always, never what the " \
+                  "caller actually sent"
+          end
+
+          def undeclared_argument_source?(mutation)
+            CHECKED_SYMBOL_SOURCE_OPS.include?(mutation.op) && mutation.source.is_a?(Symbol) &&
+              !bare_self_reference?(mutation) && attributes.none? { |attr| attr.name == mutation.source }
+          end
+
+          # `state(:name)` snapshots one of the owner's own fields; refused at build, the
+          # same way an unknown `given` reference is.
+          def refuse_unknown_state_sources!(mutation)
+            sources = mutation.source.is_a?(Hash) ? mutation.source.values : [mutation.source]
+            sources.grep(StateRef).each do |ref|
+              next if @owner_attributes.any? { |attr| attr.name == ref.name }
+
+              raise Malformed, "#{@name}'s sets :#{mutation.target} reads state(:#{ref.name}), " \
+                               "which the owner does not declare"
+            end
+          end
+
+          # Only a Symbol naming its own target qualifies — a literal that merely spells the
+          # same word (`sets :moved, to: "moved"`) must not import a phantom argument.
+          def bare_self_reference?(mutation)
+            mutation.source.is_a?(Symbol) && mutation.source.to_s == mutation.target.to_s
+          end
+
+          def resolve_bare_set!(mutation)
+            return unless bare_self_reference?(mutation)
+            return if attributes.any? { |attr| attr.name == mutation.target }
+
+            owner_attr = @owner_attributes.find { |attr| attr.name == mutation.target }
+            attributes << owner_attr if owner_attr
+          end
+
+          # One hop deeper than `resolve_bare_set!`: an `append:` mutation builds a new list
+          # element, so a bare self-referential field inside it resolves against the list's
+          # own element type (`element_type_for`), not `@owner_attributes`.
+          def resolve_append_fields!(mutation)
+            element = element_type_for(mutation.target) if mutation.source.is_a?(Hash)
+            return unless element
+
+            fields = self_referential_fields(mutation.source)
+            present = fields.filter_map { |field| attributes.find { |attr| attr.name == field } }
+            # Already fully declared — nothing to resolve.
+            reinsert_fields(fields, present, element) unless fields.empty? || present.size == fields.size
+          end
+
+          def self_referential_fields(source)
+            source.select { |field, value| value.is_a?(Symbol) && value.to_s == field.to_s }.keys
+          end
+
+          # Position-preserving, not appended at the end — the exported IR is array-order-
+          # sensitive, so resolved fields are reinserted at the position the group's leftmost
+          # still-declared member already occupied.
+          def reinsert_fields(fields, present, element)
+            anchor = present.empty? ? attributes.length : present.map { |attr| attributes.index(attr) }.min
+            attributes.reject! { |attr| present.include?(attr) }
+            attributes.insert(anchor, *resolved_group(fields, present, element))
+          end
+
+          def resolved_group(fields, present, element)
+            fields.filter_map do |field|
+              present.find { |attr| attr.name == field } || element.attributes.find { |attr| attr.name == field }
+            end
+          end
+
+          # The owner's own list attribute names its element type as text; resolved against
+          # `@owner_constructs` (the only two kinds an element can be) by `hecks_name`.
+          def element_type_for(list_field)
+            list_attr = @owner_attributes.find { |attr| attr.name == list_field && attr.list? }
+            return nil unless list_attr
+
+            @owner_constructs.find { |construct| construct.hecks_name.to_s == list_attr.type.to_s }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/command_builder/mutations.rb

@@ -0,0 +1,190 @@
+module Hecks
+  module Bluebook
+    module DSL
+      # The effect words of a command: `sets`, its frozen-era spelling `then_set`,
+      # `delegates_to` and `corrects`, each recording one `Mutation`.
+      class CommandBuilder
+        # Maps each `sets` kwarg to the mutation op it selects. `to:` is the one kwarg
+        # whose own name differs from the op it selects (`:set`); every other kwarg
+        # selects the op of its own name.
+        KWARG_TO_OP = { to: :set, append: :append, increment: :increment, decrement: :decrement,
+                        multiply: :multiply, clamp: :clamp, remove: :remove }.freeze
+
+        # The effects that write a field of the record — `delegate` and
+        # `corrects` name a command and an event, never a field.
+        FIELD_EFFECTS = %i[set append remove increment decrement multiply clamp].freeze
+
+        # Declares one mutation this command applies to `target`, its op selected by
+        # whichever single keyword names a source; omitting all of them means `to: target`.
+        #
+        # @param target [Symbol, String] the field the mutation writes
+        # @param positional_to [Object] the source, written without `to:`
+        # @param ops [Hash] at most one of `to:`, `append:`, `increment:`, `decrement:`,
+        #   `multiply:`, `clamp:` (the `[min, max]` pair to bound the current value to),
+        #   `remove:`; a Symbol `to:` equal to `target` is redundant and refused
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] if `to:` redundantly repeats `target`, or more than
+        #   one op-selecting keyword is given
+        # @raise [ArgumentError] on any other keyword
+        def sets_impl(target, positional_to = UNSET, **ops)
+          refuse_unknown_ops!(ops, KWARG_TO_OP.keys)
+          ops = ops.merge(to: positional_to) unless ops.key?(:to) || positional_to.equal?(UNSET)
+
+          # Only a Symbol can repeat the target's name; a literal value (`to: false`,
+          # a String, ...) never has `.to_sym` to compare in the first place.
+          refuse_repeated_target!(target, ops[:to])
+
+          named = KWARG_TO_OP.keys.select { |kwarg| ops.key?(kwarg) }.to_h { |kwarg| [KWARG_TO_OP[kwarg], ops[kwarg]] }
+
+          # No operation named at all (not even bare `to:`) means `sets :field` alone.
+          record_mutation("sets", target, named.empty? ? { set: target } : named)
+        end
+
+        # Refuses the `then_set` spelling outside shadow-parsing; while shadow-parsing frozen
+        # era text, reads it via `legacy_then_set` instead.
+        #
+        # @param target [Symbol, String] the field this mutation writes
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] outside shadow-parsing, always; under
+        #   shadow-parsing, if `legacy_then_set` names no operation or more than one
+        def then_set_impl(target, positional_to = UNSET, **)
+          return legacy_then_set(target, positional_to, **) if MetaValidator.shadow_parsing?
+
+          raise Malformed, "#{@name}'s then_set is gone — sets is the word now"
+        end
+
+        # Declares a synchronous, atomic delegation of this command's dispatch to one nested
+        # entity command; unlike `trigger`/`saga`, the target's given/ensures are enforced as
+        # real exceptions, so its refusal is the delegating command's own refusal too.
+        #
+        # @param target [String, Symbol] the delegated command, dotted `"Entity.Command"`
+        # @param with [Hash{Symbol => Symbol, Object}] projects this command's own arguments
+        #   onto the target's; a Symbol value names one of this command's own arguments,
+        #   anything else is a literal
+        # @return [Array<Bluebook::Mutation>] every mutation declared so far, this one last
+        # @raise [Bluebook::DSL::Malformed] if `target` is not `"Entity.Command"` shaped
+        def delegates_to_impl(target, with: {})
+          entity_name, _dot, command_name = target.to_s.rpartition(".")
+          if entity_name.empty? || command_name.empty?
+            raise Malformed,
+                  "#{@name}'s delegates_to #{target.inspect} does not name an entity and a command " \
+                  "(\"Entity.Command\") — the same one-hop shape a bare given reference already uses"
+          end
+
+          @mutations << Mutation.new(target: target.to_s, op: :delegate, source: with)
+        end
+
+        # Declares that this command amends a past event, rather than rewriting it. `reverses:
+        # true` auto-derives the corrective `sets` from the original event's own mutations,
+        # and is mutually exclusive with an explicit `sets` on the same command.
+        #
+        # @param event [String, Symbol, Module] the event this command corrects
+        # @param as [Symbol, nil] binds the located instance for a `given`/`ensures` to reference
+        # @param reason [String, nil] why the correction is made, carried as audit data; required
+        # @param reverses [Boolean] auto-derive the corrective `sets` from the original mutations
+        # @return [Array<Bluebook::Mutation>] every mutation declared so far, this one last
+        # @raise [Bluebook::DSL::Malformed] if `reason` is nil or blank
+        def corrects_impl(event, as: nil, reason: nil, reverses: false)
+          if reason.to_s.strip.empty?
+            raise Malformed,
+                  "#{@name}'s corrects #{event.inspect} names no reason — a correction " \
+                  "is carried as data (an audit trail needs to say WHY), the same way a " \
+                  "given's own description must say something"
+          end
+
+          @mutations << Mutation.new(target: event.to_s, op: :corrects,
+                                     source: { as: as&.to_s, reason: reason.to_s, reverses: reverses })
+        end
+
+        private
+
+        # A command's effects are one update set over the pre-dispatch state — a field
+        # written twice would make declaration order silently significant.
+        def refuse_duplicate_targets!
+          return if MetaValidator.shadow_parsing? # frozen era text is history
+
+          seen = {}
+          @mutations.select { |mutation| FIELD_EFFECTS.include?(mutation.op) }.each do |mutation|
+            earlier = seen[mutation.target.to_sym]
+            refuse_double_write!(mutation, earlier) if earlier
+            seen[mutation.target.to_sym] = mutation
+          end
+        end
+
+        def refuse_double_write!(mutation, earlier)
+          raise Malformed,
+                "#{@name} writes #{mutation.target} twice (#{earlier.op} and #{mutation.op}) — a command's " \
+                "effects are one update set over the pre-dispatch state, so each field is written at most once"
+        end
+
+        # Refuses a keyword the word does not take, the way a keyword parameter list would.
+        def refuse_unknown_ops!(ops, allowed)
+          unknown = ops.keys - allowed
+          return if unknown.empty?
+
+          raise ArgumentError, "unknown keyword#{"s" if unknown.size > 1}: #{unknown.map(&:inspect).join(", ")}"
+        end
+
+        def refuse_repeated_target!(target, to)
+          return unless to.is_a?(Symbol) && to == target.to_sym
+
+          raise Malformed,
+                "#{@name}'s sets :#{target}, to: :#{target} repeats the target — " \
+                "sets :#{target} alone already means the same"
+        end
+
+        # Records the one mutation `named` selects, refusing a second op.
+        def record_mutation(word, target, named)
+          if named.size > 1
+            raise Malformed,
+                  "#{@name}'s #{word} :#{target} tries to #{named.keys.join(" and ")} " \
+                  "at once — one mutation, one meaning"
+          end
+
+          op, source = named.first
+          @mutations << Mutation.new(target: target.to_sym, op: op, source: normalize_append_source(op, source))
+        end
+
+        # The ops `then_set` selects between, in the order its refusals name them.
+        LEGACY_OPS = %i[append increment decrement multiply clamp remove].freeze
+        private_constant :LEGACY_OPS
+
+        # Preserves `then_set`'s exact prior reading (`from:` a synonym for `to:`, no
+        # omittable-`to:` shorthand) so frozen era text always re-parses to the same meaning.
+        def legacy_then_set(target, positional_to = UNSET, **ops)
+          refuse_unknown_ops!(ops, [:to, :from, *LEGACY_OPS])
+          ops = ops.merge(to: positional_to) unless ops.key?(:to) || positional_to.equal?(UNSET)
+
+          named = legacy_named_ops(ops)
+          refuse_unnamed_then_set!(target) if named.empty?
+
+          record_mutation("then_set", target, named)
+        end
+
+        # The ops a `then_set` names, `set` first, the rest in `LEGACY_OPS` order.
+        def legacy_named_ops(ops)
+          named = {}
+          named[:set] = (ops.key?(:to) ? ops[:to] : ops[:from]) if ops.key?(:to) || ops.key?(:from)
+          LEGACY_OPS.each { |op| named[op] = ops[op] if ops.key?(op) }
+          named
+        end
+
+        def refuse_unnamed_then_set!(target)
+          raise Malformed,
+                "#{@name}'s then_set :#{target} names no operation — " \
+                "give it to:, append:, increment:, decrement:, multiply:, clamp:, or remove:"
+        end
+
+        # `append:` normally binds a Hash of fields; a bare value (`append: :single_field`)
+        # is the one-field shorthand for `append: { value: :single_field }` — without this,
+        # downstream code that reads `mutation.source` as a Hash unconditionally would crash.
+        def normalize_append_source(oper, source)
+          return source unless oper == :append
+          return source if source.is_a?(::Hash)
+
+          { value: source }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/command_builder/owner.rb

@@ -0,0 +1,22 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class CommandBuilder
+        # What a command is declared on and what it can reach there: the owning aggregate or
+        # entity's name, its givens, attributes and constructs, and the aggregate-wide pool of
+        # entity-level givens that a piece-owned command's bare reference also consults.
+        Owner = Struct.new(:owner, :named_givens, :owner_attributes, :owner_constructs,
+                           :entity_shared_givens, keyword_init: true) do
+          # Builds an `Owner` with every field defaulted to empty, refusing an unknown keyword.
+          #
+          # @param context [Hash] any of the struct's own fields
+          # @return [Owner] the owner, with a fresh empty collection for each field left out
+          def self.from(**context)
+            new(owner: nil, named_givens: {}, owner_attributes: [], owner_constructs: [],
+                entity_shared_givens: {}, **context)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/command_builder/rules.rb

@@ -0,0 +1,57 @@
+module Hecks
+  module Bluebook
+    module DSL
+      # The rule words of a command: `given` preconditions and `ensures` postconditions.
+      class CommandBuilder
+        # Declares a precondition this command requires, or references one the owning aggregate
+        # (or a sibling piece) already declared.
+        #
+        # No block given means "use the one already declared" rather than a fresh rule (ADR 0025).
+        #
+        # @param description [String] the rule's description; also the name the owning
+        #   aggregate's rule is referenced by when no block is given
+        # @yield the predicate body; evaluated for its extracted source, never called directly
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] if given a block whose source cannot be extracted, or
+        #   given no block and the description names no precondition the owner (or a sibling
+        #   piece under the same aggregate) declares
+        def given_impl(description, &predicate)
+          return reference_named_given(description) unless predicate
+
+          @givens << build_rule(Given, description, predicate, owner_name: @name, word: "given",
+                                 extraction_failure: "its source could not be read, so no other runtime could ever evaluate it")
+        end
+
+        # Declares a postcondition, checked against the settled record after the command's own
+        # mutations apply; `old` names the pre-mutation state.
+        #
+        # @param description [String] the rule's description
+        # @yield the predicate body; evaluated for its extracted source, never called directly
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] if the block's source could not be extracted
+        def ensures(description, &predicate)
+          @ensures << build_rule(Given, description, predicate, owner_name: @name, word: "ensures",
+                                  extraction_failure: "a postcondition is carried as text, and this one has none")
+        end
+
+        private
+
+        # Checks the command's own owner first, then — for a piece-owned command only —
+        # a sibling piece's entity-level givens, since two pieces under the same
+        # aggregate can share a precondition declared on just one of them.
+        def reference_named_given(description)
+          verify_resolves_via!("given", "Command", "hash_chain")
+          named = resolve_hash_chain([@named_givens, @entity_shared_givens], description) ||
+                  raise(Malformed,
+                        "#{@name}'s given #{description.inspect} names no precondition " \
+                        "#{@owner} declares, and no sibling piece under the same " \
+                        "aggregate declares it either — declare it once with a block " \
+                        "(#{@owner}'s own given(#{description.inspect}) { ... }), before " \
+                        "the commands that reference it")
+
+          @givens << named
+        end
+      end
+    end
+  end
+end