hecks 2.8.0 → 3.0.0

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

@@ -3,30 +3,20 @@ require_relative "../../bluebook/hexagon"
 module Hecks
   module Runtime
     class Registry
-      # The wiring gate: every bind names a declared aggregate, every
-      # adapter satisfies the verb its port declares, every world setting is
-      # a field the adapter admits, and the default adapter is usable at
-      # all. Included into Registry — `verify!` is what a boot calls after
-      # loading, and the smaller checks are also called piecemeal by the
-      # repository factory.
+      # The wiring gate: every bind names a declared aggregate, every adapter satisfies its
+      # port's verb, and every world default is usable. `verify!` runs it all at boot.
       module Verification
-        # Runs the whole wiring gate against this registry's loaded bluebooks,
-        # hexagons, ports and adapters.
-        #
-        # @return [Runtime::Registry] self
-        # @raise [Runtime::WiringError] if a bind names an undeclared aggregate, an
-        #   adapter cannot satisfy its port's verb or declared `answers`, a world
-        #   setting names a field its adapter does not declare, the default adapter
-        #   is unusable, a world's `default_adapter` is not a persistence adapter, a
-        #   command declares a role with no authorization provider attached, or a
-        #   membership chapter is loaded with no identity chapter
+        # Runs every wiring check against this registry's loaded bluebooks, hexagons, ports
+        # and adapters.
         def verify!
           verify_default_adapter!
           verify_world_defaults!
           verify_singleton_port_answers!
           refuse_cross_package_bluebook_merge!
+          refuse_reserved_chapter_names!
           refuse_membership_without_identity!
           refuse_unresolved_port_operations!
+          refuse_unanswerable_queries!
 
           @hecksagons.each_value do |hexagon|
             refuse_ungoverned_roles!(hexagon)
@@ -35,19 +25,9 @@ module Hecks
             refuse_bounded_without_acl!(hexagon)
 
             hexagon.binds.each do |bind|
-              # A domain-level default (§0) — `persisted_by "Heki"` bare,
-              # applying to whichever aggregates don't override it — names
-              # no aggregate of its own, so there's nothing to look up in
-              # the bluebook for this row specifically. Still validate its
-              # own adapter/verb shape (the same reason
-              # `verify_default_adapter!` checks the framework-wide
-              # default the same way, aggregate-less). Coverage of real
-              # aggregates that only resolve through this default comes
-              # from their own dispatch-time `BindingPolicy.resolve` —
-              # deliberately not required to be exhaustive here, the same
-              # leniency this method already extended to any aggregate
-              # left out of an explicit bind list entirely (real test
-              # fixtures bind only the aggregates they exercise).
+              # A domain-level default (§0) names no aggregate of its own; still validate its
+              # adapter/verb shape. Real aggregates resolving through it are covered by their
+              # own dispatch-time `BindingPolicy.resolve`, not required to be exhaustive here.
               if bind.aggregate.nil?
                 check_verb(bind)
                 next
@@ -67,13 +47,7 @@ module Hecks
           self
         end
 
-        # Checks that the framework-wide default persistence adapter (used by any
-        # aggregate left out of an explicit bind list) is itself wired correctly.
-        #
-        # @return [Runtime::Registry] self
-        # @raise [Runtime::WiringError] if the default adapter cannot satisfy the
-        #   persistence port's verb, is missing a declared `answers` method, or has
-        #   no Ruby implementation
+        # Checks that the framework-wide default persistence adapter is itself wired correctly.
         def verify_default_adapter!
           name = Ports::Persistence::DEFAULT_ADAPTER
 
@@ -92,14 +66,7 @@ module Hecks
                 "aggregate with no bind could not be given one: #{e.message}"
         end
 
-        # Checks that `bind`'s adapter implements the port it names and satisfies
-        # the verb the bind declares.
-        #
-        # @param bind [Bluebook::Bind] the bind to check
-        # @return [void]
-        # @raise [Runtime::WiringError] if `bind`'s adapter is unknown, declares an
-        #   unknown port, is missing a declared `answers` method, or cannot satisfy
-        #   `bind`'s own verb
+        # Checks that `bind`'s adapter implements the port it names and satisfies its verb.
         def check_verb(bind)
           port = port_for(bind)
           check_answers(port, bind.adapter)
