hecks 5.0.0 → 6.0.0

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

@@ -12,7 +12,7 @@ module Hecks
   module Bluebook
     module DSL
       class BluebookBuilder
-        # Whole-chapter, cross-aggregate checks that `#build` runs once a chapter is assembled.
+        # Whole-bluebook, cross-aggregate checks that `#build` runs once a bluebook is assembled.
         # Extended onto BluebookBuilder: pure functions of their arguments, no builder state.
         # Each family of checks lives in its own module under `validation/`.
         module Validation
@@ -26,10 +26,10 @@ module Hecks
           include ComputedSources
           include CorrelationKeys
 
-          # Runs every whole-chapter check against one assembled chapter.
+          # Runs every whole-bluebook check against one assembled bluebook.
           # Public so `MetaValidator.judge_deferred!` can call it with no builder instance.
           #
-          # @param bluebook [Bluebook::Chapter] the assembled chapter to validate
+          # @param bluebook [Bluebook::Declaration] the assembled bluebook to validate
           # @return [void]
           # @raise [Bluebook::DSL::Malformed] if any check finds a violation
           # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] if a

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

@@ -5,7 +5,7 @@ module Hecks
   module Bluebook
     module DSL
       # The `Hecks.bluebook "Name" do ... end` receiver, collecting every aggregate,
-      # read model, policy and process manager a chapter declares.
+      # read model, policy and process manager a bluebook declares.
       class BluebookBuilder
         GRAMMAR_CONTEXT = "Bluebook".freeze
 
@@ -14,8 +14,8 @@ module Hecks
 
         attr_reader :classification
 
-        # @param name [String] the chapter's declared name
-        # @param version [String, nil] the chapter's pinned version, or nil for unversioned
+        # @param name [String] the bluebook's declared name
+        # @param version [String, nil] the bluebook's pinned version, or nil for unversioned
         def initialize(name, version: nil)
           @name       = name
           @version    = version
@@ -23,23 +23,23 @@ module Hecks
           @read_models      = []
           @policies         = []
           @process_managers = []
-          # The root of the chapter-wide given pool, one level wider than
+          # The root of the bluebook-wide given pool, one level wider than
           # `AggregateBuilder`'s `@entity_named_givens` (S10). See `#given` for
           # what this closes.
-          @chapter_named_givens = {}
-          # Every bare chapter-given reference left unresolved so far, threaded into
-          # every aggregate like `@chapter_named_givens`. See
-          # `AggregateBuilder#pending_chapter_given` for what queues here.
-          @chapter_pending_givens = []
-          # One level wider still — the chapter-wide, entity-scoped pool, the piece
-          # analogue of `@chapter_named_givens`. See `EntityBuilder#given_impl` and
-          # docs/implemented/resolution-rules/chapter-entity-given.md for the algorithm.
-          @chapter_entity_named_givens   = {}
-          @chapter_entity_pending_givens = []
+          @bluebook_named_givens = {}
+          # Every bare bluebook-given reference left unresolved so far, threaded into
+          # every aggregate like `@bluebook_named_givens`. See
+          # `AggregateBuilder#pending_bluebook_given` for what queues here.
+          @bluebook_pending_givens = []
+          # One level wider still — the bluebook-wide, entity-scoped pool, the piece
+          # analogue of `@bluebook_named_givens`. See `EntityBuilder#given_impl` and
+          # docs/implemented/resolution-rules/bluebook-entity-given.md for the algorithm.
+          @bluebook_entity_named_givens   = {}
+          @bluebook_entity_pending_givens = []
         end
 
-        # Chapter metadata belongs to the composed builder, not whichever file sorts
-        # first; two different versions for one chapter is a real contradiction.
+        # Bluebook metadata belongs to the composed builder, not whichever file sorts
+        # first; two different versions for one bluebook is a real contradiction.
         def adopt_version(version)
           return if version.nil?
           if @version && @version.to_s != version.to_s
@@ -51,7 +51,7 @@ module Hecks
         end
         private :adopt_version
 
-        # Records the chapter's vision statement.
+        # Records the bluebook's vision statement.
         #
         # @param value [String] the vision text, as given to `vision "..."`
         # @return [void]
@@ -59,70 +59,70 @@ module Hecks
           @vision = value
         end
 
