hecks 3.9.1 → 3.11.0

data/lib/hecks/projector/exporter/bindings.rb

@@ -1,3 +1,5 @@
+require_relative "capability_values"
+
 module Hecks
   module Projector
     module Exporter
@@ -5,6 +7,8 @@ module Hecks
       # membership, identity, newsletter, registrations, payments): a per-deployment binding fact,
       # not part of the declared IR. Each answers `{}` when nothing the domain attaches provides it.
       module Bindings
+        include CapabilityValues
+
         # Which chapter this domain's role checks resolve against
         # (`Registry#authorization_provider_for`); `{}` if none does.
         #
@@ -70,16 +74,20 @@ module Hecks
         # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
         # @param domain_name [String] the domain to export the newsletter binding for
         # @return [Hash{Symbol => String, nil}] `:provider` (name), `:subscribe`, `:add_name`,
-        #   `:confirm`, `:unsubscribe` (qualified verbs), and `:aggregate` (`:subscribe`'s own
-        #   leading qualified aggregate name); `{}` if nothing this domain attaches provides
-        #   newsletter
+        #   `:confirm`, `:unsubscribe` (qualified verbs), `:aggregate` (`:subscribe`'s own
+        #   leading qualified aggregate name) and, when declared, `:awaiting_confirmation`,
+        #   `:receives_issues` and `:left` (the states of the lifecycle marks they name) and
+        #   `:confirm_window` and `:unsubscribe_window` (seconds); `{}` if nothing this domain
+        #   attaches provides newsletter
         def newsletter(registry, domain_name)
           provider = registry.newsletter_provider_for(domain_name)
           return {} unless provider
 
           verbs = verbs_of(provider, Bluebook::Capabilities::NEWSLETTER,
                            :subscribe, :add_name, :confirm, :unsubscribe)
-          { provider: provider.name, **verbs, aggregate: aggregate_of(verbs[:subscribe]) }
+          { provider: provider.name, **verbs, aggregate: aggregate_of(verbs[:subscribe]),
+            **all_marked_states(provider, Bluebook::Capabilities::NEWSLETTER),
+            **all_durations(provider, Bluebook::Capabilities::NEWSLETTER) }
         end
 
         # Which chapter answers sending a newsletter issue
@@ -107,15 +115,18 @@ module Hecks
         # @param domain_name [String] the domain to export the registrations binding for
         # @return [Hash{Symbol => String, nil}] `:provider` (name), `:schedule`, `:request`
         #   (qualified verbs), `:event_aggregate` and `:registration_aggregate` (each verb's own
-        #   leading qualified aggregate name); `{}` if nothing this domain attaches provides
-        #   registrations
+        #   leading qualified aggregate name) and, when declared, `:frees_seat` (the states of the
+        #   lifecycle mark it names) and `:registered_at` (the attribute that stamps a request);
+        #   `{}` if nothing this domain attaches provides registrations
         def registrations(registry, domain_name)
           provider = registry.registrations_provider_for(domain_name)
           return {} unless provider
 
           verbs = verbs_of(provider, Bluebook::Capabilities::REGISTRATIONS, :schedule, :request)
           { provider: provider.name, **verbs,
-            **aggregates_of(verbs, event_aggregate: :schedule, registration_aggregate: :request) }
+            **aggregates_of(verbs, event_aggregate: :schedule, registration_aggregate: :request),
+            **all_marked_states(provider, Bluebook::Capabilities::REGISTRATIONS),
+            **all_words(provider, Bluebook::Capabilities::REGISTRATIONS) }
         end
 
         # Which chapter owns the payment-processor connection
@@ -142,14 +153,33 @@ module Hecks
         # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
         # @param domain_name [String] the domain to export the payments binding for
         # @return [Hash{Symbol => String, nil}] `:provider` (name), `:initiate`, `:succeeded`,
-        #   `:failed` (qualified verbs), and `:aggregate` (`:initiate`'s own leading qualified
-        #   aggregate name); `{}` if nothing this domain attaches provides payments
+        #   `:failed` (qualified verbs), `:aggregate` (`:initiate`'s own leading qualified
+        #   aggregate name) and, when declared, `:holds_seat` (the states of the lifecycle mark
+        #   it names) and `:lapse_reason` (the word a lapsed hold
+        #   records); `{}` if nothing this domain attaches provides payments
         def payments(registry, domain_name)
           provider = registry.payments_provider_for(domain_name)
           return {} unless provider
 
           verbs = verbs_of(provider, Bluebook::Capabilities::PAYMENTS, :initiate, :succeeded, :failed)
