hecks 3.5.0 → 3.7.0

data/lib/hecks/rust_build/project_rust/target_ir.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module RustBuild
+    class ProjectRust
+      # The target domain's IR, with the binding facts that ride beside it (they are not shape
+      # facts, so `bluebook.to_h` never mentions them).
+      class TargetIr
+        # The optional attachments `rust/host` reads from `ir.json`, each omitted when nothing
+        # attached provides it: exporter method, then the key it is written under.
+        SEAMS = %i[authorization membership identity newsletter newsletter_issues payments
+                   registrations payment_connection].freeze
+
+        # Round-trips a value through JSON so generators see the string-keyed shape a real
+        # `ir.json` carries, never live Ruby symbols.
+        #
+        # @param payload [Object] a JSON-compatible value
+        # @return [Object] the same value with symbol keys, as parsed from JSON
+        def self.json_shaped(payload) = JSON.parse(JSON.generate(payload), symbolize_names: true)
+
+        # @param registry [Hecks::Runtime::Registry] the loaded registry
+        # @param domain_name [String] the target bluebook's name
+        # @param bluebook_dir [String] the target's `bluebook/` directory
+        def initialize(registry, domain_name, bluebook_dir)
+          @registry = registry
+          @domain_name = domain_name
+          @bluebook_dir = bluebook_dir
+        end
+
+        # @return [Hash{Symbol => Object}] the IR the generator reads
+        # @raise [Failure] when the domain provides membership but not identity
+        def call
+          exporter = Hecks::Projector::Exporter
+          ir = shaped(exporter.call(@registry).fetch(@domain_name))
+          ir[:lineage] = shaped(exporter.lineage(@registry, @domain_name))
+          ir[:persistence] = shaped(exporter.persistence(@registry, @domain_name))
+          add_seams(ir, exporter)
+          add_edges_and_source(ir)
+          ir
+        end
+
+        private
+
+        def shaped(payload) = self.class.json_shaped(payload)
+
+        def add_seams(document, exporter)
+          seams = SEAMS.to_h { |seam| [seam, exporter.public_send(seam, @registry, @domain_name)] }
+          seams.each { |seam, value| document[seam] = shaped(value) unless value.empty? }
+          return unless !seams[:membership].empty? && seams[:identity].empty?
+
+          raise Failure, "#{@domain_name} provides membership but not identity — rust/host Google sign-in " \
+                         "cannot register or link an identity from ir.json. Attach Identity " \
+                         "(`attaches \"Identity\"` plus a sibling Hecks.hecksagon \"Identity\") so the " \
+                         "hecksagon, not a deploy-time guess, names the identity verbs."
+        end
+
+        # Edges carry their own precompiled SQL, so a boot-time mint only executes it. Committed
+        # approvals sit beside the edges. The source text is verbatim: the era's integrity digest is
+        # the SHA256 of it, not of anything re-derived from the parsed IR.
+        def add_edges_and_source(document)
+          edges = Hecks::Projector::Exporter.translations(@registry).select { |edge| edge[:domain] == @domain_name }
+          document[:translations] = shaped(edges)
+          approvals = Hecks::Translation::ApprovalFile.read_all(@bluebook_dir)
+          document[:approvals] = shaped(approvals) unless approvals.empty?
+          document[:source_text] = Hecks::Runtime::EraCheck.source_text_for(
+            @registry.bluebooks.fetch(@domain_name), @bluebook_dir, registry: @registry
+          )
+        end
+      end
+    end
+  end
+end

data/lib/hecks/rust_build/project_rust.rb

@@ -22,11 +22,6 @@ module Hecks
     # The era plugin is required unconditionally so the generator works for any domain, lineage
     # capable or not; `pg` stays lazy inside it, so nothing here opens a database connection.
     class ProjectRust
-      # The optional attachments `rust/host` reads from `ir.json`, each omitted when nothing
-      # attached provides it: exporter method, then the key it is written under.
-      SEAMS = %i[authorization membership identity newsletter newsletter_issues payments
-                 registrations payment_connection].freeze
-
       # @param argv [Array<String>] the domain's directory
       # @return [Integer] the exit status
       # @raise [Failure] when the domain's name cannot be a Rust module and Cargo feature name
@@ -59,110 +54,45 @@ module Hecks
                        "be used as-is — it has to double as a Rust module identifier and a Cargo feature " \
                        "name, and this one is either not a plain lowercase identifier, is a Rust keyword, " \
                        "or collides with a reserved Cargo.toml key " \