-        # Records the chapter's earlier name, so the storage layer recognizes its history
-        # under it instead of minting a new lineage — a chapter's identity can change.
+        # Records the bluebook's earlier name, so the storage layer recognizes its history
+        # under it instead of minting a new lineage — a bluebook's identity can change.
         #
-        # @param value [String, Symbol] the chapter's earlier name
+        # @param value [String, Symbol] the bluebook's earlier name
         # @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.
+        # Names the Ruby module the bluebook's constants install under instead of its own name,
+        # such as `namespace "Hecks::Domain"` for a bluebook 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).
+        # Names a core grammar context this bluebook's sub-language extends (ADR 0026).
         # Variadic and accumulates across calls, like `identified_by`/`group_by`.
         #
         # Reached through `calls: "attaches_to_impl"`, not bootstrap-reachable — only
-        # sub-language chapters like Paging call it, never a core chapter.
+        # sub-language bluebooks like Paging call it, never a core bluebook.
         #
         # @param contexts [Array<String>] one or more core grammar context names, such as
         #   `"Query"`/`"ReadModel"`
         # @return [Array<String>] every context named so far, this call's included
         def attaches_to_impl(*contexts) = (@attaches_to ||= []).concat(contexts.map(&:to_s))
 
-        # Records a capability this chapter answers for other domains, one row per key —
-        # checked once the chapter is whole, since verbs may be declared later in the file.
+        # Records a capability this bluebook answers for other domains, one row per key —
+        # checked once the bluebook is whole, since verbs may be declared later in the file.
         #
         # @param capability [String] the capability's own name, such as `"authorization"`
         # @param verbs [Hash{Symbol => String}] one command/query reference per capability
         #   key, e.g. `grant: "RoleAssignment.Assign"`
-        # @return [Array<Bluebook::Chapter::Provision>] every provision row declared so far,
+        # @return [Array<Bluebook::Declaration::Provision>] every provision row declared so far,
         #   this capability's included
         # @raise [Bluebook::DSL::Malformed] if `verbs` is empty
         def provides_impl(capability, **verbs)
           if verbs.empty?
             raise Malformed, "#{@name}'s provides #{capability.inspect} names no verb — say which of this " \
-                             "chapter's commands and queries answer it"
+                             "bluebook's commands and queries answer it"
           end
 
-          rows = verbs.map { |key, verb| Chapter::Provision.new(capability: capability.to_s, key: key.to_s, verb: verb.to_s) }
+          rows = verbs.map { |key, verb| Declaration::Provision.new(capability: capability.to_s, key: key.to_s, verb: verb.to_s) }
           (@provides ||= []).concat(rows)
         end
 
-        # Classifies this chapter as core to the framework, rather than a domain built on it.
+        # Classifies this bluebook as core to the framework, rather than a domain built on it.
         #
         # @return [Symbol] `:core`
         def core       = @classification = :core
 
-        # Classifies this chapter as a supporting piece of the framework, rather than a domain
+        # Classifies this bluebook as a supporting piece of the framework, rather than a domain
         # built on it.
         #
         # @return [Symbol] `:supporting`
         def supporting = @classification = :supporting
 
-        # Classifies this chapter as generic infrastructure, rather than a domain built on it.
+        # Classifies this bluebook as generic infrastructure, rather than a domain built on it.
         #
         # @return [Symbol] `:generic`
         def generic    = @classification = :generic
 
-        # Declares an aggregate belonging to this chapter. `@chapter_named_givens` is
+        # Declares an aggregate belonging to this bluebook. `@bluebook_named_givens` is
         # threaded into it — see `AggregateBuilder#given` for the sharing this enables.
         #
-        # Bootstrap-reachable (every core chapter's top-level shape uses it), so also
+        # Bootstrap-reachable (every core bluebook's top-level shape uses it), so also
         # named in `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`.
         #
         # @param name [String] the aggregate's own name
@@ -131,13 +131,13 @@ module Hecks
         # @raise [Bluebook::DSL::Malformed] if the aggregate's own body fails any check
         #   `AggregateBuilder#build` raises
         def aggregate_impl(name, &)