-          { provider: provider.name, **verbs, aggregate: aggregate_of(verbs[:initiate]) }
+          { provider: provider.name, **verbs, aggregate: aggregate_of(verbs[:initiate]),
+            **marked_states(provider, Bluebook::Capabilities::PAYMENTS, :holds_seat),
+            **all_words(provider, Bluebook::Capabilities::PAYMENTS) }
+        end
+
+        # Which chapter owns the checkout boundary (`Registry#checkout_provider_for`); `{}` if
+        # none does.
+        #
+        # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
+        # @param domain_name [String] the domain to export the checkout binding for
+        # @return [Hash{Symbol => Object}] `:provider` (name) and, when declared,
+        #   `:webhook_tolerance` and `:session_hold` (whole seconds); `{}` if nothing this
+        #   domain attaches provides checkout
+        def checkout(registry, domain_name)
+          provider = registry.checkout_provider_for(domain_name)
+          return {} unless provider
+
+          { provider: provider.name, **all_durations(provider, Bluebook::Capabilities::CHECKOUT) }
         end
 
         private

data/lib/hecks/projector/exporter/capability_values.rb

@@ -0,0 +1,55 @@
+module Hecks
+  module Projector
+    module Exporter
+      # The values a capability's optional contract entries resolve to in the exported fact: the
+      # states of a lifecycle `:mark` (ADR 0097), the whole seconds of a `:duration` (ADR 0098), and
+      # the word of a `:text` or `:attribute` entry (ADR 0099).
+      module CapabilityValues
+        private
+
+        # `{ key => states }` for each optional `:mark` entry `provider` declares under
+        # `capability`.
+        def all_marked_states(provider, capability)
+          mark_keys = declared_keys(capability, :mark)
+          mark_keys.reduce({}) { |marks, key| marks.merge(marked_states(provider, capability, key)) }
+        end
+
+        # `{ key => seconds }` for each optional `:duration` entry `provider` declares under
+        # `capability`: the whole-seconds default of the attribute it names.
+        def all_durations(provider, capability)
+          declared_keys(capability, :duration).each_with_object({}) do |key, durations|
+            verb = provider.provision(capability)&.fetch(key, nil)
+            durations[key] = Bluebook::Capabilities.duration_of(provider, verb) if verb
+          end
+        end
+
+        # `{ key => word }` for each optional `:text` entry and `{ key => attribute_name }` for each
+        # optional `:attribute` entry `provider` declares under `capability` (ADR 0099).
+        def all_words(provider, capability)
+          words = { text: :text_of, attribute: :attribute_of }.flat_map do |kind, resolver|
+            declared_keys(capability, kind).filter_map do |key|
+              verb = provider.provision(capability)&.fetch(key, nil)
+              [key, Bluebook::Capabilities.public_send(resolver, provider, verb)] if verb
+            end
+          end
+          words.to_h
+        end
+
+        # `{ key => states }` for an optional `:mark` entry `provider` declares under `capability`:
+        # the states of the named aggregate's lifecycle mark. `{}` when the entry is not declared.
+        def marked_states(provider, capability, key)
+          verb = provider.provision(capability)&.fetch(key, nil)
+          return {} unless verb
+
+          aggregate_name, mark = verb.split(".", 2)
+          { key => provider.aggregate(aggregate_name).lifecycle.marked(mark) }
+        end
+
+        # The contract keys of `capability` whose kind is `kind`.
+        def declared_keys(capability, kind)
+          Bluebook::Capabilities::CONTRACTS.fetch(capability).select { |_, entry| entry == kind }.keys
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/narrate_projector/reactions.rb

@@ -16,7 +16,7 @@ module Hecks
         # A policy as the sentence saying it fires on its own.
         def policy_sentence(policy)
           elsewhere = policy.target_domain ? " in #{policy.target_domain}" : ""
-          "Whenever `#{policy.on_event}` happens, `#{policy.trigger_command}` fires on its own#{elsewhere} — " \
+          "Whenever `#{policy.on_event}` happens, `#{policy.reaches}` fires on its own#{elsewhere} — " \
             "nobody has to ask for it."
         end
 

data/lib/hecks/projector/target.rb

