hecks 5.0.0 → 6.0.0

data/lib/hecks/runtime/read_model_interpreter/reductions.rb

@@ -1,4 +1,6 @@
+require "json"
 require_relative "../../ports/query/in_memory"
+require_relative "../../vocabulary"
 require_relative "../../query_specification/field_path"
 
 module Hecks
@@ -14,6 +16,9 @@ module Hecks
         # The order `reduce` looks for a declared reduction; `median` is what remains.
         REDUCE_ORDER = %i[any_field all_field sum_field avg_field min_field max_field percentile_field].freeze
 
+        # Each reducer's answer over no rows, read from the Vocabulary's `Reducer` rows (ADR 0126).
+        EMPTY_ANSWER = Hecks::Vocabulary.rows("Reducer").to_h { |row| [row["name"], JSON.parse(row["identity"])] }.freeze
+
         private
 
         # Resolves a reduction's single many-side head, raising on a field that doesn't
@@ -48,8 +53,9 @@ module Hecks
           return if reduction_type_ok?(reduction.ivar, aggregate, attribute)
 
           kind = BOOLEAN_REDUCTIONS.include?(reduction.ivar) ? "boolean" : "numeric"
+          model = reduction.model
           raise ArgumentError,
-                "#{reduction.model.name}'s #{reduction.word} names #{reduction.field.inspect} on #{aggregate_name}, " \
+                "#{model.name}'s #{reduction.word} names #{reduction.field.inspect} on #{aggregate_name}, " \
                 "which is not #{kind} — #{reduction.word} needs a #{kind == "boolean" ? "true/false" : "numeric"} field"
         end
 
@@ -69,24 +75,32 @@ module Hecks
         # `Runtime::ReadModelInterpreter#project`'s `reduced_head` branch.
         def reduce(model, rows)
           name = REDUCE_ORDER.find { |candidate| model.public_send(candidate) }
-          return percentile(numeric_values(rows, model.median_field), 0.5) unless name
+          return median(rows, model.median_field) unless name
 
           apply_reduction(name, model, rows)
         end
 
+        def median(rows, field)
+          values = numeric_values(rows, field)
+          values.empty? ? EMPTY_ANSWER.fetch("median") : percentile(values, 0.5)
+        end
+
+        # An empty collection answers the reducer's declared identity; any other is reduced.
         def apply_reduction(name, model, rows)
-          field = model.public_send(name)
+          values = reduction_values(rows, model.public_send(name))
+          return EMPTY_ANSWER.fetch(REDUCTION_WORD.fetch(name)) if values.empty?
+
           case name
-          when :any_field then boolean_values(rows, field).any?
-          when :all_field then boolean_values(rows, field).all?
-          else numeric_reduction(name, model, numeric_values(rows, field))
+          when :any_field then values.any?
+          when :all_field then values.all?
+          else numeric_reduction(name, model, values)
           end
         end
 
         def numeric_reduction(name, model, values)
           case name
           when :sum_field then values.sum
-          when :avg_field then average(values)
+          when :avg_field then values.sum.to_f / values.length
           when :min_field then values.min
           when :max_field then values.max
           else percentile(values, model.percentile_at)
@@ -101,16 +115,10 @@ module Hecks
           rows.map { |record| Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row(record), field)) }.compact
         end
         alias numeric_values reduction_values
-        alias boolean_values reduction_values
-
-        # `nil` on no rows: a rate of nothing is undefined, not zero.
-        def average(values) = values.empty? ? nil : values.sum.to_f / values.length
 
-        # The value at one interpolated rank (`0.0`..`1.0`); `at: 0.5` is the standard median
-        # (middle value when odd, average of the two middle values when even). `nil` on no rows.
+        # The value at one interpolated rank (`0.0`..`1.0`) of a non-empty list; `at: 0.5` is
+        # the standard median (middle value when odd, average of the two middle values when even).
         def percentile(values, at)
-          return nil if values.empty?
-
           sorted = values.sort
           position = at * (sorted.length - 1)
           lower = position.floor

data/lib/hecks/runtime/read_model_interpreter/shaping.rb

