hecks 2.9.0 → 3.0.0

data/lib/hecks/bench/workload.rb

@@ -0,0 +1,89 @@
+require "json"
+
+module Hecks
+  module Bench
+    # A fixed command sequence for one example domain, identical for every runtime.
+    # Cycles name their records by `n`, so no command is refused and none times a rejection path.
+    class Workload
+      Step = Struct.new(:verb, :args) do
+        def to_json_line
+          JSON.generate("verb" => verb, "args" => args)
+        end
+
+        def ruby_args
+          args.transform_keys(&:to_sym)
+        end
+      end
+
+      # The example domain's directory name, also its Cargo feature.
+      attr_reader :name
+
+      # The absolute path of the example domain directory.
+      attr_reader :domain_path
+
+      # The commands run once, untimed, before any cycle.
+      attr_reader :setup
+
+      def initialize(name:, setup:, cycle:)
+        @name = name
+        @domain_path = File.expand_path("../../../examples/#{name}", __dir__)
+        @setup = setup
+        @cycle = cycle
+      end
+
+      def cycle(number) = @cycle.call(number)
+
+      def commands_per_cycle = cycle(0).size
+
+      def self.all
+        { "pizzas" => pizzas, "banking" => banking }
+      end
+
+      def self.fetch(name)
+        all.fetch(name) do
+          raise ArgumentError, "unknown domain #{name.inspect} — one of #{all.keys.join(', ')}"
+        end
+      end
+
+      def self.pizzas
+        new(name: "pizzas", setup: [], cycle: lambda { |n|
+          pizza = "pizza-#{n}"
+          [
+            Step.new("Pizzas::Order.CreatePizza",
+                     { "name"  => { "value" => pizza },
+                       "pizza" => { "price_cents" => { "cents" => 1200 }, "size" => { "value" => "large" } } }),
+            Step.new("Pizzas::Order.AddTopping",
+                     { "name" => pizza, "topping" => { "value" => "Basil" }, "amount" => { "value" => 3 } }),
+            Step.new("Pizzas::Order.AddTopping",
+                     { "name" => pizza, "topping" => { "value" => "Olive" }, "amount" => { "value" => 2 } }),
+            Step.new("Pizzas::Order.Purchase",
+                     { "name" => pizza, "customer_name" => { "value" => "Chris" },
+                       "amount" => { "cents" => 1200 } })
+          ]
+        })
+      end
+
+      def self.banking
+        register = Step.new("Banking::Customer.Register",
+                            { "reference" => { "value" => "CUST-0001" },
+                              "name"      => { "given" => "Ada", "family" => "Lovelace" },
+                              "email"     => { "address" => "ada@example.com" } })
+        new(name: "banking", setup: [register], cycle: lambda { |n|
+          number = { "value" => "acct-#{n}" }
+          money = ->(cents) { { "cents" => cents, "currency" => "USD" } }
+          [
+            Step.new("Banking::Account.Open",
+                     { "number" => number, "kind" => { "name" => "current" },
+                       "daily_limit" => { "cents" => 50_000 }, "customer" => "CUST-0001" }),
+            Step.new("Banking::Account.Credit",
+                     { "number" => number, "amount" => money.call(10_000), "narrative" => { "text" => "Deposit" } }),
+            Step.new("Banking::Account.Credit",
+                     { "number" => number, "amount" => money.call(5000), "narrative" => { "text" => "Deposit" } }),
+            Step.new("Banking::Account.Debit",
+                     { "number" => number, "amount" => money.call(2500), "narrative" => { "text" => "Groceries" } })
+          ]
+        })
+      end
+    end
+  end
+end

data/lib/hecks/bench.rb

@@ -0,0 +1,17 @@
+module Hecks
+  # Throughput and latency harness behind `hecks bench`; see `docs/benchmarks.md`.
+  # Not required by `lib/hecks.rb`: a booted domain never needs it.
+  module Bench
+  end
+end
+
+require_relative "bench/stats"
+require_relative "bench/workload"
+require_relative "bench/environment"
+require_relative "bench/postgres_probe"
+require_relative "bench/run"
+require_relative "bench/ruby_runner"
+require_relative "bench/rust_runner"
+require_relative "bench/suite"
+require_relative "bench/report"
+require_relative "bench/cli"

data/lib/hecks/bluebook/assembly/contracts.rb

