hecks 5.0.0 → 7.0.0

data/lib/hecks/bluebook/dsl/aggregate_builder/one_of_reference.rb

@@ -0,0 +1,54 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class AggregateBuilder
+        # `reference_to one_of(A, B), as: :subject`: a tagged reference to one of a closed union of
+        # aggregates (ADR 0127), minted from words the language already has. The aggregate gains a
+        # closed set of the variants' names and a value object holding the chosen `type` and `id`.
+        module OneOfReference
+          private
+
+          # Mints the closed set, the tagged value object and the attribute for one union.
+          #
+          # @param union [AttributeCollector::OneOf] the variants, written as bare constants
+          # @param as [Symbol, nil] the attribute's name; required, since a union has no one name
+          # @param optional [Boolean] whether the reference may be absent
+          # @return [void]
+          # @raise [Bluebook::DSL::Malformed] without `as:`, or with under two distinct variants
+          def one_of_reference(union, as:, optional:)
+            variants = union.values.map { |variant| Naming.demodulise(variant).to_s }
+            refuse_unfit_union!(variants, as)
+            install_union_shapes(Naming.pascal(as), variants)
+            refuse_duplicate_attribute!(as.to_sym)
+            attributes << Attribute.new(name: as, type: Naming.pascal(as), optional: optional, relationship: OneOfUnion::RELATIONSHIP)
+          end
+
+          def install_union_shapes(tagged, variants)
+            closed_sets << union_type_set("#{tagged}Type", variants) << tagged_reference(tagged, "#{tagged}Type")
+            @reference_targets.concat(variants)
+          end
+
+          def refuse_unfit_union!(variants, as)
+            listed = variants.join(", ")
+            raise Malformed, "#{@name}'s reference_to one_of(#{listed}) needs as: — a union has no one name" unless as
+            return if variants.uniq.size == variants.size && variants.size >= 2
+
+            raise Malformed, "#{@name}.#{as}'s one_of names #{listed} — a union names two or more distinct aggregates"
+          end
+
+          # The closed set of the variants' names, which the tagged value object's `type` admits.
+          def union_type_set(name, variants)
+            ValueObject.declare(name: name, attributes: [Attribute.new(name: :value, type: "String")],
+                                members: variants.map { |variant| { value: variant } }, closed_set: true)
+          end
+
+          # The stored shape: which aggregate (`type`) and which of its records (`id`).
+          def tagged_reference(name, type_set)
+            type = Attribute.new(name: :type, type: "String", admits: "#{@name}::#{type_set}")
+            ValueObject.declare(name: name, attributes: [type, Attribute.new(name: :id, type: "String")])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/aggregate_builder/query_field_sealing.rb

@@ -7,6 +7,15 @@ module Hecks
         QueryScope = Struct.new(:owner, :query, :fields, :lifecycle) do
           # @return [String] how a refusal names this query: `Owner.QueryName`
           def label = "#{owner}.#{query.hecks_name}"
+
+          # @return [Symbol, String, nil] the owner's lifecycle state field, or `nil` without one
+          def lifecycle_field = lifecycle&.field
+
+          # @return [Boolean] whether the query declares `cursor`
+          def cursor? = !query.cursor.nil?
+
+          # @return [Boolean] whether the owner is an entity (`Aggregate::Entity`), not an aggregate
+          def entity? = owner.to_s.include?("::")
         end
         private_constant :QueryScope
 
@@ -33,7 +42,7 @@ module Hecks
           end
 
           def resolvable_query_field?(scope, name, nested, attribute)
-            return scope.lifecycle&.field.to_s == name if nested.empty?
+            return scope.lifecycle_field.to_s == name if nested.empty?
 
             attribute && scalar_path?(attribute, nested)
           end
@@ -59,7 +68,7 @@ module Hecks
           # ORDER BY refuses a hop outright: a hop answers with a candidate set, not a sort key.
           #
           # A where hop is only recognised here. Its head must be one of this aggregate's own
