hecks 5.0.0 → 7.0.0

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

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

@@ -4,10 +4,10 @@ module Hecks
       class EntityBuilder
         # What a piece is handed by whatever declares it, threaded unchanged through every nested
         # piece so siblings share the same pools: the owner's value objects and givens, the
-        # naming of identity value objects, and the chapter-wide entity-given pools.
+        # naming of identity value objects, and the bluebook-wide entity-given pools.
         Scope = Struct.new(:owner_value_objects, :owner_named_givens, :identity_name_prefix,
                            :identity_value_object_installer, :aggregate_name,
-                           :chapter_entity_named_givens, :chapter_entity_pending_givens,
+                           :bluebook_entity_named_givens, :bluebook_entity_pending_givens,
                            keyword_init: true) do
           # Builds a `Scope` with every field defaulted to empty, refusing an unknown keyword.
           #
@@ -16,7 +16,7 @@ module Hecks
           def self.from(**context)
             new(owner_value_objects: [], owner_named_givens: {}, identity_name_prefix: nil,
                 identity_value_object_installer: nil, aggregate_name: nil,
-                chapter_entity_named_givens: {}, chapter_entity_pending_givens: [], **context)
+                bluebook_entity_named_givens: {}, bluebook_entity_pending_givens: [], **context)
           end
         end
       end

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

@@ -43,8 +43,8 @@ module Hecks
                                       identity_name_prefix:            "#{@identity_name_prefix}#{Naming.demodulise(name)}",
                                       identity_value_object_installer: @identity_value_object_installer,
                                       aggregate_name:                  @aggregate_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/entity_builder.rb

@@ -51,7 +51,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 entity, referenced by its plural name.
         def has_many_impl(type, as: nil, **options)
           unless options.empty?
@@ -69,7 +68,6 @@ module Hecks
           target = Naming.demodulise(type)
           relationship_attribute(target, :has_one, as || Naming.snake(target).to_sym, optional: optional)
         end
-        # rubocop:enable Naming/PredicatePrefix
 
         # Declares a single-valued relationship to the entity that owns this one.
         def belongs_to_impl(type, as: nil, optional: false)
@@ -132,11 +130,11 @@ module Hecks
           # Threaded unchanged through every nested piece so a sibling's bare given
           # reference can read the same aggregate-wide pool `given_impl` writes to.
           @owner_named_givens = scope.owner_named_givens
-          # One level wider than `@owner_named_givens`: the chapter-wide, entity-scoped
+          # One level wider than `@owner_named_givens`: the bluebook-wide, entity-scoped
           # pool, keyed "Aggregate.Entity" so `#given_impl` can resolve across aggregates.
           @aggregate_name = scope.aggregate_name || Naming.demodulise(name)
-          @chapter_entity_named_givens   = scope.chapter_entity_named_givens
-          @chapter_entity_pending_givens = scope.chapter_entity_pending_givens
+          @bluebook_entity_named_givens   = scope.bluebook_entity_named_givens
+          @bluebook_entity_pending_givens = scope.bluebook_entity_pending_givens
         end
 
         def entity_fields

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

@@ -10,6 +10,9 @@ module Hecks
 
         COERCE_BY_KIND = { "text" => :to_s, "symbol" => :to_sym }.freeze
 
