hecks 3.4.2 → 3.6.0

data/lib/hecks/bluebook/dsl/entity_builder/scope.rb

@@ -0,0 +1,25 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class EntityBuilder
+        # What a piece is handed by whatever declares it, threaded unchanged through every nested
+        # piece so siblings share the same pools: the owner's value objects and givens, the
+        # naming of identity value objects, and the chapter-wide entity-given pools.
+        Scope = Struct.new(:owner_value_objects, :owner_named_givens, :identity_name_prefix,
+                           :identity_value_object_installer, :aggregate_name,
+                           :chapter_entity_named_givens, :chapter_entity_pending_givens,
+                           keyword_init: true) do
+          # Builds a `Scope` with every field defaulted to empty, refusing an unknown keyword.
+          #
+          # @param context [Hash] any of the struct's own fields
+          # @return [Scope] the scope, with a fresh empty collection for each field left out
+          def self.from(**context)
+            new(owner_value_objects: [], owner_named_givens: {}, identity_name_prefix: nil,
+                identity_value_object_installer: nil, aggregate_name: nil,
+                chapter_entity_named_givens: {}, chapter_entity_pending_givens: [], **context)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/entity_builder/sealing.rb

@@ -0,0 +1,94 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class EntityBuilder
+        # The build-time work of a piece: building what was queued, installing synthesized closed
+        # sets, and refusing commands that disagree with the piece's lifecycle.
+        module Sealing
+          private
+
+          # A piece's own `one_of` synthesizes a closed-set value object, installed onto the
+          # owning aggregate so the runtime has it to admit against — not just on the attribute.
+          # Two sibling pieces synthesizing the same name install it once; a name collision with
+          # a different member list is refused rather than silently kept.
+          def install_closed_sets!
+            return unless @identity_value_object_installer
+
+            closed_sets.each { |value_object| install_closed_set(value_object) }
+          end
+
+          def install_closed_set(value_object)
+            existing = @owner_value_objects.find { |candidate| candidate.hecks_name == value_object.hecks_name }
+            return @identity_value_object_installer.call(value_object) unless existing
+            return if existing.to_h == value_object.to_h
+
+            raise Malformed,
+                  "#{@name}'s one_of synthesizes #{value_object.hecks_name.inspect}, but the aggregate already " \
+                  "holds a different #{value_object.hecks_name.inspect} — name the closed set's field differently"
+          end
+
+          # Entities are built first, fully, so a nested command's own `append:` can read a
+          # sibling piece's `.attributes`; then commands, then queries.
+          def drain_pending!
+            @entities = @pending_entities.map { |name, block| build_nested_entity(name, block) }
+            @commands = @pending_commands.map { |name, from, block| build_command(name, from, block) }
+            @queries  = @pending_queries.map do |name, block|
+              QueryBuilder.build(name, owner_attributes: attributes, &block)
+            end
+          end
+
+          def build_nested_entity(name, block)
+            EntityBuilder.build(name, owner_value_objects:             @owner_value_objects,
+                                      owner_named_givens:              @owner_named_givens,
+                                      identity_name_prefix:            "#{@identity_name_prefix}#{Naming.demodulise(name)}",
+                                      identity_value_object_installer: @identity_value_object_installer,
+                                      aggregate_name:                  @aggregate_name,
+                                      chapter_entity_named_givens:     @chapter_entity_named_givens,
+                                      chapter_entity_pending_givens:   @chapter_entity_pending_givens,
+                                &block)
+          end
+
+          def build_command(name, from, block)
+            CommandBuilder.build(name, owner: @name, from: from, named_givens: @named_givens,
+                                       owner_attributes: attributes,
+                                       owner_constructs: @owner_value_objects + @entities,
+                                       entity_shared_givens: @owner_named_givens, &block)
+          end
+
+          # Refuses a command that sets the lifecycle field directly, or guards `from:` with no
+          # lifecycle declared — a lifecycle field only moves by transition.
+          def seal_lifecycle_guards
+            @commands.each do |command|
+              refuse_lifecycle_field_write!(command) if @lifecycle && !MetaValidator.shadow_parsing?
+              refuse_guard_without_lifecycle!(command)
+            end
+          end
+
+          def refuse_lifecycle_field_write!(command)
+            mutation = command.mutations.find { |candidate| writes_lifecycle_field?(candidate) }
+            return unless mutation
+
+            raise Malformed,
+                  "#{@name}.#{command.hecks_name} sets #{mutation.target}, #{@name}'s lifecycle field — " \
+                  "a lifecycle field moves only by transition; declare one instead of setting it"
+          end
+
+          # `delegate`/`corrects` are exempt — the frozen-era-text case, not a live mutation.
+          def writes_lifecycle_field?(mutation)
+            ![:delegate, :corrects].include?(mutation.op) && mutation.target.to_sym == @lifecycle.field.to_sym
+          end
+
+          def refuse_guard_without_lifecycle!(command)
+            return unless command.from
+            return if @lifecycle
+
+            raise Malformed,
+                  "#{@name}.#{command.hecks_name} guards from: #{Array(command.from).inspect}, but " \
+                  "#{@name} declares no lifecycle — from: checks a lifecycle field, and there is " \
+                  "none here to check"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,4 +1,7 @@
 require_relative "word_gate"