@@ -33,11 +33,19 @@ module Hecks
           value.is_a?(Array) ? value.map { |record| Value.materialize(row(record)) } : Value.materialize(row(value))
         end
 
+        # A grouped head nests its rows; with a reduction declared too, each leaf is that
+        # reduction of the leaf's rows rather than the row itself (ADR 0126).
         def grouped_rows(value, shape)
-          nest(value.map { |record| Value.materialize_unwrapped(row(record)) }, shape.model.group_by_fields,
-               collision_check(shape.model, shape.bluebook, shape.grouped))
+          model = shape.model
+          rows = value.map { |record| Value.materialize_unwrapped(row(record)) }
+          leaf = shape.reduced ? reduced_leaf(model) : row_leaf(collision_check(model, shape.bluebook, shape.grouped))
+          nest(rows, model.group_by_fields, leaf)
         end
 
+        def reduced_leaf(model) = ->(rows, _path) { reduced_value(rows, model) }
+
+        def row_leaf(checked) = ->(rows, path) { leaf(rows, checked, path) }
+
         def reduced_value(value, model)
           model.count? ? value.length : reduce(model, value)
         end
@@ -55,10 +63,12 @@ module Hecks
 
         def check_group_field!(model, aggregate, target, field)
           return if aggregate.attribute(field)
+
           # A lifecycle field is a real field too — it's stored on the record like
           # any attribute, just declared via `lifecycle :status`, and it's usually
           # exactly the field a report wants to group by.
-          return if aggregate.lifecycle && aggregate.lifecycle.field.to_sym == field.to_sym
+          lifecycle_field = aggregate.lifecycle_field
+          return if lifecycle_field && lifecycle_field.to_sym == field.to_sym
 
           raise ArgumentError,
                 "#{model.name}'s group_by names #{field.inspect}, but #{target[:aggregate]} " \
@@ -71,9 +81,8 @@ module Hecks
           model.groups_by_identity?(bluebook.aggregate(grouped_head[:aggregate])) ? nil : model
         end
 
-        # Nests one level per `group_by` field; a leaf holding more than one row
-        # is a `group_by` collision (ADR 0061 D1), refused rather than picking one.
-        def nest(rows, fields, checked, reached = [])
+        # Nests one level per `group_by` field, answering each leaf's rows through `leaf`.
+        def nest(rows, fields, leaf, reached = [])
           field, *rest = fields
           rows.group_by { |row| row[field] }.to_h do |key, group|
             # Strip only the field just grouped by, not the whole remaining
@@ -81,10 +90,12 @@ module Hecks
             # call below, or the next level groups by a key that's already gone.
             stripped = group.map { |row| row.reject { |name, _| name == field } }
             path = reached + [[field, key]]
-            [key, rest.empty? ? leaf(stripped, checked, path) : nest(stripped, rest, checked, path)]
+            [key, rest.empty? ? leaf.call(stripped, path) : nest(stripped, rest, leaf, path)]
           end
         end
 
+        # The one row a key path reached; more than one is a `group_by` collision
+        # (ADR 0061 D1), refused rather than picking one.
         def leaf(rows, checked, path)
           return rows.first unless checked && rows.size > 1
 

data/lib/hecks/runtime/read_model_interpreter.rb

@@ -31,7 +31,10 @@ module Hecks
 
       # One read model run: where it runs, the model after tenant scoping, and what the heads
       # need to be read: the reference's id and the heads a `where` or `order` applies to.
-      Request = Struct.new(:domain, :bluebook, :model, :args, :rootless, :reference_id, :eligible)
+      Request = Struct.new(:domain, :bluebook, :model, :args, :rootless, :reference_id, :eligible) do
+        # @return [String, nil] the aggregate the model's reference points at, its root head
+        def reference_target = model.reference_target
+      end
 
       # @param registry [Runtime::Registry] the booted registry whose repositories
       #   this interpreter reads
@@ -112,7 +115,7 @@ module Hecks
       end
 
       def head_rows(request, head, projected)
-        if head[:aggregate] == request.model.reference_target
+        if head[:aggregate] == request.reference_target
           [fetch(request.bluebook, request.domain, head[:aggregate], request.reference_id)]
         elsif request.rootless
           # A rootless model has no root to FK-match against, so each head

