hecks 5.0.0 → 6.0.0

data/lib/hecks/sme/bluebook/sme.bluebook

@@ -2,7 +2,7 @@
 #
 # An interview is the record of one conversation with a subject matter expert about a domain: what
 # was asked, what was said, and what a developer then accepted as established. It is development
-# time work, so this chapter ships in the gem but is not attached to the Hecks domain: nothing
+# time work, so this bluebook ships in the gem but is not attached to the Hecks domain: nothing
 # boots it except the command that runs an interview.
 Hecks.bluebook "SME" do
   vision "Learn a business from the people who know it: an interview with a subject matter expert, kept as a record of what was asked, what was said, and what was accepted as established."
@@ -119,6 +119,7 @@ Hecks.bluebook "SME" do
       lifecycle :status, default: "proposed" do
         transition "AcceptThing" => "accepted", from: "proposed"
         transition "RejectThing" => "rejected", from: "proposed"
+        mark :terminal, "rejected"
       end
 
       command "AcceptThing", from: "proposed" do
@@ -156,6 +157,7 @@ Hecks.bluebook "SME" do
       lifecycle :status, default: "proposed" do
         transition "AcceptAction" => "accepted", from: "proposed"
         transition "RejectAction" => "rejected", from: "proposed"
+        mark :terminal, "rejected"
       end
 
       command "AcceptAction", from: "proposed" do
@@ -188,6 +190,7 @@ Hecks.bluebook "SME" do
       lifecycle :status, default: "proposed" do
         transition "AcceptRule" => "accepted", from: "proposed"
         transition "RejectRule" => "rejected", from: "proposed"
+        mark :terminal, "rejected"
       end
 
       command "AcceptRule", from: "proposed" do
@@ -223,6 +226,7 @@ Hecks.bluebook "SME" do
       lifecycle :status, default: "proposed" do
         transition "AcceptField" => "accepted", from: "proposed"
         transition "RejectField" => "rejected", from: "proposed"
+        mark :terminal, "rejected"
       end
 
       command "AcceptField", from: "proposed" do
@@ -259,6 +263,7 @@ Hecks.bluebook "SME" do
       lifecycle :status, default: "proposed" do
         transition "AcceptTransition" => "accepted", from: "proposed"
         transition "RejectTransition" => "rejected", from: "proposed"
+        mark :terminal, "rejected"
       end
 
       command "AcceptTransition", from: "proposed" do
@@ -282,6 +287,7 @@ Hecks.bluebook "SME" do
       transition "Begin"    => "underway",  from: "planned"
       transition "Conclude" => "concluded", from: "underway"
       transition "Cancel"   => "cancelled", from: ["planned", "underway"]
+      mark :terminal, "cancelled", "concluded"
     end
 
     command "Plan" do

data/lib/hecks/storehouse/audit.rb

@@ -6,6 +6,9 @@ module Hecks
       # The caller-supplied fields of an audit line, in the order the line spells them.
       AUDIT_FIELDS = %i[verb summary source role actor_id].freeze
 
+      # A character a log file's name may not carry.
+      UNSAFE_NAME_CHARACTER = /[^A-Za-z0-9_-]/
+
       # Kept under Hecks::CacheDir, not the domain directory (part of the domain's
       # own state) or the gem directory (read-only once installed).
       # :nodoc:
@@ -13,7 +16,7 @@ module Hecks
 
       # :nodoc:
       def log_path(domain_name)
-        File.join(log_root, "#{domain_name.to_s.gsub(/[^A-Za-z0-9_-]/, "_")}.jsonl")
+        File.join(log_root, "#{domain_name.to_s.gsub(UNSAFE_NAME_CHARACTER, "_")}.jsonl")
       end
 
       # Never fails a real call because its own audit log couldn't be written —

data/lib/hecks/storehouse/bluebook_words.rb