@@ -58,6 +58,17 @@ module Hecks
       #   before `projects_as` is called
       def projection_needs_world? = @projection_needs_world || false
 
+      # Derives what kind of target this is from flags it already declares,
+      # so there is no second spelling to drift.
+      #
+      # @return [Symbol] `:export` if it needs a world, `:meta` if it needs a
+      #   chapter declaring particular aggregates, otherwise `:projection`
+      def projection_category
+        return :export if projection_needs_world?
+
+        projection_declares.empty? ? :projection : :meta
+      end
+
       # Names the capability module(s) a construct must satisfy, defaulting
       # to plain chapter-hood when `projects_as` named none.
       #

data/lib/hecks/projector.rb

@@ -4,10 +4,13 @@ module Hecks
   #
   #   Projector.call(:ir, bluebook: chapter)
   #
-  # A projection is inert and derived from a chapter's declaration. An export
-  # (rust crate, WASM, CloudFormation) also needs `.world` bindings and declares
-  # `needs_world: true`. State projections (`hecks project_expression_tables`) and
-  # `Ports::Projection` read-model catch-up are different things and not registered.
+  # A target's category is derived from the flags it declares (`category`):
+  #
+  # - `:projection` is inert and derived from any chapter's declaration.
+  # - `:meta` also needs a chapter declaring particular aggregates (`declares:`),
+  #   so it only fits hecks's own grammar chapters.
+  # - `:export` (CloudFormation, ...) also needs `.world` bindings and declares
+  #   `needs_world: true`; that is adapter wiring, not a projection of the domain.
   module Projector
     class UnknownProjector < StandardError; end
     # A chapter-scoped projector was handed something that is not a chapter.
@@ -38,7 +41,9 @@ module Hecks
     # @raise [WrongConstruct] if `bluebook` lacks what the projector requires
     def call(name, bluebook:, options: {}, world: nil)
       projector = registry.fetch(name.to_sym) do
-        raise UnknownProjector, "no projector registered for #{name.inspect} — registered: #{registered.sort.inspect}"
+        raise UnknownProjector,
+              "no projector registered for #{name.inspect} — registered: " \
+              "#{registered_by_category.map { |kind, keys| "#{kind} #{keys.inspect}" }.join(", ")}"
       end
       admits!(name, projector, bluebook, world)
       projector.call(bluebook: bluebook, options: world ? options.merge(world: world) : options)
@@ -114,6 +119,28 @@ module Hecks
     # @return [Array<Symbol>] every key currently registered
     def registered = registry.keys
 
+    # Gives the category of a registered target, derived from its flags.
+    # A target that answers no `projection_category` (the built-ins, which do
+    # not extend `Target`) is a plain projection.
+    #
+    # @param name [String, Symbol] the registered projector's key
+    # @return [Symbol] `:projection`, `:meta` or `:export` (`:projection` for an
+    #   unregistered `name`)
+    def category(name)
+      projector = registry.fetch(name.to_sym) { return :projection }
+      projector.respond_to?(:projection_category) ? projector.projection_category : :projection
+    end
+
+    # Lists every registered key under its category.
+    #
+    # @return [Hash{Symbol => Array<Symbol>}] `:projection`, `:meta` and `:export`
+    #   (always all three), each with its sorted keys
+    def registered_by_category
+      grouped = { projection: [], meta: [], export: [] }
+      registered.sort.each { |key| grouped[category(key)] << key }
+      grouped
+    end
+
     # Gives the live registry, initializing it on first use.
     #
     # @return [Hash{Symbol => Module, Class, #call}] the live key => projector registry

data/lib/hecks/quality_control/adapters/github_checks.rb

@@ -2,12 +2,16 @@
 
 require "open3"
 require "json"
+require_relative "../../indifferent_key"
 
 module Hecks
   module Adapters
     # The `CI` port adapter: answers `Clearance.CI.Run` from GitHub's check runs for a commit.
     # Raises when no checks exist, any are still running, or any failed.
     class GithubChecks
+      # Raised when check runs cannot be read or have not settled.
+      class Error < RuntimeError; end
+
       # All keywords are unused; the adapter takes no per-boot configuration.
       def initialize(aggregate: nil, settings: {}, root: nil); end
 
@@ -29,7 +33,7 @@ module Hecks
       #
       # @param commit [Hash, String] a materialized value object (`{value: sha}`) or a bare sha
       # @return [Hash] `{ summary: { value: ... } }` when every check is green