@@ -17,6 +17,7 @@ module Hecks
             vision:            [:vision,         :plain],
             classification:    [:classification, :plain],
             formerly_known_as: [:formerly_known_as, :plain],
+            namespace:         [:namespace, :plain],
             attaches_to:       [:attaches_to, :plain],
             provides:          [:provides, :plain]
           },
@@ -97,6 +98,7 @@ module Hecks
             wheres:         [:wheres,          [:each, :where_clause]],
             order_by:       [:order_by,        :order_by],
             limit:          [:limit,           :limit],
+            returns:        [:returns,         :plain],
             # Held by the language as an open map, so every one of these reads the
             # same way and a ninth option needs no new field on either side.
             offset:         [:offset,          [:option, :offset]],

data/lib/hecks/bluebook/attribute.rb

@@ -49,7 +49,7 @@ module Hecks
 
       # A bare constant in a bluebook is a name, even when Ruby has heard of it.
       #
-      # `Facade::Surface` installs aggregate names as top-level constants, which would win
+      # `Doors::RubyDoor` installs aggregate names as top-level constants, which would win
       # over the `const_missing` resolver and silently rebind the attribute. Demodulising
       # spells `:Target` and `QualityControl::Target` the same.
       def spell(type)

data/lib/hecks/bluebook/behaviour/aggregate.rb

@@ -64,13 +64,42 @@ module Hecks
         #   none is attached under that name
         def port(named)         = @ports_by_name[named.to_s]
 
+        # Finds every port whose adapter answers a query.
+        #
+        # @param named [String, Symbol] the query's declared name
+        # @return [Array<Bluebook::DomainPort>] the ports the hecksagon binds to the query; empty
+        #   when the query is answered from the aggregate's records
+        def query_bindings(named) = @ports.select { |port| port.answer_for(named) }
+
+        # Finds the port whose adapter answers a query.
+        #
+        # @param named [String, Symbol] the query's declared name
+        # @return [Bluebook::DomainPort, nil] the first port bound to the query, or `nil` if
+        #   the hecksagon binds none
+        def query_binding(named) = query_bindings(named).first
+
         # Attaches a port declared in the hecksagon, after the aggregate exists.
         # `HecksagonBuilder` stamps each operation's reference attributes with
-        # `declared_in = self` before calling it.
+        # `declared_in = self` before calling it. A port declared again under a name the
+        # aggregate already holds merges into it, so an overlay repeating a base
+        # declaration adds nothing twice; two different names stay two ports.
         #
         # @param port [Bluebook::DomainPort] the aggregate-scoped port to attach
         # @return [void]
         def add_port(port)
+          held = @ports_by_name[port.name]
+          return attach_port(port) unless held
+
+          operations = held.operations + port.operations.reject { |op| held.operation(op.hecks_name) }
+          answers    = held.answered_queries + port.answered_queries.reject { |a| held.answer_for(a.name) }
+          merged     = Bluebook::DomainPort.new(name: held.name, operations: operations, answered_queries: answers)
+          @ports[@ports.index(held)] = merged
+          @ports_by_name[merged.name] = merged
+        end
+
+        # @param port [Bluebook::DomainPort] a port under a name the aggregate does not hold
+        # @return [void]
+        def attach_port(port)
           @ports << port
           @ports_by_name[port.name] = port
         end

data/lib/hecks/bluebook/behaviour/domain_port.rb

@@ -47,6 +47,13 @@ module Hecks
         # @return [Bluebook::PortOperation, nil] the operation, or `nil` if none is
         #   declared by that name
         def operation(named) = @operations.find { |op| op.hecks_name == named.to_s }
+
+        # Finds the binding this port gives a query, if it answers that query.
+        #
+        # @param named [String, Symbol] the query's declared name
+        # @return [Bluebook::QueryAnswer, nil] the binding, or `nil` if this port does not
+        #   answer that query
+        def answer_for(named) = @answered_queries.find { |answer| answer.name == named.to_s }
       end
     end
   end

data/lib/hecks/bluebook/chapter.rb

@@ -24,6 +24,9 @@ module Hecks
         # differing only by their old name can't hash identically at the
         # meta-validator's cache key (`SHA256(JSON(bluebook.to_h))`).
         formerly_known_as: :formerly_known_as,