@@ -0,0 +1,35 @@
+require_relative "../naming"
+
+module Hecks
+  module Storehouse
+    # Which bluebook a command or query name speaks to, read the way the CLI reads a line: the
+    # booted domain's own bluebook, or a bluebook its hecksagon attaches when the name starts with
+    # that bluebook's word and a space (`bulk bulk_run.request` reaches the attached Bulk bluebook).
+    # Extended onto `Storehouse`.
+    module BluebookWords
+      # The bluebook `name` speaks to, and the name within that bluebook.
+      #
+      # @param runtime [Runtime::Dispatcher] the booted domain
+      # @param name [String, Symbol] a command or query name, optionally led by a bluebook word
+      # @return [Array(Bluebook::Declaration, String)] the bluebook, and the name with its bluebook
+      #   word
+      #   dropped
+      # @raise [Runtime::NotFound] if the boot loaded no bluebook
+      def bluebook_and_name(runtime, name)
+        word, rest = name.to_s.split(" ", 2)
+        attached = rest && attached_bluebook(runtime, word)
+        attached ? [runtime.bluebook(attached), rest] : [bluebook_for(runtime), name.to_s]
+      end
+
+      # The name of the bluebook the booted domain attaches under `word`, or nil.
+      #
+      # @param runtime [Runtime::Dispatcher] the booted domain
+      # @param word [String] a bluebook's snake-cased name, such as `"bulk"`
+      # @return [String, nil] the attached bluebook's name
+      def attached_bluebook(runtime, word)
+        own = bluebook_for(runtime)
+        Array(runtime.hecksagon(own.name)&.member_bluebooks).find { |declaration| Naming.snake(declaration) == word }
+      end
+    end
+  end
+end

data/lib/hecks/storehouse/dispatching.rb

@@ -17,7 +17,7 @@ module Hecks
       # @raise [ArgumentError] for any other keyword
       def dispatch(runtime:, command:, summary:, args: {}, **)
         request = Request.new(runtime: runtime, name: command, summary: summary, args: args, **)
-        request.bluebook = bluebook_for(runtime)
+        request.bluebook, request.name = bluebook_and_name(runtime, command)
         audited(request, request.dry_run ? "dry_run" : "dispatch") { perform_dispatch(request) }
       end
 
@@ -72,9 +72,12 @@ module Hecks
 
       # :nodoc:
       def settled_record(runtime, spec, result)
-        bluebook = bluebook_for(runtime)
+        bluebook = runtime.bluebook(spec[:command].to_s.split("::", 2).first) || bluebook_for(runtime)
         aggregate = top_level_aggregate(bluebook, spec[:command])
-        aggregate && runtime.registry.repository(bluebook.name, aggregate)&.find(result.id)&.to_h
+        return aggregate unless aggregate
+
+        repository = runtime.repository(bluebook.name, aggregate)
+        repository&.find(result.id)&.to_h
       end
 
       # :nodoc:

data/lib/hecks/storehouse/introspection.rb

@@ -40,12 +40,12 @@ module Hecks
           queries:  aggregate.queries.map { |q| Naming.snake(q.hecks_name) }.sort }
       end
 
-      # One aggregate's (or the whole chapter's) full usage documentation — the
+      # One aggregate's (or the whole bluebook's) full usage documentation — the
       # same document hecks docs renders for a human.
       #
       # @param runtime [Runtime::Registry] the booted domain to describe
       # @param aggregate [String, Symbol, nil] one aggregate's name, or nil for the
-      #   whole chapter
+      #   whole bluebook
       # @return [Hash] :ok, :domain, :docs; or the refused shape
       # @raise [Runtime::NotFound] if aggregate names no known aggregate
       def describe(runtime:, aggregate: nil)
@@ -79,7 +79,7 @@ module Hecks
       # :nodoc:
       def model_findings(runtime)
         require_relative "../bluebook/model_check"
-        findings = runtime.registry.bluebooks.values.flat_map { |bluebook| Bluebook::ModelCheck.call(bluebook) }
+        findings = runtime.bluebooks.values.flat_map { |bluebook| Bluebook::ModelCheck.call(bluebook) }
         findings.map { |f| { kind: f.kind, severity: f.severity, subject: f.subject, message: f.message } }
       end
 
@@ -92,7 +92,7 @@ module Hecks
       def history(runtime:)
         bluebook = bluebook_for(runtime)
         entries  = bluebook.aggregates.each_with_object({}) do |aggregate, all|