-      # @raise [RuntimeError] when the sha is malformed, `gh` is missing or fails, no checks
+      # @raise [Error] when the sha is malformed, `gh` is missing or fails, no checks
       #   exist, any are incomplete, or any failed
       def run(commit:, **)
         sha = valid_sha(commit)
@@ -49,7 +53,7 @@ module Hecks
       # @param names [Array<String>] the checks to look up
       # @return [Hash{String => Symbol}] each name to `:passed`, `:failed`, `:pending` (reported but
       #   not completed) or `:missing` (not reported at all)
-      # @raise [RuntimeError] when the sha is malformed or `gh` is missing or fails
+      # @raise [Error] when the sha is malformed or `gh` is missing or fails
       def states(commit:, names:)
         reported = check_runs(valid_sha(commit)).select { |run| actions?(run) }.group_by { |run| run["name"] }
         latest = reported.transform_values { |runs| runs.max_by { |run| run["id"].to_i } }
@@ -62,7 +66,7 @@ module Hecks
 
       def valid_sha(commit)
         sha = sha_of(commit)
-        raise "not a commit sha: #{sha.inspect}" unless sha.match?(SHA_PATTERN)
+        raise Error, "not a commit sha: #{sha.inspect}" unless sha.match?(SHA_PATTERN)
 
         sha
       end
@@ -70,11 +74,11 @@ module Hecks
       # The check runs against `sha`, once none is still running.
       def settled_runs(sha)
         runs = check_runs(sha)
-        raise "gh reports no checks at all against #{sha}" if runs.empty?
+        raise Error, "gh reports no checks at all against #{sha}" if runs.empty?
 
         # Refuse rather than answer on an incomplete run; asking again once it settles is safe.
         incomplete = runs.reject { |run| run["status"] == "completed" }
-        raise "checks against #{sha} are still running — asked before they settled" if incomplete.any?
+        raise Error, "checks against #{sha} are still running — asked before they settled" if incomplete.any?
 
         runs
       end
@@ -95,7 +99,7 @@ module Hecks
       def sha_of(commit)
         return commit if commit.is_a?(String)
 
-        (commit.key?(:value) ? commit[:value] : commit["value"]).to_s
+        IndifferentKey.read(commit, :value).to_s
       end
 
       # Every page of check runs: a red run past the first page must still be seen.
@@ -115,11 +119,11 @@ module Hecks
       def check_run_page(sha, page)
         path = "repos/{owner}/{repo}/commits/#{sha}/check-runs?per_page=#{PER_PAGE}&page=#{page}"
         out, err, status = Open3.capture3("gh", "api", path)
-        raise "gh api check-runs failed for #{sha}: #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+        raise Error, "gh api check-runs failed for #{sha}: #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
 
         JSON.parse(out)
       rescue Errno::ENOENT
-        raise "gh is not installed or not on PATH — cannot read check runs for #{sha}"
+        raise Error, "gh is not installed or not on PATH — cannot read check runs for #{sha}"
       end
     end
   end

data/lib/hecks/quality_control/adapters/github_issues.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
 require "open3"
+require_relative "../../indifferent_key"
 
 module Hecks
   module Adapters
     # The `IssueTracker` port's adapter: files a `QualityControl::Ticket` as a GitHub issue.
     # Raises when `gh` refuses, which the runtime records as the ticket's refusal.
     class GithubIssues
+      # Raised when `gh` cannot file the issue.
+      class Error < RuntimeError; end
+
       # @param aggregate [Object, nil] unused
       # @param settings [Hash] unused
       # @param root [String, nil] unused
@@ -18,7 +22,7 @@ module Hecks
       #   value objects (`{value: ...}`) or bare strings, and `pull_request` names a proposed fix
       # @return [Hash{Symbol => Hash}] `number:` and `url:` of the issue, in the shape the
       #   ticket's `Filed` command takes
-      # @raise [RuntimeError] when `gh` exits non-zero or prints no issue URL
+      # @raise [Error] when `gh` exits non-zero or prints no issue URL
       def file(**held)
         out = create_issue(plain(held[:repository]), plain(held[:title]).to_s, issue_body(held))
         url, number = issue_url_and_number(out)
@@ -37,7 +41,7 @@ module Hecks
       def issue_url_and_number(out)
         url = out.strip.lines.last.to_s.strip
         number = url[%r{/issues/(\d+)\z}, 1]