@@ -110,20 +77,8 @@ module Hecks
                 "and cannot satisfy #{bind.verb}"
         end
 
-        # The method contract a `.port` file's `verb`/`signal` never
-        # carried — an adapter can name the right port, satisfy the right
-        # verb, and admit every `.world` setting `check_settings` checks,
-        # and still be missing the one method a live dispatch will
-        # actually call. `answers` is optional per port (an empty list is
-        # today's pre-existing behavior, unchecked), so this only ever
-        # tightens a port that opted in.
-        #
-        # @param port [Bluebook::Port] the port whose declared `answers` methods
-        #   `adapter_name` must respond to
-        # @param adapter_name [String] the adapter's declared name to check
-        # @return [void]
-        # @raise [Runtime::WiringError] if `adapter_name` has no Ruby implementation,
-        #   or its implementation does not respond to one of `port.answers`
+        # `answers` is optional per port, so an adapter can satisfy a port's verb and still
+        # miss a method live dispatch will call; this only tightens ports that opt in.
         def check_answers(port, adapter_name)
           answers = Array(port.answers)
           return if answers.empty?
@@ -138,27 +93,19 @@ module Hecks
                 "#{answers.map(&:inspect).join(', ')}"
         end
 
-        # **The nine singleton ports' own gap** — `persistence`, `projection`
-        # and `loading` are per-aggregate bindings, checked above through
-        # every real `bind` a hexagon declares; a singleton port
-        # (`clock`, `authorization`, …) is never bound to an aggregate at
-        # all, so nothing above ever resolves one and nothing above ever
-        # ran `check_answers` against it. Each one's own `Ports::*.adapter`
-        # already refuses zero or multiple implementations, live, at
-        # first dispatch — that stays exactly as-is here (0 or 2+ is
-        # ambiguity, not a method-contract question, and asserting every
-        # declared port must have exactly one adapter would wrongly
-        # refuse a boot that simply never wires a port it doesn't use).
-        # This only ever tightens the one case those checks don't cover:
-        # exactly one adapter, wired, missing a method `answers` names.
+        # persistence/projection/loading are per-aggregate bound and already checked via
+        # each bind above; a singleton port is never bound to an aggregate at all.
         PER_AGGREGATE_PORTS = %w[persistence projection loading].freeze
 
-        # Checks every singleton port (not per-aggregate-bound) with exactly one
-        # wired adapter against its own declared `answers` methods.
-        #
-        # @return [Runtime::Registry] self
-        # @raise [Runtime::WiringError] if a singleton port's one wired adapter is
-        #   missing one of its declared `answers` methods
+        # The directory holding the gem's own Hecks chapter, the only place a chapter named
+        # `Hecks` may be declared from.
+        GEM_CHAPTER_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
+
+        # Checks every singleton port with exactly one wired adapter against its own
+        # declared `answers` methods.
         def verify_singleton_port_answers!
           @ports.each_value do |port|
             next if PER_AGGREGATE_PORTS.include?(port.name)
@@ -172,16 +119,8 @@ module Hecks
           self
         end
 
-        # Checks that every setting `settings` declares (besides `:adapter`) is a
-        # field `bind`'s adapter actually admits.
-        #
-        # @param bind [Bluebook::Bind] the bind naming the adapter to check against;
-        #   a no-op if its adapter is unknown
-        # @param settings [Hash{Symbol => Object}] the world's declared settings for
-        #   this bind
-        # @return [void]
-        # @raise [Runtime::WiringError] if `settings` declares a field `bind`'s
-        #   adapter does not declare
+        # Checks that every setting `settings` declares (besides `:adapter`) is a field
+        # `bind`'s adapter actually admits.
         def check_settings(bind, settings)
           adapter = @adapters[bind.adapter]
           return unless adapter
@@ -196,12 +135,6 @@ module Hecks
                 "Add the field to the adapter, or remove it from the world."
         end
 