-          repository = runtime.registry.repository(bluebook.name, aggregate)
+          repository = runtime.repository(bluebook.name, aggregate)
           all[aggregate.storage_name] = journal_entries(repository)
         end
 

data/lib/hecks/storehouse/querying.rb

@@ -17,7 +17,7 @@ module Hecks
       def query(runtime:, question:, summary:, args: {}, **options)
         check_options!(options, %i[source role actor_id])
         request = Request.new(runtime: runtime, name: question, summary: summary, args: args, **options)
-        request.bluebook = bluebook_for(runtime)
+        request.bluebook, request.name = bluebook_and_name(runtime, question)
         audited(request, "query") { perform_query(request) }
       end
 
@@ -62,7 +62,7 @@ module Hecks
       def perform_state(runtime, bluebook, aggregate, summary, id)
         require_summary!(summary)
         ir         = aggregate_ir!(bluebook, aggregate)
-        repository = runtime.registry.repository(bluebook.name, ir)
+        repository = runtime.repository(bluebook.name, ir)
         return ok(summary: summary, record: single_record(repository, ir, id)) if id
 
         records = repository.all.map { |instance| Adapters::Driving::Json.materialize(instance.to_h) }

data/lib/hecks/storehouse.rb

@@ -13,6 +13,7 @@ require_relative "storehouse/audit"
 require_relative "storehouse/dispatching"
 require_relative "storehouse/querying"
 require_relative "storehouse/introspection"
+require_relative "storehouse/bluebook_words"
 
 module Hecks
   # Dispatch/query/state and introspection over one booted domain, pure
@@ -40,6 +41,7 @@ module Hecks
     extend Dispatching
     extend Querying
     extend Introspection
+    extend BluebookWords
 
     module_function
 
@@ -59,7 +61,7 @@ module Hecks
     # the same one-bluebook-per-boot shape.
     # :nodoc:
     def bluebook_for(runtime)
-      runtime.registry.bluebooks.values.first or
+      runtime.first_bluebook or
         raise Runtime::NotFound, "this boot loaded no bluebook"
     end
 
@@ -67,7 +69,13 @@ module Hecks
     def aggregate_ir!(bluebook, name)
       bluebook.aggregate(name) or
         raise Runtime::NotFound, "#{bluebook.name} declares no aggregate named #{name.inspect} — " \
-                                 "known: #{bluebook.aggregates.map(&:hecks_name).sort.join(", ")}"
+                                 "known: #{aggregate_names(bluebook)}"
+    end
+
+    # :nodoc:
+    def aggregate_names(bluebook)
+      names = bluebook.aggregates.map(&:hecks_name)
+      names.sort.join(", ")
     end
 
     # The alias table CliRunner resolves against, for one bluebook.
@@ -125,11 +133,13 @@ module Hecks
     # :nodoc:
     def audited(request, tool)
       outcome = yield
-      record!(request.bluebook.name, tool: tool, verb: outcome[:verb], outcome: outcome, **audit_fields(request))
+      bluebook = request.bluebook
+      record!(bluebook.name, tool: tool, verb: outcome[:verb], outcome: outcome, **audit_fields(request))
       outcome.except(:verb)
     rescue *refusal_classes => e
       outcome = refused(e, summary: request.summary)
-      record!(request.bluebook&.name, tool: tool, outcome: outcome, **audit_fields(request))
+      asked_of = request.bluebook
+      record!(asked_of&.name, tool: tool, outcome: outcome, **audit_fields(request))
       outcome
     end
 

data/lib/hecks/switches.rb

