hecks 5.0.0 → 6.0.0

data/lib/hecks/bluebook/context_map.rb

@@ -0,0 +1,104 @@
+module Hecks
+  module Bluebook
+    # A context map as data: the contexts a system holds, who owns each, and how pairs of them
+    # relate (ADR 0135). Declared first; `ModelCheck::ContextMapChecks` holds the wiring to it.
+    #
+    # How a map is written down (its file kind and builder) is a separate decision. This holds
+    # only what any spelling of it must say.
+    class ContextMap
+      # The relationship kinds a map may declare. `separate_ways` is not one: it is the absence
+      # of a relationship, kept in {#separate_ways}.
+      KINDS = %i[customer_supplier conformist anticorruption_layer shared_kernel open_host
+                 partnership].freeze
+
+      # The kind of the derived edge that an `attaches` makes.
+      ATTACH = "shared_kernel".freeze
+
+      # One context: its name and the team that owns it.
+      Context = Struct.new(:name, :team, keyword_init: true)
+
+      # One declared relationship between two contexts.
+      #
+      # `upstream` supplies and `downstream` consumes. `published` lists the upstream events a
+      # downstream may depend on; `shared` the names two contexts hold in common (shared kernel).
+      # `acknowledged` maps a finding kind about the relationship to the reason it is allowed.
+      # `implied` marks one the wiring states and no one wrote down (an `attaches`, ADR 0155).
+      Relationship = Struct.new(:upstream, :downstream, :kind, :published, :shared, :acknowledged, :implied,
+                                keyword_init: true) do
+        # @return [Array(String, String)] the two contexts, sorted, whichever way the arrow runs
+        def pair = [upstream, downstream].sort
+
+        # @return [Boolean] whether the relationship allows a finding of this kind
+        def acknowledges?(finding) = (acknowledged || {}).key?(finding.to_sym)
+      end
+
+      attr_reader :name, :contexts, :relationships, :separate_ways
+
+      # @param name [String] the system the map covers
+      # @param contexts [Array<Context>] every context the system holds
+      # @param relationships [Array<Relationship>] the declared relationships
+      # @param separate_ways [Array<Array(String, String)>] pairs declared apart
+      # @raise [ArgumentError] on an unknown kind, or a relationship or pair naming an undeclared
+      #   context
+      def initialize(name:, contexts: [], relationships: [], separate_ways: [])
+        @name          = name.to_s
+        @contexts      = contexts
+        @relationships = relationships
+        @separate_ways = separate_ways.map { |pair| pair.map(&:to_s).sort }
+        refuse_unknown_kinds!
+        refuse_undeclared_contexts!
+      end
+
+      # @return [Array<String>] the declared contexts' names
+      def context_names = contexts.map { |context| context.name.to_s }
+
+      # @param left [String] a context's name
+      # @param right [String] another context's name
+      # @return [Array<Relationship>] the relationships declared between them, either way round
+      def relationships_between(left, right)
+        pair = [left.to_s, right.to_s].sort
+        relationships.select { |relationship| relationship.pair == pair }
+      end
+
+      # @return [Boolean] whether the map declares the two contexts apart
+      def separate?(left, right) = separate_ways.include?([left.to_s, right.to_s].sort)
+
+      # The map with each attach the wiring makes read as a `conformist` relationship, unless the
+      # map already says something about that pair or declares it apart (ADR 0155).
+      #
+      # @param edges [Array<Hash>] `Projections::ContextRelationships.call`
+      # @return [ContextMap] this map plus its implied relationships, or itself when none apply
+      def implying(edges)
+        implied = edges.select { |edge| edge[:kind] == ATTACH }.filter_map { |edge| implied_from(edge) }
+        return self if implied.empty?
+
+        self.class.new(name: name, contexts: contexts, relationships: relationships + implied.uniq,
+                       separate_ways: separate_ways)
+      end
+
+      private
+
+      def implied_from(edge)
+        return if separate?(edge[:from], edge[:to]) || relationships_between(edge[:from], edge[:to]).any?
+
+        Relationship.new(upstream: edge[:to], downstream: edge[:from], kind: :conformist, implied: true)
+      end
+
+      def refuse_unknown_kinds!
+        unknown = relationships.map(&:kind).uniq - KINDS
+        return if unknown.empty?
+
+        raise ArgumentError, "unknown relationship kind #{unknown.first.inspect} (known: #{KINDS.inspect})"
+      end
+
+      def refuse_undeclared_contexts!
+        named = (relationships.flat_map { |relationship| [relationship.upstream, relationship.downstream] } +
+                 separate_ways.flatten).map(&:to_s).uniq
+        missing = named - context_names
+        return if missing.empty?
+
+        raise ArgumentError, "#{name} relates #{missing.join(", ")}, which it does not declare as a context"
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/{chapter.rb → declaration.rb}