-          # references, but the target cannot resolve before the chapter exists, so
+          # references, but the target cannot resolve before the bluebook exists, so
           # BluebookBuilder#validate_query_hops! checks the tail and the target later.
           def seal_query_hop(scope, field, ordering:)
             refuse_undeclared_query_field!(scope, field) unless QuerySpecification::HopPath.hop_head?(field, scope.fields)

data/lib/hecks/bluebook/dsl/aggregate_builder/query_sealing.rb

@@ -26,9 +26,18 @@ module Hecks
           def seal_query(scope)
             query = scope.query
             query.wheres.each { |clause| seal_where_clause(scope, clause) }
-            seal_query_field(scope, query.order_by.field, ordering: true) if query.order_by
+            seal_query_field(scope, query.order_by_field, ordering: true) if query.order_by
             seal_query_argument(scope, query.limit&.value)
             seal_query_argument(scope, query.offset&.value)
+            refuse_entity_cursor!(scope)
+          end
+
+          # A cursor keys on a record's identity; an entity's rows are elements of its owner's list.
+          def refuse_entity_cursor!(scope)
+            return unless scope.cursor? && scope.entity?
+
+            raise Malformed, "#{scope.label} declares cursor, but an entity query pages its owner's list " \
+                             "elements, which have no identity of their own to key a page on — use limit/offset"
           end
 
           def seal_where_clause(scope, clause)
@@ -91,20 +100,21 @@ module Hecks
 
           # A symbolic right-hand side is a query input; when the compared path lands on this
           # owner's shape its type is known, so no `attribute` line is needed. Reference hops
-          # are inferred later by BluebookBuilder, once the chapter is owner-stamped.
+          # are inferred later by BluebookBuilder, once the bluebook is owner-stamped.
           def infer_local_query_argument(scope, clause)
             name = clause.value
+            query = scope.query
             return unless name.is_a?(Symbol)
-            return if scope.query.attribute(name)
+            return if query.attribute(name)
             return if clause.field.to_s.include?("/")
 
             leaf = inferred_argument(scope, name, clause.field)
-            scope.query.attributes << leaf if leaf
+            query.attributes << leaf if leaf
           end
 
           def inferred_argument(scope, name, field)
             head, *nested = field.to_s.split(".")
-            return Attribute.new(name: name, type: String) if nested.empty? && scope.lifecycle&.field.to_s == head
+            return Attribute.new(name: name, type: String) if nested.empty? && scope.lifecycle_field.to_s == head
 
             root = field_named(scope, head)
             found = root && leaf_of(root, nested)

data/lib/hecks/bluebook/dsl/aggregate_builder/relationships.rb

@@ -4,21 +4,39 @@ module Hecks
       # The words that tie an aggregate to others: `reference_to`, `has_many`, `has_one`,
       # `belongs_to`, and the `projects` fields read through a reference.
       class AggregateBuilder
-        # Declares a reference from this aggregate's own head to another aggregate's identity.
+        # Declares a reference from this aggregate's own head to another aggregate's identity, or
+        # with `one_of(A, B)` to one of a closed union of them (ADR 0127).
         #
-        # @param type [Module, Symbol, String] the referenced aggregate, written as a bare
-        #   constant
+        # @param type [Module, Symbol, String, AttributeCollector::OneOf] the referenced
+        #   aggregate, written as a bare constant, or `one_of` of several
         # @param as [Symbol, nil] the attribute's name; nil derives it from `type`
         # @param optional [Boolean] whether the reference may be absent
         # @return [void]
         # @raise [Bluebook::DSL::Malformed] if `as` (or the derived name) is already declared
         def reference_to_impl(type, as: nil, optional: false)
+          return one_of_reference(type, as: as, optional: optional) if type.is_a?(OneOf)
+
           target = Naming.demodulise(type)
           @reference_targets << target
           relationship_attribute(target, :reference_to,
                                  as || default_reference_name(target), optional: optional)
         end
 