-        # Finds the port `bind`'s adapter declares.
-        #
-        # @param bind [Bluebook::Bind] the bind naming the adapter to look up
-        # @return [Bluebook::Port] the port `bind`'s adapter declares
-        # @raise [Runtime::WiringError] if `bind` names an unknown adapter, or one
-        #   declaring an unknown port
         def port_for(bind)
           adapter = @adapters[bind.adapter]
           raise WiringError, "unknown adapter #{bind.adapter.inspect}" unless adapter
@@ -210,12 +143,6 @@ module Hecks
             raise(WiringError, "adapter #{bind.adapter} declares unknown port #{adapter.port.inspect}")
         end
 
-        # Finds the Ruby module implementing the adapter declared `name`.
-        #
-        # @param name [String] the adapter's declared name, such as `"PostgresEra"`
-        # @return [Module] the adapter module or class under `Hecks::Adapters`
-        # @raise [Runtime::WiringError] if no Ruby implementation named `name` exists
-        #   under `Hecks::Adapters`
         def adapter_class(name)
           Adapters.const_get(name)
         rescue NameError
@@ -225,33 +152,10 @@ module Hecks
 
         private
 
-        # `role` is real access control only when governance can check it
-        # against something — a command that declares a role but whose
-        # domain never attaches Governance would leave that role forever
-        # unchecked, exactly the defect ADR 0025 §9 names ("role gates
-        # access control by exact string equality ... Governance ...
-        # connected to none of it"). Checked here, at `verify!` — recovered
-        # and moved, not new: running this per-block, at hecksagon
-        # build time (Bluebook::DSL::HecksagonBuilder#build), breaks
-        # the moment a domain is split across multiple hecksagon
-        # blocks (base + an `environments/<name>.hecksagon` overlay,
-        # Runtime::Loader.boot's `environment:` — see its own comment for
-        # the recovery provenance): every block but the one declaring
-        # `uses_framework "Governance"` would be refused there, even
-        # though `Registry#add_hecksagon` merges every block for a domain
-        # into one Hecksagon before anything ever dispatches against it.
-        # Checking the merged result once, here, after every file for
-        # this domain has loaded, is both more permissive (no need to
-        # repeat `uses_framework` in every file) and strictly more
-        # correct (a check against an incomplete, not-yet-merged
-        # hecksagon can never see the real final shape).
-        #
-        # A provider is recognised by its declaration, not its name —
-        # `authorization_provider_for` answers for the domain's own
-        # chapter too, so Governance (which declares `provides
-        # "authorization"`) passes here because of what it declares, and
-        # the same rule `CommandRules::Authorization#governance_attached?`
-        # applies at dispatch time.
+        # Checked once against the merged hecksagon so a domain split across multiple
+        # hecksagon files sees every uses_framework declaration first. A role is real
+        # access control only once an authorization provider exists to check it against
+        # (ADR 0025); a provider is recognized by declaring authorization, not by name.
         def refuse_ungoverned_roles!(hexagon)
           return if authorization_provider_for(hexagon.domain)
 
@@ -268,15 +172,9 @@ module Hecks
                 "without that it is silent decoration, the exact defect this refusal exists to catch"
         end
 
-        # A vendored embryonaut bluebook is a bounded context, not a pile of
-        # types the consumer inlines. `uses_embryonaut_bluebook` only loads
-        # the package's `.bluebook` files — persistence, Governance, and the
-        # anti-corruption layer (`translates` field mapping) live on a named
-        # sibling hecksagon the consumer must declare. Without that hexagon
-        # the package has no wiring of its own, and cross-context field
-        # mapping has nowhere to be written. Breaking in 2.0: attaching a
-        # vendored chapter without `Hecks.hecksagon "PackageName"` refuses
-        # at boot rather than silently sharing the consumer's hexagon.
+        # `uses_embryonaut_bluebook` only loads a package's `.bluebook` files; persistence,
+        # Governance and the `translates` ACL live on a sibling hecksagon the consumer must
+        # declare, or cross-context field mapping has nowhere to be written.
         def refuse_unwired_vendored_bluebooks!(hexagon)
           Array(hexagon.vendored_bluebooks).each do |package|
             chapter_name = Naming.pascal(package)
