hecks 5.0.0 → 7.0.0

data/lib/hecks/behaviors/runner.rb

@@ -1,4 +1,5 @@
 require_relative "expectations"
+require_relative "../sentence_form"
 
 # Hecks::Behaviors.run(path) / .run_all(dir)
 #
@@ -8,10 +9,16 @@ module Hecks
   module Behaviors
     FileResult = Struct.new(:path, :parse_error, :runs, keyword_init: true)
     SweepResult = Struct.new(:root, :files_swept, :files, :summary, keyword_init: true)
-    ParseResult = Struct.new(:path, :suite, :parse_error, keyword_init: true)
+    ParseResult = Struct.new(:path, :suite, :parse_error, keyword_init: true) do
+      # @return [Array<Behaviors::TestCase>] the parsed suite's tests
+      def tests = suite.tests
+    end
 
     class LoadOutsideRunner < StandardError; end
 
+    # The last name of a namespaced class: `Hecks::SentenceForm::Refused` -> `Refused`.
+    LAST_CONSTANT = /\w+\z/
+
     class << self
       # The `.behaviors` file being `Kernel.load`ed; `Hecks.behaviors` reads it to resolve
       # `loads` and to refuse a file loaded any other way.
@@ -29,7 +36,10 @@ module Hecks
       #   a raised exception, or the file loading without calling `Hecks.behaviors`
       def parse(path)
         path = File.expand_path(path)
-        error = load_behaviors(path)
+        runnable = runnable(path)
+        return ParseResult.new(path: path, suite: nil, parse_error: runnable.fetch(:error)) if runnable.is_a?(Hash)
+
+        error = load_behaviors(runnable)
         return ParseResult.new(path: path, suite: nil, parse_error: error) if error
 
         suite = last_suite
@@ -48,7 +58,7 @@ module Hecks
         parsed = parse(path)
         return FileResult.new(path: parsed.path, parse_error: parsed.parse_error, runs: []) if parsed.parse_error
 
-        runs = parsed.suite.tests.map { |test| Expectations.run_one(test, parsed.suite) }
+        runs = parsed.tests.map { |test| Expectations.run_one(test, parsed.suite) }
         FileResult.new(path: parsed.path, parse_error: nil, runs: runs)
       end
 
@@ -59,7 +69,8 @@ module Hecks
       # @return [Behaviors::SweepResult] `files_swept` the count found, `files` one
       #   `FileResult` per file, and `summary` the aggregate counts `summarize` returns
       def run_all(dir)
-        files = Dir.glob(File.join(dir, "**", "*.behaviors"))
+        files = Dir.glob([File.join(dir, "**", "*.behaviors"),
+                          File.join(dir, "**", "*#{SentenceForm::EXAMPLES_EXTENSION}")])
         results = files.map { |path| run(path) }
         SweepResult.new(root: dir, files_swept: files.size, files: results, summary: summarize(results))
       end
@@ -84,6 +95,22 @@ module Hecks
 
       private
 
+      # The `.behaviors` file to load for `path`: the file itself, or for an examples file the
+      # `.behaviors` text compiled from it.
+      #
+      # @param path [String] an absolute `.behaviors` or examples file path
+      # @return [String, Hash{Symbol => String}] the `.behaviors` file's path, or `{error:}`
+      #   naming why the examples could not be compiled
+      def runnable(path)
+        SentenceForm.examples?(path) ? SentenceForm.write_behaviors(path) : path
+      rescue SentenceForm::Refused, SentenceForm::ParserMissing => e
+        { error: "#{refusal_name(e)}: #{e.message}" }
+      end
+
+      # @param error [Exception] a refusal raised while compiling examples
+      # @return [String] the error's class name without its namespace
+      def refusal_name(error) = error.class.name[LAST_CONSTANT]
+
       # `Kernel.load`s the file with `loading_path` pointing at it.
       #
       # @param path [String] the `.behaviors` file's absolute path

data/lib/hecks/bench/environment.rb

@@ -6,6 +6,9 @@ module Hecks
     # Describes the machine and toolchain a benchmark ran on.
     # Each probe is best effort: a missing tool yields `"unknown"`, not an error.
     module Environment
+      # The total-memory line of `/proc/meminfo`, capturing its size in KiB.
+      MEMORY_TOTAL = /MemTotal:\s+(\d+)/
+
       module_function
 
       def describe