data/lib/hecks/runtime/reference_hop.rb

@@ -29,7 +29,8 @@ module Hecks
         inner = QuerySpecification::Common::WhereClause.new(field: rest, op: clause.op, value: clause.value)
         ids   = matching_ids(domain, hop.target, [inner], args, registry: registry)
 
-        QuerySpecification::Common::WhereClause.new(field: hop.attribute.name, op: "in", value: ids)
+        attribute = hop.attribute
+        QuerySpecification::Common::WhereClause.new(field: attribute.name, op: "in", value: ids)
       end
 
       # BluebookBuilder#validate_query_hops! already checked this hop at boot; if it
@@ -37,7 +38,7 @@ module Hecks
       def refuse_unresolvable_hop!(clause)
         raise WiringError,
               "#{clause.field} hops through a reference this domain cannot resolve " \
-              "right now — the chapter seal already checked this once; something " \
+              "right now — the bluebook seal already checked this once; something " \
               "changed between then and this dispatch"
       end
 

data/lib/hecks/runtime/refusal_wording.rb

@@ -9,6 +9,11 @@ module Hecks
                                    .to_h { |row| [[row["refusal"], row["site"]].freeze, row["template"]] }
                                    .freeze
 
+      # A `{name}` placeholder in a template, captured so a split keeps it as its own piece.
+      PLACEHOLDER = /(\{\w+\})/
+      # A piece that is exactly one `{name}` placeholder, capturing the name.
+      PLACEHOLDER_NAME = /\A\{(\w+)\}\z/
+
       SHAPES   = %w[scalar list].freeze
       QUOTINGS = %w[none inspect].freeze
 
@@ -31,9 +36,9 @@ module Hecks
       # @return [Boolean]
       def already_exists?(reason, command: nil, aggregate: nil)
         given   = { "command" => command, "aggregate" => aggregate }
-        pieces  = TEMPLATES.fetch(%w[AlreadyExists creating_duplicate]).split(/(\{\w+\})/, -1)
+        pieces  = TEMPLATES.fetch(%w[AlreadyExists creating_duplicate]).split(PLACEHOLDER, -1)
         pattern = pieces.map do |piece|
-          name = piece[/\A\{(\w+)\}\z/, 1]
+          name = piece[PLACEHOLDER_NAME, 1]
           next Regexp.escape(piece) unless name
 
           given[name] ? Regexp.escape(given[name]) : ".*"
@@ -90,12 +95,16 @@ module Hecks
         end
       end
 
+      # Every RefusalSiteArgument row, grouped by its `[refusal, site]`.
+      def rows_by_site
+        Hecks::Vocabulary.rows("RefusalSiteArgument")
+                         .group_by { |row| [row["refusal"], row["site"]] }
+                         .transform_values(&:freeze)
+      end
+
       # Read lazily: hecks project_vocabulary boots this file before it writes these rows.
       def argument_rows(refusal, site)
-        @argument_rows ||= Hecks::Vocabulary.rows("RefusalSiteArgument")
-                                            .group_by { |row| [row["refusal"], row["site"]] }
-                                            .transform_values(&:freeze)
-                                            .freeze
+        @argument_rows ||= rows_by_site.freeze
         @argument_rows.fetch([refusal, site]) do
           raise KeyError, "no refusal arguments for #{refusal}/#{site} — declare them in " \
                           "Vocabulary::RefusalSiteArgument first"

data/lib/hecks/runtime/registry/adapter_capabilities.rb