+        # The arguments of one word call: its positional arguments, its keyword arguments, and its block.
+        Invocation = Struct.new(:args, :kwargs, :block)
+
         # Not derivable from `fills:` (these rows all carry `fills: ""`) — the append target
         # for each opens-block word must be named here explicitly.
         SAFE_OPENS_BLOCK = {
@@ -31,13 +34,12 @@ module Hecks
 
         # Executes a table-admitted word via the shape `shape_for` found for it, or returns
         # NOT_HANDLED so the caller can fall back to its own "not yet implemented" refusal.
-        # The seven-argument form is the entry point `WordGate` and the dispatch specs call.
-        # rubocop:disable-next Metrics/ParameterLists
-        def try(builder, context, word, args, kwargs, block, rows)
+        # The call's arguments travel together as an `Invocation`, which keeps the signature short.
+        def try(builder, context, word, invocation, rows)
           shape = shape_for(context, word, rows)
           return NOT_HANDLED unless shape
 
-          run_shape(shape, builder, args, kwargs, block)
+          run_shape(shape, builder, invocation.args, invocation.kwargs, invocation.block)
         end
 
         # Runs the dispatcher the shape's kind names.

data/lib/hecks/bluebook/dsl/hecksagon_builder/{chapter_scope.rb → bluebook_scope.rb}

@@ -3,9 +3,9 @@ module Hecks
     module DSL
       class HecksagonBuilder
         # The per-thread state of the hecksagon build in progress, and the shadowing of `Hecks`'s
-        # real modules that lets the Hecks chapter spell its aggregates `Hecks::Operation`.
+        # real modules that lets the Hecks bluebook spell its aggregates `Hecks::Operation`.
         # Extended onto `HecksagonBuilder`.
-        module ChapterScope
+        module BluebookScope
           # The bind collector of the build running on this thread; thread-local, so a build
           # on another thread never sees it.
           #
@@ -17,10 +17,10 @@ module Hecks
             Thread.current.thread_variable_set(:hecks_hecksagon_collector, value)
           end
 
-          # @return [String, nil] the name of the chapter whose hecksagon is being built
+          # @return [String, nil] the name of the bluebook whose hecksagon is being built
           def building = Thread.current.thread_variable_get(:hecks_hecksagon_building)
 
-          # @param value [String, nil] the name of the chapter whose hecksagon is being built
+          # @param value [String, nil] the name of the bluebook whose hecksagon is being built
           def building=(value)
             Thread.current.thread_variable_set(:hecks_hecksagon_building, value)
           end
@@ -33,17 +33,17 @@ module Hecks
             Thread.current.thread_variable_set(:hecks_hecksagon_hidden, value)
           end
 
-          # Takes off `Hecks` each real module a chapter aggregate shares its name with, so the
-          # name reaches `ChapterConstants#const_missing`. Only the chapter named Hecks has this
+          # Takes off `Hecks` each real module a bluebook aggregate shares its name with, so the
+          # name reaches `BluebookConstants#const_missing`. Only the bluebook named Hecks has this
           # collision; a nested build of it leaves the outer build's shadows in place.
           #
-          # @param domain [String, Symbol] the chapter whose hecksagon is being built
+          # @param domain [String, Symbol] the bluebook whose hecksagon is being built
           # @return [Hash{Symbol => Object}] what was taken off, by name: the module, or the
           #   autoload path when the constant had not loaded yet
           def shadowed(domain)
             return {} unless domain.to_s == "Hecks"
 
-            chapter_aggregate_names.select { |name| Hecks.const_defined?(name, false) }.to_h do |name|
+            bluebook_aggregate_names.select { |name| Hecks.const_defined?(name, false) }.to_h do |name|
               pending = Hecks.autoload?(name)
               held    = pending ? [:autoload, pending] : [:module, Hecks.const_get(name, false)]
               Hecks.send(:remove_const, name)
@@ -52,7 +52,7 @@ module Hecks
           end
 
           # Runs the block with every module the running build shadowed back on `Hecks`, and a
-          # missing `Hecks::X` an ordinary `NameError`, then shadows them again. A chapter loaded
+          # missing `Hecks::X` an ordinary `NameError`, then shadows them again. A bluebook loaded
           # from inside the hecksagon block is ordinary code, not the hecksagon's own vocabulary.
           # A no-op when nothing is shadowed.
           #
@@ -83,10 +83,10 @@ module Hecks
             end
           end
 
-          # Runs the block with this thread's collector, chapter name and shadowed modules set for
+          # Runs the block with this thread's collector, bluebook name and shadowed modules set for
           # building `domain`'s hecksagon, restoring the outer build's state afterwards.
           #
-          # @param domain [String, Symbol] the chapter whose hecksagon is being built
+          # @param domain [String, Symbol] the bluebook whose hecksagon is being built
           # @param binds [Array] the binds the build collects into
           # @yield the build
           # @return [Object] the block's result
@@ -101,9 +101,9 @@ module Hecks
 
           private
 
-          def chapter_aggregate_names
-            chapter = Hecks.current_registry&.bluebook("Hecks")
-            chapter ? chapter.aggregates.map { |aggregate| aggregate.hecks_name.to_sym } : []
+          def bluebook_aggregate_names
+            declaration = Hecks.current_registry&.bluebook("Hecks")
+            declaration ? declaration.aggregates.map { |aggregate| aggregate.hecks_name.to_sym } : []
           end
 
           def reshadow(hidden, name)

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

@@ -1,5 +1,5 @@
 require_relative "word_gate"
-require_relative "hecksagon_builder/chapter_scope"
+require_relative "hecksagon_builder/bluebook_scope"
 module Hecks
   module Bluebook
     module DSL
@@ -9,18 +9,18 @@ module Hecks
         GRAMMAR_CONTEXT = "Hecksagon".freeze
 
         include WordGate
-        extend ChapterScope
+        extend BluebookScope
 
-        # Lets the Hecks chapter's own hecksagon spell its aggregates `Hecks::Operation`.
+        # Lets the Hecks bluebook's own hecksagon spell its aggregates `Hecks::Operation`.
         #
-        # While the chapter named Hecks builds its hecksagon, a missing constant on `Hecks` is
-        # one of that chapter's aggregates; at any other time it is the ordinary `NameError`.
+        # While the bluebook named Hecks builds its hecksagon, a missing constant on `Hecks` is
+        # one of that bluebook's aggregates; at any other time it is the ordinary `NameError`.
         #
         # A real module of the same name (`Hecks::Release`) would answer first, so
         # `HecksagonBuilder.build` takes each off `Hecks` while the block runs (see `shadowed`).
-        # `attaches` loads whole chapters inside the block; the shadow lifts around each load
+        # `attaches` loads whole bluebooks inside the block; the shadow lifts around each load
         # (see `with_real_modules`), so loaded code sees the real modules.
-        module ChapterConstants
+        module BluebookConstants
           # @param name [Symbol] the missing constant
           # @return [Bluebook::DSL::BindingProxy] a proxy for that aggregate while building
           def const_missing(name)
@@ -37,6 +37,10 @@ module Hecks
           "uses_embryonaut_bluebook" => ->(name) { "attaches #{name.to_s.inspect}, from: :vendor" }
         }.freeze
 
