hecks 5.0.0 → 7.0.0

data/lib/hecks/bluebook/expression/resolver/parsing.rb

@@ -16,6 +16,18 @@ module Hecks
           [/\A(.+)\.set\?\z/, Assignment, { negated: false }], [/\A(.+)\.unset\?\z/, Assignment, { negated: true }]
         ].freeze
 
+        # A receiver followed by `.length`, capturing the receiver.
+        LENGTH_CALL = /\A(.+)\.length\z/
+
+        # An optionally negative whole-number literal.
+        INTEGER_LITERAL = /\A-?\d+\z/
+
+        # An optionally negative decimal literal; the digits before the point may be left out.
+        FLOAT_LITERAL = /\A-?\d*\.\d+\z/
+
+        # A `receiver.match?(/pattern/flags)` call, capturing the receiver, pattern and flags.
+        MATCHES_REGEX_CALL = %r{\A(.+)\.match\?\(/(.*)/([a-z]*)\)\z}m
+
         # The strip family, each matched as `<receiver>.<call>`, naming which ends it trims.
         STRIP_SUFFIXES = [
           [/\A(.+)\.strip\z/, :both], [/\A(.+)\.lstrip\z/, :left], [/\A(.+)\.rstrip\z/, :right]
@@ -52,7 +64,7 @@ module Hecks
         end
 
         def parse_length(expr)
-          length = expr.match(/\A(.+)\.length\z/)
+          length = expr.match(LENGTH_CALL)
           Size.new(receiver: parse(length[1])) if length
         end
 
@@ -60,10 +72,10 @@ module Hecks
           return StringLiteral.new(value: expr[1..-2]) if quoted?(expr)
 
           case expr
-          when /\A-?\d+\z/       then IntegerLiteral.new(value: Integer(expr, 10))
-          when /\A-?\d*\.\d+\z/  then FloatLiteral.new(value: Float(expr))
-          when "true", "false"   then BoolLiteral.new(value: expr == "true")
-          when "nil"             then NilLiteral.new
+          when INTEGER_LITERAL then IntegerLiteral.new(value: Integer(expr, 10))
+          when FLOAT_LITERAL   then FloatLiteral.new(value: Float(expr))
+          when "true", "false" then BoolLiteral.new(value: expr == "true")
+          when "nil"           then NilLiteral.new
           end
         end
 
@@ -73,19 +85,13 @@ module Hecks
         end
 
         # The additive level: the last top-level `+` or binary `-`, so `a - b + c` is `(a - b) + c`.
-        def parse_additive(expr)
-          parse_binary(expr, ADDITIVE)
-        end
+        def parse_additive(expr) = parse_binary(expr, ADDITIVE)
 
         # The multiplicative level, binding tighter than the additive one.
-        def parse_multiplicative(expr)
-          parse_binary(expr, MULTIPLICATIVE)
-        end
+        def parse_multiplicative(expr) = parse_binary(expr, MULTIPLICATIVE)
 
         # A parenthesised group reads as what it wraps.
-        def parse_group(expr)
-          parse(expr[1..-2]) if grouped?(expr)
-        end
+        def parse_group(expr) = (parse(expr[1..-2]) if grouped?(expr))
 
         def parse_binary(expr, table)
           operator, left, right = split_last_binary(expr, table.keys)
@@ -119,7 +125,7 @@ module Hecks
         end
 
         def parse_matches_regex(expr)
-          match = expr.match(%r{\A(.+)\.match\?\(/(.*)/([a-z]*)\)\z}m)
+          match = expr.match(MATCHES_REGEX_CALL)
           MatchesRegex.new(receiver: parse(match[1]), pattern: match[2], flags: match[3]) if match
         end
 

data/lib/hecks/bluebook/expression/resolver/scanning.rb

@@ -10,6 +10,9 @@ module Hecks
         # Quote characters a leaf expression may open a string literal with.
         QUOTES = ['"', "'"].freeze
 
+        # A final character that ends an operand: a word character, a closing bracket or a quote.
+        OPERAND_END = /[[:alnum:]_)\]"']\z/
+
         # How each bracket moves the nesting depth for a split on `+` or `,`. `{`/`}` and
         # `[`/`]` count like parens, so a `+` inside a block body or an array element is not this
         # expression's own addition.