-          @aggregates << AggregateBuilder.build(name, chapter_named_givens:          @chapter_named_givens,
-                                                      chapter_pending_givens:        @chapter_pending_givens,
-                                                      chapter_entity_named_givens:   @chapter_entity_named_givens,
-                                                      chapter_entity_pending_givens: @chapter_entity_pending_givens, &)
+          @aggregates << AggregateBuilder.build(name, bluebook_named_givens:          @bluebook_named_givens,
+                                                      bluebook_pending_givens:        @bluebook_pending_givens,
+                                                      bluebook_entity_named_givens:   @bluebook_entity_named_givens,
+                                                      bluebook_entity_pending_givens: @bluebook_entity_pending_givens, &)
         end
 
-        # Declares a read model belonging to this chapter.
+        # Declares a read model belonging to this bluebook.
         #
         # @param name [String] the read model's own name
         # @yield the read model body, evaluated against a new `ReadModelBuilder`
@@ -146,8 +146,8 @@ module Hecks
         #   raises
         def read_model(name, &)
           # A read model gathers heads from several aggregates, so no single head
-          # declares it — the chapter does. Its owner is stamped in `build`, where
-          # the chapter namespace exists.
+          # declares it — the bluebook does. Its owner is stamped in `build`, where
+          # the bluebook namespace exists.
           @read_models << ReadModelBuilder.build(name, &)
         end
 
@@ -165,17 +165,17 @@ module Hecks
           raise Malformed, "report is gone — read_model is the word now"
         end
 
-        # Declares a policy belonging to this chapter.
+        # Declares a policy belonging to this bluebook.
         #
         # @param name [String] the policy's own name
         # @yield the policy body, evaluated against a new `PolicyBuilder`
-        # @return [Array<Bluebook::Policy>] every chapter-level policy declared so far,
+        # @return [Array<Bluebook::Policy>] every bluebook-level policy declared so far,
         #   this one last
         def policy(name, &)
           @policies << PolicyBuilder.build(name, &)
         end
 
-        # Declares a process manager (saga) belonging to this chapter.
+        # Declares a process manager (saga) belonging to this bluebook.
         #
         # @param name [String] the process manager's own name
         # @yield the process manager body, evaluated against a new `ProcessManagerBuilder`
@@ -185,30 +185,30 @@ module Hecks
           @process_managers << ProcessManagerBuilder.build(name, &)
         end
 
-        # Assembles this builder's accumulated declarations into a judged `Chapter`.
+        # Assembles this builder's accumulated declarations into a judged `Bluebook`.
         #
-        # @return [Bluebook::Chapter] the built chapter, judged by the language when not
-        #   deferring across a multi-file chapter
-        # @raise [Bluebook::DSL::Malformed] if a chapter-wide given reference cannot be
+        # @return [Bluebook::Declaration] the built bluebook, judged by the language when not
+        #   deferring across a multi-file bluebook
+        # @raise [Bluebook::DSL::Malformed] if a bluebook-wide given reference cannot be
         #   resolved, if cross-construct validation fails, or if the language's own
-        #   whole-document judgment refuses the chapter
+        #   whole-document judgment refuses the bluebook
         # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] if a process
         #   manager's own structural check fails
         def build
-          # The chapter is the top of the construct chain — its constructor stamps every
+          # The bluebook is the top of the construct chain — its constructor stamps every
           # aggregate and read model with itself as owner, so `hecks_fqn` resolves by
           # walking up to it.
-          bluebook = Bluebook::Chapter.new(**chapter_identity, **chapter_constructs)
+          bluebook = Bluebook::Declaration.new(**bluebook_identity, **bluebook_constructs)
 
-          # A bare chapter-given may still be pending if a file that would resolve it
+          # A bare bluebook-given may still be pending if a file that would resolve it
           # hasn't loaded yet; deferred to `MetaValidator.judge_deferred!`, before
           # `validate_assembled!`, so nothing downstream reads an unresolved placeholder.
-          resolve_pending_chapter_givens! unless MetaValidator.deferring?
-          resolve_pending_chapter_entity_givens! unless MetaValidator.deferring?
+          resolve_pending_bluebook_givens! unless MetaValidator.deferring?
+          resolve_pending_bluebook_entity_givens! unless MetaValidator.deferring?
 
-          # A chapter may span several files; a hop/projection/event can name a construct
+          # A bluebook may span several files; a hop/projection/event can name a construct
           # not yet loaded, so this is skipped while `MetaValidator.defer` loads the
