hecks 5.0.0 → 7.0.0

data/lib/hecks/quality_control/quality_control.hecksagon

@@ -1,13 +1,24 @@
-# The QualityControl chapter, bound so it boots standing alone (a fuzz or model_check boot of this
+# The QualityControl bluebook, bound so it boots standing alone (a fuzz or model_check boot of this
 # directory). The QA ledger binds PostgresEra in qa/bluebook/quality_control.hecksagon, and the
-# Hecks chapter binds it through its world's `default_adapter`; the ports every one of them shares
+# Hecks bluebook binds it through its world's `default_adapter`; the ports every one of them shares
 # are in quality_control.ports.hecksagon.
 Hecks.hecksagon "QualityControl" do
   attaches "Governance"
   persisted_by "Memory"
+
+  # The fixer's steps, which the ledger records as the bug's state. Declarative: the Fixer domain
+  # emits them, and the Record policies above react.
+  subscribe "Fixer.AttemptClaimed"
+  subscribe "Fixer.AttemptInvestigated"
+  subscribe "Fixer.FixReady"
+  subscribe "Fixer.FixVerified"
+
+  # The coder's submitted branch, which starts the main maintenance run. Declarative: the Coder domain
+  # emits it, and the StartOnSubmission policy reacts.
+  subscribe "Coder.WorkSubmitted"
 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/quality_control/quality_control.ports.hecksagon

@@ -1,5 +1,5 @@
-# The ports QualityControl declares, for every hecksagon that attaches the chapter (`Chapters`
-# loads this file with it). Persistence is the attaching hecksagon's: the Hecks chapter binds
+# The ports QualityControl declares, for every hecksagon that attaches the bluebook (`Bluebooks`
+# loads this file with it). Persistence is the attaching hecksagon's: the Hecks bluebook binds
 # every aggregate through its world's `default_adapter`, and the QA ledger binds its own
 # (qa/bluebook/quality_control.hecksagon).
 Hecks.hecksagon "QualityControl" do
@@ -25,6 +25,28 @@ Hecks.hecksagon "QualityControl" do
     end
   end
 
+  # Bound by adapters/run_reader. It reads a CI run of main for its failing spec files, reports each
+  # to RedSpec, and answers the commit and whether the run settled.
+  QualityControl::MainRun.port "Reader" do
+    asks "Read", to: MainRun do
+      attribute :run,  MainRunId
+      attribute :repo, HeadRepo
+      answers "MainRunRead"
+      refuses "MainRunReadRefused"
+    end
+  end
+
+  # Bound by adapters/push_due_reader. It asks the rehearsal port's `Due` whether a push of local main
+  # is due, applies the world's `push_nudge` thresholds, and answers the flags and numbers the
+  # bluebook's policies file the push-due Work row from.
+  QualityControl::PushNudge.port "PushDue" do
+    asks "Read", to: PushNudge do
+      attribute :nudge, NudgeKey
+      answers "PushDueRead"
+      refuses "PushDueReadRefused"
+    end
+  end
+
   # Queries answered from outside the domain. The bluebook declares each question and the value
   # object its answer takes and never says who answers it; each `answers_query` binds it to the
   # `*Tools` port's adapter, which runs the script's own command and answers what it printed.
@@ -32,10 +54,20 @@ Hecks.hecksagon "QualityControl" do
     answers_query "Seed"
     answers_query "CheckGeneratedDomains"
     answers_query "MineCombinations"
+    answers_query "Mutate"
     answers_query "JudgeNovelty"
     answers_query "DiscoverExternalDomains"
   end
 
+  # Answers a requested pump run by running the `qa_event_pump` script, as the tick does.
+  QualityControl::EventPump.port "PumpTools" do
+    asks "Execute", to: EventPump do
+      attribute :run, PumpRun
+      answers "PumpAnswered"
+      refuses "PumpRefused"
+    end
+  end
+
   QualityControl::Sweep.port "SweepTools" do
     answers_query "Tick"
     answers_query "Run"
@@ -51,4 +83,111 @@ Hecks.hecksagon "QualityControl" do
   QualityControl::Clearance.port "ClearanceTools" do
     answers_query "CheckPullRequests"
   end