@@ -0,0 +1,43 @@
+module Hecks
+  module Runtime
+    class Registry
+      # Answers what the persistence adapter an aggregate is bound to provides, read from the
+      # `provides` lines of its `.adapter` file.
+      module AdapterCapabilities
+        # Says whether the adapter `aggregate` persists through declares `provides capability`.
+        # The bind is the one a repository uses, so a world's `default_adapter` counts.
+        #
+        # @param domain [String, Symbol] the domain the aggregate belongs to
+        # @param aggregate [Bluebook::Aggregate, String] the aggregate, or its declared name
+        # @param capability [String, Symbol] the capability, such as `"set_transform"`
+        # @return [Boolean] true only when the bound adapter is loaded and provides it
+        # @raise [WiringError] if the aggregate's binding is missing or ambiguous
+        def adapter_provides?(domain, aggregate, capability)
+          bound_adapter(domain, aggregate)&.provides?(capability) || false
+        end
+
+        # The loaded adapter declaration `aggregate` persists through.
+        #
+        # @param domain [String, Symbol] the domain the aggregate belongs to
+        # @param aggregate [Bluebook::Aggregate, String] the aggregate, or its declared name
+        # @return [Bluebook::Adapter, nil] the bound adapter, or nil when no `.adapter` file
+        #   declares the bound name
+        # @raise [WiringError] if the aggregate's binding is missing or ambiguous, or the domain
+        #   declares no aggregate by that name
+        def bound_adapter(domain, aggregate)
+          bind = Ports::Persistence::BindingPolicy.resolve(self, domain, aggregate_named(domain, aggregate))
+          adapters[bind.adapter]
+        end
+
+        private
+
+        def aggregate_named(domain, aggregate)
+          return aggregate unless aggregate.is_a?(String) || aggregate.is_a?(Symbol)
+
+          bluebook(domain)&.aggregate(aggregate.to_s) ||
+            raise(WiringError, "#{domain} declares no aggregate #{aggregate}")
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/registry/ask_verification.rb

@@ -9,7 +9,7 @@ module Hecks
       module AskVerification
         private
 
-        # A port operation a chapter provides, and an ask a policy makes, each name a port
+        # A port operation a bluebook provides, and an ask a policy makes, each name a port
         # operation the hecksagon declared.
         def refuse_unresolved_ports!
           refuse_unresolved_port_operations!
@@ -20,15 +20,26 @@ module Hecks
         #
         # @raise [WiringError] naming the policy, the ask and what the hecksagon would need
         def refuse_unresolved_asks!
-          @declared.bluebooks.each_value do |chapter|
-            chapter.policies.select(&:asks?).each do |policy|
-              outcome = Bluebook::AskResolution.call(chapter, policy)
+          @declared.bluebooks.each_value do |declaration|
+            next if awaiting_sibling?(declaration)
+
+            declaration.policies.select(&:asks?).each do |policy|
+              outcome = Bluebook::AskResolution.call(declaration, policy)
               raise WiringError, outcome.detail unless outcome.resolved?
 
               policy.resolve_ask!(outcome.verb)
             end
           end
         end
+
+        # A bounded context whose sibling hecksagon was never declared. Its asks have nowhere to
+        # resolve, and the missing sibling is the refusal that names the cause.
+        #
+        # @param declaration [Bluebook] a loaded bluebook
+        # @return [Boolean]
+        def awaiting_sibling?(declaration)
+          bounded?(declaration.hecks_name) && hecksagon(declaration.hecks_name).nil?
+        end
       end
     end
   end

data/lib/hecks/runtime/registry/{chapter_verification.rb → bluebook_verification.rb}

@@ -1,50 +1,50 @@
 module Hecks
   module Runtime
     class Registry
-      # Checks the chapters a boot loaded: no reserved name from outside the gem, and no two
+      # Checks the bluebooks a boot loaded: no reserved name from outside the gem, and no two
       # unrelated packages sharing a name. Mixed into {Verification}.
-      module ChapterVerification
-        # The directory holding the gem's own Hecks chapter, the only place a chapter named
+      module BluebookVerification
+        # The directory holding the gem's own Hecks bluebook, the only place a bluebook named
         # `Hecks` may be declared from.
-        GEM_CHAPTER_DIR = File.expand_path("../../hecks", __dir__).freeze
+        GEM_BLUEBOOK_DIR = File.expand_path("../../hecks", __dir__).freeze
 
-        # The chapter names only the gem itself may declare (ADR 0080, section 9).
-        RESERVED_CHAPTER_NAMES = %w[Hecks].freeze
+        # The bluebook names only the gem itself may declare (ADR 0080, section 9).
+        RESERVED_BLUEBOOK_NAMES = %w[Hecks].freeze
 
         private
 