@@ -88,7 +91,7 @@ module Hecks
         def binary_position?(expr, index, char)
           return true unless char == "-"
 
-          expr[0...index].rstrip.match?(/[[:alnum:]_)\]"']\z/)
+          expr[0...index].rstrip.match?(OPERAND_END)
         end
 
         # Whether `expr` is one parenthesised group: its first `(` closes at its last character.

data/lib/hecks/bluebook/expression.rb

@@ -1,7 +1,7 @@
 module Hecks
   module Bluebook
     # The expression language a bluebook's predicates are written in —
-    # canonicalised (canonical_form), resolved against a chapter's names
+    # canonicalised (canonical_form), resolved against a bluebook's names
     # (resolver), and evaluated (evaluator).
     module Expression
     end

data/lib/hecks/bluebook/hecksagon.rb

@@ -14,13 +14,37 @@ module Hecks
     # `defaults` maps a field's name to the value used when the world gives none; a string may hold
     # a `{name}` or `{storage_name}` placeholder, filled from the aggregate the adapter is built
     # for.
-    Adapter = Struct.new(:name, :port, :fields, :secrets, :defaults, keyword_init: true) do
+    #
+    # A plugin adapter instead `runs` a `.wasm` module beside its `.adapter` file (`source_dir`)
+    # and names the queries it `answers` (`"Bluebook::Aggregate.Query"`); it needs no port, and the
+    # runtime binds each query it answers without a hecksagon line.
+    #
+    # `provides` names what the adapter can do beyond its port's contract, such as
+    # `"set_transform"`; a caller asks before relying on it.
+    Adapter = Struct.new(:name, :port, :fields, :secrets, :defaults, :answers, :runs, :provides, :source_dir,
+                         keyword_init: true) do
       def declares?(field) = all_fields.include?(field.to_sym)
 
       def all_fields = (fields || []) + (secrets || [])
 
       # @return [Hash{Symbol => Object}] the declared defaults, empty when none
       def declared_defaults = defaults || {}
+
+      # @return [Array<String>] the qualified queries this adapter answers, empty when none
+      def answered_queries = answers || []
+
+      # @return [Array<String>] the capabilities this adapter provides, empty when none
+      def capabilities = provides || []
+
+      # @param capability [String, Symbol] a capability's name, such as `"set_transform"`
+      # @return [Boolean] whether this adapter declares `provides` for it
+      def provides?(capability) = capabilities.include?(capability.to_s)
+
+      # @return [Boolean] whether this adapter is a wasm plugin
+      def plugin? = !runs.nil?
+
+      # @return [String, nil] where the plugin's module is, beside its `.adapter` file
+      def plugin_path = runs && File.expand_path(runs, source_dir || Dir.pwd)
     end
 
     Bind = Struct.new(:aggregate, :verb, :adapter, :role, keyword_init: true) do
@@ -28,18 +52,19 @@ module Hecks
       def aggregate_name = Naming.demodulise(aggregate)
     end
 
-    # One chapter a hecksagon attaches, with where it was found.
+    # One bluebook a hecksagon attaches, with where it was found.
     #
-    # `source` is `:gem` for a chapter the gem carries (a framework member such as Governance,
-    # or a language chapter such as Deploy) and `:vendor` for a package vendored into the
-    # consuming project, whose `name` is the package's directory name (`"membership"`).
-    Attachment = Struct.new(:name, :source, keyword_init: true) do
-      # @return [Boolean] whether the chapter is a vendored package
+    # `source` is `:gem` for a bluebook the gem carries (a framework member such as Governance,
+    # or a language bluebook such as Deploy) and `:vendor` for a package vendored into the
+    # consuming project, whose `name` is the package's directory name (`"membership"`) and whose
+    # `bluebook` is the name its bluebook declares, which the directory name need not spell.
+    Attachment = Struct.new(:name, :source, :declaration, keyword_init: true) do
+      # @return [Boolean] whether the bluebook is a vendored package
       def vendor? = source == :vendor
 