+
+  # Remote CI's verdict on one commit of a repository's main, answered by `adapters/ci_head`, which
+  # reads the
+  # runs GitHub reports for the commit. A run still going is a refusal: no verdict until every job
+  # settled.
+  QualityControl::Head.port "CiHead" do
+    asks "Check", to: Head do
+      attribute :branch, HeadBranch
+      attribute :repo,   HeadRepo
+      answers "HeadChecked"
+      refuses "HeadRefused"
+    end
+  end
+
+  # Answered by `adapters/image_roll`: the classifier reads remote CI's green commit's change set,
+  # and the roll runs the console image's deploy; an infra roll also needs the quick gate on record
+  # green. A refusal ends the chain.
+  QualityControl::ImageRoll.port "ImageRoll" do
+    asks "Classify", to: ImageRoll do
+      attribute :branch, RollBranch
+      attribute :repo,   RollRepo
+      answers "ImageClassified"
+      refuses "ClassifyRefused"
+    end
+
+    asks "Roll", to: ImageRoll do
+      attribute :app, AppName
+      answers "RollAnswered"
+      refuses "RollRefused"
+    end
+  end
+
+  # Answered by `adapters/main_maintenance`: the quick gate on main, the reconcile, and the push through the
+  # train. Each answers the event its policy waits for, or refuses with a named event and stops the run.
+  QualityControl::Maintenance.port "MainMaintenance" do
+    asks "Gate", to: Maintenance do
+      answers "GateVerdict"
+      refuses "GateRefused"
+    end
+
+    asks "Reconcile", to: Maintenance do
+      answers "ReconcileDone"
+      refuses "ReconcileRefused"
+    end
+
+    asks "Push", to: Maintenance do
+      answers "Pushed"
+      refuses "PushRefused"
+    end
+
+    # The mint answers `Minted`; a refusal (no would_mint, a stranded landing, the era check's refusal) is
+    # `MintRefused`. The landing answers `Landed`, and a landing that fails leaves the ledger ahead of main:
+    # that refusal is `MintStranded`, which stops every later mint until the owner resolves it.
+    # The mint's facts: the domain, the era and branch it lands, the rehearsal's verdict and the watermark it
+    # read, and whether the mint was confirmed. They are not attributes of Maintenance, so each is declared here.
+    # A mint with no `confirm` runs only when the auto-mint rule holds; a held mint is refused as
+    # "needs owner approval", and `AskOwnerApprovalOnHeldMint` asks for the approval.
+    asks "Mint", to: Maintenance do
+      attribute :domain,            String
+      attribute :era,               Integer
+      attribute :sha,               MaintenanceSha
+      attribute :branch,            String
+      attribute :watermark,         Integer
+      attribute :rehearsal_verdict, MintVerdict
+      attribute :refusal_total,     Integer, optional: true
+      attribute :ledger_dir,        String, optional: true
+      attribute :confirm,           Confirmation, optional: true
+      answers "Minted"
+      refuses "MintRefused"
+    end
+
+    # Answered by the mint entry point's approval step: a mint the auto-mint rule does not cover waits
+    # for the owner's confirm. The answer is `MintNeedsApproval`, and nothing follows it.
+    asks "Approval", to: Maintenance do
+      attribute :domain, String
+      attribute :era,    Integer
+      attribute :reason, MintRefusal
+      answers "MintNeedsApproval"
+      refuses "MintApprovalRefused"
+    end
+
+    asks "Land", to: Maintenance do
+      attribute :era,    MintedEra
+      attribute :sha,    MaintenanceSha
+      attribute :branch, String
+      answers "Landed"
+      refuses "MintStranded"
+    end
+  end
+
+  # Answered by the `gh` adapter for the release PR: opening the PR for a version bump, and writing the
+  # release trailer on its merge once the owner has approved it. A refusal names the failure and stops the run.
+  QualityControl::ReleasePR.port "ReleaseGh" do
+    asks "OpenPullRequest", to: ReleasePR do
+      attribute :branch, ReleaseBranch
+      attribute :sha,    MaintenanceSha
+      answers "ReleaseOpened"
+      refuses "ReleaseOpenRefused"
+    end
+
+    asks "WriteTrailer", to: ReleasePR do
+      attribute :approver, ReleaseApprover
+      attribute :trailer,  ReleaseTrailer
+      answers "TrailerWritten"
+      refuses "TrailerRefused"
+    end
+  end
 end