+require_relative "entity_builder/scope"
+require_relative "entity_builder/rules"
+require_relative "entity_builder/sealing"
 module Hecks
   module Bluebook
     module DSL
@@ -11,29 +14,23 @@ module Hecks
         include IdentityDeclaration
         include RuleReference
         include WordGate
+        include Rules
+        include Sealing
 
         # Builds a piece nested under an aggregate (or another piece), threading the owner's
         # value-object and given pools through unchanged so nested pieces share the same state.
-        def initialize(name, owner_value_objects: [], owner_named_givens: {},
-                       identity_name_prefix: nil, identity_value_object_installer: nil,
-                       aggregate_name: nil, chapter_entity_named_givens: {}, chapter_entity_pending_givens: [])
+        #
+        # @param name [String] the piece's name
+        # @param context [Hash] what the owner hands down (see `Scope`)
+        # @raise [ArgumentError] on an unknown keyword
+        def initialize(name, **context)
           @name         = name
           @commands     = []
           @queries      = []
           @entities     = []
           @named_givens = {}
           @invariants   = []
-          @owner_value_objects = owner_value_objects
-          @identity_name_prefix = identity_name_prefix || Naming.demodulise(name)
-          @identity_value_object_installer = identity_value_object_installer
-          # Threaded unchanged through every nested piece so a sibling's bare given
-          # reference can read the same aggregate-wide pool `given_impl` writes to.
-          @owner_named_givens = owner_named_givens
-          # One level wider than `@owner_named_givens`: the chapter-wide, entity-scoped
-          # pool, keyed "Aggregate.Entity" so `#given_impl` can resolve across aggregates.
-          @aggregate_name = aggregate_name || Naming.demodulise(name)
-          @chapter_entity_named_givens   = chapter_entity_named_givens
-          @chapter_entity_pending_givens = chapter_entity_pending_givens
+          adopt_scope(name, Scope.from(**context))
           # Deferred: built once every sibling in this block has been seen, so a nested
           # command can resolve a sibling entity/command/query declared later in the block.
           @pending_entities = []
@@ -104,35 +101,6 @@ module Hecks
           @lifecycle = LifecycleBuilder.build(field, default: default, &)
         end
 