+        # The Ruby module the chapter's constants install under, when it is not the chapter's
+        # own name (the Hecks domain nests under `Hecks::Domain`); nil for every other chapter.
+        namespace:         :namespace,
         aggregates:        many(:aggregates),
         read_models:       many(:read_models),
         policies:          many(:policies),
@@ -53,7 +56,7 @@ module Hecks
       end
 
       attr_reader :name, :version, :vision, :aggregates, :policies, :process_managers,
-                  :classification, :read_models, :ports, :formerly_known_as, :attaches_to, :provides
+                  :classification, :read_models, :ports, :formerly_known_as, :namespace, :attaches_to, :provides
 
       # @param policies [Array<Bluebook::Policy>] every reaction declared across the
       #   chapter's own aggregates, hoisted here
@@ -61,7 +64,7 @@ module Hecks
       #   its project's own domain model, or `nil` if undeclared
       def initialize(name:, version: nil, vision: nil, aggregates: [], policies: [],
                      process_managers: [], classification: nil, read_models: [], formerly_known_as: nil,
-                     attaches_to: [], provides: [])
+                     namespace: nil, attaches_to: [], provides: [])
         @policies         = policies
         @process_managers = process_managers
         @name       = name.to_s
@@ -73,6 +76,7 @@ module Hecks
         @read_models = read_models
         @classification = classification&.to_s
         @formerly_known_as = formerly_known_as&.to_s
+        @namespace   = namespace&.to_s
         @attaches_to = Array(attaches_to).map(&:to_s)
         @provides    = Array(provides).map { |row| Provision.from(row) }
         settle

data/lib/hecks/bluebook/domain_port.rb

@@ -58,20 +58,51 @@ module Hecks
       end
     end
 
-    # A named group of operations an aggregate exposes to whatever adapter calls in.
+    # A query the hecksagon binds to a port's adapter: the bluebook declares the question and the
+    # value object its answer takes (`returns`), and this declares that something outside the
+    # domain answers it.
+    class QueryAnswer
+      include Hecks::IR
+
+      emits_ir(name: :name)
+
+      attr_reader :name
+
+      # @param name [String, Symbol] the bound query's declared name
+      def initialize(name:)
+        @name = name.to_s
+      end
+    end
+
+    # A named group of operations an aggregate exposes to whatever adapter calls in, plus the
+    # queries its adapter answers.
     class DomainPort
       include Hecks::IR
       include Behaviour::DomainPort
 
       emits_ir(name: :name, operations: many(:operations))
 
-      attr_reader :name, :operations
+      attr_reader :name, :operations, :answered_queries
 
       # @param name [String, Symbol] the port's declared name
       # @param operations [Array<Bluebook::PortOperation>] the port's declared operations
-      def initialize(name:, operations: [])
-        @name       = name.to_s
-        @operations = operations
+      # @param answered_queries [Array<Bluebook::QueryAnswer>] the queries this port's adapter
+      #   answers instead of the aggregate's stored records
+      def initialize(name:, operations: [], answered_queries: [])
+        @name             = name.to_s
+        @operations       = operations
+        @answered_queries = answered_queries
+      end
+
+      # `answered_queries` is merged in only when there are some, so a port that binds no query
+      # emits the shape it always did.
+      #
+      # @return [Hash] the port's IR
+      def to_h
+        shape = super
+        return shape if @answered_queries.empty?
+
+        shape.merge(answered_queries: @answered_queries.map(&:to_h))
       end
     end
   end

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

@@ -14,6 +14,7 @@ module Hecks
           # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] if a
           #   `correlates_by` resolves to something other than a scalar field
           def validate_assembled!(bluebook)
+            validate_not_the_gem_module!(bluebook)
             # an attribute type references its Shape, so an undeclared value object
             # fails resolution
             validate_reference_value_objects!(bluebook.aggregates)
@@ -289,6 +290,15 @@ module Hecks
           # chapter level because seeing a cycle needs every end declared (ADR 0025). Catches
           # any ring length; self-reference stays legal, and a cross-chapter target is a
           # dangling name, not an edge.