-                       "(#{DomainName::CARGO_RESERVED.join(', ')}). " \
+                       "(#{DomainName::CARGO_RESERVED.join(", ")}). " \
                        "Rename the domain directory."
       end
 
       def generate
-        load_registry
-        @rust_dir = ENV.fetch("HECKS_RUST_DIR", File.join(RustBuild::ROOT, "rust"))
-        @out_root = File.join(@rust_dir, "src/generated")
-        FileUtils.mkdir_p(@out_root)
-        build_target_ir
+        loader = DomainLoader.new(@domain).call
+        @registry = loader.registry
+        @domain_name = loader.domain_name
+        prepare_output
+        @ir = TargetIr.new(@registry, @domain_name, loader.bluebook_dir).call
         FileUtils.rm_rf(File.join(@out_root, "active"))
         generate_with_codegen
         write_root_mod
         sync_cargo_features
       end
 
+      def prepare_output
+        @rust_dir = ENV.fetch("HECKS_RUST_DIR", File.join(RustBuild::ROOT, "rust"))
+        @out_root = File.join(@rust_dir, "src/generated")
+        FileUtils.mkdir_p(@out_root)
+      end
+
       # `hecks-codegen` is the generator; this process only builds the IR it reads from the live
       # registry, so a domain's persistence, seams, translations and source text reach `ir.json`.
       def generate_with_codegen
         meta = Hecks::Projector::Exporter.call(Hecks::Bluebook::MetaValidator.grammar_registry).fetch("Bluebook")
-        vendored = @registry.hecksagons.values.flat_map(&:vendored_packages)
-        chapters = (@registry.bluebooks.keys - [@domain_name]).map do |name|
-          ir = Hecks::Projector::Exporter.call(@registry).fetch(name)
-          CodegenRun::Chapter.new(name.downcase, "#{@domain} (#{attachment(name, vendored)})", json_shaped(ir))
-        end
         CodegenRun.new(
-          rust_dir: @rust_dir, out_root: @out_root, meta: json_shaped(meta), chapters: chapters,
+          rust_dir: @rust_dir, out_root: @out_root, meta: TargetIr.json_shaped(meta), chapters: chapters,
           target: CodegenRun::Chapter.new(@mod_name, @domain, @ir)
         ).call
       end
 
-      # Round-trips a value through JSON so generators see the string-keyed shape a real `ir.json`
-      # carries, never live Ruby symbols.
-      def json_shaped(payload) = JSON.parse(JSON.generate(payload), symbolize_names: true)
-
-      # `root:` is the domain's own directory: a domain that declares `attaches ... from: :vendor`
-      # resolves its vendored chapters beneath it.
-      def load_registry
-        @registry = Hecks::Runtime::Registry.new(root: File.expand_path(@domain))
-        Hecks.with_registry(@registry) do
-          lib = File.expand_path("..", __dir__)
-          %w[ports/persistence.port ports/extraction.port adapters/driven/memory.adapter
-             adapters/driven/prism.adapter adapters/driven/postgres_era.adapter].each do |file|
-            Kernel.load(File.join(lib, file))
-          end
-          @bluebook_dir = File.join(@domain, "bluebook")
-          Hecks::Adapters::Folder.new.load_bluebooks(@bluebook_dir)
-          load_siblings
-          load_environment
-        end
-        @domain_name = @registry.bluebooks.keys.first
-      end
-
-      # Translation edges, hecksagons (whose `attaches` loads a framework chapter into the
-      # same registry) and worlds (whose `default_adapter` binds what a hecksagon leaves out), in
-      # the order the language loads them.
-      def load_siblings
-        Dir[File.join(@bluebook_dir, "translations", "*.bluebook")].each { |file| Kernel.load(file) }
-        Dir.glob(File.join(@bluebook_dir, "*.hecksagon")).each { |file| Kernel.load(file) }
-        Dir.glob(File.join(@bluebook_dir, "*.world")).each { |file| Kernel.load(file) }
-      end
-
-      # Production is the default environment when `environments/production.hecksagon` exists
-      # (`rust/host` is the production runtime); `HECKS_PROJECT_ENVIRONMENT` overrides it.
-      def load_environment
-        environment = ENV.fetch("HECKS_PROJECT_ENVIRONMENT") do
-          File.exist?(File.join(@bluebook_dir, "environments", "production.hecksagon")) ? "production" : nil
-        end
-        return if environment.nil? || environment.empty?
-
-        folder = Hecks::Adapters::Folder.new
-        folder.load_each(@bluebook_dir, [File.join("environments", "#{environment}.hecksagon")])
-        folder.load_each(@bluebook_dir, [File.join("environments", "#{environment}.world")])
-      end
-
-      # The target's IR, with the binding facts that ride beside it (they are not shape facts, so
-      # `bluebook.to_h` never mentions them).
-      def build_target_ir
-        exporter = Hecks::Projector::Exporter
-        @ir = json_shaped(exporter.call(@registry).fetch(@domain_name))
-        @ir[:lineage] = json_shaped(exporter.lineage(@registry, @domain_name))
-        @ir[:persistence] = json_shaped(exporter.persistence(@registry, @domain_name))
-        seams = SEAMS.to_h { |seam| [seam, exporter.public_send(seam, @registry, @domain_name)] }
-        seams.each { |seam, value| @ir[seam] = json_shaped(value) unless value.empty? }
-        if !seams[:membership].empty? && seams[:identity].empty?
-          raise Failure, "#{@domain_name} provides membership but not identity — rust/host Google sign-in " \
-                         "cannot register or link an identity from ir.json. Attach Identity " \
-                         "(`attaches \"Identity\"` plus a sibling Hecks.hecksagon \"Identity\") so the " \
-                         "hecksagon, not a deploy-time guess, names the identity verbs."
+      def chapters
+        vendored = @registry.hecksagons.values.flat_map(&:vendored_packages)
+        (@registry.bluebooks.keys - [@domain_name]).map do |name|
+          ir = Hecks::Projector::Exporter.call(@registry).fetch(name)
+          label = "#{@domain} (#{attachment(name, vendored)})"
+          CodegenRun::Chapter.new(name.downcase, label, TargetIr.json_shaped(ir))
         end