@@ -20,7 +23,8 @@ module Hecks
       # Read before and after a run to show whether something else was busy.
       def load_average
         text = RUBY_PLATFORM.include?("darwin") ? capture("sysctl", "-n", "vm.loadavg").delete("{}") : File.read("/proc/loadavg")
-        text.split.first.to_f.round(2)
+        one_minute = text.split.first
+        one_minute.to_f.round(2)
       rescue SystemCallError
         nil
       end
@@ -39,7 +43,7 @@ module Hecks
           if RUBY_PLATFORM.include?("darwin")
             capture("sysctl", "-n", "hw.memsize").to_i
           else
-            File.read("/proc/meminfo")[/MemTotal:\s+(\d+)/, 1].to_i * 1024
+            File.read("/proc/meminfo")[MEMORY_TOTAL, 1].to_i * 1024
           end
         bytes.zero? ? "unknown" : (bytes / (1024.0**3)).round(1)
       rescue SystemCallError

data/lib/hecks/bench/postgres_probe.rb

@@ -1,3 +1,5 @@
+require_relative "../text"
+
 module Hecks
   module Bench
     # Decides whether the Postgres targets can run at all.
@@ -12,7 +14,7 @@ module Hecks
       rescue LoadError
         "the `pg` gem is not installed"
       rescue PG::Error => e
-        "no Postgres server is reachable (#{e.message.lines.first.to_s.strip}); start one, or point " \
+        "no Postgres server is reachable (#{Text.first_line(e.message)}); start one, or point " \
         "PGHOST, PGPORT and PGUSER at one"
       end
 

data/lib/hecks/bench/report.rb

@@ -5,6 +5,9 @@ module Hecks
     # Renders a `Suite.call` result as Markdown or JSON.
     # The Markdown carries machine, counts and skips so a pasted table is never a bare number.
     module Report
+      # A digit followed by whole groups of three digits to the end: where a thousands comma goes.
+      THOUSANDS_BOUNDARY = /(\d)(?=(\d{3})+\z)/
+
       module_function
 
       def markdown(result)
@@ -36,7 +39,7 @@ module Hecks
         return "n/a" if value.nil?
 
         whole, fraction = format("%.#{places}f", value).split(".")
-        [whole.gsub(/(\d)(?=(\d{3})+\z)/, '\1,'), fraction].compact.join(".")
+        [whole.gsub(THOUSANDS_BOUNDARY, '\1,'), fraction].compact.join(".")
       end
 
       def environment_block(environment)

data/lib/hecks/bench/suite.rb

@@ -10,7 +10,13 @@ module Hecks
 
       # What one domain's measuring holds across its rounds: the binaries built so far, and each
       # target's run summaries.
-      Round = Struct.new(:workload, :config, :log, :binaries, :summaries)
+      Round = Struct.new(:workload, :config, :log, :binaries, :summaries) do
+        # @return [Integer] how many runs each target gets
+        def runs = config.runs
+
+        # @return [String] the name of the domain being measured
+        def domain_name = workload.name
+      end
 
       module_function
 
@@ -82,8 +88,8 @@ module Hecks
       def measure_target(round, target, index)
         summary = measure_once(round.workload, target, round.config, round.binaries).summary
         round.summaries[target] << summary
-        position = "run #{index + 1}/#{round.config.runs}"
-        round.log.puts progress_line("#{round.workload.name} #{target}", position, summary)
+        position = "run #{index + 1}/#{round.runs}"
+        round.log.puts progress_line("#{round.domain_name} #{target}", position, summary)
       end
 
       def progress_line(label, position, summary)

data/lib/hecks/bluebook/acknowledgements.rb