+        # Allows a finding `model_check` would report about this aggregate, saying why.
+        #
+        # @param finding [Symbol, String] the kind of finding, such as `:large_aggregate`
+        # @param reason [String] why the aggregate means what it says; required text
+        # @param of [Symbol, String, nil] the attribute (`:key_by_value`) or referenced aggregate
+        #   (`:orphaned_reference`) the acknowledgement is for; those kinds require it
+        # @return [Array<Bluebook::Acknowledgement>] every acknowledgement so far, this one last
+        # @raise [Bluebook::DSL::Malformed] if the kind is not acknowledgeable, the reason is
+        #   blank, or the subject does not suit the kind
+        def acknowledges_impl(finding, reason, of: nil)
+          kind = Acknowledgements.kind!(@name.to_s, finding, reason)
+          subject = Acknowledgements.subject!(@name.to_s, kind, of)
+          @acknowledgements << Acknowledgement.new(finding: kind, reason: reason, subject: subject)
+        end
+
         # Declares that this aggregate holds its own kept-fresh copy of a field reached through
         # a reference, so a rule can read it locally instead of reaching across the boundary.
         #
@@ -47,7 +65,6 @@ module Hecks
 
         # `has_many_impl`/`has_one_impl` are DSL keywords (`has_many`/`has_one` in a bluebook),
         # not real predicates, so Naming/PredicatePrefix does not apply here.
-        # rubocop:disable Naming/PredicatePrefix
 
         # Declares a list-typed relationship to another aggregate, referenced by its plural name.
         #
@@ -87,7 +104,6 @@ module Hecks
           relationship_attribute(target, :has_one, as || Naming.snake(target).to_sym,
                                  optional: optional)
         end
-        # rubocop:enable Naming/PredicatePrefix
 
         # Declares a single-valued relationship toward the aggregate that owns this one.
         #

data/lib/hecks/bluebook/dsl/aggregate_builder/renaming.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Bluebook
+    module DSL
+      class AggregateBuilder
+        # The names an aggregate keeps: the name it held before a rename, which keeps the old name
+        # resolving, and the command that creates its records, which a missing-record refusal names.
+        module Renaming
+          # @param value [Object] the name the aggregate held before, as the attribute types it
+          # @return [Object] the old name as stored
+          def formerly_known_as_impl(value)
+            @formerly_known_as = value
+          end
+
+          # @param value [Object] the command's name, as the bluebook writes it (e.g. "Adr.draft!")
+          # @return [Object] the command name as stored
+          def created_by_impl(value)
+            @created_by = value
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,7 +1,7 @@
 module Hecks
   module Bluebook
     module DSL
-      # The rule words of an aggregate: `given` preconditions, shared across the chapter by
+      # The rule words of an aggregate: `given` preconditions, shared across the bluebook by
       # description, and whole-aggregate `invariant`s.
       class AggregateBuilder
         # Declares a rule this aggregate's own commands must satisfy, or references a sibling's.
@@ -13,17 +13,17 @@ module Hecks
         # @yield the predicate body; evaluated for its extracted source, never called directly
         # @return [void]
         # @raise [Bluebook::DSL::Malformed] if the source can't be extracted, or a bare reference
-        #   resolves to none or more than one candidate once the chapter has loaded
+        #   resolves to none or more than one candidate once the bluebook has loaded
         def given_impl(description, declared_by: nil, &predicate)
-          return reference_named_chapter_given(description, declared_by: declared_by) unless predicate
+          return reference_named_bluebook_given(description, declared_by: declared_by) unless predicate
 
           named = build_rule(Given, description, predicate, owner_name: @name, word: "given",
                               extraction_failure: "its source could not be read, so no other runtime could ever evaluate it")
           @named_givens[description] = named
           # Keyed by [description, this aggregate's name] so two aggregates sharing a
           # description are distinct candidates, never merged into one slot.