-          # chapter's files and run once by `judge_deferred!` against the whole chapter.
+          # bluebook's files and run once by `judge_deferred!` against the whole bluebook.
           self.class.validate_assembled!(bluebook) unless MetaValidator.deferring?
 
           # The language judges the bluebook last, so the meta-domain sees a fully built
@@ -217,15 +217,15 @@ module Hecks
           MetaValidator.call(bluebook)
         end
 
-        # Builds a `Chapter` from a `Hecks.bluebook "Name" do ... end` block, reusing one open
-        # builder per chapter name so several files accumulate into it rather than replacing it.
+        # Builds a `Bluebook` from a `Hecks.bluebook "Name" do ... end` block, reusing one open
+        # builder per bluebook name so several files accumulate into it rather than replacing it.
         #
-        # @param name [String] the chapter's declared name
-        # @param version [String, nil] the chapter's pinned version, or nil for unversioned
-        # @yield the chapter body; a bare constant resolves to a `ConstShim::ScopedConstant`
-        # @return [Bluebook::Chapter] the built, judged chapter
+        # @param name [String] the bluebook's declared name
+        # @param version [String, nil] the bluebook's pinned version, or nil for unversioned
+        # @yield the bluebook body; a bare constant resolves to a `ConstShim::ScopedConstant`
+        # @return [Bluebook::Declaration] the built, judged bluebook
         # @raise [Bluebook::DSL::Malformed] if `version` conflicts with an already-adopted
-        #   version, or the built chapter fails validation
+        #   version, or the built bluebook fails validation
         # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] if a process
         #   manager's structural check fails
         def self.build(name, version: nil, &block)
@@ -246,14 +246,14 @@ module Hecks
 
         private
 
-        # The chapter's own metadata.
-        def chapter_identity
+        # The bluebook's own metadata.
+        def bluebook_identity
           { name: @name, version: @version, vision: @vision, classification: @classification,
             formerly_known_as: @formerly_known_as, namespace: @namespace }
         end
 
