hecks 4.0.0 → 6.0.0

data/lib/hecks/bluebook/meta_validator/reconstruction.rb

@@ -12,18 +12,18 @@ module Hecks
         include Reading
         include Heads
 
-        # Reads one judged chapter back out of `runtime` and assembles it.
-        def self.of(runtime, chapter) = new(runtime, chapter).to_h
+        # Reads one judged bluebook back out of `runtime` and assembles it.
+        def self.of(runtime, declaration) = new(runtime, declaration).to_h
 
-        def initialize(runtime, chapter)
+        def initialize(runtime, declaration)
           @runtime = runtime
           @plan    = Plan.for(MetaValidator.grammar_registry)
-          @chapter = runtime.query("Bluebook::Bluebook.Called", name: { value: chapter }).first or
-            raise Runtime::NotFound, "the meta-domain holds no bluebook called #{chapter.inspect}"
+          @declaration = runtime.query("Bluebook::Bluebook.Called", name: { value: declaration }).first or
+            raise Runtime::NotFound, "the meta-domain holds no bluebook called #{declaration.inspect}"
         end
 
         def to_h
-          chapter_fields.merge(
+          bluebook_fields.merge(
             aggregates:       declared_as("Aggregate", :aggregate),
             read_models:      declared_as("ReadModel", :read_model),
             policies:         declared_as("Policy", :policy),
@@ -33,7 +33,7 @@ module Hecks
 
         private
 
-        def chapter_id = @chapter[:id].to_s
+        def bluebook_id = @declaration[:id].to_s
 
         def closed_set?(row) = !text(row[:rows]).nil?
 
@@ -52,22 +52,22 @@ module Hecks
           end
         end
 
-        # Everything of `category` declared in the chapter, each row read back by `builder`.
+        # Everything of `category` declared in the bluebook, each row read back by `builder`.
         def declared_as(category, builder)
-          declared(category, chapter_id).map { |row| send(builder, row) }
+          declared(category, bluebook_id).map { |row| send(builder, row) }
         end
 
-        # What the chapter itself holds, apart from what is declared in it.
-        def chapter_fields
+        # What the bluebook itself holds, apart from what is declared in it.
+        def bluebook_fields
           {
-            name:              text(@chapter[:name]),
-            version:           text(@chapter[:version]),
-            vision:            text(@chapter[:vision]),
-            classification:    text(@chapter[:classification]),
-            formerly_known_as: text(@chapter[:formerly_known_as]),
-            namespace:         text(@chapter[:namespace]),
-            attaches_to:       attached_contexts(@chapter),
-            provides:          provisions(@chapter)
+            name:              text(@declaration[:name]),
+            version:           text(@declaration[:version]),
+            vision:            text(@declaration[:vision]),
+            classification:    text(@declaration[:classification]),
+            formerly_known_as: text(@declaration[:formerly_known_as]),
+            namespace:         text(@declaration[:namespace]),
+            attaches_to:       attached_contexts(@declaration),
+            provides:          provisions(@declaration)
           }
         end
 

data/lib/hecks/bluebook/meta_validator/shapes.rb

@@ -28,7 +28,7 @@ module Hecks
 
           type = text(field[:type]).to_s
           # A qualified name is the tell: an ordinary type (`Money`, `AccountNumber`)
-          # carries no join at all, while a head's id always does (chapter + name).
+          # carries no join at all, while a head's id always does (bluebook + name).
           attribute_row(field, type.include?(Naming::IDENTITY_JOIN) ? reference_type(type) : text(field[:type]))
         end
 
@@ -44,6 +44,8 @@ module Hecks
           { name: text(row[:name]), reference: text(row[:reference]), remote_field: text(row[:remote_field]) }
         end
 
+        def acknowledgement(row) = { finding: text(row[:finding]), subject: text(row[:subject]), reason: text(row[:reason]) }
+
         # `provenance from: {...}` rides the same literal encoding `default:` does,
         # one level up: a whole keyword's argument rather than an attribute's.
         def provenance(row) = decode_literal(text(row[:provenance]))
@@ -55,6 +57,9 @@ module Hecks
         # A flag held as text ("true"/"false"), emitted as a boolean.
         def expect_undelivered?(row) = text(row[:expect_undelivered]).to_s == "true"
 
+        # `idempotent` is held as text like `expect_undelivered`, and emitted as a boolean.
+        def idempotent?(row) = text(row[:idempotent]).to_s == "true"
+
         # Kept as raw text, not decoded: this feeds `Assembly::Marks#where_clause`,
         # which decodes it via `read` — decoding here first would strip a kwarg
         # reference's colon, indistinguishable after from a same-named literal.

data/lib/hecks/bluebook/meta_validator/syntax_boot/disk_cache.rb

@@ -1,3 +1,5 @@
+require_relative "../../../switches"
+
 module Hecks
   module Bluebook
     module MetaValidator
@@ -8,31 +10,31 @@ module Hecks
           # marks an entry as used, so only the tables of other code age out.
           UNREAD_KEEP_SECONDS = 24 * 60 * 60
 
-          # `equal?`, not `==` — chapter identity, not value equality, is the
+          # `equal?`, not `==` — bluebook identity, not value equality, is the
           # fact this cache key tracks.
-          def same_chapters?(cached, current)
+          def same_bluebooks?(cached, current)
             cached.size == current.size &&
-              cached.zip(current).all? do |(cached_name, cached_chapter), (name, chapter)|
-                cached_name == name && cached_chapter.equal?(chapter)
+              cached.zip(current).all? do |(cached_name, cached_bluebook), (name, declaration)|
+                cached_name == name && cached_bluebook.equal?(declaration)
               end
           end
 
           # Cross-process persistence for the same build `call` already memoizes
-          # in-process, keyed by chapter name (not identity, which means nothing
+          # in-process, keyed by bluebook name (not identity, which means nothing
           # across processes) plus a content hash of every grammar file `boot`
           # can read from — so a source edit anywhere in that set misses the
           # cache rather than silently serving a stale table.
           def cache_dir = Hecks::CacheDir.path("hecks_syntax_boot_cache")
 
-          def disk_cache_enabled? = ENV["HECKS_SYNTAX_BOOT_CACHE"] != "off"
+          def disk_cache_enabled? = Hecks::Switches.syntax_boot_cache?
 
           # Fails toward a real boot, never toward a wrong table: a missing
           # file, a corrupt blob, or a permission error just misses the cache. A table
           # the user has not cached is looked for among the ones the gem ships.
-          def read_disk_cache(chapters)
+          def read_disk_cache(declarations)
             return nil unless disk_cache_enabled?
 
-            path = disk_cache_path(chapters)
+            path = disk_cache_path(declarations)
             return load_table(path, touch: true) if File.exist?(path)
 
             shipped = Hecks::CacheDir.prebuilt(File.basename(path))
@@ -53,10 +55,10 @@ module Hecks
           # Writes to a PID-suffixed temp file and renames it into place, so a
           # concurrent writer's rename can only overwrite with identical
           # content, never leave a torn file for a concurrent reader.
-          def write_disk_cache(chapters, result)
+          def write_disk_cache(declarations, result)
             return unless disk_cache_enabled?
 
-            path = disk_cache_path(chapters)
+            path = disk_cache_path(declarations)
             FileUtils.mkdir_p(cache_dir)
             tmp_path = "#{path}.#{Process.pid}.tmp"
             File.binwrite(tmp_path, Marshal.dump(result))
@@ -75,23 +77,24 @@ module Hecks
             end
           end
 
-          def disk_cache_path(chapters)
-            File.join(cache_dir, "#{disk_cache_key(chapters)}.marshal")
+          def disk_cache_path(declarations)
+            File.join(cache_dir, "#{disk_cache_key(declarations)}.marshal")
           end
 
-          def disk_cache_key(chapters)
-            names = chapters.map { |name, _chapter| name }
+          def disk_cache_key(declarations)
+            names = declarations.map { |name, _bluebook| name }
             Digest::SHA256.hexdigest("#{names.join(",")}:#{grammar_content_digest}:#{VerdictCache.code_digest}")
           end
 
           # The key also carries `VerdictCache.code_digest` (all of `lib/`), so an
           # edit to Ruby that builds or judges the grammar misses too.
           #
-          # Covers every chapter's grammar files, not just the core ones —
+          # Covers every bluebook's grammar files, not just the core ones —
           # coarser than strictly necessary, but under-covering this set would
           # let a stale table survive a real grammar edit.
           def grammar_content_digest
             files = (MetaValidator::GRAMMAR_FILES + MetaValidator::WORLD_GRAMMAR + MetaValidator::HECKSAGON_GRAMMAR +
+                      MetaValidator::CONTEXT_MAP_GRAMMAR +
                       Dir.glob(File.join(MetaValidator::ATTACHED_GRAMMAR_DIR, "*.bluebook"))).sort
             Digest::SHA256.hexdigest(files.map { |file| File.read(file) }.join("\0"))
           end

data/lib/hecks/bluebook/meta_validator/syntax_boot.rb

@@ -15,27 +15,35 @@ module Hecks
 
         module_function
 
-        # Memoized per grammar-registry chapter set (identity, not a "ready"
+        # Memoized per grammar-registry bluebook set (identity, not a "ready"
         # flag), and cross-process on disk, since a full boot is real work.
         #
         # @return [Hash{Symbol => Array<Hash{Symbol => String}>}] `:keywords`
         #   and `:arguments`, each an array of plain, string-valued row
         #   hashes (`status` included)
         def call
-          chapters = MetaValidator.grammar_registry.bluebooks.to_a
-          return @call if @call && same_chapters?(@call_chapters, chapters)
+          declarations = grammar_bluebooks.to_a
+          return @call if @call && same_bluebooks?(@call_bluebooks, declarations)
 
-          result = read_disk_cache(chapters) || begin
+          result = read_disk_cache(declarations) || begin
             fresh = boot
-            write_disk_cache(chapters, fresh)
+            write_disk_cache(declarations, fresh)
             fresh
           end
 
           @call = result
-          @call_chapters = chapters
+          @call_bluebooks = declarations
           result
         end
 
+        # The bluebooks the grammar registry holds, in insertion order.
+        #
+        # @return [Hash{String => Bluebook::Declaration}] each bluebook by name
+        def grammar_bluebooks
+          registry = MetaValidator.grammar_registry
+          registry.bluebooks
+        end
+
         # Dispatches every seed row into a fresh "Bluebook" instance and
         # reads the result back. The table is memoized for the process, so it is built with no
         # ambient caller: an enclosing `Hecks.as_caller` would have the language's own
@@ -73,7 +81,7 @@ module Hecks
           v(text)
         end
 
-        # This fresh runtime holds no chapter record of its own, so one is
+        # This fresh runtime holds no bluebook record of its own, so one is
         # declared first, purely to satisfy `Syntax.Declare`'s `reference_to
         # Bluebook` — its vision/classification are never read afterward.
         def declare_syntax(runtime, bluebook)
@@ -131,13 +139,13 @@ module Hecks
         # Concatenated into one sequence because `position` is minted from
         # the walk index and must not collide across concepts.
         def all_rows(bluebook, name)
-          seed_chapters(bluebook).flat_map { |chapter| rows(chapter, name) }
+          seed_bluebooks(bluebook).flat_map { |declaration| rows(declaration, name) }
         end
 
         # `bluebook` first, then registry insertion order, so the core
-        # chapter is never read twice.
-        def seed_chapters(bluebook)
-          [bluebook] + MetaValidator.grammar_registry.bluebooks.values.reject { |chapter| chapter.name == bluebook.name }
+        # bluebook is never read twice.
+        def seed_bluebooks(bluebook)
+          [bluebook] + grammar_bluebooks.values.reject { |declaration| declaration.name == bluebook.name }
         end
 
         def rows(bluebook, name)
@@ -153,7 +161,7 @@ module Hecks
         # `rows` hands the seed data in as.
         def read_back(runtime, bluebook)
           syntax = bluebook.aggregate("Syntax")
-          repository = runtime.registry.repository("Bluebook", syntax)
+          repository = runtime.repository("Bluebook", syntax)
           instance   = repository.find(Naming.identity([syntax.hecks_name]))
 
           {
@@ -163,9 +171,7 @@ module Hecks
         end
 
         def stringify(row)
-          row.to_h.transform_values do |cell|
-            scalar(cell).to_s
-          end
+          row.to_h.transform_values { |cell| scalar(cell).to_s }
         end
 
         # Unwraps a value-object-wrapped field back to its bare scalar.

data/lib/hecks/bluebook/meta_validator/verdict_cache/prebuilt.rb

@@ -5,11 +5,14 @@ module Hecks
         # The verdict file the process reads (its own, else the one a packaged gem ships) and the
         # Ruby series that file is valid for.
         module Prebuilt
+          # The major and minor parts of a version string: the "3.3" of "3.3.6".
+          MAJOR_MINOR = /\A\d+\.\d+/
+
           # The Ruby the judging code ran on, to the minor version: a patch release changes neither
           # a verdict nor the encoding of one, so a cache built on one patch serves the others.
           #
           # @return [String] such as `ruby-3.3`
-          def ruby_series = "#{RUBY_ENGINE}-#{RUBY_VERSION[/\A\d+\.\d+/]}"
+          def ruby_series = "#{RUBY_ENGINE}-#{RUBY_VERSION[MAJOR_MINOR]}"
 
           # The file the gem ships for the current code's verdicts, when it ships one.
           #

data/lib/hecks/bluebook/meta_validator/verdict_cache.rb

@@ -5,17 +5,18 @@ require_relative "../../cache_dir"
 require_relative "../../version"
 require_relative "verdict_cache/tagging"
 require_relative "verdict_cache/prebuilt"
+require_relative "../../switches"
 
 module Hecks
   module Bluebook
     module MetaValidator
-      # Cross-process store of the meta-domain's chapter verdicts, so a boot
-      # judges only the chapters no earlier process has judged.
+      # Cross-process store of the meta-domain's bluebook verdicts, so a boot
+      # judges only the bluebooks no earlier process has judged.
       #
-      # Only chapter verdicts live here; `Assembly.call` still runs every boot
+      # Only bluebook verdicts live here; `Assembly.call` still runs every boot
       # and a miss judges as a cold process does. The file name carries a digest
       # of the judging code (`lib/` outside `CONSUMER_TREES`, the Ruby and Hecks
-      # versions, `FORMAT`); each entry is keyed by the chapter IR's SHA-256.
+      # versions, `FORMAT`); each entry is keyed by the bluebook IR's SHA-256.
       # The file is tagged JSON, never `Marshal`, read only from a private,
       # user-owned directory: a forged "no refusals" entry would skip validation.
       #
@@ -31,7 +32,7 @@ module Hecks
         FORMAT = 1
 
         # The subtrees of `lib/` that read the language and never judge it: they
-        # project, serve or deploy from a chapter, and nothing the judge runs
+        # project, serve or deploy from a bluebook, and nothing the judge runs
         # calls into them. An edit there leaves every verdict as it was, so
         # their files stay out of the key. Paths are relative to `lib/hecks`.
         CONSUMER_TREES = %r{\A/hecks/(?:bench|cli|codemod|deploy|doc|adapters/driving|fuzzing|projections|
@@ -44,7 +45,7 @@ module Hecks
         # Whether the disk cache is on; `HECKS_VERDICT_CACHE=off` disables it.
         #
         # @return [Boolean]
-        def enabled? = ENV["HECKS_VERDICT_CACHE"] != "off"
+        def enabled? = Hecks::Switches.verdict_cache?
 
         # The directory the verdict files live in.
         #
@@ -90,7 +91,7 @@ module Hecks
         # Loads the stored verdicts, once per process; later calls return an
         # empty hash so a caller that resets its own memo re-judges for real.
         #
-        # @return [Hash{String => Hash}] verdicts by chapter key; empty when
+        # @return [Hash{String => Hash}] verdicts by bluebook key; empty when
         #   the cache is off, absent, unreadable, corrupt or not private
         def seed
           return {} if @seeded
@@ -105,9 +106,9 @@ module Hecks
           {}
         end
 
-        # Remembers a freshly judged chapter verdict for the next `flush`.
+        # Remembers a freshly judged bluebook verdict for the next `flush`.
         #
-        # @param key [String] the chapter's SHA-256 key
+        # @param key [String] the bluebook's SHA-256 key
         # @param held [Hash] the verdict `MetaValidator.hold` returned
         # @return [void]
         def record(key, held)
@@ -160,7 +161,7 @@ module Hecks
         end
 
         # @param entries [Object] a decoded `entries` value
-        # @return [Boolean] whether it is a hash of chapter verdicts
+        # @return [Boolean] whether it is a hash of bluebook verdicts
         def well_formed?(entries)
           entries.is_a?(Hash) && entries.all? do |key, held|
             key.is_a?(String) && held.is_a?(Hash) && held[:refusals].is_a?(Array) &&

data/lib/hecks/bluebook/meta_validator.rb

@@ -15,6 +15,7 @@ module Hecks
       GRAMMAR_FILES = Dir.glob(File.join(GRAMMAR_DIR, "*.bluebook")).freeze
       WORLD_GRAMMAR = Dir.glob(File.expand_path("../language/world/*.bluebook", __dir__)).freeze
       HECKSAGON_GRAMMAR = Dir.glob(File.expand_path("../language/hecksagon/*.bluebook", __dir__)).freeze
+      CONTEXT_MAP_GRAMMAR = Dir.glob(File.expand_path("../language/context_map/*.bluebook", __dir__)).freeze
       # Backs PortJudge, the same entry point shape as WorldJudge.
       PORT_GRAMMAR = File.expand_path("../language/port.bluebook", __dir__).freeze
       # Backs AdapterJudge, one file over.
@@ -23,22 +24,22 @@ module Hecks
       TRANSLATION_GRAMMAR = Dir.glob(File.expand_path("../language/translation/*.bluebook", __dir__)).freeze
 
       # (ADR 0026) Any bluebook file placed here is auto-discovered and
-      # loaded as an extension chapter; nothing else in this file changes.
+      # loaded as an extension bluebook; nothing else in this file changes.
       ATTACHED_GRAMMAR_DIR = File.expand_path("../language/bluebook/attaches", __dir__).freeze
 
-      # The chapters loaded raw at bootstrap, then judged through themselves
+      # The bluebooks loaded raw at bootstrap, then judged through themselves
       # and replaced by their own self-assembled graphs.
-      LANGUAGE_CHAPTERS = %w[Bluebook World Hecksagon].freeze
+      LANGUAGE_BLUEBOOKS = %w[Bluebook World Hecksagon].freeze
 
       # Process-wide judging cache, keyed on a SHA-256 digest of the judged
       # artifact so a changed bluebook is always re-judged.
       #
-      # Seeded once per process with the chapter verdicts earlier processes
+      # Seeded once per process with the bluebook verdicts earlier processes
       # stored (see `VerdictCache`); every other verdict starts empty.
       #
       # @return [Hash{String => Object}] refusal messages per digest for a
       #   world/port/adapter/translation (`[]` when well formed); the held
-      #   verdict Hash for a chapter
+      #   verdict Hash for a bluebook
       def self.verdicts = @verdicts ||= VerdictCache.seed
 
       # Judges `world` through the meta-domain's own `WorldJudge` entry point.
@@ -71,7 +72,8 @@ module Hecks
       # @raise [DSL::Malformed] if `AdapterJudge` finds `adapter` malformed
       def self.call_adapter(adapter)
         judge_artifact(adapter, AdapterJudge, "#{adapter.name}'s adapter") do
-          JSON.generate([adapter.name, adapter.port, adapter.fields, adapter.secrets, adapter.declared_defaults])
+          JSON.generate([adapter.name, adapter.port, adapter.fields, adapter.secrets, adapter.declared_defaults,
+                         adapter.answered_queries, adapter.runs, adapter.capabilities])
         end
       end
 
@@ -91,7 +93,7 @@ module Hecks
         judge_artifact(translation, TranslationJudge, "#{translation.domain}'s translation") { translation.inspect }
       end
 
-      # The one entry point every artifact but a chapter goes through: skip while judging is off,
+      # The one entry point every artifact but a bluebook goes through: skip while judging is off,
       # else judge once per distinct `key_text` and refuse a malformed artifact.
       #
       # @param subject [Object] the artifact to judge
@@ -114,7 +116,7 @@ module Hecks
       # meta-domain assembles from its own judged declarations, not the
       # builder's original object graph.
       #
-      # @param bluebook [Object] a built bluebook chapter graph (an
+      # @param bluebook [Object] a built bluebook graph (an
       #   `Aggregate`/`Entity`/`ValueObject`/... instance from
       #   `lib/hecks/bluebook/`), answering `to_h` and `hecks_name`
       # @return [Object] `bluebook` unchanged while disabled, bootstrapping,
@@ -125,7 +127,7 @@ module Hecks
       def self.call(bluebook)
         return bluebook if disabled? || bootstrapping? || shadow_parsing?
 
-        return defer_chapter(bluebook) if deferring?
+        return defer_bluebook(bluebook) if deferring?
 
         held = held_verdict(bluebook)
         unless held[:refusals].empty?
@@ -136,14 +138,14 @@ module Hecks
         Assembly.call(held[:declaration])
       end
 
-      # @param bluebook [Object] a built bluebook chapter graph
+      # @param bluebook [Object] a built bluebook graph
       # @return [Object] `bluebook`, queued for `judge_deferred!`
-      def self.defer_chapter(bluebook)
-        deferred_chapters << bluebook.hecks_name
+      def self.defer_bluebook(bluebook)
+        deferred_bluebooks << bluebook.hecks_name
         bluebook
       end
 
-      # @param bluebook [Object] a built bluebook chapter graph
+      # @param bluebook [Object] a built bluebook graph
       # @return [Hash{Symbol => Object}] the verdict `hold` produced for it, cached by digest
       def self.held_verdict(bluebook)
         key = Digest::SHA256.hexdigest(JSON.generate(bluebook.to_h))
@@ -151,10 +153,10 @@ module Hecks
       end
 
       # Dispatches `bluebook` into the meta-domain and reads the result back.
-      # A refused chapter carries only its refusals — the records are
+      # A refused bluebook carries only its refusals — the records are
       # half-written by definition.
       #
-      # @param bluebook [Object] a built bluebook chapter graph, as `call`
+      # @param bluebook [Object] a built bluebook graph, as `call`
       #   receives it
       # @return [Hash{Symbol => Object}] `{refusals: [...]}` when `Judge`
       #   refuses any declaration; otherwise `{refusals: [],
@@ -172,7 +174,7 @@ module Hecks
       # ambient caller bound. A caller inside `while_shadow_parsing` that is first to ask would
       # otherwise memoize a grammar parsed in that mode, or fail to load it; one inside
       # `Hecks.as_caller` would have the language's own `Language`-role commands refused, and the
-      # grammar would be memoized without the chapters those refusals dropped.
+      # grammar would be memoized without the bluebooks those refusals dropped.
       #
       # @return [Runtime::Registry] the booted, fixpoint-judged language
       #   registry
@@ -193,7 +195,7 @@ module Hecks
         # judged by that assembled graph, not the raw bootstrap one. Must
         # run after load_grammar_into's ensure clears @bootstrapping.
         while_forcing_fixpoint do
-          LANGUAGE_CHAPTERS.each { |name| registry.add_bluebook(call(registry.bluebook(name))) }
+          LANGUAGE_BLUEBOOKS.each { |name| registry.add_bluebook(call(registry.bluebook(name))) }
           load_attached_grammar_into(registry)
         end
         # Keyed on this registry's object identity, not a bare boolean, so
@@ -203,11 +205,11 @@ module Hecks
         registry
       end
 
-      # Loads every `ATTACHED_GRAMMAR_DIR` chapter file into `registry`,
+      # Loads every `ATTACHED_GRAMMAR_DIR` bluebook file into `registry`,
       # judged the ordinary way since the fixpoint has already run.
       #
       # @param registry [Runtime::Registry] the registry to load every
-      #   `ATTACHED_GRAMMAR_DIR` chapter file into
+      #   `ATTACHED_GRAMMAR_DIR` bluebook file into
       # @return [void]
       def self.load_attached_grammar_into(registry)
         Hecks.with_registry(registry) do
@@ -215,10 +217,10 @@ module Hecks
         end
       end
 
-      # Loads the whole grammar (ports, adapters, every language chapter)
+      # Loads the whole grammar (ports, adapters, every language bluebook)
       # into `registry`, raw and unjudged.
       #
-      # The `@bootstrapping` guard matters: without it a chapter split
+      # The `@bootstrapping` guard matters: without it a bluebook split
       # across files would get judged one file at a time and refuse early.
       #
       # @param registry [Runtime::Registry] the registry to load the whole
@@ -237,7 +239,8 @@ module Hecks
         preamble = ["../ports/persistence.port", "../ports/extraction.port",
                     "../adapters/driven/memory.adapter", "../adapters/driven/prism.adapter"]
         preamble.map { |path| File.expand_path(path, __dir__) } +
-          GRAMMAR_FILES + WORLD_GRAMMAR + HECKSAGON_GRAMMAR + [PORT_GRAMMAR, ADAPTER_GRAMMAR] + TRANSLATION_GRAMMAR
+          GRAMMAR_FILES + WORLD_GRAMMAR + HECKSAGON_GRAMMAR + [PORT_GRAMMAR, ADAPTER_GRAMMAR] + TRANSLATION_GRAMMAR +
+          CONTEXT_MAP_GRAMMAR
       end
 
       # A dispatcher over the shared grammar registry with its records

data/lib/hecks/bluebook/model_check/aggregate_checks.rb

@@ -0,0 +1,68 @@
+require_relative "lifecycle_checks"
+
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The checks over an aggregate's size: one that keeps collecting commands, entities and
+      # states usually holds more than one consistency boundary (ADR 0137). Its lifecycle states
+      # are counted with {LifecycleChecks#full_states}, so the two come together.
+      module AggregateChecks
+        include LifecycleChecks
+
+        # How much an aggregate may declare before it is reported: its commands, entities and
+        # lifecycle states, counted together.
+        LARGE_AGGREGATE_LIMIT = 40
+
+        # How many of the least-attached commands the message names.
+        SUGGESTED_COMMANDS = 3
+
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook to check
+        # @param limit [Integer] the weight an aggregate may reach before it is reported
+        # @return [Array<Finding>] one :large_aggregate warning per aggregate over the limit
+        def large_aggregate_findings(bluebook, limit: LARGE_AGGREGATE_LIMIT)
+          bluebook.aggregates.filter_map { |aggregate| large_aggregate_finding(aggregate, limit) }
+        end
+
+        # @return [Finding, nil] the warning for an aggregate heavier than `limit`
+        def large_aggregate_finding(aggregate, limit)
+          weight = aggregate_weight(aggregate)
+          return unless weight > limit
+          return if Acknowledgements.held?(aggregate, :large_aggregate)
+
+          Finding.new(kind: :large_aggregate, severity: :warning, subject: aggregate.hecks_name,
+                      message: "declares #{weight} commands, entities and states together, past the " \
+                               "limit of #{limit} — it may hold more than one consistency boundary" \
+                               "#{loosest_commands_hint(aggregate)}")
+        end
+
+        # @return [Integer] the aggregate's commands, entities and states, counted together
+        def aggregate_weight(aggregate)
+          aggregate.commands.size + aggregate.entities.size + lifecycle_state_count(aggregate.lifecycle)
+        end
+
+        # @return [Integer] the states the lifecycle names, or zero without one
+        def lifecycle_state_count(lifecycle)
+          lifecycle ? full_states(lifecycle).size : 0
+        end
+
+        # The commands that set the fewest of the aggregate's own fields are the likeliest to
+        # belong to another aggregate, so the message names them.
+        #
+        # @return [String] a clause naming those commands, or an empty string if none set a field
+        def loosest_commands_hint(aggregate)
+          loosest = aggregate.commands.reject { |command| fields_set_by(command).empty? }
+                             .min_by(SUGGESTED_COMMANDS) { |command| fields_set_by(command).size }
+          return "" if loosest.empty?
+
+          "; the commands setting the fewest fields are #{loosest.map(&:hecks_name).join(", ")}"
+        end
+
+        # @return [Array<String>] the own fields a command sets; a delegation names none of its own
+        def fields_set_by(command)
+          own = command.mutations.reject { |mutation| mutation.op == :delegate }
+          own.map { |mutation| mutation.target.to_s }.uniq
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/model_check/ask_checks.rb

@@ -6,7 +6,7 @@ module Hecks
       # The checks over `ask`: one that resolves to no declared port operation, a port trigger
       # that should be an ask, and a declared ask no policy reaches.
       module AskChecks
-        # @param bluebook [Bluebook::Chapter] the chapter the policy is declared in
+        # @param bluebook [Bluebook::Declaration] the bluebook the policy is declared in
         # @param policy [Bluebook::Policy] the policy to check
         # @return [Finding, nil] an error for an `ask` that names no declared ask (or an
         #   ambiguous one), a warning for a `trigger` that names a port operation, else `nil`
@@ -21,7 +21,7 @@ module Hecks
 
         # A port operation no policy reaches, by `ask` or by a trigger that names it.
         #
-        # @param bluebook [Bluebook::Chapter] the chapter whose aggregates declare the ports
+        # @param bluebook [Bluebook::Declaration] the bluebook whose aggregates declare the ports
         # @return [Array<Finding>] one warning per outbound operation nothing asks
         def unused_ask_findings(bluebook)
           reached = reached_port_verbs(bluebook)
@@ -39,11 +39,12 @@ module Hecks
         private
 
         def port_trigger_finding(bluebook, policy)
-          return unless port_operation_verb?(bluebook, policy.trigger_command)
+          trigger = policy.trigger_command
+          return unless port_operation_verb?(bluebook, trigger)
 
           Finding.new(kind: :port_trigger, severity: :warning, subject: policy.name,
-                      message: "trigger #{policy.trigger_command.inspect} names a port operation — " \
-                               "write `ask :#{Naming.snake(policy.trigger_command.to_s.split(".").last)}` and " \
+                      message: "trigger #{trigger.inspect} names a port operation — " \
+                               "write `ask :#{Naming.snake(Naming.last_segment(trigger))}` and " \
                                "let the hecksagon map the port")
         end