+        # Words older hecksagons carry that no grammar word or port defines and nothing reads. They
+        # are refused by name so the file fails at the line, not later as an unknown adapter.
+        RETIRED_WORDS = %w[capabilities concerns annotate].freeze
+
         attr_reader :binds, :subscriptions, :attachments
 
         def initialize(domain)
@@ -49,7 +53,7 @@ module Hecks
           @translates         = []
         end
 
-        # Marks this chapter as a bounded context; an attachment marks its chapter bounded too.
+        # Marks this bluebook as a bounded context; an attachment marks its bluebook bounded too.
         # Must declare at least one `translates` ACL or boot refuses.
         def bounded
           @bounded = true
@@ -65,15 +69,15 @@ module Hecks
         # @return [void]
         def driven_by(adapter) = @driving << adapter.to_s
 
-        # Attaches a chapter by name and loads it into the current registry, marked bounded.
+        # Attaches a bluebook by name and loads it into the current registry, marked bounded.
         #
-        # Without `from:` the name is a chapter the gem carries (a framework member such as
-        # Governance, or a language chapter such as Deploy) with the ports and adapters it
+        # Without `from:` the name is a bluebook the gem carries (a framework member such as
+        # Governance, or a language bluebook such as Deploy) with the ports and adapters it
         # ships. `from: :vendor` loads `vendor/embryonaut_bluebooks/<name>/bluebook` instead,
         # and is never a fallback for a misspelt gem name.
         #
-        # @param name [String, Symbol] a gem chapter's name or a vendored package's directory name
-        # @param from [Symbol, nil] `:vendor` for a vendored package, nil for a gem chapter
+        # @param name [String, Symbol] a gem bluebook's name or a vendored package's directory name
+        # @param from [Symbol, nil] `:vendor` for a vendored package, nil for a gem bluebook
         # @raise [Runtime::WiringError] if the name is unknown, or `from:` names another source
         def attaches(name, from: nil)
           unless [nil, :vendor].include?(from)
@@ -84,7 +88,7 @@ module Hecks
           from == :vendor ? attach_vendored(name) : attach_gem(name)
         end
 
-        # Declares a port at the hecksagon's root — the chapter as a whole, not one aggregate.
+        # Declares a port at the hecksagon's root — the bluebook as a whole, not one aggregate.
         def port_impl(name, &block)
           bluebook_ir = Hecks.current_registry.bluebook(@domain) or
             raise Malformed, "#{@domain} declares no such bluebook — a port needs one to belong to"
@@ -123,21 +127,21 @@ module Hecks
                         driving: @driving)
         end
 
-        # Loads a chapter the gem carries and records it as attached from the gem.
+        # Loads a bluebook the gem carries and records it as attached from the gem.
         def attach_gem(name)