-        add_edges_and_source
-      end
-
-      # Edges carry their own precompiled SQL, so a boot-time mint only executes it. Committed
-      # approvals sit beside the edges. The source text is verbatim: the era's integrity digest is
-      # the SHA256 of it, not of anything re-derived from the parsed IR.
-      def add_edges_and_source
-        edges = Hecks::Projector::Exporter.translations(@registry).select { |edge| edge[:domain] == @domain_name }
-        @ir[:translations] = json_shaped(edges)
-        approvals = Hecks::Translation::ApprovalFile.read_all(@bluebook_dir)
-        @ir[:approvals] = json_shaped(approvals) unless approvals.empty?
-        @ir[:source_text] = Hecks::Runtime::EraCheck.source_text_for(
-          @registry.bluebooks.fetch(@domain_name), @bluebook_dir, registry: @registry
-        )
       end
 
       # How the target attached a chapter, across every hecksagon the registry loaded: a chapter a
@@ -230,3 +160,5 @@ end
 
 require_relative "project_rust/root_mod"
 require_relative "project_rust/codegen_run"
+require_relative "project_rust/domain_loader"
+require_relative "project_rust/target_ir"

data/lib/hecks/rust_build/wasm.rb

@@ -15,10 +15,15 @@ module Hecks
     # `wasmtime run rust/dist/<domain>.wasm < script.json`, and the domain's `ir.json` beside it,
     # which `rust/host` reads at runtime. `HECKS_RUST_DIR` names the workspace to build in and
     # `CARGO_TARGET_DIR` where build output goes, beside the workspace by default.
+    # `HECKS_WASM_PROFILE=dev` builds without `--release`: a much faster compile, for tests that
+    # only run the module, not for one that ships.
     module Wasm
       # The Cargo target the module is built for.
       TARGET = "wasm32-wasip1"
 
+      # The Cargo flags and the `target/<target>/` directory of each build profile.
+      PROFILES = { "release" => { flags: ["--release"], dir: "release" }, "dev" => { flags: [], dir: "debug" } }.freeze
+
       module_function
 
       # @param argv [Array<String>] the domain's directory
@@ -31,15 +36,18 @@ module Hecks
         require_target!
         rust_dir = RustBuild.rust_dir
         scratch = scratch_copy(rust_dir)
-        puts "== regenerating #{scratch}/src/generated/ for #{domain} =="
-        status = RustBuild.with_env("HECKS_RUST_DIR" => scratch) { ProjectRust.call([domain]) }
-        raise Failure, "project_rust failed for #{domain}" unless status.zero?
-
+        regenerate(scratch, domain)
         compile(scratch)
         publish(scratch, rust_dir, File.basename(domain))
         0
       end
 