@@ -0,0 +1,81 @@
+module Hecks
+  module Bluebook
+    # The findings a declaration may acknowledge, and the rule an acknowledgement must meet: a
+    # reason, and a kind the check really emits (ADR 0150).
+    module Acknowledgements
+      # The finding kinds an aggregate may acknowledge.
+      AGGREGATE_KINDS = %i[large_aggregate key_by_value orphaned_reference no_command_surface].freeze
+
+      # The kinds that are reported once per attribute or per referenced aggregate, so an
+      # acknowledgement of one names which (`of:`): the attribute for `key_by_value`, the
+      # referenced aggregate for `orphaned_reference`.
+      SUBJECT_KINDS = %i[key_by_value orphaned_reference].freeze
+
+      # The finding kinds a context-map relationship may acknowledge: those about the relationship
+      # itself. An undeclared coupling or a separate-ways breach has no relationship to carry the
+      # allowance; the fix is to declare one.
+      RELATIONSHIP_KINDS = %i[relationship_kind_mismatch conformist_translates unpublished_dependency
+                              unused_relationship redundant_relationship].freeze
+
+      # @param owner [String] the declaration carrying the word, for the message
+      # @param finding [Symbol, String] the kind being acknowledged
+      # @param reason [Object] why; must be non-blank text
+      # @param among [Array<Symbol>] the kinds the owner may acknowledge
+      # @return [Symbol] the kind, once it passes
+      # @raise [DSL::Malformed] if the kind is not among those, or the reason is blank
+      def self.kind!(owner, finding, reason, among: AGGREGATE_KINDS)
+        kind = finding.to_s.to_sym
+        refuse_kind!(owner, kind, among) unless among.include?(kind)
+        refuse_reason!(owner, kind) unless reason.is_a?(String) && !reason.strip.empty?
+        kind
+      end
+
+      # @param owner [String] the declaration carrying the word, for the message
+      # @param kind [Symbol] the kind being acknowledged
+      # @param subject [Symbol, String, nil] what `of:` named
+      # @return [String, nil] the subject as text, once the kind and subject agree
+      # @raise [DSL::Malformed] if a per-subject kind names none, or another kind names one
+      def self.subject!(owner, kind, subject)
+        named = subject.to_s unless subject.nil? || subject.to_s.strip.empty?
+        return named if SUBJECT_KINDS.include?(kind) == !named.nil?
+
+        raise DSL::Malformed, subject_message(owner, kind)
+      end
+
+      # @return [String] why the subject and the kind disagree
+      def self.subject_message(owner, kind)
+        if SUBJECT_KINDS.include?(kind)
+          "#{owner} acknowledges :#{kind} without saying which — add `of:` naming the " \
+            "#{kind == :key_by_value ? "attribute" : "referenced aggregate"} it is for"
+        else
+          "#{owner} acknowledges :#{kind} with `of:`, which names a subject only :key_by_value and " \
+            ":orphaned_reference have"
+        end
+      end
+
+      # @raise [DSL::Malformed] always, naming the kinds that can be acknowledged
+      def self.refuse_kind!(owner, kind, among)
+        raise DSL::Malformed,
+              "#{owner} acknowledges :#{kind}, a finding model_check does not report here — " \
+              "the kinds are #{among.map(&:inspect).join(", ")}"
+      end
+
+      # @raise [DSL::Malformed] always, saying a reason is required
+      def self.refuse_reason!(owner, kind)
+        raise DSL::Malformed,
+              "#{owner} acknowledges :#{kind} without a reason in text — an allowance says why it is allowed"
+      end
+
+      # @param aggregate [Bluebook::Aggregate] the aggregate to read
+      # @param kind [Symbol] a finding kind
+      # @param subject [Symbol, String, nil] the attribute or referenced aggregate, for the kinds
+      #   reported once per subject
+      # @return [Boolean] whether the aggregate acknowledges that kind (for that subject)
+      def self.held?(aggregate, kind, subject: nil)
+        aggregate.acknowledgements.any? do |held|
+          held.finding.to_sym == kind && (subject.nil? || held.subject.to_s == subject.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/aggregate.rb

@@ -8,7 +8,11 @@ module Hecks
     # `reference` is the local reference attribute to walk; `remote_field` the target's scalar.
     ProjectedField = Struct.new(:name, :reference, :remote_field, keyword_init: true)
 
-    # An aggregate: carries its own identity and sits in the owner chain below its chapter.
+    # A finding the aggregate means, with the reason it is allowed (`acknowledges :kind, "why"`).
+    # `subject` names the one attribute or referenced aggregate a finding about several is for.
+    Acknowledgement = Struct.new(:finding, :reason, :subject, keyword_init: true)
+
+    # An aggregate: carries its own identity and sits in the owner chain below its bluebook.
     # The holding half only; `Behaviour::Aggregate` carries what the declaration cannot derive.
     class Aggregate
       include Construct
@@ -16,39 +20,47 @@ module Hecks
       include Behaviour::Aggregate
 
       emits_ir(
-        name:             :name,
-        description:      :description,
-        identified_by:    :identity_paths,
-        attributes:       many(:attributes),
-        value_objects:    many(:value_objects),
-        commands:         many(:commands),
-        invariants:       -> { invariants.map { |rule| Expression::AstJson.rule_row(rule) } },
+        name:              :name,
+        description:       :description,
+        identified_by:     :identity_paths,
+        attributes:        many(:attributes),
+        value_objects:     many(:value_objects),
+        commands:          many(:commands),
+        invariants:        -> { invariants.map { |rule| Expression::AstJson.rule_row(rule) } },
         # The named `given`s a referencing command's resolved `givens` entry came from.
-        preconditions:    -> { preconditions.map { |rule| Expression::AstJson.rule_row(rule) } },
+        preconditions:     -> { preconditions.map { |rule| Expression::AstJson.rule_row(rule) } },
         # Not folded into `attributes`: EraGuard::ShapeDiff walks those, and a record predating
         # `projects` is expected to lack this field until the rebuild sweep runs.
-        projected_fields: lambda {
+        projected_fields:  lambda {
           projected_fields.map do |field|
             { name: field.name.to_s, reference: field.reference.to_s, remote_field: field.remote_field.to_s }
           end
         },
-        lifecycle:        one(:lifecycle),
-        entities:         many(:entities),
-        queries:          many(:queries),
+        lifecycle:         one(:lifecycle),
+        entities:          many(:entities),
+        queries:           many(:queries),
         # Additive: domains that declare no port emit `ports: []`; no existing key moves.
-        ports:            many(:ports),
-        provenance:       :provenance
+        ports:             many(:ports),
+        provenance:        :provenance,
+        formerly_known_as: :formerly_known_as,
+        created_by:        :created_by,
+        # Additive: an aggregate that acknowledges no finding emits `acknowledgements: []`.
+        acknowledgements:  lambda {
+          acknowledgements.map { |held| { finding: held.finding.to_s, subject: held.subject, reason: held.reason } }
+        }
       )
 
       attr_reader :name, :description, :attributes, :value_objects, :commands, :invariants, :preconditions,
                   :projected_fields, :identified_by, :identity_paths, :identity_heads, :lifecycle,
-                  :entities, :queries, :policies, :ports, :reference_targets, :provenance
+                  :entities, :queries, :policies, :ports, :reference_targets, :provenance,
+                  :acknowledgements, :formerly_known_as, :created_by
 
       # Every optional field and what it holds when the declaration omits it.
       FIELD_DEFAULTS = {
         description: nil, attributes: [], value_objects: [], commands: [], invariants: [],
         preconditions: [], projected_fields: [], identified_by: [], lifecycle: nil, entities: [],
-        queries: [], policies: [], ports: [], reference_targets: [], provenance: nil
+        queries: [], policies: [], ports: [], reference_targets: [], provenance: nil, acknowledgements: [],
+        formerly_known_as: nil, created_by: nil
       }.freeze
 
       # Assigns the declared fields, then `settle` derives identity, name indexes and owner stamps.

data/lib/hecks/bluebook/ask_resolution.rb

@@ -24,13 +24,13 @@ module Hecks
 
       module_function
 
-      # Resolves one ask policy against a chapter's aggregates and their declared ports.
+      # Resolves one ask policy against a bluebook's aggregates and their declared ports.
       #
-      # @param chapter [Bluebook::Chapter] the chapter the policy is declared in
+      # @param bluebook [Bluebook::Declaration] the bluebook the policy is declared in
       # @param policy [Bluebook::Policy] a policy that `asks?`
       # @return [Outcome] the verb, or the problem
-      def call(chapter, policy)
-        aggregate = event_aggregate(chapter, policy)
+      def call(declaration, policy)
+        aggregate = event_aggregate(declaration, policy)
         return no_aggregate(policy) unless aggregate
 
         found = picked(candidates(aggregate, policy.ask))
@@ -50,14 +50,14 @@ module Hecks
         found.size > 1 && !chosen.empty? ? chosen : found
       end
 
-      # Binds every ask policy of a chapter that resolves, leaving the rest for the boot gate and
+      # Binds every ask policy of a bluebook that resolves, leaving the rest for the boot gate and
       # `model_check` to name.
       #
-      # @param chapter [Bluebook::Chapter] the chapter whose policies to resolve
+      # @param bluebook [Bluebook::Declaration] the bluebook whose policies to resolve
       # @return [void]
-      def bind_resolved(chapter)
-        chapter.policies.select(&:asks?).each do |policy|
-          outcome = call(chapter, policy)
+      def bind_resolved(declaration)
+        declaration.policies.select(&:asks?).each do |policy|
+          outcome = call(declaration, policy)
           policy.resolve_ask!(outcome.verb) if outcome.resolved?
         end
       end
@@ -65,14 +65,14 @@ module Hecks
       # Marks the named ask on the named port as the one policies reach, for `ask_via`, and
       # re-binds every ask the pick settles.
       #
-      # @param chapter [Bluebook::Chapter, nil] the chapter the aggregate belongs to
+      # @param bluebook [Bluebook::Declaration, nil] the bluebook the aggregate belongs to
       # @param aggregate_name [String] the aggregate declaring the port
       # @param name [String, Symbol] the ask's declared name
       # @param port [String, Symbol] the port whose ask is picked
       # @return [void]
       # @raise [Bluebook::DSL::Malformed] if no such ask is declared on that port yet
-      def pick!(chapter, aggregate_name, name, port)
-        held = chapter&.aggregate(aggregate_name)&.port(port)
+      def pick!(declaration, aggregate_name, name, port)
+        held = declaration&.aggregate(aggregate_name)&.port(port)
         operation = held&.operation(name)
         unless operation
           raise DSL::Malformed, "#{aggregate_name}.ask_via #{name.to_s.inspect}, port: #{port.to_s.inspect} " \
@@ -80,18 +80,18 @@ module Hecks
         end
 
         operation.choose!
-        bind_resolved(chapter)
+        bind_resolved(declaration)
       end
 
       # The aggregate whose event the policy reacts to: the one the event is qualified with, or
       # the one whose commands emit it when the event is written bare.
       #
       # @return [Bluebook::Aggregate, nil]
-      def event_aggregate(chapter, policy)
+      def event_aggregate(declaration, policy)
         qualifier = policy.event_qualifier
-        return chapter.aggregate(Naming.demodulise(qualifier)) if qualifier
+        return declaration.aggregate(Naming.demodulise(qualifier)) if qualifier
 
-        chapter.aggregates.find do |aggregate|
+        declaration.aggregates.find do |aggregate|
           aggregate.commands.any? { |command| Array(command.emits).include?(policy.event_name) }
         end
       end
@@ -108,7 +108,7 @@ module Hecks
       def no_aggregate(policy)
         Outcome.new(problem: :no_aggregate,
                     detail:  "#{policy.name}'s ask #{policy.ask.to_sym.inspect} reacts to " \
-                             "#{policy.on_event.inspect}, whose aggregate this chapter does not declare")
+                             "#{policy.on_event.inspect}, whose aggregate this bluebook does not declare")
       end
 
       def unmatched(aggregate, policy)

data/lib/hecks/bluebook/assembly/aggregate_assembly.rb

@@ -31,7 +31,7 @@ module Hecks
             entities:          Array(@row[:entities]).map { |piece| entity(piece) },
             queries:           build_all("Query", @row[:queries]),
             lifecycle:         lifecycle_of(@row),
-            # Policies live on the chapter, which is what `PolicyInterpreter` reads.
+            # Policies live on the bluebook, which is what `PolicyInterpreter` reads.
             policies:          [],
             reference_targets: reference_targets(Array(@row[:attributes]).map { |field| Marks.attribute(field) })
           }