-          @chapter_named_givens[description] ||= {}
-          @chapter_named_givens[description][@name] ||= named
+          @bluebook_named_givens[description] ||= {}
+          @bluebook_named_givens[description][@name] ||= named
         end
 
         # Declares a rule the whole aggregate must satisfy, checked after every command, before
@@ -40,41 +40,41 @@ module Hecks
 
         private
 
-        # Unresolved (no candidate yet) doesn't raise here — a chapter split across files
-        # may still declare this precondition in a later file (see `#pending_chapter_given`).
-        def reference_named_chapter_given(description, declared_by:)
+        # Unresolved (no candidate yet) doesn't raise here — a bluebook split across files
+        # may still declare this precondition in a later file (see `#pending_bluebook_given`).
+        def reference_named_bluebook_given(description, declared_by:)
           verify_resolves_via!("given", "Aggregate", "owner_keyed")
-          candidates = resolve_owner_keyed(@chapter_named_givens, description)
+          candidates = resolve_owner_keyed(@bluebook_named_givens, description)
 
-          @named_givens[description] = pick_chapter_given(candidates, description, declared_by)
+          @named_givens[description] = pick_bluebook_given(candidates, description, declared_by)
         end
 
-        def pick_chapter_given(candidates, description, declared_by)
-          return declared_chapter_given(candidates, description, declared_by) if declared_by
+        def pick_bluebook_given(candidates, description, declared_by)
+          return declared_bluebook_given(candidates, description, declared_by) if declared_by
           return candidates.values.first if candidates.size == 1
-          return pending_chapter_given(description, declared_by: nil) if candidates.empty?
+          return pending_bluebook_given(description, declared_by: nil) if candidates.empty?
 
-          raise Malformed, ambiguous_chapter_given_message(candidates, description)
+          raise Malformed, ambiguous_bluebook_given_message(candidates, description)
         end
 
-        def declared_chapter_given(candidates, description, declared_by)
+        def declared_bluebook_given(candidates, description, declared_by)
           owner = Naming.demodulise(declared_by)
-          candidates[owner] || pending_chapter_given(description, declared_by: owner)
+          candidates[owner] || pending_bluebook_given(description, declared_by: owner)
         end
 
-        def ambiguous_chapter_given_message(candidates, description)
-          "#{@name}'s given #{description.inspect} is ambiguous in this chapter — " \
+        def ambiguous_bluebook_given_message(candidates, description)
+          "#{@name}'s given #{description.inspect} is ambiguous in this bluebook — " \
             "#{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}))"
         end
 
         # Returns a placeholder `Given`, embedded by reference in this aggregate's IR;
-        # `BluebookBuilder#resolve_pending_chapter_givens!` mutates it in place once the
-        # whole chapter loads, so every existing reference sees the resolved fields together.
-        def pending_chapter_given(description, declared_by:)
+        # `BluebookBuilder#resolve_pending_bluebook_givens!` mutates it in place once the
+        # whole bluebook loads, so every existing reference sees the resolved fields together.
+        def pending_bluebook_given(description, declared_by:)
           placeholder = Given.new(description: description, canonical: nil, predicate: nil)