-        # Refuses a chapter whose name is reserved unless every file that declared it sits under
-        # the gem's own chapter directory. A rename is the only fix, so the message says so.
+        # Refuses a bluebook whose name is reserved unless every file that declared it sits under
+        # the gem's own bluebook directory. A rename is the only fix, so the message says so.
         #
         # @raise [WiringError] naming the reserved word and the offending file(s)
-        def refuse_reserved_chapter_names!
-          RESERVED_CHAPTER_NAMES.each do |reserved|
+        def refuse_reserved_bluebook_names!
+          RESERVED_BLUEBOOK_NAMES.each do |reserved|
             next unless @declared.bluebooks.key?(reserved)
 
             sources = Array(@declared.bluebook_sources[reserved]).compact
-            foreign = sources.reject { |path| gem_chapter_source?(path) }
+            foreign = sources.reject { |path| gem_bluebook_source?(path) }
             next if foreign.empty? && !sources.empty?
 
-            raise WiringError, reserved_chapter_message(reserved, foreign)
+            raise WiringError, reserved_bluebook_message(reserved, foreign)
           end
         end
 
-        def reserved_chapter_message(reserved, foreign)
+        def reserved_bluebook_message(reserved, foreign)
           where = foreign.empty? ? "" : " (declared in #{foreign.join(", ")})"
-          "a chapter named #{reserved.inspect} is refused: #{reserved.inspect} is a reserved " \
-            "word, the name of the gem's own chapter, and only the gem may declare it#{where}. " \
-            "Rename the chapter (for example to your app's name) in its " \
+          "a bluebook named #{reserved.inspect} is refused: #{reserved.inspect} is a reserved " \
+            "word, the name of the gem's own bluebook, and only the gem may declare it#{where}. " \
+            "Rename the bluebook (for example to your app's name) in its " \
             "`Hecks.bluebook #{reserved.inspect}` line and in its hecksagon."
         end
 
-        # Whether `path` is a file of the gem's own chapter directory.
-        def gem_chapter_source?(path)
-          File.expand_path(path.to_s).start_with?("#{GEM_CHAPTER_DIR}/")
+        # Whether `path` is a file of the gem's own bluebook directory.
+        def gem_bluebook_source?(path)
+          File.expand_path(path.to_s).start_with?("#{GEM_BLUEBOOK_DIR}/")
         end
 
-        # Two packages can share a chapter name by coincidence (a stale vendored
+        # Two packages can share a bluebook name by coincidence (a stale vendored
         # fork of Governance/Identity/Deploy still on an app's load paths).
-        # Intentional accumulation (several files declaring the same chapter on
+        # Intentional accumulation (several files declaring the same bluebook on
         # purpose) is distinguished by package root, not file identity, and is left
         # untouched here — checked once, after every file has loaded.
         def refuse_cross_package_bluebook_merge!
@@ -54,8 +54,8 @@ module Hecks
 
             raise WiringError,
                   "#{name.inspect} is declared by more than one package: #{roots.join(" and ")} — " \
-                  "these are two unrelated sources sharing a chapter name by coincidence, not one " \
-                  "domain split across files, and merging their declarations into one chapter is " \
+                  "these are two unrelated sources sharing a bluebook name by coincidence, not one " \
+                  "domain split across files, and merging their declarations into one bluebook is " \
                   "almost certainly a stale/vendored copy left on the load path (paths: " \
                   "#{paths.join(", ")})"
           end

data/lib/hecks/runtime/registry/context_maps.rb

