hecks 6.0.0 → 7.0.0

data/lib/hecks/quality_control/quality_control.hecksagon

@@ -5,6 +5,17 @@
 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 bluebook's roles are checked against.

data/lib/hecks/quality_control/quality_control.ports.hecksagon

@@ -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.
@@ -37,6 +59,15 @@ Hecks.hecksagon "QualityControl" do
     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"
@@ -52,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/touchpoints.rb

@@ -33,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) }
         ]
@@ -52,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}:")

data/lib/hecks/refused.rb

@@ -18,6 +18,9 @@ module Hecks
     # 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
@@ -75,6 +78,24 @@ module Hecks
       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}")
 

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
@@ -57,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

data/lib/hecks/release/conditions.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Release
+    # The auto-approval conditions of a release PR, judged from facts a check has gathered.
+    #
+    # The names are the `ReleaseCondition` values the QualityControl bluebook declares. A release is
+    # approved only when every condition holds; otherwise the first failure in the order below is
+    # named, and that name is the refusal.
+    module Conditions
+      # The value an approval accepts.
+      MET = "met"
+
+      module_function
+
+      # @param version [String] the version the release bumps to
+      # @param stable_head [Boolean] whether the commit is on stable's head after promotion
+      # @param checks_green [Boolean] whether every required check passed on the commit
+      # @param changelog_dated [Boolean] whether the changelog has a dated `## [version]` heading
+      # @param versions [Hash{String => String}] each version file's version, keyed by its name
+      # @return [String] `met`, or the name of the first condition that failed
+      def judge(version:, stable_head:, checks_green:, changelog_dated:, versions:)
+        return "not_on_stable_head" unless stable_head
+        return "checks_not_green" unless checks_green
+        return "changelog_undated" unless changelog_dated
+        return "version_mismatch" unless versions_agree?(version, versions)
+
+        MET
+      end
+
+      # @param changelog [String] the text of the changelog
+      # @param version [String] the version the release bumps to
+      # @return [Boolean] whether a `## [version] - YYYY-MM-DD` heading stands in the changelog
+      def changelog_dated?(changelog, version)
+        changelog.match?(/^## \[#{Regexp.escape(version)}\] - \d{4}-\d{2}-\d{2}$/)
+      end
+
+      # @param version [String] the version the release bumps to
+      # @param versions [Hash{String => String}] each version file's version, keyed by its name
+      # @return [Boolean] whether every version file names the same version
+      def versions_agree?(version, versions)
+        versions.any? && versions.values.all?(version)
+      end
+    end
+  end
+end

data/lib/hecks/release/runner/gem_publisher.rb

@@ -1,13 +1,12 @@
 require_relative "commands"
 require_relative "clean_tree"
 require_relative "git"
-require_relative "../../cli/release_gem"
 require "hecks/hecks/adapters/codebase/gem_registry"
 
 module Hecks
   module Release
     class Runner
-      # The gem step: hands the push to `Hecks::CLI::ReleaseGem`, which builds and pushes
+      # The gem step: hands the push to `Hecks::Tools::ReleaseGem`, which builds and pushes
       # it with the key 1Password holds; a dry run only builds it, then deletes it.
       class GemPublisher
         # @param root [String] the repository root
@@ -32,9 +31,10 @@ module Hecks
 
           CleanTree.new(git: Git.new(root: @root, commands: @commands)).check!
 
+          require_relative "../../tools/release_gem"
           @console.say("Publishing hecks #{version} to rubygems.org...")
-          status = Hecks::CLI::ReleaseGem.call(root: @root, commands: @commands, out: @console.out,
-                                               err: @console.err, version: version)
+          status = Hecks::Tools::ReleaseGem.call(root: @root, commands: @commands, out: @console.out,
+                                                 err: @console.err, version: version)
           raise CommandFailed, "the gem push was refused" unless status.zero?
         end
 

data/lib/hecks/release/version_commit.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Hecks
+  module Release
+    # The message of the commit that set the version, as the owner's approval is read from it.
+    #
+    # A release branch merged with a merge commit leaves the version change on the merged side:
+    # the first-parent commit that touches `lib/hecks/version.rb` is then the merge, whose message
+    # the owner never wrote. For a merge, the message is that of the newest non-merge commit on
+    # the merged side that changed the `VERSION =` line, so a bump without the trailer still
+    # refuses, however the merge is worded.
+    module VersionCommit
+      # Raised when git cannot answer, so a release is never judged from a guess.
+      class GitFailed < StandardError; end
+
+      VERSION_LINE = "^ *VERSION = "
+      VERSION_FILE = "lib/hecks/version.rb"
+
+      module_function
+
+      # @param commit [String] the first-parent commit that touches the version file
+      # @param dir [String] the git work tree
+      # @return [String] the message of the commit that set the version
+      def message(commit, dir: Dir.pwd)
+        parents = git(dir, "rev-list", "--parents", "-n", "1", commit).split.drop(1)
+        side = parents.size > 1 ? side_message(dir, commit, parents) : ""
+        side.strip.empty? ? git(dir, "log", "-1", "--format=%B", commit) : side
+      end
+
+      # @return [String] the newest non-merge bump on the merged side, or "" when it has none
+      def side_message(dir, commit, parents)
+        git(dir, "log", "--no-merges", "-1", "--format=%B", "-G#{VERSION_LINE}", "#{parents.first}..#{commit}",
+            "--", VERSION_FILE)
+      end
+
+      # @return [String] what `git` prints in `dir`
+      # @raise [GitFailed] when git refuses
+      def git(dir, *args)
+        out, status = Open3.capture2e("git", "-C", dir, *args)
+        raise GitFailed, "git #{args.join(" ")} failed: #{out}" unless status.success?
+
+        out
+      end
+    end
+  end
+end

data/lib/hecks/runtime/command_interpreter/hydration.rb

@@ -111,10 +111,11 @@ module Hecks
         end
 
         def raise_record_missing(aggregate, id)
-          raise(NotFound, RefusalWording.render_site("NotFound", "record_missing",
-                                                     aggregate: aggregate.hecks_name,
-                                                     identity:  identity_reading(aggregate),
-                                                     offered:   Rendering.describe(id)))
+          message = RefusalWording.render_site("NotFound", "record_missing",
+                                               aggregate: aggregate.hecks_name,
+                                               identity:  identity_reading(aggregate),
+                                               offered:   Rendering.describe(id))
+          raise(NotFound, RefusalWording.with_creator_hint(message, aggregate))
         end
 
         def raise_creating_no_identity(command, aggregate)

data/lib/hecks/runtime/command_interpreter/persisting.rb

@@ -20,6 +20,7 @@ module Hecks
 
           if ctx.dry_run
             step(:save) { check_dry_run_creates_duplicate(ctx) }
+            DryRunPlan.write(ctx.aggregate, ctx.instance)
           else
             step(:save) { persist_and_check(ctx) }
           end
@@ -47,15 +48,22 @@ module Hecks
             # this interpreter reading the record first to check — a
             # `repository.find` before every atomic_put would be exactly the
             # read this strategy exists to skip.
-            ctx.repository.atomic_put(ctx.instance, insert_only: ctx.command.creates?)
+            ctx.repository.atomic_put(ctx.instance, insert_only: ctx.command.creates?, mints_era: mints_era?(ctx))
           else
             # `expected_version:` is nil for a brand-new record or a
             # non-CAS repository, either of which falls through to a
-            # plain, unconditional save inside `AppendOnly#save`.
-            ctx.repository.save(ctx.instance, expected_version: ctx.instance_version)
+            # plain, unconditional save inside `AppendOnly#save`. `mints_era:`
+            # reaches the journal entry only when this command declares it.
+            ctx.repository.save(ctx.instance, expected_version: ctx.instance_version, mints_era: mints_era?(ctx))
           end
         end
 
+        # The one-write allowance this command's record holds through an unminted boot: the
+        # binding names it (`mints_era` in the world), or the command still says `mints_era true`.
+        def mints_era?(ctx)
+          ctx.command.mints_era? || ctx.repository.mints_era_declared?(ctx.aggregate_hecks_name, ctx.command_hecks_name)
+        end
+
         def raise_for_persistence_outcome!(ctx)
           case ctx.outcome_status
           when :conflicted

data/lib/hecks/runtime/command_interpreter.rb

@@ -4,6 +4,7 @@ require_relative "command_interpreter/mutation_applier"
 require_relative "command_interpreter/enforcement"
 require_relative "command_interpreter/hydration"
 require_relative "command_interpreter/persisting"
+require_relative "dry_run_plan"
 require_relative "command_interpreter/delegation"
 require_relative "../rendering"
 require_relative "errors"
@@ -68,7 +69,6 @@ module Hecks
       # @param dispatch_key [String, nil] a saga dispatch's identity; an applied one runs no step
       # @return [Array] the settled instance, events, plan, persistence outcome, and outbox rows
       # @raise [StandardError] a domain refusal, a StaleWrite once retries run out, or a WiringError
-      # rubocop:disable-next Metrics/ParameterLists -- the public dispatch signature every entry point calls
       def call(domain, aggregate, command, invocation, correlation = nil, dry_run: false, dispatch_key: nil)
         args     = invocation.to_args
         settings = { invocation:, route: invocation.target, correlation:, dry_run:, dispatch_key: }
@@ -181,7 +181,7 @@ module Hecks
       # `dry_run:` skips this too — nothing was committed, so `ctx.result`
       # stays nil.
       def step_emit(ctx)
-        return if ctx.dry_run
+        return DryRunPlan.emits(ctx.command) if ctx.dry_run
 
         ctx.result = step(:emit) { emit_events(ctx) }
       end

data/lib/hecks/runtime/command_rules/admissibility.rb

@@ -29,7 +29,6 @@ module Hecks
         # @return [void]
         # @raise [Runtime::GivenNotMet] a declared `given` does not hold
         # @raise [Runtime::LifecycleRefused] `declaring`'s `from:` guard refuses the state
-        # rubocop:disable-next Metrics/ParameterLists -- the dispatch context every interpreter passes by keyword
         def enforce_givens(subject, command, args, domain:, declaring: nil, parent: nil, correction: {})
           # A rule reads only within its own aggregate boundary (ADR 0025);
           # `dereference` below resolves fresh reference arguments only,
@@ -111,7 +110,6 @@ module Hecks
         # @param correction [Hash{Symbol => Object}] `corrects` event bindings, if any
         # @return [void]
         # @raise [Runtime::EnsuresNotMet] a declared `ensures` does not hold
-        # rubocop:disable-next Metrics/ParameterLists -- the dispatch context every interpreter passes by keyword
         def enforce_ensures(subject, command, args, old:, domain:, parent: nil, correction: {})
           state = GuardState.new(subject)
           # Same aggregate-boundary rule as enforce_givens (ADR 0025) —

data/lib/hecks/runtime/command_rules/emission.rb

@@ -15,7 +15,6 @@ module Hecks
         # @param repository [Ports::Persistence::AppendOnly] asked to `record_event` if it can
         # @param correlation [Hash, nil] saga correlation, set before the event freezes
         # @return [Array<Runtime::Event>] the emitted events in `emits` order
-        # rubocop:disable-next Metrics/ParameterLists -- the positional signature both interpreters call
         def emit(command, domain, aggregate, instance, args, repository, correlation = nil)
           stamp = { aggregate: "#{domain}::#{aggregate.hecks_name}", id: instance.id,
                     payload: args, correlation: correlation }

data/lib/hecks/runtime/dependency_planning/expression_reads.rb

@@ -13,7 +13,6 @@ module Hecks
         # raises before it is stored, so a failure is never cached. Written from dispatch
         # threads, so every access holds PATHS_LOCK; the cache is cleared when it reaches
         # PATHS_CACHE_LIMIT entries, so distinct texts cannot grow it without bound.
-        # rubocop:disable-next Style/MutableConstant
         PATHS_CACHE = {}
         PATHS_LOCK = Mutex.new
         PATHS_CACHE_LIMIT = 4096

data/lib/hecks/runtime/dispatcher/planning.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Runtime
+    class Dispatcher
+      # What a command would write and announce, listed without writing or announcing it. Runs the
+      # in-memory pipeline `dry_run?` runs; the save and emit seams report to DryRunPlan.
+      module Planning
+        # Lists what a command would write and announce, without writing or announcing it.
+        #
+        # Runs the same in-memory pipeline as `dry_run?`, with the save and emit seams reporting
+        # instead of acting, so every command gets its plan from one place.
+        #
+        # @param verb [String] the fully qualified aggregate command verb
+        # @param args [Hash{Symbol => Object}] the facts as flat keywords
+        # @return [Array<String>] one `would write` or `would emit` line per effect, in order
+        # @raise [StandardError] any refusal the real dispatch would raise
+        def plan_flat(verb, **args)
+          DryRunPlan.collect { dry_run_call(flat_call(verb, args)) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/dispatcher/routing.rb

@@ -2,6 +2,7 @@ require_relative "../errors"
 require_relative "../refusal_wording"
 require_relative "../invocation"
 require_relative "../../naming"
+require_relative "value_routing"
 
 module Hecks
   module Runtime
@@ -9,6 +10,8 @@ module Hecks
       # Finds what a verb names and runs it through the interpreter that owns it. Mixed into
       # {Dispatcher}, which holds the interpreters and the registry these read.
       module Routing
+        include ValueRouting
+
         # One dispatch request as the caller spelled it: the verb, its receiver and facts, and
         # the saga correlation to stamp on emitted events.
         Call = Struct.new(:verb, :to, :with, :saga_correlation, :dispatch_key, :flat, keyword_init: true)
@@ -57,6 +60,9 @@ module Hecks
 
         def route_aggregate(call, domain, aggregate, aggregate_name, command_name)
           command = command_of(aggregate, aggregate_name, command_name)
+          handler = value_handler(domain, aggregate, command, call)
+          return route_port(call, domain, aggregate, handler) if handler
+
           invocation = Invocation.from_call(call.verb, to: call.to, with: call.with, flat: call.flat) { command }
           @commands.call(domain, aggregate, command, invocation, call.saga_correlation, dispatch_key: call.dispatch_key)
         end

data/lib/hecks/runtime/dispatcher/value_routing.rb

@@ -0,0 +1,54 @@
+module Hecks
+  module Runtime
+    class Dispatcher
+      # Routes a command value to the port operation a hecksagon binds to it: the operations whose
+      # `handles` name this command and value (ADR 0163 step 52). Mixed into {Routing}.
+      module ValueRouting
+        private
+
+        # The port operation a command value is routed to, or nil when no hecksagon binds the
+        # command by value. A command that has bindings refuses a value none of them names.
+        def value_handler(domain, aggregate, command, call)
+          key = command_key(aggregate, command)
+          bindings = value_bindings(domain, key)
+          return nil if bindings.empty?
+
+          supplied = supplied_values(call)
+          found = bindings.find { |_, value| supplied.include?(value) }
+          return found.first if found
+
+          no_value_handler!(key, bindings, supplied)
+        end
+
+        def command_key(aggregate, command) = "#{aggregate.name}.#{Naming.snake(command.hecks_name)}!"
+
+        # Every port operation of the domain's aggregates that names the command, with its value.
+        def value_bindings(domain, key)
+          bluebook = @registry.bluebook(domain)
+          return [] unless bluebook
+
+          handling_operations(bluebook).flat_map { |operation| bindings_of(operation, key) }
+        end
+
+        def handling_operations(bluebook) = bluebook.aggregates.flat_map(&:ports).flat_map(&:operations)
+
+        def bindings_of(operation, key)
+          operation.handles.select { |held| held[:command] == key }.map { |held| [operation, held[:value]] }
+        end
+
+        # The string values the call supplies, one level down from a value object
+        # (`target: {value:}`).
+        def supplied_values(call)
+          facts = (call.with || {}).merge(call.flat || {})
+          facts.values.flat_map { |value| value.is_a?(Hash) ? value.values : [value] }.grep(String)
+        end
+
+        def no_value_handler!(key, bindings, supplied)
+          handled = bindings.map { |_, value| value }.join(", ")
+          raise(UnknownVerb, "#{key} has no handler for #{supplied.inspect}; " \
+                             "its hecksagon handles #{handled.inspect}")
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/dispatcher.rb

@@ -16,6 +16,8 @@ require_relative "dispatcher/routing"
 require_relative "dispatcher/validating"
 require_relative "dispatcher/queries"
 require_relative "declarations"
+require_relative "dry_run_plan"
+require_relative "dispatcher/planning"
 require_relative "../naming"
 
 module Hecks
@@ -27,6 +29,7 @@ module Hecks
       include Validating
       include Queries
       include Declarations
+      include Planning
 
       MAX_REACTION_DEPTH = 5
 
@@ -67,6 +70,10 @@ module Hecks
       # @return [Array<Hash{Symbol => Object}>]
       def sagas = @registry.saga_log
 
+      # The interpreter that moves sagas through their stages, for `resume` and redelivery.
+      # @return [SagaInterpreter]
+      def saga_interpreter = @sagas
+
       # Exposes the raw inputs each saga dispatch bound its arguments from (Ruby-only).
       #
       # @return [Array<Hash{Symbol => Object}>]
@@ -147,7 +154,6 @@ module Hecks
       # @raise [Runtime::UnknownVerb] if the domain, aggregate, port or operation is undeclared
       # @raise [Runtime::TypeMismatch] if no receiving identity is found, or `to:`/`with:` is bad
       # @raise [Runtime::NotFound] if the receiving record does not exist
-      # rubocop:disable-next Metrics/ParameterLists -- the public dispatcher's parts, one argument per verb segment
       def dispatch_port(domain, aggregate_name, port_name, operation_name, to: nil, with: nil, flat: {})
         verb = "#{domain}::#{aggregate_name}.#{port_name}.#{operation_name}"
         aggregate = resolve_aggregate(domain, aggregate_name, verb)