-      # @return [String] the chapter's name in the registry: a gem chapter's own name, a
-      #   vendored package's directory name in Pascal case
-      def chapter_name = vendor? ? Naming.pascal(name) : name
+      # @return [String] the bluebook's name in the registry: a gem bluebook's own name, a
+      #   vendored package's declared bluebook, else its directory name in Pascal case
+      def declaration_name = declaration || (vendor? ? Naming.pascal(name) : name)
 
       # @return [Hash{Symbol => String}] the attachment as plain data
       def to_h = { name: name.to_s, source: source.to_s }
@@ -75,10 +100,10 @@ module Hecks
       # @param binds [Array<Bluebook::Bind>] the declared adapter binds
       # @param subscriptions [Array<String, Symbol>] the external events this domain
       #   subscribes to
-      # @param attachments [Array<Bluebook::Attachment>] every chapter this hecksagon attaches,
+      # @param attachments [Array<Bluebook::Attachment>] every bluebook this hecksagon attaches,
       #   each with its source (`:gem` or `:vendor`)
-      # @param bounded [Boolean] whether this chapter is an explicit bounded context
-      #   (consumer-owned; `attaches` marks attached chapters bounded on the registry instead)
+      # @param bounded [Boolean] whether this bluebook is an explicit bounded context
+      #   (consumer-owned; `attaches` marks attached bluebooks bounded on the registry instead)
       # @param translates [Array<String>] names of `translates` ACL blocks declared here
       # @param driving [Array<String>] the driving adapters `driven_by` admits; empty admits all
       def initialize(domain:, **given)
@@ -89,22 +114,22 @@ module Hecks
         @driving            = Array(@driving).map(&:to_s)
       end
 
-      # Says whether this hecksagon marked its own chapter `bounded`.
+      # Says whether this hecksagon marked its own bluebook `bounded`.
       #
       # @return [Boolean] whether `bounded` was declared on this block
       def bounded? = @bounded
 
-      # Every chapter this hecksagon brings into its domain's registry, gem and vendored alike.
+      # Every bluebook this hecksagon brings into its domain's registry, gem and vendored alike.
       #
-      # @return [Array<String>] the chapters' names as the registry holds them, in the order
+      # @return [Array<String>] the bluebooks' names as the registry holds them, in the order
       #   they were attached
-      def member_chapters = attachments.map(&:chapter_name)
+      def member_bluebooks = attachments.map(&:declaration_name)
 
-      # Says whether this hecksagon attaches a chapter, whatever its source.
+      # Says whether this hecksagon attaches a bluebook, whatever its source.
       #
-      # @param chapter [String, Symbol] a chapter's name as the registry holds it
-      # @return [Boolean] whether that chapter is attached here
-      def attaches?(chapter) = member_chapters.include?(chapter.to_s)
+      # @param bluebook [String, Symbol] a bluebook's name as the registry holds it
+      # @return [Boolean] whether that bluebook is attached here
+      def attaches?(declaration) = member_bluebooks.include?(declaration.to_s)
 
       # Says whether a driving adapter may reach this hecksagon's domain: every adapter may when
       # none is declared, and only the declared ones may once any is.
@@ -142,11 +167,11 @@ module Hecks
       #   if none is declared
       # @param settings [Hash] the declared adapter bind settings, keyed by verb and,
       #   for a qualified entry, `"verb:adapter"`
-      # @param default_database [String, nil] the connection every chapter's
+      # @param default_database [String, nil] the connection every bluebook's
       #   database-taking persistence adapter uses unless its own settings name one,
       #   or `nil` if none is declared
       # @param default_adapter [String, nil] the persistence adapter every aggregate