-          require_relative "../../chapters"
+          require_relative "../../framework_bluebooks"
           @attachments << Attachment.new(name: name.to_s, source: :gem)
-          self.class.with_real_modules { Hecks::Chapters.attach!(name) }
+          self.class.with_real_modules { Hecks::FrameworkBluebooks.attach!(name) }
           Hecks.current_registry&.mark_bounded(name.to_s)
         end
         private :attach_gem
 
-        # Loads a vendored package and records it as attached from `vendor/`. The directory name
-        # Pascal-cases to the chapter name (`"membership"` becomes `Membership`).
+        # Loads a vendored package and records it as attached from `vendor/`, under the bluebook
+        # its bluebook declares: `"document"` attaches `Documents`.
         def attach_vendored(name)
-          @attachments << Attachment.new(name: name.to_s, source: :vendor)
-          Hecks::EmbryonautBluebook.load!(name)
-          Hecks.current_registry&.mark_bounded(Hecks::Naming.pascal(name.to_s))
+          declaration = Hecks::EmbryonautBluebook.load!(name)
+          @attachments << Attachment.new(name: name.to_s, source: :vendor, declaration: declaration)
+          Hecks.current_registry&.mark_bounded(declaration)
         end
         private :attach_vendored
 
@@ -158,16 +162,18 @@ module Hecks
           self
         end
 
-        # Raises for a word 3.4.0 removed, naming the spelling that replaces it.
+        # Raises for a word 3.4.0 removed, naming the spelling that replaces it, and for a retired
+        # word that has no replacement.
         #
         # @param verb [Symbol] the word the hecksagon block called
         # @param name [Object, nil] its first argument, echoed into the replacement
-        # @raise [Malformed] when the word is one of `REMOVED_WORDS`
+        # @raise [Malformed] when the word is one of `REMOVED_WORDS` or `RETIRED_WORDS`
         def refuse_removed_word(verb, name)
           instead = REMOVED_WORDS[verb.to_s]
-          return unless instead
+          raise Malformed, "`#{verb}` was removed in 3.4.0; use `#{instead.call(name)}`" if instead
+          return unless RETIRED_WORDS.include?(verb.to_s)
 
-          raise Malformed, "`#{verb}` was removed in 3.4.0; use `#{instead.call(name)}`"
+          raise Malformed, "`#{verb}` is not a hecksagon word and nothing reads it; delete the line"
         end
         private :refuse_removed_word
 
@@ -188,4 +194,4 @@ module Hecks
   end
 end
 
-Hecks.singleton_class.prepend(Hecks::Bluebook::DSL::HecksagonBuilder::ChapterConstants)
+Hecks.singleton_class.prepend(Hecks::Bluebook::DSL::HecksagonBuilder::BluebookConstants)

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

@@ -4,6 +4,9 @@ module Hecks
       # `identified_by`, shared by AggregateBuilder and EntityBuilder (ADR 0025).
       # The includer must include AttributeCollector and define a private `identity_pool`.
       module IdentityDeclaration
+        # A name that starts with a capital letter: a value-object type, not an attribute name.
+        CAPITALISED = /\A[A-Z]/
+
         # Records which `identified_by` form a builder declared; resolution waits for build time.
         #
         #   identified_by AccountNumber, as: :number # one identity concept
@@ -41,7 +44,7 @@ module Hecks
           end
         end
 
-        def identity_type?(target) = target.to_s.match?(/\A[A-Z]/)
+        def identity_type?(target) = target.to_s.match?(CAPITALISED)
 
         def refuse_second_identity!
           # Transitional: a one-symbol declaration may still be replaced by a later one.
@@ -110,7 +113,8 @@ module Hecks
 
           raise Malformed, "#{@name}.identified_by names no field" unless path
 
-          paths = Ports::Extraction.canonical(path).to_s.split.reject(&:empty?)
+          canonical = Ports::Extraction.canonical(path).to_s
+          paths = canonical.split.reject(&:empty?)
           raise Malformed, "#{@name}.identified_by names no field" if paths.empty?
 
           @identity_paths = paths

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