data/lib/hecks/query_ir/rules.rb

@@ -8,11 +8,11 @@ module Hecks
       # Object identity carries no signal: `MetaValidator.call` rebuilds the graph from flat rows,
       # so a bare `given("x")` reference and its block declaration are distinct objects by then.
       # @param registry [Runtime::Registry] the booted registry to walk
-      # @param chapter_name [String, nil] one chapter to walk, every booted chapter when nil
+      # @param declaration_name [String, nil] one bluebook to walk, every booted bluebook when nil
       # @return [Array<Rule>]
-      def collect_rules(registry, chapter_name = nil)
-        chapters = chapter_name ? [registry.bluebook(chapter_name)] : registry.bluebooks.values
-        chapters.flat_map { |chapter| chapter.aggregates.flat_map { |aggregate| aggregate_rules(aggregate) } }
+      def collect_rules(registry, declaration_name = nil)
+        declarations = declaration_name ? [registry.bluebook(declaration_name)] : registry.bluebooks.values
+        declarations.flat_map { |declaration| declaration.aggregates.flat_map { |aggregate| aggregate_rules(aggregate) } }
       end
 
       # A rule's owner: the path a "(declared)" location names, or a command-level location
@@ -51,10 +51,10 @@ module Hecks
       end
 
       def duplicate_groups(all_rules)
-        all_rules.group_by { |r| [r.kind, r.description, r.canonical] }
-                 .map { |key, rules| [key, rules, declaration_count(rules)] }
-                 .select { |_, _, count| count > 1 }
-                 .map do |(kind, description, canonical), rules, _|
+        counted = all_rules.group_by { |r| [r.kind, r.description, r.canonical] }
+                           .map { |key, rules| [key, rules, declaration_count(rules)] }
+        counted.select { |_, _, count| count > 1 }
+               .map do |(kind, description, canonical), rules, _|
           { kind: kind, description: description, canonical: canonical, locations: rules.map(&:location) }
         end
       end
@@ -102,7 +102,7 @@ module Hecks
       # A rule owned by a nested entity is also covered by a "(declared)" entry anywhere under the
       # same root aggregate, matching the DSL's shared given pool.
       #
-      # Known gap: a bare chapter-wide `given(desc)` reference still shows as its own "(declared)"
+      # Known gap: a bare bluebook-wide `given(desc)` reference still shows as its own "(declared)"
       # owner, because the built IR cannot tell a reference from a declaration. Verify a flagged
       # group by hand before treating it as fresh duplication.
       # @param rules [Array<Rule>] one duplicate-key group's own rules

data/lib/hecks/query_ir/touchpoints.rb

@@ -7,6 +7,9 @@ module Hecks
       # `Assembly::Contracts`; `impact_preview` checks touchpoint 4 only for these.
       RECONSTRUCTION_METHODS = { "Aggregate" => :aggregate, "Entity" => :entity }.freeze
 
+      # The whitespace a line starts with.
+      LEADING_WHITESPACE = /\A\s*/
+
       # Checks the six touchpoints of `.claude/skills/bluebook-construct-creator/SKILL.md` for a
       # construct/field pair. Advisory, not a gate: a `false` can be a legitimate exemption
       # (`Deviations`, `GUARANTEED_BY_CONSTRUCTION`, or the spec-only `META_DOMAIN_KNOWN_GAPS`).
@@ -30,7 +33,7 @@ module Hecks
           { touchpoint: "meta-domain grammar declares it", present: meta_declared(name).map(&:to_s).include?(field) },
           { touchpoint: "docs/resolution-rules/ names it", present: resolution_rule_mentions?(field) },
           { touchpoint: "Assembly::Contracts consumes it", present: contract_consumes?(name, field) },
-          { touchpoint: "Reconstruction's hand-typed method reads it", present: reconstruction_reads?(name, field) },
+          { touchpoint: "Reconstruction's hand-typed method reads it", present: reconstruction_reads(name, field) },
           { touchpoint: "fuzzer FEATURE_COVERAGE/GUARANTEED_BY_CONSTRUCTION claims it", present: fuzzer_claims?(name, field) },
           { touchpoint: "Rust mirror (rust/parser/src/parse/*.rs) mentions it", present: rust_mentions?(field) }
         ]
