hecks 3.4.2 → 3.6.0

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

@@ -31,15 +31,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)
@@ -94,6 +97,10 @@ module Hecks
         FileUtils.cp(File.join(target_dir, TARGET, "release", "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/site/bluebook/site.bluebook

@@ -99,6 +99,8 @@ Hecks.bluebook "Site" do
     attribute :run,       RunKey
     attribute :out,       Location,  optional: true
     attribute :template,  Location,  optional: true
+    attribute :cms,       Location,  optional: true
+    attribute :root,      Location,  optional: true
     attribute :extension, Extension, optional: true
     attribute :check,     Switch,    optional: true
     attribute :live,      Location,  optional: true
@@ -162,7 +164,7 @@ Hecks.bluebook "Site" do
       transition "Fault"    => "faulted",   from: "requested"
     end
 
-    # `hecks site site_projection.project_site <project> [out=<dir>] [template=<file>] [extension=ts|mts] [--check]`.
+    # `hecks site site_projection.project_site <project> [out=<dir>] [template=<file>] [cms=<dir>] [root=<dir>] [extension=ts|mts] [--check]`.
     # With `check` nothing is written: a routes.ts that differs from the table is faulted, naming the
     # file, so a CI job fails on drift.
     command "ProjectSite" do
@@ -172,6 +174,8 @@ Hecks.bluebook "Site" do
       attribute :run,       RunKey
       attribute :out,       Location,  optional: true
       attribute :template,  Location,  optional: true
+      attribute :cms,       Location,  optional: true
+      attribute :root,      Location,  optional: true
       attribute :extension, Extension, optional: true
       attribute :check,     Switch,    optional: true
 
@@ -179,6 +183,8 @@ Hecks.bluebook "Site" do
       sets :run
       sets :out
       sets :template
+      sets :cms
+      sets :root
       sets :extension
       sets :check
 

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

data/lib/hecks/storehouse/dispatching.rb

@@ -0,0 +1,149 @@
+module Hecks
+  module Storehouse
+    # Issuing commands, singly or as a batch, and describing how to call them. Extended onto
+    # `Storehouse`.
+    module Dispatching
+      # Issues a command, or previews it with dry_run: true.
+      #
+      # @param runtime [Runtime::Registry] the booted domain to dispatch against
+      # @param command [String, Symbol] the command name, bare or qualified
+      # @param summary [String] a one-line audit summary; required
+      # @param args [Hash] the command's arguments, JSON-shaped
+      # @param options [Hash] `source:` a SOURCE_TAGS tag naming the caller; `dry_run:` true to
+      #   preview (a false would_succeed is no failure); `role:` the caller's bound role, nil to
+      #   run unbound; `actor_id:` the caller's identity, which requires role:
+      # @return [Hash] :ok plus :id/:state/:events (real) or :would_succeed/:error
+      #   (dry run); or the refused shape
+      # @raise [ArgumentError] for any other keyword
+      def dispatch(runtime:, command:, summary:, args: {}, **)
+        request = Request.new(runtime: runtime, name: command, summary: summary, args: args, **)
+        request.bluebook = bluebook_for(runtime)
+        audited(request, request.dry_run ? "dry_run" : "dispatch") { perform_dispatch(request) }
+      end
+
+      # :nodoc:
+      def perform_dispatch(request)
+        validate_caller_fields!(request)
+        spec = resolve!(cli_for(request.bluebook), request.name, asking: false)
+        require_caller_for_role_gated!(spec, request.role)
+        envelope = command_envelope(request.args, spec)
+
+        result = with_caller(request.role, request.actor_id) { carry_out(request, spec, envelope) }
+        result.merge(verb: spec[:command])
+      end
+
+      # :nodoc:
+      def command_envelope(args, spec)
+        Doors::CommandRequest.normalize(Doors::JsonDoor.deep_symbolize(args),
+                                        receiver:        spec[:receiver],
+                                        legacy_receiver: spec[:legacy_receiver])
+      end
+
+      # :nodoc:
+      def carry_out(request, spec, envelope)
+        return dry_run_outcome(request.runtime, spec, envelope, summary: request.summary) if request.dry_run
+
+        real_dispatch(request.runtime, spec, envelope, request.summary)
+      end
+
+      # :nodoc:
+      def real_dispatch(runtime, spec, envelope, summary)
+        result = runtime.dispatch_flat(spec[:command], envelope)
+        ok(summary: summary,
+           id:      result.id,
+           state:   settled_state(runtime, spec, result),
+           events:  result.events.map { |event| { name: event.name, payload: Doors::JsonDoor.materialize(event.payload) } })
+      end
+
+      # The record as its repository holds it once every reaction has run, which is the state the
+      # dispatch resulted in; the handle's own state is the record as the command left it, so a run
+      # record that a reaction completes would otherwise read as `requested`. Falls back to the
+      # handle's state for a command that belongs to no top-level aggregate or whose record cannot
+      # be
+      # read.
+      # :nodoc:
+      def settled_state(runtime, spec, result)
+        return if result.state.nil?
+
+        Doors::JsonDoor.materialize(settled_record(runtime, spec, result) || result.state)
+      end
+
+      # :nodoc:
+      def settled_record(runtime, spec, result)
+        bluebook = bluebook_for(runtime)
+        aggregate = top_level_aggregate(bluebook, spec[:command])
+        aggregate && runtime.registry.repository(bluebook.name, aggregate)&.find(result.id)&.to_h
+      end
+
+      # :nodoc:
+      def top_level_aggregate(bluebook, command)
+        head = command.split("::", 2).last
+        return unless head.count(".") == 1
+
+        bluebook.aggregates.find { |candidate| candidate.hecks_name == head.split(".").first }
+      end
+
+      # What a caller needs to call each of the named commands: its qualified name, the role it
+      # declares, what it does, and its argument names, a trailing `*` marking a required one.
+      #
+      # @param runtime [Runtime::Dispatcher] the booted domain
+      # @param names [Array<String>] short or qualified command names
+      # @return [Array<String>] one line per name that resolves, in order
+      def command_guide(runtime, names)
+        cli = cli_for(bluebook_for(runtime))
+        names.filter_map do |name|
+          guide_line(name, resolve!(cli, name.to_s, asking: false))
+        rescue Runtime::NotFound
+          nil
+        end
+      end
+
+      # :nodoc:
+      def guide_line(name, spec)
+        arguments = spec[:arguments].map { |arg| arg[:path].split(".").first + (arg[:required] ? "*" : "") }
+        "#{name} (role #{spec[:role] || "none"}): #{spec[:summary]}. Arguments: #{arguments.uniq.join(", ")}"
+      end
+
+      # :nodoc:
+      def dry_run_outcome(runtime, spec, envelope, summary:)
+        flat = flatten_legacy(envelope, spec[:receiver], spec[:legacy_receiver])
+        runtime.dry_run?(spec[:command], **flat)
+        ok(summary: summary, would_succeed: true)
+      rescue Runtime::WiringError, *Runtime::DOMAIN_REFUSALS => e
+        ok(summary: summary, would_succeed: false, error: e.message)
+      end
+
+      # Dispatches a sequence of commands as one call, through dispatch itself: same audit log
+      # line per step. Runs every step even after a refusal, since a later step naming a
+      # since-refused record refuses honestly on its own.
+      #
+      # @param runtime [Runtime::Registry] the booted domain to dispatch against
+      # @param steps [Array<Hash>] each step's command/args, JSON-shaped
+      # @param summary [String] a one-line audit summary; required
+      # @param options [Hash] `source:`, a SOURCE_TAGS tag naming who is calling; `role:`, the
+      #   caller's bound role, or nil to run unbound; `actor_id:`, the caller's identity, which
+      #   requires role:
+      # @return [Hash] :ok (true only if every step's own :ok was true), :results
+      # @raise [ArgumentError] for any other keyword
+      def dispatch_batch(runtime:, steps:, summary:, **options)
+        check_options!(options, %i[source role actor_id])
+        run_batch(runtime, steps, summary, options)
+      end
+
+      # :nodoc:
+      def run_batch(runtime, steps, summary, options)
+        require_summary!(summary)
+        results = Array(steps).map { |raw| batch_step(runtime, raw, summary, options) }
+        { ok: results.all? { |r| r[:ok] }, summary: summary, results: results }
+      rescue *refusal_classes => e
+        refused(e, summary: summary)
+      end
+
+      # :nodoc:
+      def batch_step(runtime, raw, summary, options)
+        step = Doors::JsonDoor.deep_symbolize(raw)
+        dispatch(runtime: runtime, command: step[:command], args: step[:args] || {}, summary: summary, **options)
+      end
+    end
+  end
+end