@@ -291,16 +189,14 @@ module Hecks
           end
         end
 
-        # Same gate as vendored packages: `uses_framework` loads a bounded
-        # context, and the consumer must declare the sibling hecksagon that
-        # is its ACL. Governance/Identity/Privacy already follow this in
-        # every real consumer; boot now refuses a silent miss.
+        # `uses_framework` and `attaches` load a bounded context; the consumer must declare the
+        # sibling hecksagon that is its ACL (Governance/Identity/Privacy already do).
         def refuse_unwired_framework_members!(hexagon)
-          Array(hexagon.framework_members).each do |member|
+          hexagon.member_chapters.each do |member|
             next if hecksagon(member)
 
             raise WiringError,
-                  "#{hexagon.domain} attaches framework member #{member.inspect} " \
+                  "#{hexagon.domain} attaches #{member.inspect} " \
                   "(bounded context) but never declared Hecks.hecksagon " \
                   "#{member.inspect} — put that sibling (and any `translates` " \
                   "ACL) in context_map.hecksagon; same-name blocks merge, " \
@@ -308,19 +204,12 @@ module Hecks
           end
         end
 
-        # An explicit `bounded` mark on a consumer chapter always needs an
-        # ACL — at least one `translates` block. Any field can be mapped;
-        # the BC does not list which. `uses_framework` / `uses_embryonaut_bluebook`
-        # mark the attached chapter bounded (module wrap, no Object shortcut)
-        # and require the sibling hecksagon above; they do not require a
-        # `translates` on that sibling unless the consumer also wrote `bounded`.
-        # rust/host Google sign-in reads `ir.json`'s `membership` and
-        # `identity` keys (Exporter.membership / Exporter.identity) —
-        # never a deploy-time env var. Membership without Identity is
-        # the exact gap that produced a live `google_unlinked` after a
-        # successful Google handshake: provision cannot Register/Link.
-        # Refuse at Ruby boot (and project_rust, which exports the same
-        # pair) so a missing sibling cannot ship.
+        # An explicit `bounded` mark on a consumer chapter always needs an ACL. `uses_framework`
+        # / `uses_embryonaut_bluebook` mark the attached chapter bounded and require 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 @bluebooks.values.any? { |chapter| chapter.provides?(Bluebook::Capabilities::MEMBERSHIP) }
           return if @bluebooks.values.any? { |chapter| chapter.provides?(Bluebook::Capabilities::IDENTITY) }
@@ -333,11 +222,8 @@ module Hecks
                 "identity verbs are exported onto ir.json, not guessed at deploy."
         end
 
-        # A `provides` row whose contract kind is `:port_operation` names an
-        # operation the chapter's hecksagon declares, and the hecksagon
-        # attaches after the chapter is built, so this is the first point the
-        # operation can be checked. Without it, a host reading the declared
-        # verb would dispatch to an operation nothing declares.
+        # A hecksagon attaches after its chapter builds, so this is the first point a
+        # declared `:port_operation` capability can be checked against it.
         def refuse_unresolved_port_operations!
           @bluebooks.each_value do |chapter|
             chapter.provides.each do |row|
@@ -352,12 +238,130 @@ module Hecks
           end
         end
 