-        # Declares a rule this piece's own commands must satisfy, or references one a sibling
-        # piece anywhere in the chapter already declared.
-        #
-        # Order doesn't matter: `command` only queues a descriptor here and builds for real at
-        # `#drain_pending!` time, after every `given` in this block has already run.
-        def given_impl(description, declared_by: nil, &predicate)
-          return reference_named_chapter_entity_given(description, declared_by: declared_by) unless predicate
-
-          named = 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")
-          @named_givens[description] = named
-          # First-declared-wins (`||=`): a second piece under the same aggregate declaring
-          # the exact same description independently stays local, never silently overwritten.
-          @owner_named_givens[description] ||= named
-          # Chapter-wide analogue of the line above, keyed by "Aggregate.Entity" rather than
-          # description alone, so two different pieces sharing a description stay distinct
-          # candidates a later bare reference chooses between via `declared_by:`.
-          @chapter_entity_named_givens[description] ||= {}
-          @chapter_entity_named_givens[description]["#{@aggregate_name}.#{@name}"] ||= named
-        end
-
-        # Declares a rule every instance of this piece must satisfy — checked per instance,
-        # not once against the aggregate's own flat state. No reference-by-name form (unlike
-        # `given`); extend that pattern here if cross-piece sharing is ever needed.
-        def invariant_impl(description, &predicate)
-          @invariants << build_rule(Invariant, description, predicate, owner_name: @name, word: "invariant",
-                                     extraction_failure: "it would be a rule the IR cannot carry")
-        end
-
         # Assembles the declared attributes, relationships, nested constructs and rules into an
         # `Entity`.
         def build
@@ -140,143 +108,41 @@ module Hecks
           resolve_pending_identity!
           seal_lifecycle_guards
           install_closed_sets!
-          Entity.declare(
-            name:          @name,
-            description:   @description,
-            identified_by: @identity_paths,
-            attributes:    attributes,
-            commands:      @commands,
-            queries:       @queries,
-            entities:      @entities,
-            preconditions: @named_givens.values,
-            invariants:    @invariants,
-            lifecycle:     @lifecycle
-          )
+          Entity.declare(**entity_fields)
         end
 
         # Evaluates an `entity` block against a fresh builder and returns what it built.
-        def self.build(name, owner_value_objects: [], owner_named_givens: {},
-                       identity_name_prefix: nil, identity_value_object_installer: nil,
-                       aggregate_name: nil, chapter_entity_named_givens: {}, chapter_entity_pending_givens: [], &block)
-          builder = new(name, owner_value_objects: owner_value_objects, owner_named_givens: owner_named_givens,
-                              identity_name_prefix: identity_name_prefix,
-                              identity_value_object_installer: identity_value_object_installer,
-                              aggregate_name: aggregate_name,
-                              chapter_entity_named_givens: chapter_entity_named_givens,
-                              chapter_entity_pending_givens: chapter_entity_pending_givens)
+        #
+        # @param name [String] the piece's name
+        # @param context [Hash] what the owner hands down (see `Scope`)
+        # @yield the entity body, evaluated with the builder as `self`; may be omitted
+        # @return [Bluebook::Entity] the built entity
+        def self.build(name, **context, &block)
+          builder = new(name, **context)
           builder.instance_eval(&block) if block
           builder.build
         end
 
         private
 