-      #   binds to unless its chapter's hecksagon binds it, or `nil` if none is declared
+      #   binds to unless its bluebook's hecksagon binds it, or `nil` if none is declared
       def initialize(domain:, **given)
         KeywordFields.assign(self, KeywordFields.fill(given, FIELD_DEFAULTS))
         @domain           = domain.to_s

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

@@ -36,9 +36,12 @@ module Hecks
         end
 
         def judge!
-          send_to("Adapter::Adapter.Declare", @adapter.name, name: v(@adapter.name), port: v(@adapter.port))
+          send_to("Adapter::Adapter.Declare", @adapter.name, name: v(@adapter.name), port: v(@adapter.port),
+                                                             runs: v(@adapter.runs))
           add_fields
           add_all("AddSecret", @adapter.secrets)
+          add_all("AnswerQuery", @adapter.answered_queries)
+          add_all("Provide", @adapter.capabilities)
         end
 
         # Offers one `AddField` per field, each with its declared default when it has one.

data/lib/hecks/bluebook/meta_validator/judge/cells.rb

@@ -43,7 +43,7 @@ module Hecks
           end
 
           # A value object's type may be declared on a different aggregate
-          # in the same chapter; the local aggregate is tried first, then
+          # in the same bluebook; the local aggregate is tried first, then
           # the first (declaration-order) other aggregate that declares it.
           def owning_aggregate_id(id, value)
             local = @bluebook.aggregates.find { |aggregate| Naming.identity([@bluebook.name, aggregate.name]) == id }

data/lib/hecks/bluebook/meta_validator/judge/identity.rb

@@ -17,14 +17,19 @@ module Hecks
             { value: text.to_s }
           end
 
-          # A reference argument is passed as the bare id it names; every
-          # other field is wrapped as a one-field value object instead.
+          # A reference argument is passed as the bare id it names; a list argument is passed
+          # as one value per item; every other field is wrapped as a one-field value object.
           def carried(plan, verb, argument, value)
-            return v(value) unless plan && verb && plan.references?(verb, argument)
+            return value if reference?(plan, verb, argument)
+            return value.map { |item| v(item) } if list?(plan, verb, argument, value)
 
-            value
+            v(value)
           end
 
+          def reference?(plan, verb, argument) = !!(plan && verb && plan.references?(verb, argument))
+
+          def list?(plan, verb, argument, value) = value.is_a?(Array) && !!(plan && verb && plan.list?(verb, argument))
+
           # A record's id is its declared identity, joined the same way the
           # runtime joins it, so there is exactly one way to name a thing.
           # Each part comes from the parent link, the walk index
@@ -49,7 +54,8 @@ module Hecks
           def v_scalar(held)
             return held.to_s unless held.respond_to?(:to_h) && !held.is_a?(String)
 
-            held.to_h.values.first.to_s
+            values = held.to_h.values
+            values.first.to_s
           end
 
           # Each identity field comes from one of three places: the parent

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

@@ -14,16 +14,16 @@ module Hecks
         # @return [Boolean]
         def bootstrapping? = @bootstrapping
 
-        # Whether `call` is queuing chapters instead of judging them, while a
-        # chapter's own files are still being merged (see `defer`).
+        # Whether `call` is queuing bluebooks instead of judging them, while a
+        # bluebook's own files are still being merged (see `defer`).
         #
         # @return [Boolean]
         def deferring? = @deferring
 
-        # Queues every chapter `call` sees while the block runs, instead of
-        # judging them immediately (see `deferred_chapters`).
+        # Queues every bluebook `call` sees while the block runs, instead of
+        # judging them immediately (see `deferred_bluebooks`).
         #
-        # @yield the caller's own load of every file in one chapter window
+        # @yield the caller's own load of every file in one bluebook window
         # @return [Object] the block's own return value
         def defer
           previous   = @deferring
@@ -33,52 +33,52 @@ module Hecks
           @deferring = previous
         end
 
-        # The chapters queued while `defer`'s block ran, awaiting
+        # The bluebooks queued while `defer`'s block ran, awaiting
         # `judge_deferred!`.
         #