+          # A chapter's constants install under its name, or its `namespace`; landing in the
+          # gem's own `Hecks` module would shadow the gem's modules (ADR 0080), so it refuses.
+          def validate_not_the_gem_module!(bluebook)
+            return unless (bluebook.namespace || bluebook.name) == "Hecks"
+
+            raise Malformed, "#{bluebook.name}'s constants would install in the gem's own Hecks module — " \
+                             "declare a namespace, such as namespace \"Hecks::Domain\", or rename the chapter"
+          end
+
           def validate_no_bidirectional_references!(aggregates)
             edges = aggregates.to_h do |aggregate|
               [aggregate.hecks_name, aggregate.reference_targets.uniq.reject { |target| target == aggregate.hecks_name }]

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

@@ -65,6 +65,13 @@ module Hecks
         # @return [String] `value`, stringified, as stored
         def formerly_known_as(value) = @formerly_known_as = value.to_s
 
+        # Names the Ruby module the chapter's constants install under instead of its own name,
+        # such as `namespace "Hecks::Domain"` for a chapter that would otherwise collide.
+        #
+        # @param value [String] a constant path, such as `"Hecks::Domain"`
+        # @return [String] `value`, stringified, as stored
+        def namespace(value) = @namespace = value.to_s
+
         # Names a core grammar context this chapter's sub-language extends (ADR 0026).
         # Variadic and accumulates across calls, like `identified_by`/`group_by`.
         #
@@ -197,6 +204,7 @@ module Hecks
                                            process_managers: @process_managers,
                                            classification: @classification,
                                            formerly_known_as: @formerly_known_as,
+                                           namespace: @namespace,
                                            attaches_to: @attaches_to || [],
                                            provides: @provides || [])
 

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

@@ -3,7 +3,7 @@
 # KeywordSeed under lib/hecks/language/).
 #
 # Do not edit. spec/bootstrap_table_spec.rb re-projects this in memory
-# and refuses a diff — run bin/project_bootstrap_table instead.
+# and refuses a diff — run hecks project_bootstrap_table instead.
 #
 # Plain data, no requires: this is read while the grammar table it was
 # projected from is still being built (`MetaValidator.bootstrapping?`).
@@ -88,6 +88,7 @@ module Hecks
           ["DomainPort", "operation"] => :tells_impl,
           ["DomainPort", "tells"] => :tells_impl,
           ["DomainPort", "asks"] => :asks_impl,
+          ["DomainPort", "answers_query"] => :answers_query_impl,
           ["Hecksagon", "port"] => :port_impl,
           ["PortOperation", "reference_to"] => :reference_to_impl,
           ["PortOperation", "attribute"] => :attribute_impl,

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

@@ -23,6 +23,7 @@ module Hecks
           @operations       = []
           @signal           = :reply
           @answers          = []
+          @answered_queries = []
           @legacy_bare_port = legacy_bare_port
         end
 
@@ -58,6 +59,30 @@ module Hecks
           @operations << PortOperationBuilder.build(name, to: to, owner: @owner, direction: :outbound, &)
         end
 
+        # Declares that this port's adapter answers one of the owning aggregate's queries.
+        #
+        # The bluebook declares the question and the shape of its answer (`returns`) and never
+        # says who answers it; this binds it. The adapter is asked by the query's snake-cased
+        # name with its arguments. The aggregate's stored records are never read.
+        #
+        # @param name [String] the query's name, as the aggregate declares it
+        # @param removed [Hash] any keyword at all; the binding takes only the name
+        # @return [Array<Bluebook::QueryAnswer>] every binding declared so far, this one last
+        # @raise [Bluebook::DSL::Malformed] if a keyword such as `shape:` is written, or the query
+        #   is already bound on this port
+        def answers_query_impl(name, **removed)
+          unless removed.empty?
+            raise Malformed, "answers_query #{name.inspect} takes only the query's name — the shape " \
+                             "of its answer is the query's own `returns`, declared in the bluebook " \
+                             "(#{removed.keys.join(', ')} is not a word here)"
+          end
+          if @answered_queries.any? { |answer| answer.name == name.to_s }
+            raise Malformed, "#{@name} binds #{name} twice — a query has one answer"
+          end
+
+          @answered_queries << QueryAnswer.new(name: name)
+        end
+
         # Names the verb aggregates call this port by, making it a driven `Port` rather than a
         # `DomainPort` of operations. A port is one shape or the other, never both.
         #