@@ -0,0 +1,30 @@
+module Hecks
+  module Runtime
+    class Registry
+      # The context maps a boot loaded from `.contextmap` files, one per system.
+      module ContextMaps
+        # Boot-time-only, single-threaded: it runs from Hecks.collect while a `.contextmap` file is
+        # being Kernel.loaded, before the registry reaches a live, multi-threaded caller.
+        # rubocop:disable Hecks/ThreadSharedIvarMutation
+        # Registers a declared context map under its system's name, a later one of the same name
+        # replacing the earlier (a map is one declaration, not a layered overlay).
+        #
+        # @param item [Bluebook::ContextMap] the declared map
+        # @return [Bluebook::ContextMap] the map
+        def add_context_map(item)
+          @declared.context_maps[item.name] = item
+        end
+        # rubocop:enable Hecks/ThreadSharedIvarMutation
+
+        # Finds a system's declared context map by name.
+        #
+        # @param name [String, Symbol] the system the map covers
+        # @return [Bluebook::ContextMap, nil] the map, or nil if none is registered under `name`
+        def context_map(name) = @declared.context_maps[name.to_s]
+
+        # @return [Array<Bluebook::ContextMap>] every declared context map
+        def context_maps = @declared.context_maps.values
+      end
+    end
+  end
+end

data/lib/hecks/runtime/registry/declarations.rb

@@ -1,15 +1,17 @@
 module Hecks
   module Runtime
     class Registry
-      # What a boot gathers while the `.bluebook`, `.hecksagon` and `.world` files load: the
-      # chapters and their builders, the wiring, ports, adapters, worlds, translations, the
-      # eras the boot gate resolved, and the privacy markings still to be dispatched.
-      Declarations = Struct.new(:bluebooks, :bluebook_sources, :hecksagons, :bounded_chapters, :ports,
+      # What a boot gathers while the `.bluebook`, `.hecksagon`, `.world` and `.contextmap` files
+      # load: the bluebooks and their builders, the wiring, ports, adapters, worlds, translations,
+      # context maps, the eras the boot gate resolved, and the privacy markings still to be
+      # dispatched.
+      Declarations = Struct.new(:bluebooks, :bluebook_sources, :hecksagons, :bounded_bluebooks, :ports,
                                 :adapters, :worlds, :translations, :bluebook_builders,
-                                :pending_privacy_markings, :resolved_eras, :superseded_eras) do
+                                :pending_privacy_markings, :resolved_eras, :superseded_eras,
+                                :context_maps) do
         # @return [Declarations] every collection empty
         def self.empty
-          new({}, {}, {}, {}, {}, {}, {}, [], {}, [], {}, {})
+          new({}, {}, {}, {}, {}, {}, {}, [], {}, [], {}, {}, {})
         end
       end
     end

data/lib/hecks/runtime/registry/durability_warnings.rb

@@ -44,10 +44,26 @@ module Hecks
 
         # The name of every event the aggregates' commands and port operations announce.
         def emitted_event_names(bluebook_ir)
-          bluebook_ir.aggregates.flat_map do |aggregate|
+          names = bluebook_ir.aggregates.flat_map do |aggregate|
             aggregate.commands.flat_map(&:emits) +
               aggregate.ports.flat_map { |port| port.operations.flat_map { |op| [*op.emits, op.answers, op.refuses] } }
-          end.compact.map(&:to_s)
+          end
+          names.compact.map(&:to_s)
+        end
+
+        # A hecksagon that never mentions persistence wires none, so its aggregates are in Memory:
+        # the default, and nothing to say. The one case worth saying is a world that names a store
+        # (a database or persistence settings) that no bind uses, which is a forgotten decision.
+        def warn_unwired_persistence!(hecksagon)
+          domain = hecksagon.domain
+          return unless Ports::Persistence::BindingPolicy.unwired?(self, domain) && store_named?(domain)
+
+          warn "[hecks] #{domain} names a store but binds no persistence, so its aggregates are in Memory " \
+               "and keep nothing across a restart. Add `persisted_by \"<adapter>\"` to its hecksagon."
+        end
+
+        def store_named?(domain)
+          !default_database_for(domain).nil? || !world(domain)&.for_verb("persistence").to_h.empty?
         end
 
         # A warning, not a refusal: running sagas on a store with no `save_saga` is

data/lib/hecks/runtime/registry/hecksagon_rules.rb

@@ -2,7 +2,7 @@ module Hecks
   module Runtime
     class Registry
       # The checks a loaded hecksagon owes: roles need an authorization provider, attachments need
-      # their sibling hecksagon, a bounded chapter needs its ACL, and a chapter's declared
+      # their sibling hecksagon, a bounded bluebook needs its ACL, and a bluebook's declared
       # capabilities need what they name. Mixed into {Verification}.
       module HecksagonRules
         private