-        # Says whether a chapter declares the port operation an
-        # `"Aggregate.Port.Operation"` verb names.
-        #
-        # @param chapter [Bluebook::Chapter] the chapter whose aggregates' ports are searched
-        # @param verb [String] the verb, spelled `"Aggregate.Port.Operation"`
-        # @return [Boolean] whether that aggregate has that port with that operation
+        # A query has exactly one answer path. It is derivable when the bluebook says which of the
+        # aggregate's own records it wants (a where, order_by, limit or offset, or no arguments at
+        # all: the plain list) and returns no value object of its own; it is bound when it
+        # `returns` a value object and the hecksagon names the port whose adapter answers it. None
+        # of the two is "no answer path"; both is "two answer paths". A bound query also needs an
+        # adapter behind its port that implements it, found here so it fails at boot rather than
+        # on the first ask.
+        def refuse_unanswerable_queries!
+          @bluebooks.each_value do |chapter|
+            chapter.aggregates.each do |aggregate|
+              refuse_misbound_queries!(chapter, aggregate)
+
+              aggregate.queries.each { |query| refuse_answer_paths!(chapter, aggregate, query) }
+              aggregate.entities.each do |entity|
+                entity.queries.each { |query| refuse_entity_answer_path!(chapter, aggregate, entity, query) }
+              end
+            end
+          end
+        end
+
+        # Counts the query's answer paths (the bindings, plus the derived answer when it exists)
+        # and refuses any count but one, then checks a bound query's shape and adapter.
+        def refuse_answer_paths!(chapter, aggregate, query)
+          where  = "#{chapter.name}::#{aggregate.hecks_name}.#{query.hecks_name}"
+          ports  = aggregate.query_bindings(query.hecks_name)
+          paths  = ports.size + (derivable?(query) ? 1 : 0)
+
+          if paths > 1
+            raise WiringError, "#{where} has two answer paths: #{answer_path_names(query, ports)} — " \
+                               "a query is answered from records or from outside, not both"
+          end
+          return check_bound_query!(chapter, aggregate, query, ports.first) if ports.any?
+          return if paths == 1
+
+          raise WiringError, no_answer_path_message(chapter, aggregate, query, where)
+        end
+
+        # A query that returns nothing and says something about which records it wants, or wants
+        # all of them. One that takes arguments but filters, orders and bounds nothing reads none
+        # of them, so it derives no answer.
+        def derivable?(query)
+          return false if query.returns
+
+          filters_records?(query) || query.attributes.empty?
+        end
+
+        def answer_path_names(query, ports)
+          names = ports.map { |port| "the #{port.name} port" }
+          names.unshift("its records") if derivable?(query)
+          names.join(" and ")
+        end
+
+        def no_answer_path_message(chapter, aggregate, query, where)
+          if query.returns
+            "#{where} has no answer path: it returns #{query.returns}, which only an adapter can " \
+              "answer, and no hecksagon port binds it. Bind it: `#{chapter.name}::#{aggregate.hecks_name}" \
+              ".port \"Port\" do answers_query \"#{query.hecks_name}\" end`."
+          else
+            "#{where} has no answer path: it declares no where and returns nothing, and no hecksagon " \
+              "binds it — its arguments (#{query.attributes.map(&:name).join(', ')}) select nothing. " \
+              "Add a where, or declare what it returns and bind it in the hecksagon."
+          end
+        end
+
+        # Checks what a binding needs to be answerable: a returned value object the aggregate
+        # declares, and one adapter behind the port that implements the query's method.
+        def check_bound_query!(chapter, aggregate, query, port)
+          where = "#{chapter.name}::#{aggregate.hecks_name}.#{query.hecks_name}"
+          unless query.returns
+            raise WiringError, "#{where} is bound to the #{port.name} port but returns nothing — " \
+                               "declare the value object its answer takes with `returns`"
+          end
+          if filters_records?(query)
+            raise WiringError, "#{where} has two answer paths: it is bound to the #{port.name} port but " \
+                               "also declares where, order_by or limit over stored records"
+          end
+          if query.authorization
+            raise WiringError, "#{where} is bound to the #{port.name} port but declares authorize — " \
+                               "an outside answer is never tenant-scoped or authorized, so drop the " \
+                               "authorize or answer the query from records"
+          end
+          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
+
+          klass = AdapterLookup.adapter_class(self, port.name, asked: where)
+          AdapterLookup.check_answers!(klass, port.name, Naming.snake(query.hecks_name), query, asked: where)
+        end
+
+        # An entity's query reads the elements of its aggregate's list, and nothing outside can
+        # be bound to one, so declaring a value object to return leaves it no answer.
+        def refuse_entity_answer_path!(chapter, aggregate, entity, query)
+          where = "#{chapter.name}::#{aggregate.hecks_name}.#{entity.hecks_name}.#{query.hecks_name}"
+          if query.returns
+            raise WiringError, "#{where} has no answer path: it returns #{query.returns}, but " \
+                               "only an aggregate's queries can be bound to a port"
+          end
+          return if derivable?(query)
+
+          raise WiringError, "#{where} has no answer path: it declares no where and returns nothing — its " \
+                             "arguments (#{query.attributes.map(&:name).join(', ')}) select nothing"
+        end
+
+        # Refuses a binding that names a query its aggregate does not declare, or names one twice
+        # on a single port (the DSL already refuses that, so this guards a hand-built port).
+        def refuse_misbound_queries!(chapter, aggregate)
+          aggregate.ports.each do |port|
+            names = port.answered_queries.map(&:name)
+            names.each do |name|
+              where = "#{chapter.name}::#{aggregate.hecks_name}.#{name}"
+              unless aggregate.query(name)
+                raise WiringError, "the #{port.name} port binds #{where}, which the aggregate does not declare"
+              end
+              raise WiringError, "#{where} has two answer paths: the #{port.name} port twice" if names.count(name) > 1
+            end
+          end
+        end
+
+        # A query that says anything about which stored records it wants.
+        def filters_records?(query)
+          !(query.wheres.empty? && query.order_by.nil? && query.limit.nil? && query.offset.nil?)
+        end
+
         def port_operation_declared?(chapter, verb)
           aggregate_name, port_name, operation_name = verb.split(".", 3)
           ports = chapter.aggregate(aggregate_name)&.ports || []