@@ -49,13 +52,11 @@ module Hecks
         false
       end
 
-      # nil, not false, for constructs without a hand-typed method: the touchpoint does not apply.
-      def reconstruction_reads?(name, field)
+      # Whether the hand-typed Reconstruction method reads `field`. Answers nil, not false, for a
+      # construct without one: nil means "not applicable", false means "applicable, and it fails",
+      # and the touchpoint reports each differently. Named without `?` because it is not a predicate.
+      def reconstruction_reads(name, field)
         method_name = RECONSTRUCTION_METHODS[name]
-        # rubocop:disable-next Style/ReturnNilInPredicateMethodDefinition -- nil vs
-        # false is a deliberate distinction here: nil means "not applicable" (no
-        # hand-typed method to check), false means "applicable, and it fails" —
-        # see the spec's own "not-applicable (nil), not false" example.
         return nil unless method_name
 
         reconstruction_body(method_name).include?("#{field}:")
@@ -78,7 +79,7 @@ module Hecks
       def reconstruction_method_source(method_name)
         file, start_line = Hecks::Bluebook::MetaValidator::Reconstruction.instance_method(method_name).source_location
         lines = File.readlines(file)
-        indent = lines[start_line - 1][/\A\s*/]
+        indent = lines[start_line - 1][LEADING_WHITESPACE]
 
         lines[start_line..].take_while { |line| inside_method?(line, indent) }.join
       end
@@ -87,7 +88,7 @@ module Hecks
       # @return [Boolean] whether the line still belongs to the method: blank, indented deeper, or
       #   not the next `def`
       def inside_method?(line, indent)
-        line.strip.empty? || line[/\A\s*/].size > indent.size || !line.lstrip.start_with?("def ")
+        line.strip.empty? || line[LEADING_WHITESPACE].size > indent.size || !line.lstrip.start_with?("def ")
       end
 
       def fuzzer_claims?(name, field)

data/lib/hecks/query_ir.rb