@@ -0,0 +1,21 @@
+module Hecks
+  # The switches a test process can flip through its environment, read in one place so the
+  # runtime and the bluebook layer never read `ENV` themselves.
+  #
+  # Each turns a cache off for a child process that must boot uncached. A person ruling a cache
+  # out as the cause empties it instead, with `hecks test_suite_run.clear_caches!`.
+  #
+  # @example
+  #   Hecks::Switches.verdict_cache?  # => false under HECKS_VERDICT_CACHE=off
+  module Switches
+    module_function
+
+    # @return [Boolean] whether the syntax-boot table is cached on disk;
+    #   `HECKS_SYNTAX_BOOT_CACHE=off` turns it off
+    def syntax_boot_cache? = ENV["HECKS_SYNTAX_BOOT_CACHE"] != "off"
+
+    # @return [Boolean] whether meta-validator verdicts are cached on disk;
+    #   `HECKS_VERDICT_CACHE=off` turns it off
+    def verdict_cache? = ENV["HECKS_VERDICT_CACHE"] != "off"
+  end
+end

data/lib/hecks/tenancy/bluebook/tenancy.bluebook

@@ -45,15 +45,11 @@ Hecks.bluebook "Tenancy" do
     command "Register" do
       goal "Record that a tenant now exists, after its shape has been validated and its schema provisioned"
 
-      attribute :slug,   Slug
-      attribute :domain, DomainName
-      attribute :realm,  Realm
-      attribute :schema, Schema
-
-      sets :slug
-      sets :domain
-      sets :realm
-      sets :schema
+      attribute :slug,   Slug, sets: true
+      attribute :domain, DomainName, sets: true
+      attribute :realm,  Realm, sets: true
+      attribute :schema, Schema, sets: true
+
 
       emits "TenantRegistered"
     end

data/lib/hecks/text.rb

@@ -0,0 +1,57 @@
+module Hecks
+  # Plain-text readings the framework takes again and again: the first line of a message, a
+  # comma-separated list, whether a value says anything at all. Each pipeline is named here once,
+  # so a caller says what it wants instead of replaying how to get it.
+  module Text
+    # Any run of whitespace.
+    WHITESPACE = /\s+/
+
+    # A comma and the space around it, as in "a, b ,c".
+    COMMA = /\s*,\s*/
+
+    module_function
+
+    # The first line of `text`, stripped. Error messages put their sentence on the first line.
+    #
+    # @param text [String, #to_s, nil] the text to read
+    # @return [String] the first line without surrounding whitespace, or `""` for no text
+    def first_line(text) = text.to_s.lines.first.to_s.strip
+
+    # The first line of `text` with only its line ending removed: a message's headline.
+    #
+    # @param text [String, #to_s, nil] the text to read
+    # @return [String] the first line, its own spacing kept, or `""` for no text
+    def headline(text) = text.to_s.lines.first.to_s.chomp
+
+    # The last `count` lines of `text`, joined and stripped: the tail of a command's output.
+    #
+    # @param text [String, #to_s, nil] the text to read
+    # @param count [Integer] how many lines to keep
+    # @return [String] the kept lines, joined, without surrounding whitespace
+    def last_lines(text, count) = text.to_s.lines.last(count).join.strip
+
+    # Says whether `value` holds no text once whitespace is set aside.
+    #
+    # @param value [String, #to_s, nil] the value to read
+    # @return [Boolean] whether `value` is `nil`, empty or only whitespace
+    def blank?(value) = value.to_s.strip.empty?
+
+    # Splits a comma-separated value into its items, dropping empty ones.
+    #
+    # @param value [String, #to_s, nil] a list such as `"a, b,,c"`
+    # @return [Array<String>] the stripped, non-empty items, in order
+    def comma_list(value) = value.to_s.split(",").map(&:strip).reject(&:empty?)
+
+    # Joins the stripped, non-empty lines of `lines` back into one text.
+    #
+    # @param lines [Array<String>] the lines to keep
+    # @return [String] the non-blank lines, stripped, one per line
+    def compact_lines(lines) = lines.map(&:strip).reject(&:empty?).join("\n")
+
+    # The names of `items`, sorted and comma-joined: how a refusal lists what it would accept.
+    #
+    # @param items [Array<#name>] the things to name
+    # @return [String] their names, sorted, joined with ", "
+    def name_list(items) = items.map(&:name).sort.join(", ")
+  end
+end

data/lib/hecks/tickets/bluebook/tickets.bluebook