@@ -1,14 +1,14 @@
-require_relative "behaviour/chapter"
+require_relative "behaviour/declaration"
 require_relative "capabilities"
 require_relative "keyword_fields"
 require_relative "../ir"
 
 module Hecks
   module Bluebook
-    # The chapter, distinct from the `Bluebook` namespace it lives in.
-    class Chapter
+    # The bluebook, distinct from the `Bluebook` namespace it lives in.
+    class Declaration
       include Construct
-      include Behaviour::Chapter
+      include Behaviour::Declaration
       include Hecks::IR
 
       # The IR shape's own version — bump only when `to_h`'s shape changes,
@@ -21,12 +21,12 @@ module Hecks
         version:           :version,
         vision:            :vision,
         classification:    :classification,
-        # Present (possibly nil) rather than silently absent, so two chapters
+        # Present (possibly nil) rather than silently absent, so two bluebooks
         # differing only by their old name can't hash identically at the
         # meta-validator's cache key (`SHA256(JSON(bluebook.to_h))`).
         formerly_known_as: :formerly_known_as,
-        # The Ruby module the chapter's constants install under, when it is not the chapter's
-        # own name (the Hecks domain nests under `Hecks::Domain`); nil for every other chapter.
+        # The Ruby module the bluebook's constants install under, when it is not the bluebook's
+        # own name (the Hecks domain nests under `Hecks::Domain`); nil for every other bluebook.
         namespace:         :namespace,
         aggregates:        many(:aggregates),
         read_models:       many(:read_models),
@@ -39,14 +39,14 @@ module Hecks
         canonical_form:    -> { Expression::CanonicalForm.table }
       )
 
-      # One row of a declared capability — `verb` is chapter-local;
-      # `Behaviour::Chapter#provided_verb` qualifies it with the chapter's own name.
+      # One row of a declared capability — `verb` is bluebook-local;
+      # `Behaviour::Bluebook#provided_verb` qualifies it with the bluebook's own name.
       Provision = Struct.new(:capability, :key, :verb, keyword_init: true) do
         # Coerces one declared or reconstructed `provides` row into a `Provision`.
         #
-        # @param row [Bluebook::Chapter::Provision, #to_h] a `Provision` already, or
+        # @param row [Bluebook::Declaration::Provision, #to_h] a `Provision` already, or
         #   anything answering `to_h` with `capability`/`key`/`verb` entries
-        # @return [Bluebook::Chapter::Provision] `row` itself if it already is one, else
+        # @return [Bluebook::Declaration::Provision] `row` itself if it already is one, else
         #   a new `Provision` built from its fields
         def self.from(row)
           return row if row.is_a?(self)
@@ -67,8 +67,8 @@ module Hecks
       }.freeze
 
       # @param policies [Array<Bluebook::Policy>] every reaction declared across the