@@ -83,10 +108,11 @@ module Hecks
         #
         # @return [Bluebook::Port, Bluebook::DomainPort] a `Port` when the body named a `verb`
         #   (or was empty under `legacy_bare_port:`), otherwise a `DomainPort` of its operations
+        #   and answered queries
         # @raise [Bluebook::DSL::Malformed] if the body declares both a verb and operations,
         #   declares neither without `legacy_bare_port:`, or the port language refuses the `Port`
         def build
-          if @verb && !@operations.empty?
+          if @verb && !(@operations.empty? && @answered_queries.empty?)
             raise Malformed,
                   "#{@name} declares both a verb and operations — a port is one or the other, not both"
           end
@@ -96,9 +122,11 @@ module Hecks
                                                     answers: @answers))
           end
 
-          raise Malformed, "#{@name} declares no verb and no operations" if @operations.empty?
+          if @operations.empty? && @answered_queries.empty?
+            raise Malformed, "#{@name} declares no verb and no operations, and answers no query"
+          end
 
-          DomainPort.new(name: @name, operations: @operations)
+          DomainPort.new(name: @name, operations: @operations, answered_queries: @answered_queries)
         end
 
         # Evaluates a `port` block against a fresh builder and returns whichever shape it declared.

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

@@ -10,10 +10,54 @@ module Hecks
         include WordGate
 
         class << self
-          attr_accessor :collector
+          # 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
         end
 
-        attr_reader :binds, :subscriptions, :framework_members, :vendored_bluebooks
+        # Lets the Hecks chapter's own hecksagon spell its aggregates `Hecks::Operation`.
+        #
+        # While the chapter named Hecks builds its hecksagon, a missing constant on `Hecks` is
+        # one of that chapter's aggregates; at any other time it is the ordinary `NameError`.
+        #
+        # A real module of the same name (`Hecks::Release`) would answer first, so
+        # `HecksagonBuilder.build` takes each off `Hecks` while the block runs (see `shadowed`).
+        # `attaches` loads whole chapters inside the block; the shadow lifts around each load
+        # (see `with_real_modules`), so loaded code sees the real modules.
+        module ChapterConstants
+          # @param name [Symbol] the missing constant
+          # @return [Bluebook::DSL::BindingProxy] a proxy for that aggregate while building
+          def const_missing(name)
+            return super unless HecksagonBuilder.building == "Hecks" && HecksagonBuilder.collector
+
+            BindingProxy.new("Hecks::#{name}", HecksagonBuilder.collector)
+          end
+        end
+
+        attr_reader :binds, :subscriptions, :framework_members, :vendored_bluebooks, :attached_chapters
 
         def initialize(domain)
           @domain             = domain
@@ -21,6 +65,7 @@ module Hecks
           @subscriptions      = []
           @framework_members  = []
           @vendored_bluebooks = []
+          @attached_chapters  = []
           @bounded            = false
           @translates         = []
         end
@@ -54,6 +99,17 @@ module Hecks
           Hecks.current_registry&.mark_bounded(Hecks::Naming.pascal(name.to_s))
         end
 
+        # Attaches a chapter the gem carries (the language, Expression, Tenancy, Deploy,
+        # QualityControl) by name and loads its files into the registry, with the ports and
+        # adapters it ships. Marked bounded like a framework member, since this hecksagon is its
+        # anti-corruption layer.
+        def attaches(name)
+          require_relative "../../chapters"
+          @attached_chapters << name.to_s
+          self.class.with_real_modules { Hecks::Chapters.load!(name) }
+          Hecks.current_registry&.mark_bounded(name.to_s)
+        end
+
         # Declares a port at the hecksagon's root — the chapter as a whole, not one aggregate.
         def port_impl(name, &block)
           bluebook_ir = Hecks.current_registry.bluebook(@domain) or
@@ -90,7 +146,7 @@ module Hecks
         def build
           Hecksagon.new(domain: @domain, binds: @binds, subscriptions: @subscriptions,
                         framework_members: @framework_members, vendored_bluebooks: @vendored_bluebooks,
-                        bounded: @bounded, translates: @translates)
+                        attached_chapters: @attached_chapters, bounded: @bounded, translates: @translates)
         end
 
         # Records any verb the grammar doesn't own as a domain-wide default bind, e.g. bare
@@ -117,16 +173,79 @@ module Hecks
           resolver = ->(name) { BindingProxy.namespace(name, builder.binds) }
 
           previous       = collector