-        # Resolves a bare `given` reference against the chapter-wide, entity-scoped pool.
-        # Also writes through to `@owner_named_givens`, not just `@named_givens` — otherwise a
-        # sibling piece's own same-aggregate bare reference would never see this resolution.
-        def reference_named_chapter_entity_given(description, declared_by:)
-          verify_resolves_via!("given", "Entity", "owner_keyed")
-          candidates = resolve_owner_keyed(@chapter_entity_named_givens, description)
-
-          named =
-            if declared_by
-              candidates[declared_by] || pending_chapter_entity_given(description, declared_by: declared_by)
-            elsif candidates.size == 1
-              candidates.values.first
-            elsif candidates.empty?
-              pending_chapter_entity_given(description, declared_by: nil)
-            else
-              raise(Malformed,
-                    "#{@aggregate_name}::#{@name}'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
-
-          @named_givens[description] = named
-          @owner_named_givens[description] ||= named
-        end
-
-        # A chapter may be split across files, so an unresolved bare reference defers rather
-        # than raising immediately; `BluebookBuilder#resolve_pending_chapter_entity_givens!`
-        # fills in the placeholder once every file in the chapter has loaded.
-        def pending_chapter_entity_given(description, declared_by:)
-          placeholder = Given.new(description: description, canonical: nil, predicate: nil)
-          @chapter_entity_pending_givens << { entity: "#{@aggregate_name}.#{@name}", description: description,
-                                               declared_by: declared_by, placeholder: placeholder }
-          placeholder
-        end
-
-        # A piece's own `one_of` synthesizes a closed-set value object, installed onto the
-        # owning aggregate so the runtime has it to admit against — not just on the attribute.
-        # Two sibling pieces synthesizing the same name install it once; a name collision with
-        # a different member list is refused rather than silently kept.
-        def install_closed_sets!
-          return unless @identity_value_object_installer
-
-          closed_sets.each do |value_object|
-            existing = @owner_value_objects.find { |candidate| candidate.hecks_name == value_object.hecks_name }
-            if existing
-              next if existing.to_h == value_object.to_h
-
-              raise Malformed,
-                    "#{@name}'s one_of synthesizes #{value_object.hecks_name.inspect}, but the aggregate already " \
-                    "holds a different #{value_object.hecks_name.inspect} — name the closed set's field differently"
-            end
-
-            @identity_value_object_installer.call(value_object)
-          end
-        end
-
-        # Entities are built first, fully, so a nested command's own `append:` can read a
-        # sibling piece's `.attributes`; then commands, then queries.
-        def drain_pending!
-          @entities = @pending_entities.map do |name, block|
-            EntityBuilder.build(name, owner_value_objects:             @owner_value_objects,
-                                      owner_named_givens:              @owner_named_givens,
-                                      identity_name_prefix:            "#{@identity_name_prefix}#{Naming.demodulise(name)}",
-                                      identity_value_object_installer: @identity_value_object_installer,
-                                      aggregate_name:                  @aggregate_name,
-                                      chapter_entity_named_givens:     @chapter_entity_named_givens,
-                                      chapter_entity_pending_givens:   @chapter_entity_pending_givens,
-                                &block)
-          end
-
-          @commands = @pending_commands.map do |name, from, block|
-            CommandBuilder.build(name, owner: @name, from: from, named_givens: @named_givens,
-                                        owner_attributes: attributes,
-                                        owner_constructs: @owner_value_objects + @entities,
-                                        entity_shared_givens: @owner_named_givens, &block)
-          end
-
-          @queries = @pending_queries.map do |name, block|
-            QueryBuilder.build(name, owner_attributes: attributes, &block)
-          end
+        def adopt_scope(name, scope)
+          @owner_value_objects = scope.owner_value_objects
+          @identity_name_prefix = scope.identity_name_prefix || Naming.demodulise(name)
+          @identity_value_object_installer = scope.identity_value_object_installer
+          # Threaded unchanged through every nested piece so a sibling's bare given
+          # reference can read the same aggregate-wide pool `given_impl` writes to.
+          @owner_named_givens = scope.owner_named_givens
+          # One level wider than `@owner_named_givens`: the chapter-wide, entity-scoped
+          # pool, keyed "Aggregate.Entity" so `#given_impl` can resolve across aggregates.
+          @aggregate_name = scope.aggregate_name || Naming.demodulise(name)
+          @chapter_entity_named_givens   = scope.chapter_entity_named_givens
+          @chapter_entity_pending_givens = scope.chapter_entity_pending_givens
         end
 
-        # Refuses a command that sets the lifecycle field directly, or guards `from:` with no
-        # lifecycle declared — a lifecycle field only moves by transition.
-        def seal_lifecycle_guards
-          @commands.each do |command|
-            if @lifecycle && !MetaValidator.shadow_parsing?
-              # `delegate`/`corrects` are exempt — the frozen-era-text case, not a live mutation.
-              command.mutations.each do |mutation|
-                next if [:delegate, :corrects].include?(mutation.op)
-                next unless mutation.target.to_sym == @lifecycle.field.to_sym
-
-                raise Malformed,
-                      "#{@name}.#{command.hecks_name} sets #{mutation.target}, #{@name}'s lifecycle field — " \
-                      "a lifecycle field moves only by transition; declare one instead of setting it"
-              end
-            end
-            next unless command.from
-            next if @lifecycle
-
-            raise Malformed,
-                  "#{@name}.#{command.hecks_name} guards from: #{Array(command.from).inspect}, but " \
-                  "#{@name} declares no lifecycle — from: checks a lifecycle field, and there is " \
-                  "none here to check"
-          end
+        def entity_fields
+          { name: @name, description: @description, identified_by: @identity_paths,
+            attributes: attributes, commands: @commands, queries: @queries, entities: @entities,
+            preconditions: @named_givens.values, invariants: @invariants, lifecycle: @lifecycle }
         end
 
         # A piece mints no value objects of its own, so `identified_by` resolves a bare field's

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

@@ -31,10 +31,17 @@ module Hecks
 
         # Executes a table-admitted word via the shape `shape_for` found for it, or returns
         # NOT_HANDLED so the caller can fall back to its own "not yet implemented" refusal.
+        # The seven-argument form is the entry point `WordGate` and the dispatch specs call.
+        # rubocop:disable-next Metrics/ParameterLists
         def try(builder, context, word, args, kwargs, block, rows)
           shape = shape_for(context, word, rows)
           return NOT_HANDLED unless shape
 
+          run_shape(shape, builder, args, kwargs, block)
+        end
+
+        # Runs the dispatcher the shape's kind names.
+        def run_shape(shape, builder, args, kwargs, block)
           case shape[:kind]
           when :calls_through then try_calls_through(builder, shape[:calls], args, kwargs, block)
           when :opens_block   then try_opens_block(builder, shape[:keyword], args, kwargs, block)
@@ -51,9 +58,6 @@ module Hecks
         # Classifies a (context, word) pair into one of the four table-executable shapes, or
         # nil when it falls outside this module's verified scope.
         #
-        # Early-return chain: each check depends on locals from the ones before it, read once
-        # top-to-bottom; splitting per shape would just re-thread the same locals across methods.
-        # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         def shape_for(context, word, rows)
           keyword = rows[:keywords].find { |k| k[:context] == context && k[:word] == word && k[:status] != "retired" }
           return nil unless keyword
@@ -63,19 +67,32 @@ module Hecks
 
           return { kind: :opens_block, keyword: keyword } if SAFE_OPENS_BLOCK.key?([context, word])
 
+          fill_shape(keyword, rows[:arguments])
+        end
+
+        # The `fills:`-driven shapes: a zero-argument word, or one plain positional argument.
+        def fill_shape(keyword, argument_rows)
           fills = keyword[:fills].to_s
           return nil if fills.empty?
 
-          arguments = rows[:arguments].select { |a| a[:context] == context && a[:keyword] == word && a[:status] != "retired" }
+          arguments = word_arguments(keyword, argument_rows)
           return { kind: :zero_arg, keyword: keyword } if arguments.empty?
+          return nil unless arguments.size == 1 && plain_positional?(arguments.first)
 
-          return nil unless arguments.size == 1
+          { kind: :single_fill, fills: fills, argument: arguments.first }
+        end
+
+        def word_arguments(keyword, argument_rows)
+          argument_rows.select do |a|
+            a[:context] == keyword[:context] && a[:keyword] == keyword[:word] && a[:status] != "retired"
+          end
+        end
 
-          arg = arguments.first
-          return nil if arg[:variadic] == "true" || arg[:at] != "1" || !arg[:named].to_s.empty?
-          return nil unless COERCE_BY_KIND.key?(arg[:kind])
+        # One positional argument at place 1, unnamed, of a kind `COERCE_BY_KIND` can coerce.
+        def plain_positional?(arg)
+          return false if arg[:variadic] == "true" || arg[:at] != "1" || !arg[:named].to_s.empty?
 
-          { kind: :single_fill, fills: fills, argument: arg }
+          COERCE_BY_KIND.key?(arg[:kind])
         end
 
         # Forwards a word's whole call, unchanged, to the builder method its row's `calls:`
@@ -105,37 +122,49 @@ module Hecks
         def try_zero_arg(builder, keyword, args)
           raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0)" unless args.empty?
 