@@ -1,4 +1,4 @@
-# The Tickets chapter: what a maintainer observed about Hecks that needs a decision or a fix, the
+# The Tickets bluebook: what a maintainer observed about Hecks that needs a decision or a fix, the
 # and the decisions that settle them.
 #
 # QualityControl has its own Ticket, the issue raised for a Bug in an outside tracker, and the
@@ -84,17 +84,12 @@ Hecks.bluebook "Tickets" do
     command "Report" do
       goal "Record something observed about Hecks as a finding"
 
-      attribute :finding,      FindingKey
-      attribute :title,       Title
-      attribute :body,        Body, optional: true
-      attribute :source,      Source
-      attribute :fingerprint, Fingerprint, optional: true
+      attribute :finding,      FindingKey, sets: true
+      attribute :title,       Title, sets: true
+      attribute :body,        Body, optional: true, sets: true
+      attribute :source,      Source, sets: true
+      attribute :fingerprint, Fingerprint, optional: true, sets: true
 
-      sets :finding
-      sets :title
-      sets :body
-      sets :source
-      sets :fingerprint
 
       emits "FindingReported"
     end
@@ -104,11 +99,9 @@ Hecks.bluebook "Tickets" do
     command "ReportFailedRun" do
       goal "Record a failed conformance or gate run as a finding"
 
-      attribute :finding, FindingKey
-      attribute :body,   Body
+      attribute :finding, FindingKey, sets: true
+      attribute :body,   Body, sets: true
 
-      sets :finding
-      sets :body
       sets :fingerprint, to: "run"
       sets :title,  to: "A Codebase run failed"
       sets :source, to: "qa_loop"
@@ -122,11 +115,9 @@ Hecks.bluebook "Tickets" do
     command "ReportLag" do
       goal "Record a lane that has stood behind the lane it follows too long as a finding"
 
-      attribute :finding, FindingKey
-      attribute :body,    Body
+      attribute :finding, FindingKey, sets: true
+      attribute :body,    Body, sets: true
 
-      sets :finding
-      sets :body
       sets :fingerprint, to: "lane-lag"
       sets :title,  to: "A lane is behind the lane it follows"
       sets :source, to: "qa_loop"
@@ -139,11 +130,9 @@ Hecks.bluebook "Tickets" do
       goal "Give a finding its kind and severity"
 
       reference_to Finding
-      attribute :kind,     Kind
-      attribute :severity, Severity
+      attribute :kind,     Kind, sets: true
+      attribute :severity, Severity, sets: true
 
-      sets :kind
-      sets :severity
 
       emits "FindingTriaged"
     end
@@ -153,9 +142,8 @@ Hecks.bluebook "Tickets" do
       goal "Record the pull request that fixes a triaged finding"
 
       reference_to Finding
-      attribute :fix_pr_number, Number
+      attribute :fix_pr_number, Number, sets: true
 
-      sets :fix_pr_number
 
       emits "FixLinked"
     end
@@ -174,9 +162,8 @@ Hecks.bluebook "Tickets" do
       goal "Close a finding without a fix, with the reason"
 
       reference_to Finding
-      attribute :dismissal, Body
+      attribute :dismissal, Body, sets: true
 
-      sets :dismissal
 
       emits "FindingDismissed"
     end
@@ -194,9 +181,8 @@ Hecks.bluebook "Tickets" do
       goal "Record the GitHub issue number once the issue is opened"
 
       reference_to Finding
-      attribute :issue_number, Number
+      attribute :issue_number, Number, sets: true
 
-      sets :issue_number
 
       emits "IssueRecorded"
     end
@@ -205,9 +191,8 @@ Hecks.bluebook "Tickets" do
       goal "Record that GitHub could not be driven, so a later run retries"
 
       reference_to Finding
-      attribute :sync_failure, Body
+      attribute :sync_failure, Body, sets: true
 
-      sets :sync_failure
 
       emits "SyncFailed"
     end
@@ -225,7 +210,7 @@ Hecks.bluebook "Tickets" do
     attribute :adr,       AdrNumber
     attribute :title,     AdrTitle
     attribute :supersedes, AdrNumber, optional: true