-        # @return [Array<String>] each deferred chapter's own `hecks_name`,
+        # @return [Array<String>] each deferred bluebook's own `hecks_name`,
         #   queued during the current or most recent `defer` window
-        def deferred_chapters = @deferred_chapters ||= []
+        def deferred_bluebooks = @deferred_bluebooks ||= []
 
-        # Judges every chapter queued by `defer`, once each, then clears the
+        # Judges every bluebook queued by `defer`, once each, then clears the
         # queue.
         #
         # @param registry [Runtime::Registry, nil] the registry to judge
         #   against; a no-op if `nil`
         # @return [void]
-        # @raise [DSL::Malformed] if a chapter's own whole-chapter battery
+        # @raise [DSL::Malformed] if a bluebook's own whole-bluebook battery
         #   (`BluebookBuilder.validate_assembled!`) or the meta-domain itself
         #   (`call`) refuses it
         def judge_deferred!(registry)
-          pending = deferred_chapters.uniq
-          @deferred_chapters = []
+          pending = deferred_bluebooks.uniq
+          @deferred_bluebooks = []
           return unless registry
 
-          pending.each { |name| judge_chapter!(registry, name) }
+          pending.each { |name| judge_bluebook!(registry, name) }
         end
 
-        # Judges one deferred chapter once its own files are all merged.
+        # Judges one deferred bluebook once its own files are all merged.
         #
-        # @param registry [Runtime::Registry] the registry holding the chapter
-        # @param name [String] the chapter's `hecks_name`
+        # @param registry [Runtime::Registry] the registry holding the bluebook
+        # @param name [String] the bluebook's `hecks_name`
         # @return [void]
-        def judge_chapter!(registry, name)
-          chapter = registry.bluebook(name)
-          return unless chapter
+        def judge_bluebook!(registry, name)
+          declaration = registry.bluebook(name)
+          return unless declaration
 
-          # Bare chapter-level givens must resolve before anything below
+          # Bare bluebook-level givens must resolve before anything below
           # reads a `Given`'s fields. The `raise` block never runs — this
-          # chapter's builder is always already open by the time `chapter` exists.
+          # bluebook's builder is always already open by the time `bluebook` exists.
           builder = registry.bluebook_builder(name) { raise Error, "internal: no open builder for #{name}" }
-          builder.resolve_pending_chapter_givens!
+          builder.resolve_pending_bluebook_givens!
           # Same, one level down: entity-scoped pending givens.
-          builder.resolve_pending_chapter_entity_givens!
+          builder.resolve_pending_bluebook_entity_givens!
 
-          # Whole-chapter checks (hops, projected fields, event shapes) were
-          # skipped per file while deferring; `chapter` now holds every
+          # Whole-bluebook checks (hops, projected fields, event shapes) were
+          # skipped per file while deferring; `bluebook` now holds every
           # file's declarations, so they run once here instead of per file.
-          DSL::BluebookBuilder.validate_assembled!(chapter)
-          registry.add_bluebook(call(chapter))
+          DSL::BluebookBuilder.validate_assembled!(declaration)
+          registry.add_bluebook(call(declaration))
         end
 
         # Whether meta-domain judging is off (ignored while a fixpoint build

data/lib/hecks/bluebook/meta_validator/plan/category.rb

@@ -4,7 +4,6 @@ module Hecks
       class Plan
         # One append command: the verb, and the value-object-field -> argument map.
         # `:map` shadows Enumerable#map on purpose; spec/plan_spec.rb asserts on it.
-        # rubocop:disable-next Lint/StructNewOverride
         Append = Struct.new(:verb, :map, keyword_init: true)
 
         # One setting command. `targets` is target -> argument ; Lifecycle sets two