@@ -377,8 +381,8 @@ module Hecks
                 "with: { ... } end` (any field) or drop `bounded`."
         end
 
-        # The suggestion, derived from whichever framework members actually
-        # declare `provides "authorization"` — never a hardcoded name.
+        # Derived from whichever framework members actually declare `provides
+        # "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?
@@ -386,30 +390,43 @@ module Hecks
           providers.map { |name| "uses_framework #{name.inspect}" }.join(" or ")
         end
 
-        # Every command this domain declares, an aggregate's own and every
-        # entity nested inside one — the same reach `refuse_role_mismatch`
-        # itself needs at dispatch time, just walked ahead of time here.
+        # Every command this domain declares, an aggregate's own and every entity nested
+        # inside one — the same reach dispatch-time role checking needs.
         def commands_in(bluebook_ir)
           bluebook_ir.aggregates.flat_map { |aggregate| aggregate.commands + aggregate.entities.flat_map(&:commands) }
         end
 
-        # Two unrelated packages, one chapter name by coincidence — the
-        # real risk `Registry#bluebook_sources` exists to catch (found
-        # live: a stale `vendor/hecksagain` fork's own copy of Governance/
-        # Identity/Deploy, still reachable on 4 consuming apps' own load
-        # paths alongside the real gem). `BluebookBuilder.build`'s own
-        # accumulation (several files declaring the same chapter name on
-        # purpose — `lib/hecks/language/bluebook/*.bluebook` all open
-        # `Hecks.bluebook "Bluebook"`) is never touched here — that merge
-        # stays unconditional, checked only after every file has loaded,
-        # the same "check the merged final result once" timing
-        # `refuse_ungoverned_roles!` already uses and for the same reason
-        # (a check against an incomplete load can never see the real
-        # shape). What distinguishes intentional accumulation from
-        # coincidence is package root, not file identity: files a real
-        # gemspec or a `vendor/` boundary already treats as one unit are
-        # expected to share a name; files from two different roots never
-        # legitimately do.
+        # 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.
+        #
+        # @raise [WiringError] naming the reserved word and the offending file(s)
+        def refuse_reserved_chapter_names!
+          RESERVED_CHAPTER_NAMES.each do |reserved|
+            next unless @bluebooks.key?(reserved)
+
+            sources = Array(@bluebook_sources[reserved]).compact
+            foreign = sources.reject { |path| gem_chapter_source?(path) }
+            next if foreign.empty? && !sources.empty?
+
+            where = foreign.empty? ? "" : " (declared in #{foreign.join(', ')})"
+            raise WiringError,
+                  "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 " \
+                  "`Hecks.bluebook #{reserved.inspect}` line and in its hecksagon."
+          end
+        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}/")
+        end
+
+        # Two packages can share a chapter name by coincidence (found live: a stale
+        # vendor/hecksagain fork of Governance/Identity/Deploy, still on 4 apps' load
+        # paths). Intentional accumulation (several files declaring the same chapter 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!
           @bluebook_sources.each do |name, paths|
             roots = paths.map { |path| package_root_for(path) }.uniq