-    attribute :settles,   FindingKey, optional: true
+    reference_to Finding, as: :settles, optional: true
     identified_by :adr
 
     value_object "AdrNumber" do
@@ -238,25 +223,20 @@ Hecks.bluebook "Tickets" do
       invariant("a decision has a title") { !value.to_s.empty? }
     end
 
-    value_object "FindingKey" do
-      attribute :value, String, matches: :present
-    end
-
     lifecycle :status, default: "draft" do
       transition "Accept"    => "accepted",   from: "draft"
       transition "Supersede" => "superseded", from: "accepted"
+      mark :terminal, "superseded"
     end
 
     command "Draft" do
       role "Maintainer"
       goal "Open a decision record, optionally for the finding it settles"
 
-      attribute :adr,       AdrNumber
-      attribute :title,     AdrTitle
-      attribute :settles,   FindingKey, optional: true
+      attribute :adr,       AdrNumber, sets: true
+      attribute :title,     AdrTitle, sets: true
+      reference_to Finding, as: :settles, optional: true
 
-      sets :adr
-      sets :title
       sets :settles
 
       emits "AdrDrafted"
@@ -276,9 +256,8 @@ Hecks.bluebook "Tickets" do
       goal "Record that a later decision replaces this one"
 
       reference_to Adr
-      attribute :supersedes, AdrNumber
+      attribute :supersedes, AdrNumber, sets: true
 
-      sets :supersedes
 
       emits "AdrSuperseded"
     end
@@ -293,42 +272,42 @@ Hecks.bluebook "Tickets" do
   # Each lifecycle event drives GitHub. A finding's own state never waits on the answer.
   policy "OpenIssueWhenReported" do
     on      "Finding.FindingReported"
-    trigger Finding::GitHubIssues::OpenIssue, with: { finding: :finding }
+    ask     :open_issue, with: { finding: :finding }
   end
 
   policy "OpenIssueWhenRunReported" do
     on      "Finding.RunFindingReported"
-    trigger Finding::GitHubIssues::OpenIssue, with: { finding: :finding }
+    ask     :open_issue, with: { finding: :finding }
   end
 
   policy "OpenIssueWhenLagReported" do
     on      "Finding.LagFindingReported"
-    trigger Finding::GitHubIssues::OpenIssue, with: { finding: :finding }
+    ask     :open_issue, with: { finding: :finding }
   end
 
   policy "LabelIssueWhenTriaged" do
     on      "Finding.FindingTriaged"
-    trigger Finding::GitHubIssues::LabelIssue, with: { finding: :finding }
+    ask     :label_issue, with: { finding: :finding }
   end
 
   policy "CommentWhenFixLinked" do
     on      "Finding.FixLinked"
-    trigger Finding::GitHubIssues::CommentOnIssue, with: { finding: :finding }
+    ask     :comment_on_issue, with: { finding: :finding }
   end
 
   policy "CloseIssueWhenResolved" do
     on      "Finding.FindingResolved"
-    trigger Finding::GitHubIssues::CloseIssue, with: { finding: :finding }
+    ask     :close_issue, with: { finding: :finding }
   end
 
   policy "CloseIssueWhenDismissed" do
     on      "Finding.FindingDismissed"
-    trigger Finding::GitHubIssues::CloseIssue, with: { finding: :finding }
+    ask     :close_issue, with: { finding: :finding }
   end
 
   policy "ReopenIssueWhenReopened" do
     on      "Finding.FindingReopened"
-    trigger Finding::GitHubIssues::ReopenIssue, with: { finding: :finding }
+    ask     :reopen_issue, with: { finding: :finding }
   end
 
   # A conformance or gate run that faults files its own finding.

data/lib/hecks/tickets/bluebook/tickets.hecksagon

@@ -5,7 +5,7 @@ Hecks.hecksagon "Tickets" do
   persisted_by "Memory"
 end
 
-# The anti-corruption layer for Governance, which the chapter's roles are checked against.
+# The anti-corruption layer for Governance, which the bluebook's roles are checked against.
 Hecks.hecksagon "Governance" do
   persisted_by "Memory"
 end

data/lib/hecks/tickets/bluebook/tickets.ports.hecksagon