@@ -12,7 +11,7 @@ module Hecks
         Setter = Struct.new(:verb, :targets, keyword_init: true)
 
         Category = Struct.new(:name, :declare, :parent, :parent_key, :fields,
-                              :appends, :alternates, :setters, :sealers, :references,
+                              :appends, :alternates, :setters, :sealers, :references, :lists,
                               :identity_paths, :entity_owned,
                               keyword_init: true) do
           # Every verb this category declares, in declaration order; a verb missing
@@ -35,6 +34,15 @@ module Hecks
             Array(references[verb.to_s]).include?(argument.to_s)
           end
 
+          # Whether `argument` on `verb` is a list, so each of its items is one value.
+          #
+          # @param verb [String] the command name declaring `argument`
+          # @param argument [String] the argument name to check
+          # @return [Boolean] whether `argument` on `verb` is declared as a list
+          def list?(verb, argument)
+            Array(lists&.dig(verb.to_s)).include?(argument.to_s)
+          end
+
           # Whether this category has no parent — the root of the containment tree.
           def root? = parent.nil?
         end

data/lib/hecks/bluebook/meta_validator/plan/verbs.rb

@@ -15,6 +15,15 @@ module Hecks
             end
           end
 
+          # Which arguments of which verbs are lists, read straight off the IR, so a list
+          # argument's items are each wrapped as a value rather than the list as one.
+          def lists_in(commands)
+            commands.each_with_object({}) do |command, found|
+              named = command.attributes.select(&:list?).map { |attribute| attribute.name.to_s }
+              found[command.hecks_name] = named unless named.empty?
+            end
+          end
+
           # Every reference argument is dropped, not just the parent link:
           # a reference is not a field.
           def declared_fields(declare)

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

@@ -12,16 +12,16 @@ module Hecks
         # Reads the language's own self-description off `registry`.
         #
         # @param registry [Runtime::Registry] a registry with the language's
-        #   own "Bluebook" chapter already judged and assembled
-        # @return [Plan] the plan, built from that chapter's own aggregates
+        #   own "Bluebook" bluebook already judged and assembled
+        # @return [Plan] the plan, built from that bluebook's own aggregates
         def self.for(registry)
           new(registry.bluebook("Bluebook"))
         end
 
         attr_reader :categories
 
-        # @param meta [Bluebook::Chapter] the language's own assembled
-        #   "Bluebook" chapter
+        # @param meta [Bluebook::Declaration] the language's own assembled
+        #   "Bluebook" bluebook
         def initialize(meta)
           @categories = {}
           meta.aggregates.each do |aggregate|
@@ -108,7 +108,7 @@ module Hecks
           {
             name:           aggregate.hecks_name,
             declare:        declare&.hecks_name,
-            parent:         owner || parent&.type&.target_name,
+            parent:         owner || parent&.target_name,
             parent_key:     owner ? "aggregate" : parent&.name&.to_s,
             # Read from the language, not restated: a hand-written join here
             # could disagree with the runtime's own by even one separator.
@@ -126,7 +126,8 @@ module Hecks
             sealers:    sealers_in(rest),
             # Every command, not `rest` — the creating command carries the parent
             # link, which is the most common reference of all.
-            references: references_in(aggregate.commands)
+            references: references_in(aggregate.commands),
+            lists:      lists_in(aggregate.commands)
           }
         end
 

data/lib/hecks/bluebook/meta_validator/readings/fields.rb

@@ -69,16 +69,16 @@ module Hecks
           def points_at(row, aggregate_id)
             return nil unless row.reference?
 
-            # Built the same way an aggregate id itself is built (chapter +
+            # Built the same way an aggregate id itself is built (bluebook +
             # name), because `repository.find` resolves against that same id.
-            Naming.identity([aggregate_id.split(Naming::IDENTITY_JOIN).first, row.type.target_name])
+            Naming.identity([aggregate_id.split(Naming::IDENTITY_JOIN).first, row.target_name])
           end
 
           # Self-describing so the type survives the round trip (bare `to_s`
           # can't tell 0.0 from a string); `nil` stays `nil`, a real answer.
           def encode_literal(value) = value.nil? ? nil : Literal.render(value)
 