+          previous_name  = building
           self.collector = builder.binds
+          self.building  = domain.to_s
+          previous_hidden = hidden_modules
+          hidden = previous_name == "Hecks" ? {} : shadowed(domain)
+          self.hidden_modules = hidden.empty? ? previous_hidden : hidden
           begin
             ConstShim.with(resolver) { builder.instance_eval(&block) } if block
           ensure
+            restore_shadowed(hidden)
+            self.hidden_modules = previous_hidden
             self.collector = previous
+            self.building  = previous_name
           end
 
           builder.build
         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 self.shadowed(domain)
+          return {} unless domain.to_s == "Hecks"
+
+          chapter = Hecks.current_registry&.bluebook("Hecks")
+          names   = chapter ? chapter.aggregates.map { |aggregate| aggregate.hecks_name.to_sym } : []
+          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 self.with_real_modules
+          hidden = hidden_modules
+          return yield if hidden.nil? || hidden.empty?
+
+          name = building
+          restore_shadowed(hidden)
+          self.building = nil
+          begin
+            yield
+          ensure
+            self.building = name
+            hidden.replace(shadowed(name))
+          end
+        end
+
+        # Puts back what `shadowed` took off.
+        #
+        # @param hidden [Hash{Symbol => Array}] `shadowed`'s answer
+        # @return [void]
+        def self.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
       end
     end
   end
 end
+
+Hecks.singleton_class.prepend(Hecks::Bluebook::DSL::HecksagonBuilder::ChapterConstants)

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

@@ -64,7 +64,7 @@ module Hecks
 
         # C5.3 (docs/semantics/bluebook-semantics.md): overlapping `from:` sets for one command
         # are refused. Disjoint sets are legitimate. An undeclared `from:` state is left to
-        # `bin/model_check`.
+        # `hecks model_check`.
         def refuse_ambiguity!
           return if MetaValidator.shadow_parsing? # frozen era text is exempt
 

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

@@ -27,6 +27,31 @@ module Hecks
         # @return [String] the description as stored
         def description(value) = @description = value
 
+        # Names the value object of the owning aggregate that shapes this query's answer.
+        #
+        # The bluebook owns the meaning of an answer: a query that returns a value object is
+        # answered by something outside the domain (the hecksagon binds it), and each row of
+        # that answer is built as the value object, so a wrong-shaped answer is refused before
+        # it enters the domain. A query that returns nothing answers with the aggregate's own row.
+        #
+        # @param type [Module, AttributeCollector::ListOf] a bare value-object constant, or
+        #   `list_of(Constant)` when the answer is many rows
+        # @return [String] the return type as stored: `"Name"` or `"list_of(Name)"`
+        # @raise [Bluebook::DSL::Malformed] if the query already returns, or the type is quoted text
+        def returns(type)
+          raise Malformed, "#{@name} declares returns twice — a query answers in one shape" if @returns
+
+          list  = type.is_a?(AttributeCollector::ListOf)
+          inner = list ? type.type : type
+          if inner.is_a?(::String)
+            raise Malformed, "#{@name}'s returns #{inner.inspect} is quoted text — give the bare " \
+                             "constant (#{inner}) instead"
+          end
+
+          name = Naming.demodulise(inner)
+          @returns = list ? "list_of(#{name})" : name.to_s
+        end
+
         # Declares a query parameter that names another aggregate's identity.
         #
         # A plain attribute typed as a reference; a query has no root of its own to act on.
@@ -61,7 +86,8 @@ module Hecks
             cursor:         @cursor,
             authorization:  @authorization,
             null_semantics: @null_semantics,
-            inspection:     @inspection
+            inspection:     @inspection,
+            returns:        @returns
           )
         end
 

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

@@ -55,7 +55,7 @@ module Hecks
         #
         # Projected ahead of time into bootstrap_table.rb for the bootstrap window before
         # the grammar table itself is built (MetaValidator.bootstrapping?); kept in sync by
-        # bin/project_bootstrap_table, pinned by spec/bootstrap_table_spec.rb.
+        # hecks project_bootstrap_table, pinned by spec/bootstrap_table_spec.rb.
         BOOTSTRAP_FALLBACK = BootstrapTable::RESOLVES
 
         # Reads how a (word, context) pair resolves rule references, off the self-hosted