-        # What the chapter declares: its constructs and the contexts and capabilities it names.
-        def chapter_constructs
+        # What the bluebook declares: its constructs and the contexts and capabilities it names.
+        def bluebook_constructs
           { aggregates: @aggregates, read_models: @read_models,
             policies: @aggregates.flat_map(&:policies) + @policies,
             process_managers: @process_managers,

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

@@ -28,6 +28,7 @@ module Hecks
           ["Aggregate", "attribute"] => :attribute_impl,
           ["Aggregate", "invariant"] => :invariant_impl,
           ["Aggregate", "given"] => :given_impl,
+          ["Aggregate", "acknowledges"] => :acknowledges_impl,
           ["Aggregate", "projects"] => :projects_impl,
           ["Lifecycle", "transition"] => :transition_impl,
           ["Lifecycle", "mark"] => :mark_impl,
@@ -36,6 +37,7 @@ module Hecks
           ["Bluebook", "aggregate"] => :aggregate_impl,
           ["Command", "role"] => :role_impl,
           ["Command", "provenance"] => :provenance_impl,
+          ["Command", "idempotent"] => :idempotent_impl,
           ["Command", "reference_to"] => :reference_to_impl,
           ["Command", "given"] => :given_impl,
           ["Command", "sets"] => :sets_impl,

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

@@ -0,0 +1,48 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class CommandBuilder
+        # `attribute :name, Type, sets: true`: the argument and the plain `sets :name` that a following
+        # line would record, at the same position among the command's mutations.
+        module FoldedSets
+          # Declares one argument and, with `sets: true`, the plain `sets` of the owner's field of the
+          # same name.
+          #
+          # @param name [Symbol] the argument's name
+          # @param type [Array] the type, as `attribute` takes it
+          # @param sets [Boolean] true to also record `sets name`
+          # @param options [Hash] the keywords `attribute` takes
+          # @return [void]
+          # @raise [Bluebook::DSL::Malformed] if `sets:` is anything but true
+          def attribute_impl(name, *type, sets: false, **)
+            super(name, *type, **)
+            return if sets == false
+
+            refuse_unreadable_sets_flag!(name, sets)
+            (@folded_sets ||= []) << name.to_sym
+            sets_impl(name)
+          end
+
+          private
+
+          def refuse_unreadable_sets_flag!(name, flag)
+            return if flag == true
+
+            raise Malformed, "#{@name}'s attribute :#{name} takes sets: true or no sets: at all, not #{flag.inspect}"
+          end
+
+          # Refuses an attribute that says `sets: true` where the owner has no field of that name.
+          def refuse_unowned_folded_sets!
+            missing = (@folded_sets || []).reject { |name| @owner_attributes.any? { |attr| attr.name == name } }
+            return if missing.empty?
+
+            raise Malformed,
+                  "#{@name}'s attribute#{"s" if missing.size > 1} #{missing.map { |name| ":#{name}" }.join(", ")} " \
+                  "say sets: true, but the owner declares no field of that name to set — " \
+                  "declare it on the owner, or drop sets: true"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,6 +3,7 @@ require_relative "need_word"
 require_relative "command_builder/owner"
 require_relative "command_builder/rules"
 require_relative "command_builder/mutations"
+require_relative "command_builder/folded_sets"
 require_relative "command_builder/implicit_attributes"
 require_relative "command_builder/operands"
 module Hecks
@@ -13,12 +14,17 @@ module Hecks
       class CommandBuilder
         GRAMMAR_CONTEXT = "Command".freeze
 
+        # What a second `role` declaration is refused with; `%<name>s` is the command.
+        ROLE_TWICE = "%<name>s declares role twice — a command carries one responsibility; the second would " \
+                     "silently win and the first would still look declared. Name every role in one: role \"A\", \"B\"".freeze
+
         include AttributeCollector
         include RuleReference
         include WordGate
         include NeedWord
         include ImplicitAttributes
         include Operands
+        include FoldedSets
 
         # Sentinel for "this keyword was never passed" — distinct from Ruby's own
         # nil/false, so `to: false` doesn't get treated as absent.
@@ -42,20 +48,20 @@ module Hecks
           @from = normalize_from(from)
         end
 
-        # Sets the command's one responsibility role, refusing a second declaration.
+        # Sets the role that runs the command, or the several roles any one of which may,
+        # refusing a second declaration.
         #
-        # @param value [String, Symbol] the role's name
-        # @return [Object] `value` as stored
-        # @raise [Bluebook::DSL::Malformed] if a role is already declared
-        def role_impl(value)
-          if @role
-            raise Malformed,
-                  "#{@name} declares role twice — a command carries ONE " \
-                  "responsibility; the second would silently win and the " \
-                  "first would still look declared"
-          end
-
-          @role = value
+        # With several, `role` is the first and `roles` holds them all.
+        #
+        # @param values [Array<String, Symbol>] the role names
+        # @return [Object] the first role as stored
+        # @raise [Bluebook::DSL::Malformed] if a role is already declared, or one is named twice
+        def role_impl(*values)
+          raise Malformed, format(ROLE_TWICE, name: @name) if @role
+          raise Malformed, "#{@name} names a role twice in one role declaration" if values.map(&:to_s).uniq.size != values.size
+
+          @roles = values.map(&:to_s) if values.size > 1
+          @role = values.first
         end
 
         # Sets the human-readable description shown for this command.
@@ -70,6 +76,12 @@ module Hecks
         # @return [Object] `from` as stored
         def provenance_impl(from:) = @provenance = from
 
+        # Declares the command safe to deliver twice: it leaves the same state delivered once or
+        # many times, so a saga redrive may run it again when a crash left its outcome unknown.
+        #
+        # @return [true]
+        def idempotent_impl = @idempotent = true
+
         # Declares the aggregate this command acts on (with no `as:`), or a cross-reference to
         # another aggregate (with `as:`).
         #
@@ -125,6 +137,7 @@ module Hecks
         #   state source names an undeclared field, or a delegating command also declares its
         #   own mutations or events
         def build
+          refuse_unowned_folded_sets!
           resolve_implicit_attributes!
           refuse_duplicate_targets!
           refuse_undeclared_needs!
@@ -190,13 +203,13 @@ module Hecks
         end
 
         def declared_rules
-          { name: @name, role: @role, goal: @goal, attributes: attributes, givens: @givens,
+          { name: @name, role: @role, roles: @roles || [], goal: @goal, attributes: attributes, givens: @givens,
             ensures: @ensures, needs: @needs }
         end
 
         def declared_effects
           { mutations: @mutations, emits: @emits, references: @references, from: @from,
-            provenance: @provenance }
+            provenance: @provenance, idempotent: @idempotent || false }
         end
       end
     end

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

@@ -0,0 +1,73 @@
+require_relative "../context_map"
+require_relative "../acknowledgements"
+
+module Hecks
+  module Bluebook
+    module DSL
+      # Parses a `.contextmap` file's top-level block into a {Bluebook::ContextMap}: the contexts a
+      # system holds and how pairs of them relate, written before the wiring and held against it
+      # by `model_check` (ADR 0135).
+      class ContextMapBuilder
+        # @param name [String, Symbol] the system the map covers
+        # @yield the map's body
+        # @return [Bluebook::ContextMap] the built map
+        # @raise [ArgumentError] on an unknown kind, or a relationship naming an undeclared context
+        def self.build(name, &block)
+          builder = new(name)
+          builder.instance_eval(&block) if block
+          builder.build
+        end
+
+        def initialize(name)
+          @name          = name.to_s
+          @contexts      = []
+          @relationships = []
+          @separate_ways = []
+        end
+
+        # Declares a context and, if known, the team that owns it.
+        def context(name, team: nil)
+          @contexts << ContextMap::Context.new(name: name.to_s, team: team)
+        end
+
+        # Declares that `upstream => downstream` relate as `kind`. `published:` lists the upstream
+        # events a downstream may depend on, `of:` the names a shared kernel holds in common, and
+        # `acknowledges:` the findings about the relationship it allows, each with its reason.
+        #
+        # @raise [ArgumentError] unless exactly one `"Upstream" => "Downstream"` pair is given
+        # @raise [Bluebook::DSL::Malformed] if an acknowledgement names a kind the relationship
+        #   cannot carry, or gives no reason
+        def relate(as:, published: [], of: [], acknowledges: {}, **pair)
+          raise ArgumentError, "relate takes one \"Upstream\" => \"Downstream\" pair" unless pair.size == 1
+
+          upstream, downstream = pair.first
+          @relationships << ContextMap::Relationship.new(
+            upstream: upstream.to_s, downstream: downstream.to_s, kind: as,
+            published: Array(published).map(&:to_s), shared: Array(of).map(&:to_s),
+            acknowledged: acknowledged_by("#{upstream} => #{downstream}", acknowledges)
+          )
+        end
+
+        # Declares two contexts apart: any coupling between them is an error.
+        def separate_ways(left, right)
+          @separate_ways << [left.to_s, right.to_s]
+        end
+
+        def build
+          ContextMap.new(name: @name, contexts: @contexts, relationships: @relationships,
+                         separate_ways: @separate_ways)
+        end
+
+        private
+
+        # @return [Hash{Symbol=>String}] each acknowledged kind with its reason, once all pass
+        def acknowledged_by(owner, acknowledges)
+          acknowledges.to_h do |finding, reason|
+            kind = Acknowledgements.kind!(owner, finding, reason, among: Acknowledgements::RELATIONSHIP_KINDS)
+            [kind, reason]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -2,11 +2,11 @@ module Hecks
   module Bluebook
     module DSL
       class EntityBuilder
-        # The rule words of a piece: `given` preconditions, shared across the chapter by
+        # The rule words of a piece: `given` preconditions, shared across the bluebook by
         # description, and per-instance `invariant`s.
         module Rules
           # Declares a rule this piece's own commands must satisfy, or references one a sibling
-          # piece anywhere in the chapter already declared.
+          # piece anywhere in the bluebook already declared.
           #
           # Order doesn't matter: `command` only queues a descriptor here and builds for real at
           # `#drain_pending!` time, after every `given` in this block has already run.
@@ -18,7 +18,7 @@ module Hecks
           # @raise [Bluebook::DSL::Malformed] if the rule's source cannot be extracted, or a
           #   reference is ambiguous
           def given_impl(description, declared_by: nil, &predicate)
-            return reference_named_chapter_entity_given(description, declared_by: declared_by) unless predicate
+            return reference_named_bluebook_entity_given(description, declared_by: declared_by) unless predicate
 
             named = build_rule(Given, description, predicate, owner_name: @name, word: "given",
                                 extraction_failure: "its source could not be read, so no other runtime could ever evaluate it")
@@ -26,11 +26,11 @@ module Hecks
             # First-declared-wins (`||=`): a second piece under the same aggregate declaring
             # the exact same description independently stays local, never silently overwritten.
             @owner_named_givens[description] ||= named
-            # Chapter-wide analogue of the line above, keyed by "Aggregate.Entity" rather than
+            # Bluebook-wide analogue of the line above, keyed by "Aggregate.Entity" rather than
             # description alone, so two different pieces sharing a description stay distinct
             # candidates a later bare reference chooses between via `declared_by:`.
-            @chapter_entity_named_givens[description] ||= {}
-            @chapter_entity_named_givens[description]["#{@aggregate_name}.#{@name}"] ||= named
+            @bluebook_entity_named_givens[description] ||= {}
+            @bluebook_entity_named_givens[description]["#{@aggregate_name}.#{@name}"] ||= named
           end
 
           # Declares a rule every instance of this piece must satisfy — checked per instance,
@@ -48,12 +48,12 @@ module Hecks
 
           private
 
-          # Resolves a bare `given` reference against the chapter-wide, entity-scoped pool.
+          # Resolves a bare `given` reference against the bluebook-wide, entity-scoped pool.
           # Also writes through to `@owner_named_givens`, not just `@named_givens` — otherwise a
           # sibling piece's own same-aggregate bare reference would never see this resolution.
-          def reference_named_chapter_entity_given(description, declared_by:)
+          def reference_named_bluebook_entity_given(description, declared_by:)
             verify_resolves_via!("given", "Entity", "owner_keyed")
-            candidates = resolve_owner_keyed(@chapter_entity_named_givens, description)
+            candidates = resolve_owner_keyed(@bluebook_entity_named_givens, description)
 
             named = pick_entity_given(candidates, description, declared_by)
             @named_givens[description] = named
@@ -63,29 +63,29 @@ module Hecks
           def pick_entity_given(candidates, description, declared_by)
             return declared_entity_given(candidates, description, declared_by) if declared_by
             return candidates.values.first if candidates.size == 1
-            return pending_chapter_entity_given(description, declared_by: nil) if candidates.empty?
+            return pending_bluebook_entity_given(description, declared_by: nil) if candidates.empty?
 
             raise Malformed, ambiguous_entity_given_message(candidates, description)
           end
 
           def declared_entity_given(candidates, description, declared_by)
-            candidates[declared_by] || pending_chapter_entity_given(description, declared_by: declared_by)
+            candidates[declared_by] || pending_bluebook_entity_given(description, declared_by: declared_by)
           end
 
           def ambiguous_entity_given_message(candidates, description)
             "#{@aggregate_name}::#{@name}'s given #{description.inspect} is ambiguous " \
-              "across the chapter's own pieces — #{candidates.keys.join(", ")} each declare " \
+              "across the bluebook's own pieces — #{candidates.keys.join(", ")} each declare " \
               "a DIFFERENT predicate under this same description; name which one with " \
               "declared_by: (e.g. given(#{description.inspect}, declared_by: " \
               "#{candidates.keys.first.inspect}))"
           end
 
-          # A chapter may be split across files, so an unresolved bare reference defers rather
-          # than raising immediately; `BluebookBuilder#resolve_pending_chapter_entity_givens!`
-          # fills in the placeholder once every file in the chapter has loaded.
-          def pending_chapter_entity_given(description, declared_by:)
+          # A bluebook may be split across files, so an unresolved bare reference defers rather
+          # than raising immediately; `BluebookBuilder#resolve_pending_bluebook_entity_givens!`
+          # fills in the placeholder once every file in the bluebook has loaded.
+          def pending_bluebook_entity_given(description, declared_by:)
             placeholder = Given.new(description: description, canonical: nil, predicate: nil)
-            @chapter_entity_pending_givens << { entity: "#{@aggregate_name}.#{@name}", description: description,
+            @bluebook_entity_pending_givens << { entity: "#{@aggregate_name}.#{@name}", description: description,
                                                  declared_by: declared_by, placeholder: placeholder }
             placeholder
           end