@@ -43,61 +43,64 @@ module Hecks
         # on that sibling too, or cross-context field mapping has nowhere to be written.
         def refuse_unwired_attachments!(hecksagon)
           hecksagon.attachments.each do |attachment|
-            next if hecksagon(attachment.chapter_name)
+            next if hecksagon(attachment.declaration_name)
 
             raise WiringError, unwired_attachment_message(hecksagon, attachment)
           end
         end
 
         def unwired_attachment_message(hecksagon, attachment)
-          chapter_name = attachment.chapter_name
-          what = attachment.vendor? ? "vendored bluebook #{attachment.name.inspect}" : chapter_name.inspect
+          declaration_name = attachment.declaration_name
+          what = attachment.vendor? ? "vendored bluebook #{attachment.name.inspect}" : declaration_name.inspect
           "#{hecksagon.domain} attaches #{what} " \
-            "(bounded context #{chapter_name}) but never declared " \
-            "Hecks.hecksagon #{chapter_name.inspect} — put that sibling " \
+            "(bounded context #{declaration_name}) but never declared " \
+            "Hecks.hecksagon #{declaration_name.inspect} — put that sibling " \
             "(and any `translates` ACL) in context_map.hecksagon; " \
             "same-name blocks merge, order-independent."
         end
 
-        # An explicit `bounded` mark on a consumer chapter always needs an ACL. `attaches`
-        # marks the attached chapter bounded and requires the sibling
+        # An explicit `bounded` mark on a consumer bluebook always needs an ACL. `attaches`
+        # marks the attached bluebook bounded and requires the sibling
         # hecksagon above; they don't require a `translates` on it unless the consumer also
         # wrote `bounded`.
         # rust/host Google sign-in reads ir.json's membership/identity keys, never a deploy-time
         # env var; Membership without Identity means provision cannot Register/Link an identity.
         def refuse_membership_without_identity!
-          return unless @declared.bluebooks.values.any? { |chapter| chapter.provides?(Bluebook::Capabilities::MEMBERSHIP) }
-          return if @declared.bluebooks.values.any? { |chapter| chapter.provides?(Bluebook::Capabilities::IDENTITY) }
+          unless @declared.bluebooks.values.any? { |declaration| declaration.provides?(Bluebook::Capabilities::MEMBERSHIP) }
+            return
+          end
+          return if @declared.bluebooks.values.any? { |declaration| declaration.provides?(Bluebook::Capabilities::IDENTITY) }
 
           raise WiringError,
-                "a chapter that provides \"membership\" is loaded, but none provides " \
+                "a bluebook that provides \"membership\" is loaded, but none provides " \
                 "\"identity\" — rust/host Google sign-in cannot register or link an " \
                 "identity from the hecksagon/world. Attach Identity (`attaches " \
                 "\"Identity\"` plus a sibling Hecks.hecksagon \"Identity\") so the " \
                 "identity verbs are exported onto ir.json, not guessed at deploy."
         end
 
-        # A hecksagon attaches after its chapter builds, so this is the first point a
-        # declared `:port_operation` capability can be checked against it.
+        # A hecksagon attaches after its bluebook builds, so this is the first point a
+        # `provides` key that names a port operation can be checked against it.
         def refuse_unresolved_port_operations!
-          @declared.bluebooks.each_value do |chapter|
-            chapter.provides.each { |row| refuse_unresolved_port_operation!(chapter, row) }
+          @declared.bluebooks.each_value do |declaration|
+            declaration.provides.each { |row| refuse_unresolved_port_operation!(declaration, row) }
           end
         end
 
-        def refuse_unresolved_port_operation!(chapter, row)
-          return unless Bluebook::Capabilities::CONTRACTS.dig(row.capability, row.key.to_sym) == :port_operation
-          return if port_operation_declared?(chapter, row.verb)
+        def refuse_unresolved_port_operation!(declaration, row)
+          return if Bluebook::Capabilities.language_defined?(row.capability)
+          return unless Bluebook::Capabilities.kinds_of(declaration, row.verb) == [:port_operation]
+          return if port_operation_declared?(declaration, row.verb)
 
           raise WiringError,