-        raise "gh issue create printed no issue URL: #{out.strip.inspect}" unless number
+        raise Error, "gh issue create printed no issue URL: #{out.strip.inspect}" unless number
 
         [url, number]
       end
@@ -45,7 +49,7 @@ module Hecks
       def create_issue(repository, title, body)
         out, err, status = Open3.capture3("gh", "issue", "create", "--repo", repository,
                                           "--title", title, "--body", body)
-        raise "gh issue create failed — #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+        raise Error, "gh issue create failed — #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
 
         out
       end
@@ -54,7 +58,7 @@ module Hecks
       def plain(field)
         return field unless field.is_a?(Hash)
 
-        field.key?(:value) ? field[:value] : field["value"]
+        IndifferentKey.read(field, :value)
       end
     end
   end

data/lib/hecks/quality_control/cli/qa_open_pr.rb

@@ -11,8 +11,8 @@ require_relative "qa_open_pr/recording"
 module Hecks
   module QualityControlCli
     # The command behind `hecks quality_control patch.open`: opens a PR and records it in the
-    # QualityControl ledger in one step. It is the only door into `QualityControl::Patch.Open` and
-    # `QualityControl::Improvement.Open`.
+    # QualityControl ledger in one step. It is the only entry point into
+    # `QualityControl::Patch.Open` and `QualityControl::Improvement.Open`.
     #
     # It refuses (exit 1, nothing opened or recorded) unless the ledger's own `Open` command would
     # take the record and the `GitPr` adapter agrees. The command's `given`s are the rules, asked

data/lib/hecks/quality_control/cli/qa_sweep/checks/shrinking.rb

@@ -10,7 +10,7 @@ module Hecks
           private
 
           # Re-runs only the comparison that surprised; `seat` matters only for `self_consistency`,
-          # which reads the Rust binary's rehydration door under a differential seat.
+          # which reads the Rust binary's rehydration entry point under a differential seat.
           def candidate_divergences(check_mode, seat, steps)
             case check_mode
             when :differential

data/lib/hecks/quality_control/cli/qa_sweep/finding_report.rb

@@ -37,7 +37,7 @@ module Hecks
 
         def print_finding_instructions
           puts "No Bug was logged (that needs a real failing-test demonstration, which"
-          puts "needs judgment this script does not have — hecks quality_control log is the door)"
+          puts "needs judgment this script does not have — hecks quality_control log is the entry point)"
           puts "and the sweep was not concluded. The ledger's own SuspendOnSurprise"
           puts "policy took the target out of the rotation; it stays out until a PERSON"
           puts "runs: hecks quality_control ask run target=#{@target_reference} " \

data/lib/hecks/quality_control/cli/qa_sweep.rb

@@ -130,7 +130,7 @@ module Hecks
         @trace_last = now
       end
 
-      # Default `install_doors` so `QualityControl::Target` and friends are top-level constants.
+      # Default `install_driving` so `QualityControl::Target` and friends are top-level constants.
       def boot_ledger
         Hecks.boot(@domain_dir)
       rescue StandardError => e

data/lib/hecks/quality_control/quality_control.bluebook

@@ -164,7 +164,7 @@ Hecks.bluebook "QualityControl" do
       role "QA engineer"
       goal "Hand a chapter back to the rotation, stamped with when, what this pass was worth, and how the clean streak moves"
 
-      # `now` is the argument and `last_swept` the field, so the door can fill the clock.
+      # `now` is the argument and `last_swept` the field, so the entry point can fill the clock.
       #
       # `next_streak` is the caller's to compute (`clean_streak + 1` if every check held and none
       # was ever surprised, else 0): `Target` cannot read `Sweep` state and no policy payload can
@@ -530,6 +530,7 @@ Hecks.bluebook "QualityControl" do
     end
 
     lifecycle :status, default: "sweeping" do
+      mark :failure, "abandoned"
       transition "Check"    => "sweeping",  from: "sweeping"
       transition "Waive"    => "sweeping",  from: "sweeping"
       transition "Conclude" => "concluded", from: "sweeping"
@@ -778,7 +779,7 @@ Hecks.bluebook "QualityControl" do
       invariant("a bug sequence is positive") { value.positive? }
     end
 