-          @chapter_pending_givens << { aggregate: @name, description: description,
+          @bluebook_pending_givens << { aggregate: @name, description: description,
                                         declared_by: declared_by, placeholder: placeholder }
           placeholder
         end

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

@@ -35,7 +35,7 @@ module Hecks
           # through a contained piece is refused like a direct aggregate-to-aggregate ring.
           # Command/query reference arguments are excluded: they are dispatch data, not state.
           def entity_reference_targets
-            @entities.flat_map { |entity| entity.attributes.select(&:reference?).map { |a| a.type.target_name.to_s } }
+            @entities.flat_map { |entity| entity.attributes.select(&:reference?).map { |a| a.target_name.to_s } }
           end
 
           def reference_bearing_attributes
@@ -87,7 +87,7 @@ module Hecks
 
           # The local half of `projects` resolution: `reference` must name a reference attribute
           # here and `name` must not collide with a declared attribute. The target aggregate's
-          # field is checked later by BluebookBuilder, once the whole chapter exists.
+          # field is checked later by BluebookBuilder, once the whole bluebook exists.
           def seal_projected_fields
             declared = attributes.map { |attribute| attribute.name.to_sym }
 

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

@@ -1,8 +1,10 @@
 require_relative "word_gate"
 require_relative "aggregate_builder/sealing"
 require_relative "aggregate_builder/relationships"
+require_relative "aggregate_builder/one_of_reference"
 require_relative "aggregate_builder/rules"
 require_relative "aggregate_builder/draining"
+require_relative "aggregate_builder/renaming"
 module Hecks
   module Bluebook
     module DSL
@@ -16,28 +18,31 @@ module Hecks
         include RuleReference
         include WordGate
         include Sealing
+        include Renaming
+        include OneOfReference
 
         # @param name [String] the aggregate's name, as written after `aggregate`
-        # @param chapter_named_givens [Hash{String => Hash{String => Bluebook::Given}}] the
-        #   chapter-wide given pool, shared and written through by `given_impl`
-        # @param chapter_pending_givens [Array<Hash>] unresolved chapter-wide bare given
+        # @param bluebook_named_givens [Hash{String => Hash{String => Bluebook::Given}}] the
+        #   bluebook-wide given pool, shared and written through by `given_impl`
+        # @param bluebook_pending_givens [Array<Hash>] unresolved bluebook-wide bare given
         #   references, appended to when this aggregate's own reference cannot resolve yet
-        # @param chapter_entity_named_givens [Hash{String => Hash{String => Bluebook::Given}}]
-        #   the chapter-wide, entity-scoped given pool, threaded unchanged to every entity
-        # @param chapter_entity_pending_givens [Array<Hash>] unresolved chapter-wide,
+        # @param bluebook_entity_named_givens [Hash{String => Hash{String => Bluebook::Given}}]
+        #   the bluebook-wide, entity-scoped given pool, threaded unchanged to every entity
+        # @param bluebook_entity_pending_givens [Array<Hash>] unresolved bluebook-wide,
         #   entity-scoped bare given references, threaded unchanged to every entity
-        def initialize(name, chapter_named_givens: {}, chapter_pending_givens: [],
-                       chapter_entity_named_givens: {}, chapter_entity_pending_givens: [])
+        def initialize(name, bluebook_named_givens: {}, bluebook_pending_givens: [],
+                       bluebook_entity_named_givens: {}, bluebook_entity_pending_givens: [])
           @name = name
           start_declarations
-          # Threaded in from `BluebookBuilder#aggregate`; shared chapter-wide across aggregates.
-          @chapter_named_givens = chapter_named_givens
-          # Threaded chapter-wide; a chapter may span multiple files (see `#pending_chapter_given`)
-          @chapter_pending_givens = chapter_pending_givens
-          # One level wider than `@chapter_named_givens`: the chapter's entity-scoped pool,
+          # Threaded in from `BluebookBuilder#aggregate`; shared bluebook-wide across aggregates.
+          @bluebook_named_givens = bluebook_named_givens
+          # Threaded bluebook-wide; a bluebook may span multiple files (see
+          # `#pending_bluebook_given`)
+          @bluebook_pending_givens = bluebook_pending_givens
+          # One level wider than `@bluebook_named_givens`: the bluebook's entity-scoped pool,
           # passed through unchanged to every entity this aggregate builds.
-          @chapter_entity_named_givens   = chapter_entity_named_givens
-          @chapter_entity_pending_givens = chapter_entity_pending_givens
+          @bluebook_entity_named_givens   = bluebook_entity_named_givens
+          @bluebook_entity_pending_givens = bluebook_entity_pending_givens
         end
 
         # Sets the human-readable description shown for this aggregate.
@@ -119,16 +124,16 @@ module Hecks
         end
 
         # Evaluates an `aggregate` block against a fresh builder and returns the built aggregate.
-        # The `chapter_*` params thread the chapter-wide and entity-scoped given pools through.
+        # The `bluebook_*` params thread the bluebook-wide and entity-scoped given pools through.
         #
         # @yield the aggregate body, evaluated with the builder as `self`; may be omitted
         # @return [Bluebook::Aggregate] the built aggregate
         # @raise [Bluebook::DSL::Malformed] if the body fails any check `#build` raises
-        def self.build(name, chapter_named_givens: {}, chapter_pending_givens: [],
-                       chapter_entity_named_givens: {}, chapter_entity_pending_givens: [], &block)
-          builder = new(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)
+        def self.build(name, bluebook_named_givens: {}, bluebook_pending_givens: [],
+                       bluebook_entity_named_givens: {}, bluebook_entity_pending_givens: [], &block)
+          builder = new(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)
           builder.instance_eval(&block) if block
           builder.build
         end
@@ -140,6 +145,7 @@ module Hecks
           @invariants        = []
           @named_givens      = {}
           @projected_fields  = []
+          @acknowledgements  = []
           @identity_paths    = []
           @policies          = []
           @reference_targets = []
@@ -172,7 +178,9 @@ module Hecks
         def aggregate_shape
           { name: @name, description: @description, attributes: attributes,
             value_objects: @value_objects + closed_sets, identified_by: @identity_paths,
-            lifecycle: @lifecycle, entities: @entities, provenance: @provenance }
+            lifecycle: @lifecycle, entities: @entities, provenance: @provenance,
+            formerly_known_as: @formerly_known_as, created_by: @created_by,
+            acknowledgements: @acknowledgements }
         end
 
         # What the aggregate does and the rules it keeps.

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