-                "#{chapter.name} provides #{row.capability.inspect} #{row.key}: #{row.verb.inspect}, " \
+                "#{declaration.name} provides #{row.capability.inspect} #{row.key}: #{row.verb.inspect}, " \
                 "but its hecksagon declares no such port operation — declare it with " \
-                "`#{chapter.name}::Aggregate.port \"Port\" do operation \"Operation\" ... end`."
+                "`#{declaration.name}::Aggregate.port \"Port\" do operation \"Operation\" ... end`."
         end
 
-        def port_operation_declared?(chapter, verb)
+        def port_operation_declared?(declaration, verb)
           aggregate_name, port_name, operation_name = verb.split(".", 3)
-          ports = chapter.aggregate(aggregate_name)&.ports || []
+          ports = declaration.aggregate(aggregate_name)&.ports || []
           ports.any? { |port| port.name == port_name && port.operations.any? { |op| op.hecks_name == operation_name } }
         end
 
@@ -107,7 +110,7 @@ module Hecks
 
           raise WiringError,
                 "#{hecksagon.domain} is marked bounded but never declared a " \
-                "translates ACL — a bounded chapter wraps in its own module and " \
+                "translates ACL — a bounded bluebook wraps in its own module and " \
                 "cross-context field mapping lives on the hecksagon, not in " \
                 "rust/host and not as a field list on the bluebook. " \
                 "Add `translates \"Name\" do on Foreign::Event; trigger Local::Command, " \
@@ -118,7 +121,7 @@ module Hecks
         # "authorization"` — never a hardcoded name.
         def authorization_attachment_hint
           providers = Framework.providers_of(Bluebook::Capabilities::AUTHORIZATION)
-          return "attaches a chapter that provides \"authorization\" (no framework member declares one)" if providers.empty?
+          return "attaches a bluebook that provides \"authorization\" (no framework member declares one)" if providers.empty?
 
           providers.map { |name| "attaches #{name.inspect}" }.join(" or ")
         end

data/lib/hecks/runtime/registry/plugin_query_verification.rb

@@ -0,0 +1,45 @@
+require_relative "../wasm_plugin"
+
+module Hecks
+  module Runtime
+    class Registry
+      # Holds a `returns` query no hecksagon binds to the one wasm plugin that says it answers it,
+      # and that plugin to a module that compiles. Mixed into {Verification}, beside
+      # {QueryVerification}, which asks it when a query has no other answer path.
+      module PluginQueryVerification
+        private
+
+        # The one plugin adapter that says it answers a query no hecksagon binds: a `returns` query
+        # is bound to it without a hecksagon line. Two plugins claiming one query is refused, since
+        # the runtime will not choose between them; a hecksagon binding still overrides either.
+        #
+        # @param query [Bluebook::Query] the declared query
+        # @param where [String] the qualified query, `"Bluebook::Aggregate.Query"`
+        # @return [Bluebook::Adapter, nil] the claiming plugin, or nil when none claims it
+        # @raise [WiringError] if more than one plugin claims the query
+        def plugin_for(query, where)
+          return nil unless query.returns
+
+          plugins = plugins_answering(where)
+          return plugins.first if plugins.size <= 1
+
+          raise WiringError, "#{plugins.size} plugins answer #{where} (#{plugins.map(&:name).join(", ")}) — " \
+                             "the runtime will not choose: bind one in the hecksagon"
+        end
+
+        # A plugin-answered query returns a value object the aggregate declares, and the plugin's
+        # module compiles, so a missing or broken module stops the boot rather than the first ask.
+        #
+        # @raise [WiringError] if the value object is undeclared or the module will not compile
+        def check_plugin_query!(aggregate, query, where)
+          unless Value.value_object_for(aggregate, query.returns_name)
+            raise WiringError, "#{where} returns #{query.returns_name}, but #{aggregate.hecks_name} " \
+                               "declares no such value object"
+          end
+
+          WasmPlugin.compile!(plugin_for(query, where))
+        end
+      end
+    end
+  end
+end