-    # Prefixed on purpose: `Doors::RubyDoor.install` puts every aggregate name on Object, so a
+    # Prefixed on purpose: `Adapters::Driving::Ruby.install` puts every aggregate name on Object, so a
     # value object sharing a word with any aggregate resolves to that class once the other domain
     # boots.
     value_object "BugTitle" do
@@ -1456,6 +1457,7 @@ Hecks.bluebook "QualityControl" do
     # filing. `Submit` is non-creating, so `TicketSubmitted` carries `{ id: ... }`, which a
     # reference slot takes.
     lifecycle :status, default: "raised" do
+      mark :failure, "refused", "abandoned"
       transition "Submit"  => "submitting", from: ["raised", "refused"]
       transition "Filed"   => "filed",      from: "submitting"
       transition "Refused" => "refused",    from: "submitting"
@@ -1866,6 +1868,7 @@ Hecks.bluebook "QualityControl" do
     # proof-only PR can be closed while still "opened" (`retire_if_settled?` hit
     # `LifecycleRefused`).
     lifecycle :status, default: "opened" do
+      mark :failure, "needs_fix"
       transition "Land"    => "landed",   from: ["opened", "needs_fix"]
       transition "Regress" => "needs_fix", from: "landed"
       transition "Merge"   => "merged",   from: ["opened", "landed", "needs_fix"]
@@ -1983,6 +1986,7 @@ Hecks.bluebook "QualityControl" do
     end
 
     lifecycle :status, default: "running" do
+      mark :failure, "red"
       transition "Passed" => "green", from: "running"
       transition "Failed" => "red",   from: "running"
     end

data/lib/hecks/release/approval.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "hecks/vocabulary"
+
+module Hecks
+  module Release
+    # Whether the commit that set the version carries the owner's approval of the release.
+    #
+    # Releases are the owner's decision. A bump on `main` reaches `stable` by itself, so the bump
+    # commit must say, in its message, that a release is wanted: a trailer line named by the
+    # `release_trailer` of the `Lane` row a release is cut from, `Release-Approved-By: <name>`. The
+    # 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
+      module_function
+
+      # @return [String] the trailer key, read from the `Lane` row that feeds a tag
+      # @raise [KeyError] when that row names no trailer
+      def trailer
+        row = Hecks::Vocabulary.rows("Lane").find { |lane| !lane["feeds"].to_s.empty? }
+        key = row && row["release_trailer"].to_s
+        raise KeyError, "the Lane row a release is cut from names no release_trailer" if key.nil? || key.empty?
+
+        key
+      end
+
+      # @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*/, "")
+      end
+
+      # @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
+      # @param explicit [String, nil] a name the owner passed to a by-hand run
+      # @return [Array(Boolean, String)] whether the release may go ahead, and the words to print
+      def verdict(message:, tag_exists: false, explicit: nil)
+        return [true, "approved by #{explicit.strip} (by-hand run)"] unless explicit.to_s.strip.empty?
+        return [true, "the tag already stands; finishing a release that was begun"] if tag_exists
+
+        who = approver(message)
+        return [true, "approved by #{who} (#{trailer} trailer)"] if who
+
+        [false, "the commit that set the version has no '#{trailer}: <name>' line in its message, so it " \
+                "is not a release the owner asked for. Nothing was tagged or pushed. To release it, " \
+                "re-run by hand with the approval: gh workflow run release.yml -f tag=vX.Y.Z -f approved_by=<name>"]
+      end
+
+      # Reads the decision's inputs from the environment `release.yml` gives it.
+      #
+      # @param env [#[]] `COMMIT_MESSAGE`, `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"])
+        out.puts(ok ? "release approval: #{words}" : "::error::#{words}")
+        ok ? 0 : 1
+      end
+    end
+  end
+end

data/lib/hecks/router/{door.rb → aggregate_reader.rb}

@@ -1,12 +1,13 @@
-require_relative "../doors/handle"
+require_relative "../adapters/driving/handle"
 
 module Hecks
   class Router
     class NamespaceInstaller
       # One aggregate's repository and event log, read through its dispatcher.
-      Door = Struct.new(:dispatcher, :domain, :aggregate) do
+      AggregateReader = Struct.new(:dispatcher, :domain, :aggregate) do
         # @param entry [Router::Entry] a router entry
-        # @return [Door, nil] the door for the entry's aggregate; nil for a query/command-only entry
+        # @return [AggregateReader, nil] the reader for the entry's aggregate; nil for a
+        #   query/command-only entry
         #   whose owner isn't a real aggregate root
         def self.for(entry)
           domain = entry.fqn.domain