@@ -43,7 +43,7 @@ module Hecks
 
         # Read from attributes, not commands: a command's self-references are not targets.
         def reference_targets(fields)
-          fields.select(&:reference?).map { |field| field.type.target_name }
+          fields.select(&:reference?).map(&:target_name)
         end
 
         # Recurses, so entities nest to any depth (ADR 0026).
@@ -84,7 +84,7 @@ module Hecks
             field:       declared[:field],
             default:     declared[:default],
             transitions: transitions(Array(declared[:transitions])),
-            marks:       marks(Array(declared[:marks]))
+            marks:       marks(declared[:marks])
           )
         end
 
@@ -98,9 +98,12 @@ module Hecks
               end
         end
 
-        # Regroups the one-row-per-state marks back into `name => states`, in declared order.
+        # Regroups the one-row-per-state marks back into `name => states`, in declared order. The
+        # IR's own `to_h` already carries them as `name => states`, which passes through.
         def marks(rows)
-          rows.group_by { |held| held[:name].to_s }.transform_values { |held| held.map { |row| row[:state].to_s } }
+          return rows.to_h { |name, states| [name.to_s, Array(states).map(&:to_s)] } if rows.is_a?(Hash)
+
+          Array(rows).group_by { |held| held[:name].to_s }.transform_values { |held| held.map { |row| row[:state].to_s } }
         end
 
         def from_of(froms)