-      #   chapter's own aggregates, hoisted here
-      # @param classification [String, Symbol, nil] whether this chapter is central to
+      #   bluebook's own aggregates, hoisted here
+      # @param classification [String, Symbol, nil] whether this bluebook is central to
       #   its project's own domain model, or `nil` if undeclared
       def initialize(name:, **given)
         KeywordFields.assign(self, KeywordFields.fill(given, FIELD_DEFAULTS))

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

@@ -14,11 +14,16 @@ module Hecks
         include WordGate
 
         # @param name [String] the adapter's name, as written after `Hecks.adapter`
-        def initialize(name)
+        # @param source_dir [String, nil] the directory of the `.adapter` file, which a plugin's
+        #   `runs` path is read against
+        def initialize(name, source_dir: nil)
           @name = name
+          @source_dir = source_dir
           @fields   = []
           @secrets  = []
           @defaults = {}
+          @answers  = []
+          @provides = []
         end
 
         # Names the port this adapter implements; a repeated call replaces the earlier name.
@@ -44,14 +49,33 @@ module Hecks
         # @return [Array<Symbol>] every secret declared so far, this one last
         def secret(name) = @secrets << name.to_sym
 
-        # Assembles the collected port, fields, defaults and secrets, judged by the adapter
+        # Names one query this adapter answers, qualified by its bluebook and aggregate.
+        #
+        # @param name [String] the query, such as `"Calendar::Event.Occurrences"`
+        # @return [Array<String>] every query named so far, this one last
+        def answers_query(name) = @answers << name.to_s
+
+        # Names one capability this adapter provides beyond its port's contract.
+        #
+        # @param capability [String, Symbol] the capability, such as `"set_transform"`
+        # @return [Array<String>] every capability named so far, this one last
+        def provides(capability) = @provides << capability.to_s
+
+        # Names the wasm module this adapter runs, beside its `.adapter` file.
+        #
+        # @param file [String] the module's file name, such as `"occurrences.wasm"`
+        # @return [String] the file name as stored
+        def runs(file) = @runs = file.to_s
+
+        # Assembles the collected port, fields, defaults, secrets and plugin, judged by the adapter
         # language.
         #
         # @return [Bluebook::Adapter] the adapter, returned once the language accepts it
         # @raise [Bluebook::DSL::Malformed] if the adapter language refuses the declaration
         def build
           MetaValidator.call_adapter(
-            Adapter.new(name: @name, port: @port, fields: @fields, secrets: @secrets, defaults: @defaults)
+            Adapter.new(name: @name, port: @port, fields: @fields, secrets: @secrets, defaults: @defaults,
+                        answers: @answers, runs: @runs, provides: @provides, source_dir: @source_dir)
           )
         end
 
@@ -63,7 +87,7 @@ module Hecks
         # @raise [Bluebook::DSL::Malformed] if the adapter language refuses the declaration, or
         #   the block uses a word the `Adapter` grammar does not admit
         def self.build(name, &block)
-          builder = new(name)
+          builder = new(name, source_dir: block && File.dirname(block.source_location.first))
           builder.instance_eval(&block) if block
           builder.build
         end

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

@@ -58,8 +58,8 @@ module Hecks
                                     identity_name_prefix:            "#{Naming.demodulise(@name)}#{Naming.demodulise(name)}",
                                     identity_value_object_installer: ->(value_object) { @value_objects << value_object },
                                     aggregate_name:                  @name,
-                                    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,
                               &block)
         end
 

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.
         #

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,6 +1,7 @@
 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"
 module Hecks
@@ -16,28 +17,30 @@ module Hecks
         include RuleReference
         include WordGate
         include Sealing
+        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 +122,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 +143,7 @@ module Hecks
           @invariants        = []
           @named_givens      = {}
           @projected_fields  = []
+          @acknowledgements  = []
           @identity_paths    = []
           @policies          = []
           @reference_targets = []
@@ -172,7 +176,8 @@ 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,
+            acknowledgements: @acknowledgements }
         end
 
         # What the aggregate does and the rules it keeps.