@@ -1,4 +1,4 @@
-# The port Tickets declares, for every hecksagon that attaches the chapter (`Chapters` loads this
+# The port Tickets declares, for every hecksagon that attaches the bluebook (`Bluebooks` loads this
 # file with it). Each lifecycle event of a finding asks the GitHubIssues port, which the Hecks domain
 # binds (lib/hecks/hecks/adapters/finding_github.rb): the outside a finding reaches. The ask is
 # answered with the record's own arguments or refused with a reason, and a refusal is recorded on the

data/lib/hecks/tools/argument_gate_matrix/dispatching.rb

@@ -55,7 +55,7 @@ module Hecks
           dispatch_row(runtime, row, args)
           [nil, nil, nil]
         rescue *Hecks::Runtime::DOMAIN_REFUSALS => e
-          [e.class.name.split("::").last, e.message, refused_step(kind)]
+          [Hecks::Naming.demodulise(e.class), e.message, refused_step(kind)]
         end
 
         def dispatch_row(runtime, row, args)

data/lib/hecks/tools/argument_gate_matrix/rows.rb

@@ -92,24 +92,24 @@ module Hecks
           Violations::MISMATCHED_ROLE if [earlier, later].include?("refuse_role_mismatch")
         end
 
-        def candidates(runtime, chapter)
-          bluebook = runtime.registry.bluebook(chapter)
+        def candidates(runtime, declaration)
+          bluebook = runtime.bluebook(declaration)
           random = SteadyRandom.new(20_260_918)
           bluebook.aggregates.flat_map do |aggregate|
-            aggregate_rows(aggregate, chapter, random) + entity_rows(aggregate, chapter, random)
+            aggregate_rows(aggregate, declaration, random) + entity_rows(aggregate, declaration, random)
           end
         end
 
-        def aggregate_rows(aggregate, chapter, random)
+        def aggregate_rows(aggregate, declaration, random)
           aggregate.commands.flat_map do |command|
-            rows_for(command, aggregate, "#{chapter}::#{aggregate.hecks_name}.#{command.hecks_name}", "aggregate", random)
+            rows_for(command, aggregate, "#{declaration}::#{aggregate.hecks_name}.#{command.hecks_name}", "aggregate", random)
           end
         end
 
-        def entity_rows(aggregate, chapter, random)
+        def entity_rows(aggregate, declaration, random)
           aggregate.entities.flat_map do |entity|
             entity.commands.flat_map do |command|
-              verb = "#{chapter}::#{aggregate.hecks_name}.#{entity.hecks_name}.#{command.hecks_name}"
+              verb = "#{declaration}::#{aggregate.hecks_name}.#{entity.hecks_name}.#{command.hecks_name}"
               rows = rows_for(command, aggregate, verb, "entity", random)
               rows.each { |row| row[:args] = identity_args(entity, aggregate, random).merge(row[:args]) }
             end

data/lib/hecks/tools/argument_gate_matrix/violations.rb

@@ -99,7 +99,7 @@ module Hecks
         def violate_reference!(args, command)
           reference = command.attributes.find(&:reference?) or return nil
 
-          args[reference.name.to_s] = "no-such-#{reference.type.target_name.to_s.downcase}"
+          args[reference.name.to_s] = "no-such-#{reference.target_name.to_s.downcase}"
           reference.name.to_s
         end
       end

data/lib/hecks/tools/argument_gate_matrix.rb

@@ -85,9 +85,9 @@ module Hecks
 
       # Files each candidate row of one booted domain under `kept` or `dropped`.
       def sweep_domain(runtime, domain, kept, dropped)
-        chapters = runtime.registry.bluebooks.keys
-        chapter = chapters.find { |name| candidates(runtime, name).any? } || chapters.first
-        candidates(runtime, chapter).each do |row|
+        declarations = runtime.bluebooks.keys
+        declaration = declarations.find { |name| candidates(runtime, name).any? } || declarations.first
+        candidates(runtime, declaration).each do |row|
           verdict, judged = judge(runtime, row, domain)
           (verdict == :kept ? kept : dropped) << judged
         end