data/lib/hecks/bluebook/assembly/contracts/sagas.rb

@@ -13,6 +13,8 @@ module Hecks
             correlates_by: [:correlates_by, :identity],
             starts_on:     [:starts_on,     :plain],
             ends_on:       [:ends_on,       :plain],
+            endings:       [:endings,       :plain],
+            resumes:       [:resumes,       :plain],
             states:        [:states,        :plain]
           },
           reads: { states: :names },

data/lib/hecks/bluebook/assembly/contracts/structure.rb

@@ -1,11 +1,11 @@
 module Hecks
   module Bluebook
     class Assembly
-      # The contracts for the chapter, aggregate, command and value object;
+      # The contracts for the bluebook, aggregate, command and value object;
       # `CONTRACTS` merges every group.
       STRUCTURE = {
         "Bluebook"    => Contract.new(
-          holder: Chapter, make: :new,
+          holder: Declaration, make: :new,
           fields: {
             name:              [:name,           :plain],
             version:           [:version,        :plain],
@@ -14,7 +14,8 @@ module Hecks
             formerly_known_as: [:formerly_known_as, :plain],
             namespace:         [:namespace, :plain],
             attaches_to:       [:attaches_to, :plain],
-            provides:          [:provides, :plain]
+            provides:          [:provides, :plain],
+            modules:           [:modules, :plain]
           },
           rows: { normalisations: :normalisation_table },
           derived: { normalisations: :elsewhere }
@@ -23,22 +24,25 @@ module Hecks
         "Aggregate"   => Contract.new(
           holder: Aggregate, make: :new,
           fields: {
-            name:             [:name,          :plain],
-            description:      [:description,   :plain],
-            identified_by:    [:identified_by, :plain],
-            attributes:       [:attributes,    [:each, :attribute]],
+            name:              [:name,          :plain],
+            description:       [:description,   :plain],
+            identified_by:     [:identified_by, :plain],
+            attributes:        [:attributes,    [:each, :attribute]],
             # Aggregate's own precondition, referenced by name from a command (ADR 0025).
-            invariants:       [:invariants,    [:each, :invariant]],
-            preconditions:    [:preconditions, [:each, :given]],
+            invariants:        [:invariants,    [:each, :invariant]],
+            preconditions:     [:preconditions, [:each, :given]],
             # The local half of `projects :name, from: "reference.remote_field"` (ADR 0025).
-            projected_fields: [:projected_fields, [:each, :projected_field]],
-            provenance:       [:provenance, :plain]
+            projected_fields:  [:projected_fields, [:each, :projected_field]],
+            provenance:        [:provenance, :plain],
+            formerly_known_as: [:formerly_known_as, :plain],
+            created_by:        [:created_by, :plain],
+            acknowledgements:  [:acknowledgements, [:each, :acknowledgement]]
           },
           rows: { transitions: :transition_rows, marks: :mark_rows, value_objects: :value_object_names,
                   identified_by: :identity_rows },
           reads: { identified_by: [:each, :identity_path], attributes: [:each_with_id, :attribute],
                    invariants: [:each, :rule], preconditions: [:each, :rule],
-                   projected_fields: [:each, :projected_field] },
+                   projected_fields: [:each, :projected_field], acknowledgements: [:each, :acknowledgement] },
           derived: {
             position:      :walk,
             state_field:   [:folded, :lifecycle, :field],
@@ -54,6 +58,8 @@ module Hecks
           fields: {
             name:       [:name,       :plain],
             role:       [:role,       :plain],
+            roles:      [:roles,      :plain],
+            audience:   [:audience,   :plain],
             goal:       [:goal,       :plain],
             references: [:references, :plain],
             attributes: [:attributes, [:each, :shape_field]],
@@ -64,12 +70,15 @@ module Hecks
             emits:      [:emits,      :plain],
             # Lifecycle state as a command guard: one state, an array, or nil (ADR 0025).
             from:       [:from,       :plain],
-            provenance: [:provenance, :plain]
+            provenance: [:provenance, :plain],
+            idempotent: [:idempotent, :plain],
+            mints_era:  [:mints_era, :plain]
           },
           rows: { mutations: :mutation_rows },
           reads: { attributes: [:each, :shape_field], givens: [:each, :rule], ensures: [:each, :rule],
-                  needs: [:each, :need], mutations: [:call, :mutations], emits: :names, provenance: :provenance,
-                  from: :from },
+                  needs: [:each, :need], mutations: [:call, :mutations], emits: :names, roles: :names, audience: :names,
+                  provenance: :provenance,
+                  from: :from, idempotent: :idempotent?, mints_era: :mints_era? },
           derived: { position: :walk }
         ),
 

data/lib/hecks/bluebook/assembly/marks.rb

@@ -4,13 +4,16 @@ module Hecks
       # Reads the leaf shapes of an assembly's `to_h` export back into IR objects.
       # Each method inverts one textual spelling, so types are recovered, not just strings.
       module Marks
+        # A reference type as `to_s` spells it, capturing the target: "Reference<Customer>".
+        REFERENCE_SPELLING = /\AReference<(.+)>\z/
+
         module_function
 
         # `Attribute#to_h` spells a type with `to_s`, so a reference arrives as
         # "Reference<Customer>" and has to become an edge again.
         def attribute(field)
           type = field[:type].to_s
-          target = type[/\AReference<(.+)>\z/, 1]
+          target = type[REFERENCE_SPELLING, 1]
 
           Attribute.new(name: field[:name], type: target ? Reference.new(target) : type, **attribute_options(field))
         end
@@ -73,6 +76,12 @@ module Hecks
                              remote_field: row[:remote_field].to_sym)
         end
 