@@ -10,7 +10,6 @@ module Hecks
 
         ListOf = Struct.new(:type)
         # `:values` shadows Struct#values so the accessor returns the flat permitted-value array.
-        # rubocop:disable-next Lint/StructNewOverride
         OneOf  = Struct.new(:values)
 
         UNSET = Object.new.freeze

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

@@ -0,0 +1,40 @@
+module Hecks
+  module Bluebook
+    module DSL
+      # The `audience` word of a command: who a launcher lists it for (ADR 0163). It decides
+      # listing only; the role still decides who may run the command. The including builder holds
+      # `@name`.
+      module AudienceWord
+        # The audiences a command may be listed for: a person at a keyboard, an agent through the
+        # MCP door, a CI step, or the run's own bookkeeping.
+        AUDIENCES = %w[person agent ci record].freeze
+
+        # Names who a launcher lists the command for.
+        #
+        # @param values [Array<Symbol, String>] one or several of `AUDIENCES`
+        # @return [Array<String>] the audience as stored
+        # @raise [Bluebook::DSL::Malformed] if one is already declared, one is not an audience, or
+        #   one is named twice
+        def audience_impl(*values)
+          names = values.map(&:to_s)
+          raise Malformed, "#{@name} declares its audience twice" if @audience
+          raise Malformed, audience_problem(names) if audience_problem(names)
+
+          @audience = names
+        end
+
+        private
+
+        # Why an audience declaration is refused, or nil when every name is an audience named once.
+        def audience_problem(names)
+          return "#{@name} names no audience" if names.empty?
+
+          unknown = names - AUDIENCES
+          return "#{@name} names #{unknown.join(", ")} as an audience; the audiences are #{AUDIENCES.join(", ")}" if unknown.any?
+
+          "#{@name} names an audience twice" if names.uniq.size != names.size
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class BluebookBuilder
+        # The words that describe the whole bluebook rather than one construct in it: its earlier
+        # name, the Ruby module its constants install under, and its classification. Each refuses
+        # to sit inside a `domain_module` block, since a module names a task, not the bluebook.
+        module Metadata
+          # 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 bluebook's earlier name
+          # @return [String] `value`, stringified, as stored
+          def formerly_known_as(value)
+            bluebook_wide!(:formerly_known_as)
+            @formerly_known_as = value.to_s
+          end
+
+          # 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)
+            bluebook_wide!(:namespace)
+            @namespace = value.to_s
+          end
+
+          # Classifies this bluebook as core to the framework, rather than a domain built on it.
+          #
+          # @return [Symbol] `:core`
+          def core       = classify(:core)
+
+          # Classifies this bluebook as a supporting piece of the framework, rather than a domain
+          # built on it.
+          #
+          # @return [Symbol] `:supporting`
+          def supporting = classify(:supporting)
+
+          # Classifies this bluebook as generic infrastructure, rather than a domain built on it.
+          #
+          # @return [Symbol] `:generic`
+          def generic    = classify(:generic)
+
+          private
+
+          # Sets how this bluebook is classified, which describes the whole of it.
+          def classify(kind)
+            bluebook_wide!(kind)
+            @classification = kind
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class BluebookBuilder
+        # Groups a bluebook's aggregates in the modules it declares (ADR 0163). `domain_module
+        # "Deliver" do … end` opens a block whose `aggregate` words are recorded under the module;
+        # the module changes no aggregate, it names the task each one belongs to. Policies, read
+        # models and process managers inside the block are the bluebook's own, as they are outside it.
+        module Modules
+          # Opens the module `name` and evaluates its body; a module of that name that an earlier
+          # file opened gains the aggregates this body declares.
+          #
+          # @param name [String] the module's own name, such as `"Deliver"`
+          # @yield the module body: its vision, aggregates, policies, read models and process managers
+          # @return [Array<Bluebook::Declaration::ModuleRow>] every membership declared so far
+          # @raise [Bluebook::DSL::Malformed] if a module opens inside another, or holds no aggregate
+          def domain_module(name, &)
+            refuse_nested_module!(name)
+            @open_module = name.to_s
+            instance_eval(&) if block_given?
+            refuse_empty_module!(@open_module)
+            module_rows
+          ensure
+            @open_module = nil
+          end
+
+          private
+
+          # One row per aggregate a module groups, in declaration order, each carrying its module's
+          # vision (empty when the module names none).
+          def module_rows
+            module_members.map do |name, aggregate|
+              Declaration::ModuleRow.new(name: name, vision: module_visions[name].to_s, aggregate: aggregate)
+            end
+          end
+
+          # Each `[module, aggregate]` pair declared so far, in declaration order.
+          def module_members = @module_members ||= []
+
+          # Each module's vision by its name, for the modules that declared one.
+          def module_visions = @module_visions ||= {}
+
+          # Records an aggregate under the open module, if one is open.
+          def note_in_open_module(name)
+            module_members << [@open_module, name.to_s] if @open_module
+          end
+
+          # Records the open module's vision.
+          def module_vision(value)
+            held = module_visions[@open_module]
+            raise Malformed, "domain_module #{@open_module.inspect} declares two visions" if held && held != value
+
+            module_visions[@open_module] = value
+          end
+
+          # Refuses a bluebook-wide word written inside a module block.
+          def bluebook_wide!(word)
+            return unless @open_module
+
+            raise Malformed, "#{word} describes the whole bluebook, so it cannot sit inside " \
+                             "domain_module #{@open_module.inspect}"
+          end
+
+          def refuse_nested_module!(name)
+            return unless @open_module
+
+            raise Malformed, "domain_module #{name.inspect} sits inside domain_module " \
+                             "#{@open_module.inspect}; modules do not nest"
+          end
+
+          def refuse_empty_module!(name)
+            return if module_members.any? { |held, _| held == name }
+
+            raise Malformed, "domain_module #{name.inspect} holds no aggregate"
+          end
+        end
+      end
+    end
+  end
+end