-          rows = MetaValidator::SyntaxBoot.call[:keywords]
-          siblings = rows.count do |k|
-            k[:context] == keyword[:context] && k[:fills] == keyword[:fills] && k[:status] != "retired"
-          end
-          value = siblings > 1 ? keyword[:word].to_sym : true
+          value = fill_siblings(keyword) > 1 ? keyword[:word].to_sym : true
 
           builder.instance_variable_set(:"@#{keyword[:fills]}", value)
         end
 
+        # How many live words in the keyword's context fill the same instance variable.
+        def fill_siblings(keyword)
+          MetaValidator::SyntaxBoot.call[:keywords].count do |k|
+            k[:context] == keyword[:context] && k[:fills] == keyword[:fills] && k[:status] != "retired"
+          end
+        end
+
         # Coerces a word's one positional argument and stores it, appending when the target
         # ivar already holds an Array and assigning otherwise.
         def try_single_fill(builder, fills, arg, args, kwargs)
           return NOT_HANDLED unless kwargs.empty?
 
-          coerce = COERCE_BY_KIND.fetch(arg[:kind])
-
-          raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 1)" unless args.size == 1
+          store_fill(builder, :"@#{fills}", fill_value(arg, args))
+        end
 
-          value = arg[:coerce] == "false" ? args.first : args.first.public_send(coerce)
+        # The word's one argument, coerced as its row says and refused when blank.
+        def fill_value(arg, args)
+          value = coerced_argument(arg, args)
 
           message = arg[:blank_message].to_s
           raise Malformed, message if !message.empty? && value.to_s.empty?
 