@@ -0,0 +1,53 @@
+module Hecks
+  module Bluebook
+    module DSL
+      # The aggregate kinds: `aggregate "GateRun", kind: "Run"` evaluates the kind's own text,
+      # written in the bluebook's words, around the aggregate's body. A kind is data, the file
+      # `lib/hecks/language/kinds/<kind>.kind`, not code: `{Name}` in it stands for the aggregate's
+      # name and `{Stem}` for that name without the kind, and a `# body` line marks where the
+      # aggregate's own body is evaluated.
+      module Kinds
+        DIRECTORY = File.expand_path("../../language/kinds", __dir__).freeze
+        BODY_MARK = /^# body\n/
+
+        module_function
+
+        # The block an aggregate is built from: its own body, or, for a kind, that body inside the
+        # kind's text.
+        #
+        # @param name [String] the aggregate's name
+        # @param kind [String, nil] the kind written after `kind:`, if any
+        # @yield the aggregate's own body; may be omitted
+        # @return [Proc, nil] the block to evaluate on the aggregate's builder
+        # @raise [Malformed] if the kind has no file
+        def wrap(name, kind, &body)
+          return body unless kind
+
+          before, after = halves(kind, name)
+          file = path(kind)
+          proc do
+            instance_eval(before, file, 1)
+            instance_eval(&body) if body
+            instance_eval(after, file, before.lines.size + 2)
+          end
+        end
+
+        # @return [Array(String, String)] the kind's text, names filled in, split at the body
+        def halves(kind, name)
+          before, after = File.read(path(kind)).split(BODY_MARK, 2)
+          [before, after].map { |text| fill(text, name, kind) }
+        rescue Errno::ENOENT
+          raise Malformed, "#{name} declares kind #{kind.inspect}, which has no file at #{path(kind)}"
+        end
+
+        # @return [String] the kind's text with `{Name}` and `{Stem}` replaced
+        def fill(text, name, kind)
+          text.gsub("{Name}", name.to_s).gsub("{Stem}", name.to_s.delete_suffix(kind.to_s))
+        end
+
+        # @return [String] the file that holds a kind
+        def path(kind) = File.join(DIRECTORY, "#{kind.to_s.downcase}.kind")
+      end
+    end
+  end
+end

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

@@ -6,6 +6,9 @@ module Hecks
       class LifecycleBuilder
         GRAMMAR_CONTEXT = "Lifecycle".freeze
 
+        # A lowercase word: a letter, then letters, digits and underscores (`holds_seat`).
+        LOWERCASE_WORD = /\A[a-z][a-z0-9_]*\z/
+
         include WordGate
 
         # @param field [Symbol, String] the attribute the state machine lives on, such as `:status`
@@ -29,7 +32,7 @@ module Hecks
         #   declared twice, no states, or a state named twice in one mark
         def mark_impl(name, *states)
           mark = name.to_s
-          unless mark.match?(/\A[a-z][a-z0-9_]*\z/)
+          unless mark.match?(LOWERCASE_WORD)
             raise Malformed, "lifecycle :#{@field} mark #{name.inspect} is not a lowercase word (such as :holds_seat)"
           end
           raise Malformed, "lifecycle :#{@field} declares mark :#{mark} twice" if @marks.key?(mark)

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

@@ -25,6 +25,7 @@ module Hecks
           @owner     = owner
           @direction = direction
           @emits     = []
+          @handles   = []
         end
 
         # Refuses `reference_to` inside an operation body; a port operation has no self-reference
@@ -47,6 +48,12 @@ module Hecks
         # Names one event an inbound operation records once the external fact has arrived.
         def emits(event_name) = @emits << event_name.to_s
 
+        # Names one value of a command this operation handles, e.g. `handles "Build.build!",
+        # value: "wasm"`. Recorded in the IR only; nothing routes on it yet.
+        def handles_impl(command, value:)
+          @handles << { command: command.to_s, value: value.to_s }
+        end
+
         # `answers`/`refuses`, the two halves of an `asks` — separate words rather than two
         # `emits` so a reader can tell what came back from what the outside refused, without
         # reading the adapter.
@@ -64,7 +71,8 @@ module Hecks
 
           PortOperation.new(
             name: @name, attributes: attributes, emits: @emits,
-            direction: @direction, answers: @answers, refuses: @refuses, to: @to
+            direction: @direction, answers: @answers, refuses: @refuses, to: @to,
+            handles: @handles
           )
         end
 
@@ -116,7 +124,6 @@ module Hecks
 
         # Evaluates one operation block against a fresh builder and returns what it built;
         # `private` above doesn't reach this singleton method, since `.build` is the real entry.
-        # rubocop:disable-next Lint/IneffectiveAccessModifier
         def self.build(name, to: nil, owner: nil, direction: :inbound, &block)
           builder = new(name, to: to, owner: owner, direction: direction)
           builder.instance_eval(&block) if block