@@ -29,7 +30,7 @@ module Hecks
         def all = repository.all.map { |instance| handle(instance) }
 
         def handle(instance)
-          Doors::Handle.new(dispatcher: dispatcher, domain: domain, aggregate: aggregate, instance: instance)
+          Adapters::Driving::Handle.new(dispatcher: dispatcher, domain: domain, aggregate: aggregate, instance: instance)
         end
       end
     end

data/lib/hecks/router/namespace_installer.rb

@@ -1,6 +1,6 @@
 require_relative "../fqn"
 require_relative "options_proxy"
-require_relative "door"
+require_relative "aggregate_reader"
 
 module Hecks
   class Router
@@ -12,11 +12,11 @@ module Hecks
       end
 
       # Installs every current-version route as a namespace constant/method, plus
-      # the aggregate CRUD door and short `Aggregate.verb` shortcuts.
+      # the aggregate CRUD module and short `Aggregate.verb` shortcuts.
       def install!
         current_entries.each { |entry| install_namespace_entry(entry) }
         install_shortcuts!
-        install_aggregate_doors!
+        install_aggregate_modules!
         self
       end
 
@@ -48,26 +48,26 @@ module Hecks
       end
 
       # `.find`/`.all`/`.count`/`.events`/`.repository`, matching `Hecks.boot`'s
-      # door; grouped by (realm, domain, aggregate) since the five don't vary by verb.
-      def install_aggregate_doors!
+      # module; grouped by (realm, domain, aggregate) since the five don't vary by verb.
+      def install_aggregate_modules!
         current_entries.reject { |entry| entry.fqn.aggregate.nil? }
                        .group_by { |entry| [entry.fqn.realm, entry.fqn.domain, entry.fqn.aggregate] }
-                       .each_value { |entries| install_aggregate_door(entries.first) }
+                       .each_value { |entries| install_aggregate_module(entries.first) }
       end
 
-      def install_aggregate_door(entry)
-        door = Door.for(entry)
-        return unless door
+      def install_aggregate_module(entry)
+        reader = AggregateReader.for(entry)
+        return unless reader
 
-        define_door_methods(namespace_for(entry.fqn.realm, entry.fqn.domain, entry.fqn.aggregate), door)
+        define_module_methods(namespace_for(entry.fqn.realm, entry.fqn.domain, entry.fqn.aggregate), reader)
       end
 
-      def define_door_methods(target, door)
-        target.define_singleton_method(:repository) { door.repository }
-        target.define_singleton_method(:count)      { door.repository.count }
-        target.define_singleton_method(:events)     { door.events }
-        target.define_singleton_method(:find)       { |id| door.find(id) }
-        target.define_singleton_method(:all)        { door.all }
+      def define_module_methods(target, reader)
+        target.define_singleton_method(:repository) { reader.repository }
+        target.define_singleton_method(:count)      { reader.repository.count }
+        target.define_singleton_method(:events)     { reader.events }
+        target.define_singleton_method(:find)       { |id| reader.find(id) }
+        target.define_singleton_method(:all)        { reader.all }
       end
 
       def install_shortcuts!

data/lib/hecks/router.rb

@@ -1,5 +1,5 @@
 module Hecks
-  # The public, project-wide dispatch door. It owns address resolution only;
+  # The public, project-wide dispatch entry point. It owns address resolution only;
   # each discovered Bluebook keeps its own runtime and persistence bindings.
   class Router
     class UnknownAddress < StandardError; end

data/lib/hecks/runtime/best_effort.rb

@@ -0,0 +1,22 @@
+module Hecks
+  module Runtime
+    # The one place the runtime answers a default when a read raises, so a deliberate guard is
+    # named at its call site and `Hecks/SwallowedRescue` can refuse every other silent swallow.
+    #
+    # BestEffort.call(false) { adapter_class.tenant_capable? }  # => false when the lookup raises
+    module BestEffort
+      module_function
+
+      # Runs the block and answers its value, or `default` when it raises a StandardError.
+      #
+      # @param default [Object] what to answer when the block raises
+      # @yield the read that may raise
+      # @return [Object] the block's value, or `default`
+      def call(default)
+        yield
+      rescue StandardError
+        default
+      end
+    end
+  end
+end