-          ivar = :"@#{fills}"
+          value
+        end
+
+        def coerced_argument(arg, args)
+          coerce = COERCE_BY_KIND.fetch(arg[:kind])
+
+          raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 1)" unless args.size == 1
+
+          arg[:coerce] == "false" ? args.first : args.first.public_send(coerce)
+        end
+
+        def store_fill(builder, ivar, value)
           current = builder.instance_variable_get(ivar)
+          return current << value if current.is_a?(Array)
 
-          if current.is_a?(Array)
-            current << value
-          else
-            builder.instance_variable_set(ivar, value)
-          end
+          builder.instance_variable_set(ivar, value)
         end
       end
     end

data/lib/hecks/bluebook/dsl/hecksagon_builder/chapter_scope.rb

@@ -0,0 +1,133 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class HecksagonBuilder
+        # The per-thread state of the hecksagon build in progress, and the shadowing of `Hecks`'s
+        # real modules that lets the Hecks chapter spell its aggregates `Hecks::Operation`.
+        # Extended onto `HecksagonBuilder`.
+        module ChapterScope
+          # The bind collector of the build running on this thread; thread-local, so a build
+          # on another thread never sees it.
+          #
+          # @return [Array, nil] the binds the running build collects into
+          def collector = Thread.current.thread_variable_get(:hecks_hecksagon_collector)
+
+          # @param value [Array, nil] the binds the running build collects into
+          def collector=(value)
+            Thread.current.thread_variable_set(:hecks_hecksagon_collector, value)
+          end
+
+          # @return [String, nil] the name of the chapter whose hecksagon is being built
+          def building = Thread.current.thread_variable_get(:hecks_hecksagon_building)
+
+          # @param value [String, nil] the name of the chapter whose hecksagon is being built
+          def building=(value)
+            Thread.current.thread_variable_set(:hecks_hecksagon_building, value)
+          end
+
+          # @return [Hash, nil] the modules this thread's build has taken off `Hecks`
+          def hidden_modules = Thread.current.thread_variable_get(:hecks_hecksagon_hidden)
+
+          # @param value [Hash, nil] the modules this thread's build has taken off `Hecks`
+          def hidden_modules=(value)
+            Thread.current.thread_variable_set(:hecks_hecksagon_hidden, value)
+          end
+
+          # Takes off `Hecks` each real module a chapter aggregate shares its name with, so the
+          # name reaches `ChapterConstants#const_missing`. Only the chapter named Hecks has this
+          # collision; a nested build of it leaves the outer build's shadows in place.
+          #
+          # @param domain [String, Symbol] the chapter whose hecksagon is being built
+          # @return [Hash{Symbol => Object}] what was taken off, by name: the module, or the
+          #   autoload path when the constant had not loaded yet
+          def shadowed(domain)
+            return {} unless domain.to_s == "Hecks"
+
+            chapter_aggregate_names.select { |name| Hecks.const_defined?(name, false) }.to_h do |name|
+              pending = Hecks.autoload?(name)
+              held    = pending ? [:autoload, pending] : [:module, Hecks.const_get(name, false)]
+              Hecks.send(:remove_const, name)
+              [name, held]
+            end
+          end
+
+          # Runs the block with every module the running build shadowed back on `Hecks`, and a
+          # missing `Hecks::X` an ordinary `NameError`, then shadows them again. A chapter loaded
+          # from inside the hecksagon block is ordinary code, not the hecksagon's own vocabulary.
+          # A no-op when nothing is shadowed.
+          #
+          # @yield the code that must see `Hecks`'s real modules
+          # @return [Object] the block's result
+          def with_real_modules
+            hidden = hidden_modules
+            return yield if hidden.nil? || hidden.empty?
+
+            name = building
+            restore_shadowed(hidden)
+            self.building = nil
+            begin
+              yield
+            ensure
+              reshadow(hidden, name)
+            end
+          end
+
+          # Puts back what `shadowed` took off.
+          #
+          # @param hidden [Hash{Symbol => Array}] `shadowed`'s answer
+          # @return [void]
+          def restore_shadowed(hidden)
+            hidden.each do |name, (kind, held)|
+              Hecks.send(:remove_const, name) if Hecks.const_defined?(name, false)
+              kind == :autoload ? Hecks.autoload(name, held) : Hecks.const_set(name, held)
+            end
+          end
+
+          # Runs the block with this thread's collector, chapter name and shadowed modules set for
+          # building `domain`'s hecksagon, restoring the outer build's state afterwards.
+          #
+          # @param domain [String, Symbol] the chapter whose hecksagon is being built
+          # @param binds [Array] the binds the build collects into
+          # @yield the build
+          # @return [Object] the block's result
+          def scoped_to(domain, binds)
+            saved = enter_scope(domain, binds)
+            begin
+              yield
+            ensure
+              leave_scope(saved)
+            end
+          end
+
+          private
+
+          def chapter_aggregate_names
+            chapter = Hecks.current_registry&.bluebook("Hecks")
+            chapter ? chapter.aggregates.map { |aggregate| aggregate.hecks_name.to_sym } : []
+          end
+
+          def reshadow(hidden, name)
+            self.building = name
+            hidden.replace(shadowed(name))
+          end
+
+          def enter_scope(domain, binds)
+            saved = { collector: collector, building: building, hidden_modules: hidden_modules }
+            self.collector = binds
+            self.building  = domain.to_s
+            hidden = saved[:building] == "Hecks" ? {} : shadowed(domain)
+            self.hidden_modules = hidden.empty? ? saved[:hidden_modules] : hidden
+            saved.merge(hidden: hidden)
+          end
+
+          def leave_scope(saved)
+            restore_shadowed(saved[:hidden])
+            self.hidden_modules = saved[:hidden_modules]
+            self.collector      = saved[:collector]
+            self.building       = saved[:building]
+          end
+        end
+      end
+    end
+  end
+end