-          # The inverse of `points_at`: strips the id's chapter prefix, joined
+          # The inverse of `points_at`: strips the id's bluebook prefix, joined
           # with `Naming::IDENTITY_JOIN` rather than the wire format's `::`.
           def reference_type(points_at_id) = "Reference<#{points_at_id.to_s.split(Naming::IDENTITY_JOIN).last}>"
 

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

@@ -2,7 +2,7 @@ module Hecks
   module Bluebook
     module MetaValidator
       class Reconstruction
-        # Rebuilds the heads of a chapter: an aggregate, its value objects and the entities
+        # Rebuilds the heads of a bluebook: an aggregate, its value objects and the entities
         # nested under it, each with its own commands and asks.
         module Heads
           private
@@ -26,7 +26,9 @@ module Hecks
               description:   text(row[:description]),
               identified_by: identity_paths(row),
               attributes:    Array(row[:attributes]).map { |field| attribute(field, id) }
-            }.merge(aggregate_rules(row)).merge(lifecycle: lifecycle(row), provenance: provenance(row))
+            }.merge(aggregate_rules(row)).merge(lifecycle: lifecycle(row), provenance: provenance(row),
+                                                formerly_known_as: row[:formerly_known_as],
+                                                created_by: row[:created_by])
           end
 
           # The rules and projected fields an aggregate row holds.
@@ -34,7 +36,8 @@ module Hecks
             {
               invariants:       rules_in(row, :invariants),
               preconditions:    rules_in(row, :preconditions),
-              projected_fields: Array(row[:projected_fields]).map { |held| projected_field(held) }
+              projected_fields: Array(row[:projected_fields]).map { |held| projected_field(held) },
+              acknowledgements: Array(row[:acknowledgements]).map { |held| acknowledgement(held) }
             }
           end
 
@@ -80,9 +83,16 @@ module Hecks
               field:       field,
               default:     text(row[:state_start]),
               transitions: Array(row[:transitions]).map { |move| transition(move) },
-              marks:       Array(row[:marks]).map { |held| mark(held) }
+              marks:       marks_by_name(row[:marks])
             }
           end
+
+          # The one-row-per-state marks as the IR spells them: `name => states`, in declared order.
+          def marks_by_name(rows)
+            Array(rows).map { |held| mark(held) }
+                       .group_by { |held| held[:name] }
+                       .transform_values { |held| held.map { |row| row[:state] } }
+          end
         end
       end
     end

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

@@ -55,7 +55,7 @@ module Hecks
           # and a join read out of order names a different record.
           def identity_paths(row) = Array(row[:identified_by]).map { |part| text(part[:value]).to_s }
 
-          # The contexts one chapter names itself onto, in the order they were
+          # The contexts one bluebook names itself onto, in the order they were
           # attached — same shape identity_paths reads back, one level up.
           def attached_contexts(row) = Array(row[:attaches_to]).map { |part| text(part[:value]).to_s }
 
@@ -65,10 +65,17 @@ module Hecks
             end
           end
 
+          def memberships(row)
+            Array(row[:modules]).map do |part|
+              { name: text(part[:name]).to_s, vision: text(part[:vision]).to_s, aggregate: text(part[:aggregate]).to_s }
+            end
+          end
+
           # Every cell of the meta-domain is a single-field value object, so a row
           # arrives holding Values rather than Strings.
           def text(cell)
             return nil if cell.nil?
+            return cell.map { |held| text(held) } if cell.is_a?(Array)
             return cell.to_h.values.first if cell.respond_to?(:to_h) && !cell.is_a?(String)
 
             cell

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,25 +52,30 @@ 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]),
+            **row_fields(@declaration)
           }
         end
 
+        # The row-valued fields of the bluebook: its attachments, provisions and module memberships.
+        def row_fields(declaration)
+          { attaches_to: attached_contexts(declaration), provides: provisions(declaration),
+            modules: memberships(declaration) }
+        end
+
         def policy(row) = declaration("Policy", row)
 
         # A process manager's handlers live inline on its own dispatched state,