+      def regenerate(scratch, domain)
+        puts "== regenerating #{scratch}/src/generated/ for #{domain} =="
+        status = RustBuild.with_env("HECKS_RUST_DIR" => scratch) { ProjectRust.call([domain]) }
+        raise Failure, "project_rust failed for #{domain}" unless status.zero?
+      end
+
       # With the Rust parser and codegen, `hecks-build` runs the same steps and writes the same
       # outputs.
       def build_with_rust(domain)
@@ -80,20 +88,32 @@ module Hecks
       # `rustup run`, not bare `cargo`: a `cargo` earlier on PATH may never have seen
       # `rustup target add` and fail with "can't find crate for `std`".
       def compile(scratch)
-        puts "== cargo build --release --target #{TARGET} =="
+        flags = profile.fetch(:flags)
+        puts "== cargo build #{flags.join(" ")} --target #{TARGET} =="
         target_dir = ENV.fetch("CARGO_TARGET_DIR", File.join(RustBuild.rust_dir, "target"))
-        RustBuild.command!("rustup", "run", "stable", "cargo", "build", "--release", "--target", TARGET,
+        RustBuild.command!("rustup", "run", "stable", "cargo", "build", *flags, "--target", TARGET,
                            chdir: scratch, env: { "CARGO_TARGET_DIR" => target_dir })
       end
 
+      # @return [Hash] the flags and directory of the profile `HECKS_WASM_PROFILE` names
+      # @raise [Failure] when the name is not `release` or `dev`
+      def profile
+        name = ENV.fetch("HECKS_WASM_PROFILE", "release")
+        PROFILES.fetch(name) { raise Failure, "HECKS_WASM_PROFILE=#{name} is not release or dev" }
+      end
+
       def publish(scratch, rust_dir, name)
         dist = File.join(rust_dir, "dist")
         FileUtils.mkdir_p(dist)
         target_dir = ENV.fetch("CARGO_TARGET_DIR", File.join(rust_dir, "target"))
         out = File.join(dist, "#{name}.wasm")
-        FileUtils.cp(File.join(target_dir, TARGET, "release", "rust.wasm"), out)
+        FileUtils.cp(File.join(target_dir, TARGET, profile.fetch(:dir), "rust.wasm"), out)
         puts "wrote #{out}"
         puts %(run it: wasmtime run #{out} < script.json)
+        publish_sidecar(scratch, dist, name)
+      end
+
+      def publish_sidecar(scratch, dist, name)
         sidecar = File.join(scratch, "src", "generated", name, "ir.json")
         return unless File.exist?(sidecar)
 

data/lib/hecks/rust_build/wasm_browser.rb

@@ -29,16 +29,12 @@ module Hecks
         domain = argv.first or raise Failure, "usage: hecks build_browser_wasm <domain>"
         rust_dir = RustBuild.rust_dir
         web_dir = File.join(rust_dir, "web")
-        name = File.basename(domain)
         require_target!
         require_cli!(web_dir)
         scratch = scratch_copy(rust_dir)
-        puts "== regenerating #{scratch}/src/generated/ for #{domain} =="
-        status = RustBuild.with_env("HECKS_RUST_DIR" => scratch) { ProjectRust.call([domain]) }
-        raise Failure, "project_rust failed for #{domain}" unless status.zero?
-
+        Wasm.regenerate(scratch, domain)
         compile(File.join(scratch, "web"), web_dir)
-        bind(web_dir, name)
+        bind(web_dir, File.basename(domain))
         0
       end
 
@@ -99,7 +95,11 @@ module Hecks
         puts "== wasm-bindgen --target web =="
         RustBuild.command!("wasm-bindgen", "--target", "web", "--out-dir", out_dir, "--out-name", name, built)
         puts "wrote #{out_dir}/"
-        puts <<~MSG
+        puts browser_usage(name)
+      end
+
+      def browser_usage(name)
+        <<~MSG
           use it in a browser:
               <script type="module">
                 import init, { dispatch } from "./#{name}.js";

data/lib/hecks/rust_build/write_if_changed.rb

@@ -71,12 +71,9 @@ module Hecks
         tmp = "#{path}.tmp-#{Process.pid}-#{rand(1_000_000)}"
         begin
           File.open(tmp, "w", &)
-          if File.exist?(path) && FileUtils.compare_file(tmp, path)
-            false
-          else
-            FileUtils.mv(tmp, path)
-            true
-          end
+          changed = !(File.exist?(path) && FileUtils.compare_file(tmp, path))
+          FileUtils.mv(tmp, path) if changed
+          changed
         ensure
           FileUtils.rm_f(tmp)
         end

data/lib/hecks/rust_build.rb

@@ -80,7 +80,7 @@ module Hecks
         options[:chdir] = chdir if chdir
         return if system(env, *command, **options)
 
-        raise Failure, "`#{command.join(' ')}` failed#{" in #{chdir}" if chdir}"
+        raise Failure, "`#{command.join(" ")}` failed#{" in #{chdir}" if chdir}"
       end
 
       # Runs a tool and holds what it printed.
@@ -127,10 +127,14 @@ module Hecks
         $stdout, $stderr = saved
       end
 
-      def finish(tool, argv)
+      def load_tool(tool)
         file, constant = TOOLS.fetch(tool)
         require_relative file
-        RustBuild.const_get(constant).call(argv)
+        RustBuild.const_get(constant)
+      end
+
+      def finish(tool, argv)
+        load_tool(tool).call(argv)
       rescue Failure => e
         warn e.message
         1

data/lib/hecks/storehouse/audit.rb

@@ -0,0 +1,106 @@
+module Hecks
+  module Storehouse
+    # The bus's own JSONL audit log: writing a line for each dispatch, query and state call, and
+    # reading it back as a tail or as the events it announced. Extended onto `Storehouse`.
+    module Audit
+      # The caller-supplied fields of an audit line, in the order the line spells them.
+      AUDIT_FIELDS = %i[verb summary source role actor_id].freeze
+
+      # Kept under Hecks::CacheDir, not the domain directory (part of the domain's
+      # own state) or the gem directory (read-only once installed).
+      # :nodoc:
+      def log_root = Hecks::CacheDir.path("storehouse")
+
+      # :nodoc:
+      def log_path(domain_name)
+        File.join(log_root, "#{domain_name.to_s.gsub(/[^A-Za-z0-9_-]/, "_")}.jsonl")
+      end
+
+      # Never fails a real call because its own audit log couldn't be written —
+      # a full disk silences follow, not the dispatch/query/state call itself.
+      #
+      # @param entry [Hash] the line's `verb:`, `summary:`, `source:`, `role:` and `actor_id:`
+      # :nodoc:
+      def record!(domain_name, tool:, outcome:, **entry)
+        return unless domain_name
+
+        line = { time: Time.now.utc.iso8601, tool: tool }.merge(AUDIT_FIELDS.to_h { |field| [field, entry[field]] })
+                                                         .merge(outcome.slice(:ok, :id, :error, :events)).compact
+        FileUtils.mkdir_p(log_root)
+        File.open(log_path(domain_name), "a") { |f| f.puts(JSON.generate(line)) }
+      rescue StandardError
+        nil
+      end
+
+      # Tails this bus's own dispatch/query/state audit log — a pull-based
+      # substitute for a push subscription, since a stdio door answers one
+      # request at a time with no channel to push through.
+      #
+      # @param runtime [Runtime::Registry] the booted domain to tail
+      # @param limit [Integer, #to_i] how many recent log entries to return
+      # @return [Hash] :ok, :domain, :entries; or the refused shape
+      def follow(runtime:, limit: 20)
+        bluebook = bluebook_for(runtime)
+        entries  = log_lines(bluebook.name).last([limit.to_i, 1].max)
+
+        ok(domain: bluebook.name, entries: entries)
+      rescue *refusal_classes => e
+        refused(e)
+      end
+
+      # :nodoc:
+      def log_lines(domain_name)
+        path = log_path(domain_name)
+        return [] unless File.exist?(path)
+
+        File.readlines(path).map { |line| JSON.parse(line, symbolize_names: true) }
+      end
+
+      # What actually happened, with payloads, to one aggregate or record — read
+      # off this bus's own audit log (a dispatch's announced events), not a full
+      # event-sourcing replay. aggregate: narrows the search; id: (requires
+      # aggregate:) narrows further to one record.
+      #
+      # @param runtime [Runtime::Registry] the booted domain to search
+      # @param aggregate [String, Symbol, nil] narrows the search to one aggregate
+      # @param id [String, Object, nil] narrows further to one record; requires aggregate
+      # @param limit [Integer, #to_i, nil] how many recent matching events to
+      #   return; nil returns every one found
+      # @return [Hash] :ok, :domain, :events; or the refused shape
+      # @raise [Runtime::TypeMismatch] if id is given without aggregate
+      def events(runtime:, aggregate: nil, id: nil, limit: nil)
+        if id && !aggregate
+          raise Runtime::TypeMismatch, "id: requires aggregate: too — an id alone is not unique across aggregates"
+        end
+
+        bluebook = bluebook_for(runtime)
+        fqn      = aggregate ? "#{bluebook.name}::#{aggregate_ir!(bluebook, aggregate).hecks_name}" : nil
+
+        ok(domain: bluebook.name, events: matching_events(bluebook, fqn, id, limit))
+      rescue *refusal_classes => e
+        refused(e)
+      end
+
+      # :nodoc:
+      def matching_events(bluebook, fqn, id, limit)
+        found = log_lines(bluebook.name).filter_map { |entry| entry_events(entry, fqn, id) }.flatten(1)
+        limit ? found.last(limit.to_i) : found
+      end
+
+      # :nodoc:
+      def entry_events(entry, fqn, id)
+        return unless entry[:tool] == "dispatch" && entry[:ok] && entry[:events]
+        return unless targets?(entry, fqn, id)
+
+        entry[:events].map { |event| event.merge(time: entry[:time], verb: entry[:verb], id: entry[:id]) }
+      end
+
+      # @return [Boolean] whether the audit entry is about the aggregate and record asked for
+      def targets?(entry, fqn, id)
+        return false if fqn && !entry[:verb].to_s.start_with?("#{fqn}.")
+
+        !(id && entry[:id] != id)
+      end
+    end
+  end
+end

data/lib/hecks/storehouse/callers.rb

@@ -0,0 +1,73 @@
+module Hecks
+  module Storehouse
+    # The checks on who is calling and what a call may carry: its options, summary, source and
+    # role. Extended onto `Storehouse`.
+    module Callers
+      # Refuses an option a call does not take, as a method without that keyword would.
+      #
+      # @param options [Hash] the keywords the caller passed
+      # @param allowed [Array<Symbol>] the keywords the call takes
+      # @raise [ArgumentError] naming the first one not in `allowed`
+      # :nodoc:
+      def check_options!(options, allowed)
+        unknown = options.keys - allowed
+        raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?
+      end
+
+      # The checks every dispatch and query makes before it reads anything: a summary, a known
+      # source,
+      # and a role to go with an actor.
+      # :nodoc:
+      def validate_caller_fields!(request)
+        require_summary!(request.summary)
+        valid_source!(request.source)
+        valid_caller!(request.role, request.actor_id)
+      end
+
+      # Required on dispatch/query/state: what makes an audit row legible later.
+      # :nodoc:
+      def require_summary!(summary)
+        return unless summary.nil? || summary.to_s.strip.empty?
+
+        raise Runtime::TypeMismatch,
+              "a one-line summary: is required on dispatch/query/state — it is what makes an audit row legible later"
+      end
+
+      # :nodoc:
+      def valid_source!(source)
+        return if source.nil? || SOURCE_TAGS.include?(source.to_s)
+
+        raise Runtime::TypeMismatch, "source: #{source.inspect} is not one of #{SOURCE_TAGS.join(", ")}"
+      end
+
+      # actor_id without role would silently bind nothing rather than a real
+      # caller — refusing here beats a caller thinking it identified itself.
+      # :nodoc:
+      def valid_caller!(role, actor_id)
+        return unless actor_id && role.nil?
+
+        raise Runtime::TypeMismatch, "actor_id: requires role: too — a caller names WHO through WHICH role they hold"
+      end
+
+      # Binds role/actor_id for the block's duration via Hecks.as_caller; role: nil
+      # runs the block unbound (query's own authorization does not depend on it).
+      # :nodoc:
+      def with_caller(role, actor_id, &)
+        return yield if role.nil?
+
+        Hecks.as_caller(role: role, actor_id: actor_id, &)
+      end
+
+      # A caller who omits role: would otherwise reach a role-gated command
+      # unchecked (refuse_role_mismatch no-ops with no bound caller) — refuse here instead.
+      # :nodoc:
+      def require_caller_for_role_gated!(spec, role)
+        return unless spec[:role_gated] && role.nil?
+
+        raise Runtime::Unauthorized,
+              "#{spec[:command]} requires role: #{spec[:role].inspect} — this command is role-gated and no caller " \
+              "(role:/actor_id:) is bound; dispatching it unbound is refused, not silently unchecked"
+      end
+    end
+  end
+end