@@ -424,15 +441,9 @@ module Hecks
           end
         end
 
-        # The nearest boundary a path already belongs to — a real
-        # gemspec (this is a package, whatever depends on it or vendors
-        # it), or a bare `vendor/` path component, treated as its own
-        # root regardless of what gemspec might sit above it: vendored
-        # code should never be considered "the same package" as whatever
-        # it's vendored into, even when nothing else marks the boundary.
-        # Neither found, the path's own directory is the root — two
-        # files with no closer marker only "belong together" if they are
-        # literally the same file.
+        # The nearest boundary a path belongs to: a real gemspec, or a bare `vendor/`
+        # component (vendored code is never "the same package" as what vendors it).
+        # Falls back to the path's own directory when neither is found.
         def package_root_for(path)
           return path.to_s if path.nil?
 
@@ -448,37 +459,10 @@ module Hecks
           end
         end
 
-        # A domain that declares a `process_manager` but whose
-        # `saga_persistence` resolves to `NULL_SAGA_STORE` (no anchor
-        # aggregate, a RemoteRuntime-shaped adapter, an adapter that
-        # doesn't `respond_to?(:save_saga)`, or a rescued WiringError —
-        # see `SagaPersistence#resolve_saga_persistence`) gets sagas that
-        # advance correctly in-process and vanish on restart: no
-        # checkpoint written, nothing for `rehydrate_sagas!` to find, no
-        # compensation ever replayed. That is silent right up until the
-        # process actually dies mid-saga — the same "consistency/
-        # freshness defect applied to access control, failing open" ADR
-        # 0025 named for an unchecked `role`, here applied to saga
-        # durability instead.
-        #
-        # A warning, not a refusal — unlike `refuse_ungoverned_roles!`,
-        # running sagas on a store with no `save_saga` is legitimate on
-        # purpose in a fast in-memory test/dev boot (this project's own
-        # `saga_durability_spec.rb` boots a process manager on `Memory`
-        # specifically to exercise the saga_mutex without real I/O), so
-        # refusing the boot outright would break a choice an author made
-        # deliberately. What a deploy needs is for the gap to be loud and
-        # undeniable, not for local dev/test to become impossible.
-        # The outbox's twin of `warn_undurable_sagas!` — a domain that
-        # declares anything a commit could owe a reaction to (a policy
-        # listening to one of its events, or a process manager) but is
-        # bound to an adapter with no outbox (`AppendOnly#outbox?`) gets
-        # reactions the pre-outbox way: run inline, lost on a crash
-        # between commit and reaction. A warning, not a refusal, for the
-        # reason `warn_undurable_sagas!` gives — and Memory has an outbox
-        # (in-process, like everything else it holds), so a dev/test
-        # boot stays quiet; this speaks up for the file/remote adapters
-        # that persist state durably but hand reactions to nothing.
+        # A domain with policies/a process_manager but no outbox on its bound adapter
+        # (`AppendOnly#outbox?`) runs reactions inline — lost on a crash between a
+        # commit and its reaction. A warning, not a refusal: Memory has an in-process
+        # outbox, so dev/test stays quiet, but file/remote adapters need this to be loud.
         def warn_undurable_outbox!(hexagon)
           bluebook_ir = bluebook(hexagon.domain)
           return unless bluebook_ir
@@ -505,6 +489,8 @@ module Hecks
           @bluebooks.each_value.any? { |candidate| candidate.policies.any? { |policy| emitted.include?(policy.event_name.to_s) } }
         end
 
+        # A warning, not a refusal: running sagas on a store with no `save_saga` is
+        # legitimate on purpose in a fast in-memory test/dev boot.
         def warn_undurable_sagas!(hexagon)
           bluebook_ir = bluebook(hexagon.domain)
           return unless bluebook_ir