@@ -18,7 +18,7 @@ module Hecks
 
     # Mirrors the conformance spec's MODEL_CONSTRUCTS; kept here because a spec is not a library.
     CONSTRUCTS = {
-      "Bluebook"       => Hecks::Bluebook::Chapter,
+      "Bluebook"       => Hecks::Bluebook::Declaration,
       "Aggregate"      => Hecks::Bluebook::Aggregate,
       "Command"        => Hecks::Bluebook::Command,
       "Entity"         => Hecks::Bluebook::Entity,
@@ -43,8 +43,8 @@ module Hecks
     # @return [Array<Symbol>] the attribute names the self-hosted meta-domain
     #   grammar declares for `name`
     def meta_declared(name)
-      Hecks::Bluebook::MetaValidator.grammar_registry
-                                    .bluebook("Bluebook").aggregate(name).attributes.map(&:name)
+      grammar = Hecks::Bluebook::MetaValidator.grammar_registry.bluebook("Bluebook")
+      grammar.aggregate(name).attributes.map(&:name)
     end
 
     # The structural diff between what a Ruby IR class emits (`ir_spec.keys`) and what the

data/lib/hecks/query_specification/common/comparison.rb

@@ -177,7 +177,7 @@ module Hecks
           return true unless record
 
           # The state lives on the target's lifecycle field, else on `:state`.
-          field = target_ir.lifecycle&.field || :state
+          field = target_ir.lifecycle_field || :state
           comparable(record.state[field]) != state
         end
 

data/lib/hecks/query_specification/common/dsl.rb

@@ -54,11 +54,10 @@ module Hecks
         # @return [OffsetSpec] the offset just recorded
         def offset_impl(value) = @offset = OffsetSpec.new(value: value)
 
-        # Records a cursor declaration. The word parses and round-trips, but both builders
-        # refuse it at `build` (`seal_cursor`) because no interpreter applies it.
+        # Records a cursor declaration: the query pages by this field and identity. `QueryBuilder`
+        # checks it at `build`; a read model still refuses it.
         #
-        # @param value [Symbol, Object] the query argument carrying the cursor, such as
-        #   `:after`, or a literal
+        # @param value [Symbol] the order field the position is read from (`:id` with no order_by)
         # @return [CursorSpec] the cursor just recorded
         def cursor(value) = @cursor = CursorSpec.new(value: value)
 

data/lib/hecks/query_specification/hop_path.rb

@@ -9,7 +9,10 @@ module Hecks
     module HopPath
       module_function
 
-      Hop = Struct.new(:attribute, :target_name, :target, keyword_init: true)
+      Hop = Struct.new(:attribute, :target_name, :target, keyword_init: true) do
+        # @return [Array<Bluebook::Attribute>] the attributes of the aggregate the hop lands on
+        def target_attributes = target.attributes
+      end
 
       # `refusal` is nil when clean, `:unresolvable` when a hop's target is not found,
       # `:too_deep` when the chain exceeds MAX_HOPS.
@@ -52,7 +55,7 @@ module Hecks
       #   starts from
       # @return [Array(Hop, String), nil] the hop and the rest of the path after the first
       #   `/`; the hop's `target` is `nil` when the referenced aggregate is not in the
-      #   declaring chapter. `nil` when the path has no `/` or its head names no reference
+      #   declaring bluebook. `nil` when the path has no `/` or its head names no reference
       # @raise [Bluebook::DSL::Malformed] if the reference has no `declared_in` aggregate
       #   to resolve its target through
       def next_hop(field, attributes)
@@ -62,7 +65,7 @@ module Hecks
         attribute = attributes.find { |candidate| candidate.reference? && hop_name(candidate) == head }
         return nil unless attribute
 
-        hop = Hop.new(attribute: attribute, target_name: attribute.type.target_name, target: attribute.type.resolve)
+        hop = Hop.new(attribute: attribute, target_name: attribute.target_name, target: attribute.target_aggregate)
         [hop, rest]
       end
 
@@ -95,7 +98,7 @@ module Hecks
         hops << hop
         return Plan.new(hops: hops, tail: nil, refusal: :unresolvable) unless hop.target
 
-        walk(rest, hop.target.attributes, hops)
+        walk(rest, hop.target_attributes, hops)
       end
     end
   end

data/lib/hecks/rails_app/bluebook/rails_app.bluebook

@@ -0,0 +1,60 @@
+# The RailsApp bluebook: what a Rails app says of its own pages, beside the domain it drives.
+#
+# Every page is derived from the domain: a list and a form for each creating command, a record
+# page that offers the commands the signed-in person may run. A project declares only what the
+# domain cannot say, as `member` rows of a `value_object "App"` or `"Listing"` in its own bluebook;
+# the aggregates below name every field a row may carry. A project with no rows has pages that
+# work, titled after its Rails application, with a list for each aggregate in the order declared.
+#
+# `hecks-rails` reads the rows when the app boots. Nothing here names a database, a template or a
+# route: the pages are the same code for every domain, and these rows are the only place a project
+# changes them. No command declares a role: the bluebook boots standing alone.
+Hecks.bluebook "RailsApp" do
+  vision "Name a Rails app and shape its lists; every page else is derived from the domain."
+
+  aggregate "App" do
+    description "The shape of the one App row: the name the pages carry and the aggregate the app opens on."
+
+    identified_by :title
+
+    attribute :title, Title
+    attribute :home,  Home, optional: true
+
+    # Shown in the header and the browser tab; the Rails application's own name when no row names one.
+    value_object "Title" do
+      attribute :value, String, matches: :present
+    end
+
+    # The aggregate the root path lists, by its name in the domain; the first aggregate declared when
+    # no row names one.
+    value_object "Home" do
+      attribute :value, String, matches: :present
+    end
+  end
+
+  aggregate "Listing" do
+    description "The shape of one Listing row: how the list of an aggregate is headed and which of its attributes it shows."
+
+    identified_by :aggregate
+
+    attribute :aggregate, AggregateName
+    attribute :label,     Label,   optional: true
+    attribute :columns,   Columns, optional: true
+
+    # The aggregate the row shapes, by its name in the domain.
+    value_object "AggregateName" do
+      attribute :value, String, matches: :present
+    end
+
+    # The heading and navigation entry for the aggregate; its plural name in words when absent.
+    value_object "Label" do
+      attribute :value, String, matches: :present
+    end
+
+    # The attributes shown as columns, comma separated and in order; identity, lifecycle state and
+    # the first scalar attributes when absent.
+    value_object "Columns" do
+      attribute :value, String, matches: :present
+    end
+  end
+end

data/lib/hecks/rails_app/bluebook/rails_app.hecksagon

@@ -0,0 +1,4 @@
+# The RailsApp domain, bound so it boots standing alone.
+Hecks.hecksagon "RailsApp" do
+  persisted_by "Memory"
+end

data/lib/hecks/refused.rb

@@ -0,0 +1,125 @@
+require_relative "vocabulary"
+
+module Hecks
+  # The domain saying no: the parent of every class `Runtime::DOMAIN_REFUSALS` names, so a
+  # driving adapter can `rescue Hecks::Refused` instead of splatting the list. A runtime fault
+  # (`Runtime::StaleWrite`, `Runtime::WiringError`) is not one.
+  #
+  # What sort of no it is (`kind`) and which point of dispatch it came from (`stage`) are rows of
+  # the language's `RefusalClass` vocabulary table, so Ruby, Rust and every client read one table.
+  class Refused < StandardError
+    # The `RefusalClass` rows by refusal name.
+    CLASSES = Hecks::Vocabulary.rows("RefusalClass").to_h { |row| [row["name"], row] }.freeze
+
+    # What a refusal that is not a named domain refusal (the base class, an adapter's narrowing of
+    # one it does not name) is classed as.
+    DEFAULT_CLASS = { "kind" => "refused", "stage" => "state" }.freeze
+
+    # The last constant name of a class's path, such as `NotFound` of `Hecks::Runtime::NotFound`.
+    LAST_NAME = /\w+\z/
+
+    # The boundary between a lower-case or digit letter and a capital, where a snake-case word starts.
+    CAMEL_BOUNDARY = /([a-z\d])([A-Z])/
+
+    # @return [Symbol, nil] the attribute the refusal is about, when it is about one; the
+    #   first in sorted order when it names several
+    attr_reader :attribute
+
+    # @return [String, nil] the text of the rule that refused (a `given`, `ensures` or invariant)
+    attr_reader :rule
+
+    # @param message [String, nil] the refusal text
+    # @param attribute [Symbol, String, nil] the attribute the refusal is about, if any
+    # @param rule [String, nil] the description of the rule that refused, if a rule did
+    # @param stage [Symbol, String, nil] a narrower stage than the refusal's class implies
+    # @param path [String, nil] a JSON Pointer to the offending value; `/attribute` when omitted
+    def initialize(message = nil, attribute: nil, rule: nil, stage: nil, path: nil)
+      super(message)
+      @attribute = attribute&.to_sym
+      @rule      = rule
+      @stage     = stage&.to_sym
+      @path      = path
+    end
+
+    # What sort of no this is, for an adapter that answers a missing record or a caller who lacks
+    # a role differently from a rule that did not hold.
+    #
+    # @return [Symbol] one of the `RefusalKind` vocabulary rows; `:refused` for a broken rule
+    def kind = classification["kind"].to_sym
+
+    # The point of dispatch the refusal came from.
+    #
+    # @return [Symbol] one of the `DispatchStage` vocabulary rows
+    def stage = @stage || classification["stage"].to_sym
+
+    # The same refusal, placed in a stage: where it was found rather than where its class usually
+    # comes from. A stage the raise site already named is kept.
+    #
+    # @param stage [Symbol, String] a `DispatchStage`
+    # @return [Hecks::Refused] this refusal if it names a stage, else a copy that does
+    def in_stage(stage)
+      return self if @stage
+
+      dup.tap { |copy| copy.stage = stage.to_sym }
+    end
+
+    # The same refusal, placed inside an attribute of the command: a field refused within a value
+    # object is about the value object's attribute, at the path that leads to the field.
+    #
+    # @param name [Symbol, String] the command attribute the refusal came from
+    # @return [Hecks::Refused] this refusal if it is already about `name`, else a re-rooted copy
+    def within(name)
+      return self if @attribute == name.to_sym
+
+      inner = path
+      dup.tap do |copy|
+        copy.attribute = name.to_sym
+        copy.path = "/#{name}#{inner}"
+      end
+    end
+
+    # A stable identifier for the sort of no this is, for scripts and agents to branch on: the
+    # class's own name in snake case (`NotFound` is `not_found`). The names are the
+    # `DomainRefusal` vocabulary rows, so a new refusal gets its code by being declared there.
+    #
+    # @return [String] the snake-case name of the refusal's class
+    def code = snake_case(class_last_name)
+
+    # The last constant name of this refusal's class path, such as `NotFound`.
+    #
+    # @return [String] the class's own name without its namespace
+    def class_last_name = self.class.name[LAST_NAME]
+
+    # A CamelCase name in snake case, one word per capital.
+    #
+    # @param name [String] a constant's last name, such as `NotFound`
+    # @return [String] the name in snake case, such as `not_found`
+    def snake_case(name) = name.gsub(CAMEL_BOUNDARY, '\\1_\\2').downcase
+
+    # @return [String, nil] a JSON Pointer to the offending value, such as `/balance/cents`
+    def path = @path || (@attribute && "/#{@attribute}")
+
+    # The refusal as plain data, the shape every client receives.
+    #
+    # @return [Hash{Symbol => Object}] kind, stage, attribute, path, rule and message
+    def to_h
+      { kind: kind, stage: stage, attribute: attribute, path: path, rule: rule, message: message }
+    end
+
+    protected
+
+    attr_writer :attribute, :path, :stage
+
+    private
+
+    def classification
+      self.class.ancestors.each do |ancestor|
+        row = CLASSES[short_name(ancestor)]
+        return row if row
+      end
+      DEFAULT_CLASS
+    end
+
+    def short_name(klass) = klass.to_s[LAST_NAME]
+  end
+end

data/lib/hecks/release/approval.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "hecks/vocabulary"
+require "hecks/release/version_commit"
 
 module Hecks
   module Release
@@ -12,6 +13,9 @@ module Hecks
     # decision is read from git history alone, so it can be made again on any later run. It reads
     # only the Vocabulary table, so `release.yml` can run it with the runner's own Ruby.
     module Approval
+      # The key of a trailer line and the space after its colon: "Release-Approved-By: ".
+      TRAILER_KEY = /\A[^:]*:\s*/
+
       module_function
 
       # @return [String] the trailer key, read from the `Lane` row that feeds a tag
@@ -27,10 +31,14 @@ module Hecks
       # @param message [String] a commit message
       # @return [String, nil] who approved, from the first trailer line with a name, or nil
       def approver(message)
-        line = message.to_s.lines.map(&:strip).find { |text| text.match?(/\A#{Regexp.escape(trailer)}:\s*\S/) }
-        line&.sub(/\A[^:]*:\s*/, "")
+        line = stripped_lines(message).find { |text| text.match?(/\A#{Regexp.escape(trailer)}:\s*\S/) }
+        line&.sub(TRAILER_KEY, "")
       end
 
+      # @param message [String, nil] a commit message
+      # @return [Array<String>] its lines, each stripped
+      def stripped_lines(message) = message.to_s.lines.map(&:strip)
+
       # @param message [String] the message of the commit that set the version
       # @param tag_exists [Boolean] whether the release's tag already stands on origin: a release
       #   that was begun was approved when it began, so finishing it asks again for nothing
@@ -50,12 +58,14 @@ module Hecks
 
       # Reads the decision's inputs from the environment `release.yml` gives it.
       #
-      # @param env [#[]] `COMMIT_MESSAGE`, `TAG_EXISTS` (true/false), `APPROVED_BY`
+      # @param env [#[]] `COMMIT_MESSAGE`, or `COMMIT` (the first-parent commit that set the version,
+      #   whose message is read as {VersionCommit} reads it), `TAG_EXISTS` (true/false), `APPROVED_BY`
       # @param out [#puts] where the words go
       # @return [Integer] the exit status: 0 to go ahead, 1 to refuse
       def check(env: ENV, out: $stdout)
-        ok, words = verdict(message: env["COMMIT_MESSAGE"], tag_exists: env["TAG_EXISTS"] == "true",
-                            explicit: env["APPROVED_BY"])
+        ok, words = verdict(message:    env["COMMIT_MESSAGE"] || VersionCommit.message(env["COMMIT"].to_s),
+                            tag_exists: env["TAG_EXISTS"] == "true",
+                            explicit:   env["APPROVED_BY"])
         out.puts(ok ? "release approval: #{words}" : "::error::#{words}")
         ok ? 0 : 1
       end