+        # One acknowledged finding: the kind comes back a Symbol, the reason stays text.
+        def acknowledgement(row)
+          subject = row[:subject].to_s
+          Acknowledgement.new(finding: row[:finding].to_sym, reason: row[:reason], subject: (subject unless subject.empty?))
+        end
+
         # `Mutation#to_h` branches on the operation, so this does too.
         # An append binds several fields, each an argument (a Symbol) or a literal.
         def mutation(change)

data/lib/hecks/bluebook/assembly/scalars.rb

@@ -7,6 +7,12 @@ module Hecks
       # is quoted so it stays a String. The Rust parser reads a cell the same way (`cell_value`
       # in `parse/value_object.rs`).
       module Scalars
+        # An optionally negative whole number, and nothing else.
+        INTEGER = /\A-?\d+\z/
+
+        # An optionally negative decimal with digits both sides of the point, and nothing else.
+        DECIMAL = /\A-?\d+\.\d+\z/
+
         module_function
 
         # @param value [Object] a cell as the builder holds it
@@ -28,8 +34,8 @@ module Hecks
           return Literal.unquote(text) if Literal.quoted?(text)
           return true       if text == "true"
           return false      if text == "false"
-          return text.to_i  if text.match?(/\A-?\d+\z/)
-          return text.to_f  if text.match?(/\A-?\d+\.\d+\z/)
+          return text.to_i  if text.match?(INTEGER)
+          return text.to_f  if text.match?(DECIMAL)
 
           text
         end

data/lib/hecks/bluebook/assembly/specializer.rb

@@ -8,8 +8,8 @@ module Hecks
 
         # Finds a construct by name — an aggregate, or an entity nested anywhere
         # under one (recursively, since an entity like Dispatch nests two deep).
-        def construct_for(chapter, name)
-          chapter.aggregate(name) || chapter.aggregates.filter_map { |a| find_entity(a, name) }.first
+        def construct_for(declaration, name)
+          declaration.aggregate(name) || declaration.aggregates.filter_map { |a| find_entity(a, name) }.first
         end
 
         # Searches a construct's own entities, recursively, for one by name.