hecks 5.0.0 → 7.0.0

data/lib/hecks/shape_ledger.rb

@@ -0,0 +1,194 @@
+require "json"
+require "hecks"
+require_relative "ports/persistence/plugins/era/era_check"
+require_relative "shape_ledger/scope"
+require_relative "shape_ledger/status"
+require_relative "shape_ledger/edge_hygiene"
+
+module Hecks
+  # The committed record of each bluebook's storage shape, held against the shapes the bluebooks
+  # have now, so a shape cannot change without the translation edge that carries a database across.
+  #
+  # A database that holds an era refuses a newer shape no edge leads to. The check that catches
+  # that at a boot only runs against a real database, which specs and gates do not use, so this one
+  # reads nothing but the loaded bluebooks and the committed edges: it needs no database.
+  #
+  # It holds only a bluebook whose committed persistence is an era adapter, or a framework member
+  # that clients persist (see `Scope`); tooling is Memory and needs no entry.
+  #
+  # @example
+  #   ShapeLedger.check("lib/hecks/hecks")  # => "1 bluebook shapes, each ..."
+  module ShapeLedger
+    # The ledger file, beside the bluebooks it records.
+    FILE = "shapes.json".freeze
+
+    # The record beside the ledger of each implicit move: a shape change that carried no edge file
+    # and was settled with `--confirm --additive`. Each bluebook maps to its `{from, to}` moves.
+    IMPLICIT_FILE = "implicit_moves.json".freeze
+
+    # The length of the label a translation edge names a shape by.
+    LABEL = 6
+
+    # What a problem line tells the reader to do.
+    REWRITE = "rewrite the ledger with `hecks conformance_run.check_shape_ledger! --confirm --wait`".freeze
+
+    # Raised with every problem found, or when the ledger cannot be rewritten.
+    class Failure < StandardError; end
+
+    module_function
+
+    # Compares the ledger with the shapes of the bluebooks under a directory.
+    #
+    # @param directory [String] the domain directory whose bluebooks the ledger records
+    # @param confirm [Boolean] rewrite the ledger when every moved shape has an edge
+    # @param additive [Boolean] with `confirm`, move the ledger for each shape that moved with no
+    #   edge, on the operator's word that the change only adds. No edge file is written: the boot
+    #   and the mint treat such a move as an implicit empty edge, and the mint refuses any change
+    #   the scaffold does not find to be additive
+    # @return [String] the clean verdict, or what was written
+    # @raise [Failure] with each problem
+    def check(directory, confirm: false, additive: false)
+      registry = Scope.committed_registry(directory)
+      path = File.join(directory, FILE)
+      shapes, ledger, skipped = Scope.view(registry, path)
+      moves = implicit_moves(implicit_path(path))
+      edges = with_implicit(edges_of(registry), moves)
+      return rewrite(path, ledger, shapes, edges, additive) if confirm
+
+      verdict(ledger, shapes, edges) + Scope.note(skipped) +
+        EdgeHygiene.report(directory, ledger: ledger, shapes: shapes, moves: moves)
+    end
+
+    # @param registry [Runtime::Registry] the loaded bluebooks
+    # @return [Hash{String => String}] each bluebook's storage-shape hash, by name
+    def shapes_of(registry)
+      registry.bluebooks.to_h { |name, bluebook| [name, Runtime::StorageShape.mint_hash(bluebook)] }
+    end
+
+    # @param registry [Runtime::Registry] the loaded bluebooks
+    # @return [Hash{String => Array<Array(String, String)>}] each bluebook's edges as `[from, to]`
+    def edges_of(registry)
+      registry.translations.group_by(&:domain).transform_values { |edges| pairs(edges) }
+    end
+
+    def pairs(edges) = edges.map { |edge| [edge.from, edge.to] }
+
+    # @return [Hash{String => Array<Array(String, String)>}] `edges` with each recorded implicit
+    #   move added as an edge: the boot and the mint read a recorded move as an empty edge
+    def with_implicit(edges, record)
+      record.each_with_object(edges.dup) do |(name, moves), merged|
+        merged[name] = merged.fetch(name, []) + pairs_of(moves)
+      end
+    end
+
+    # @param moves [Array<Hash>] recorded `{"from" => ..., "to" => ...}` moves
+    # @return [Array<Array(String, String)>] the moves as `[from, to]`
+    def pairs_of(moves) = moves.map { |move| [move["from"], move["to"]] }
+
+    def label(hash) = hash.to_s[0, LABEL]
+
+    # @return [Boolean] whether a chain of edges leads from one label to another
+    def reachable?(from, to, edges)
+      seen = [from]
+      queue = [from]
+      queue.concat(next_labels(queue.shift, edges, seen)) until queue.empty? || seen.include?(to)
+      seen.include?(to)
+    end
+
+    def next_labels(at, edges, seen)
+      fresh = edges.filter_map { |from, to| to if from == at && !seen.include?(to) }
+      seen.concat(fresh)
+      fresh
+    end
+
+    def verdict(ledger, shapes, edges)
+      problems = problems(ledger, shapes, edges)
+      raise Failure, problems.join("\n") unless problems.empty?
+
+      "#{shapes.size} bluebook shapes, each the one the ledger holds"
+    end
+
+    # @return [Array<String>] one line per bluebook whose shape disagrees with the ledger
+    def problems(ledger, shapes, edges)
+      moved = shapes.filter_map { |name, now| problem(name, ledger[name], now, edges.fetch(name, [])) }
+      moved + (ledger.keys - shapes.keys).map { |name| "#{name}: in the ledger but no longer loaded; #{REWRITE}" }
+    end
+
+    def problem(name, held, now, edges)
+      return "#{name}: not in the ledger (shape #{label(now)}); #{REWRITE}" unless held
+      return nil if label(held) == label(now)
+
+      change = "#{name}: the shape moved #{label(held)} -> #{label(now)}"
+      return "#{change}, and an edge covers it; #{REWRITE}" if reachable?(label(held), label(now), edges)
+
+      "#{change} with no translation edge from #{label(held)}; #{edge_advice(name, label(held), label(now))}"
+    end
+
+    # What to commit: the empty edge covers a change that only adds, and a change that renames or
+    # reshapes data needs the rules the scaffold writes from the database that holds the eras.
+    def edge_advice(name, from, now)
+      "#{name} moved with no edge. A change that only adds needs no edge file: settle it in one step " \
+        "with `hecks conformance_run.check_shape_ledger! --confirm --additive --wait`, which the boot and " \
+        "the mint treat as an implicit empty edge from #{from} to #{now}. Data that is renamed or reshaped " \
+        "needs rules: `hecks query era.scaffold_translation domain.value=<directory>` writes them, reading " \
+        "the eras from the database the domain's own world names."
+    end
+
+    def rewrite(path, ledger, shapes, edges, additive)
+      implicit = additive ? uncovered_moves(ledger, shapes, edges) : []
+      uncovered = additive ? [] : problems(ledger, shapes, edges).reject { |line| line.include?(REWRITE) }
+      raise Failure, uncovered.join("\n") unless uncovered.empty?
+
+      File.write(path, "#{JSON.pretty_generate(shapes.sort.to_h)}\n")
+      record_implicit(implicit_path(path), implicit)
+      "wrote #{shapes.size} bluebook shapes to #{path}#{implicit_note(implicit)}"
+    end
+
+    # Appends each implicit move to the record, once: a move the record already holds is skipped.
+    #
+    # @param path [String] the record file beside the ledger
+    # @param moves [Array<Array(String, String, String)>] `[bluebook, from, to]` for each move
+    # @return [void]
+    def record_implicit(path, moves)
+      return if moves.empty?
+
+      record = implicit_moves(path)
+      moves.each { |name, from, now| append_move(record, name, { "from" => from, "to" => now }) }
+      File.write(path, "#{JSON.pretty_generate(record.sort.to_h)}\n")
+    end
+
+    def append_move(record, name, move)
+      entries = record.fetch(name, [])
+      record[name] = entries.include?(move) ? entries : entries + [move]
+    end
+
+    def implicit_path(path) = File.join(File.dirname(path), IMPLICIT_FILE)
+
+    def implicit_note(moves)
+      return "" if moves.empty?
+
+      named = moves.map { |name, from, now| "#{name} #{from} -> #{now}" }
+      " and #{moves.size} implicit move(s), no edge file: #{named.join(", ")}"
+    end
+
+    # @return [Array<Array(String, String, String)>] `[bluebook, from, to]` for each shape that
+    #   moved
+    #   with no chain of edges leading to it
+    def uncovered_moves(ledger, shapes, edges)
+      shapes.filter_map do |name, now|
+        held = ledger[name]
+        next unless held && label(held) != label(now)
+        next if reachable?(label(held), label(now), edges.fetch(name, []))
+
+        [name, label(held), label(now)]
+      end
+    end
+
+    # @return [Hash{String => String}] the ledger, empty when there is none yet
+    def read(path) = File.exist?(path) ? JSON.parse(File.read(path)) : {}
+
+    # @param path [String] the implicit-move record
+    # @return [Hash{String => Array<Hash>}] each bluebook's recorded moves, empty when there is none
+    def implicit_moves(path) = File.exist?(path) ? JSON.parse(File.read(path)) : {}
+  end
+end

data/lib/hecks/site/bluebook/site.bluebook

@@ -1,28 +1,29 @@
-# The Site chapter: the route table a client declares for its website, and the command that
+# The Site bluebook: the route table a client declares for its website, and the command that
 # projects it into the TypeScript the site reads.
 #
-# A client declares its routes as `member` rows of a `value_object "Route"` in its own chapter (the
+# A client declares its routes as `member` rows of a `value_object "Route"` in its own bluebook (the
 # Route aggregate below names every field a row may carry and the closed sets its values come from),
-# attaches this chapter, and runs `hecks site site_projection.project_site`. The projection (`:site_routes_ts`)
+# attaches this bluebook, and runs `hecks site site_projection.project_site`. The projection (`:site_routes_ts`)
 # writes one `routes.ts` the site's middleware, navigation, sitemap, robots file and CMS all import,
 # so a route is declared once. The Route aggregate's value objects are the one place the closed
 # vocabularies live: the projector reads them from here, so a row naming a cache class that is
 # not a member is refused with the members listed.
 #
 # The same command projects the CDN: a project that adds Edge, EdgePolicy, EdgeOrigin and EdgeRule rows
-# to its chapter has the CloudFront behaviours and the listener rules written into the marked regions
+# to its bluebook has the CloudFront behaviours and the listener rules written into the marked regions
 # of the template it owns (the `:site_cdn` projection). Those rows are the template's facts, so only the
 # closed sets they draw on, cache class, origin and the kind of an EdgeFunction row, are named here. A
 # route's `edge:` names an EdgeFunction row, a viewer-request function the projection writes into the
 # template's `edge_functions` region and attaches to that route's behaviour.
 #
 # Each run records that it was requested before the SiteToolchain port is asked, and what came of
-# it after. No command declares a role: the chapter boots standing alone.
+# it after. No command declares a role: the bluebook boots standing alone.
 Hecks.bluebook "Site" do
   vision "Declare a site's routes once and project them into the TypeScript its pages, navigation and CMS read."
 
   aggregate "Route" do
     description "The shape of one row of a site's route table: where a path is served from, who may reach it, how it is cached, and where it appears in the navigation."
+    acknowledges :no_command_surface, "a route row is declared data: the table is what a site's bluebook says, and no command changes a row"
 
     identified_by :path
 
@@ -39,7 +40,7 @@ Hecks.bluebook "Site" do
 
     # `/blog/:slug.html` names a parameter; a trailing `/*` matches everything beneath a prefix. A
     # row with a `command:` or `query:` source may leave its path out, and the projection derives it
-    # from the forms scheme (`/Chapter/Aggregate/Verb`).
+    # from the forms scheme (`/Bluebook/Aggregate/Verb`).
     value_object "Path" do
       attribute :value, String, pattern: '\A(/[^ \t\n\r]*)?\z'
     end
@@ -100,8 +101,8 @@ Hecks.bluebook "Site" do
 
     # Where a page's content comes from, one of `none`, `global:<slug>` (a CMS global),
     # `collection:<name>` (a CMS collection, whose rows fill the path's parameter),
-    # `command:<Chapter>.<Aggregate>.<Command>` or `query:<Chapter>.<Aggregate>.<Query>`. The last
-    # two are checked against the chapters the project attaches.
+    # `command:<Bluebook>.<Aggregate>.<Command>` or `query:<Bluebook>.<Aggregate>.<Query>`. The last
+    # two are checked against the bluebooks the project attaches.
     value_object "Source" do
       attribute :value, String, pattern: '\A(none|(global|collection):[a-z0-9_-]+|(command|query):[A-Za-z0-9_]+\.[A-Za-z0-9_]+\.[A-Za-z0-9_]+)\z'
     end
@@ -134,7 +135,7 @@ Hecks.bluebook "Site" do
       invariant("a run is named") { !value.to_s.empty? }
     end
 
-    # A project directory, whose `bluebook/` holds the chapter that declares the route table.
+    # A project directory, whose `bluebook/` holds the bluebook that declares the route table.
     value_object "DomainPath" do
       attribute :value, String, matches: :not_empty
 
@@ -185,6 +186,7 @@ Hecks.bluebook "Site" do
       mark :failure, "faulted"
       transition "Complete" => "projected", from: "requested"
       transition "Fault"    => "faulted",   from: "requested"
+      mark :terminal, "faulted", "projected"
     end
 
     # `hecks site site_projection.project_site <project> [out=<dir>] [template=<file>] [cms=<dir>] [root=<dir>] [editor=<dir>] [extension=ts|mts] [--check]`.
@@ -193,25 +195,16 @@ Hecks.bluebook "Site" do
     command "ProjectSite" do
       goal "Project a site's route table into routes.ts, or with check only compare it with the file on disk"
 
-      attribute :domain,    DomainPath
-      attribute :run,       RunKey
-      attribute :out,       Location,  optional: true
-      attribute :template,  Location,  optional: true
-      attribute :cms,       Location,  optional: true
-      attribute :root,      Location,  optional: true
-      attribute :editor,    Location,  optional: true
-      attribute :extension, Extension, optional: true
-      attribute :check,     Switch,    optional: true
-
-      sets :domain
-      sets :run
-      sets :out
-      sets :template
-      sets :cms
-      sets :root
-      sets :editor
-      sets :extension
-      sets :check
+      attribute :domain,    DomainPath, sets: true
+      attribute :run,       RunKey, sets: true
+      attribute :out,       Location,  optional: true, sets: true
+      attribute :template,  Location,  optional: true, sets: true
+      attribute :cms,       Location,  optional: true, sets: true
+      attribute :root,      Location,  optional: true, sets: true
+      attribute :editor,    Location,  optional: true, sets: true
+      attribute :extension, Extension, optional: true, sets: true
+      attribute :check,     Switch,    optional: true, sets: true
+
 
       emits "SiteProjectionRequested"
     end
@@ -226,25 +219,18 @@ Hecks.bluebook "Site" do
     command "CheckLive" do
       goal "Compare a project's generated CloudFront behaviours with a live distribution's"
 
-      attribute :domain,       DomainPath
-      attribute :run,          RunKey
-      attribute :template,     Location,       optional: true
-      attribute :live,         Location,       optional: true
-      attribute :distribution, DistributionId, optional: true
-      attribute :expect_new,   PathList,       optional: true
-      attribute :refs,         PolicyRefs,     optional: true
+      attribute :domain,       DomainPath, sets: true
+      attribute :run,          RunKey, sets: true
+      attribute :template,     Location,       optional: true, sets: true
+      attribute :live,         Location,       optional: true, sets: true
+      attribute :distribution, DistributionId, optional: true, sets: true
+      attribute :expect_new,   PathList,       optional: true, sets: true
+      attribute :refs,         PolicyRefs,     optional: true, sets: true
 
       given("exactly one of a saved configuration and a distribution is named: pass live= or distribution=, not both") do
         (live.set? && distribution.unset?) || (live.unset? && distribution.set?)
       end
 
-      sets :domain
-      sets :run
-      sets :template
-      sets :live
-      sets :distribution
-      sets :expect_new
-      sets :refs
 
       emits "LiveCheckRequested"
     end
@@ -258,13 +244,10 @@ Hecks.bluebook "Site" do
     command "CheckSite" do
       goal "Ask a running site what its route table says it must answer, and judge each answer"
 
-      attribute :domain, DomainPath
-      attribute :run,    RunKey
-      attribute :url,    SiteUrl
+      attribute :domain, DomainPath, sets: true
+      attribute :run,    RunKey, sets: true
+      attribute :url,    SiteUrl, sets: true
 
-      sets :domain
-      sets :run
-      sets :url
 
       emits "SiteProbeRequested"
     end
@@ -277,13 +260,10 @@ Hecks.bluebook "Site" do
     command "CheckRoles" do
       goal "Check a host on this machine refuses every role-declaring command from a caller with no role"
 
-      attribute :domain, DomainPath
-      attribute :run,    RunKey
-      attribute :url,    SiteUrl
+      attribute :domain, DomainPath, sets: true
+      attribute :run,    RunKey, sets: true
+      attribute :url,    SiteUrl, sets: true
 
-      sets :domain
-      sets :run
-      sets :url
 
       emits "RolesCheckRequested"
     end
@@ -292,9 +272,8 @@ Hecks.bluebook "Site" do
       goal "Record that routes.ts was written, or found current, or the live edge matched, and what it said"
 
       reference_to SiteProjection
-      attribute :output, Report
+      attribute :output, Report, sets: true
 
-      sets :output
 
       emits "SiteProjected"
     end
@@ -303,9 +282,8 @@ Hecks.bluebook "Site" do
       goal "Record that routes.ts could not be projected, or was out of date, and why"
 
       reference_to SiteProjection
-      attribute :refusal, Report
+      attribute :refusal, Report, sets: true
 
-      sets :refusal
 
       emits "SiteFaulted"
     end
@@ -326,22 +304,22 @@ Hecks.bluebook "Site" do
 
   policy "ProjectWhenRequested" do
     on      "SiteProjection.SiteProjectionRequested"
-    trigger SiteProjection::SiteToolchain::Project, with: { run: :run }
+    ask     :project, with: { run: :run }
   end
 
   policy "CheckWhenRequested" do
     on      "SiteProjection.LiveCheckRequested"
-    trigger SiteProjection::SiteToolchain::Compare, with: { run: :run }
+    ask     :compare, with: { run: :run }
   end
 
   policy "ProbeWhenRequested" do
     on      "SiteProjection.SiteProbeRequested"
-    trigger SiteProjection::SiteToolchain::Probe, with: { run: :run }
+    ask     :probe, with: { run: :run }
   end
 
   policy "RolesWhenRequested" do
     on      "SiteProjection.RolesCheckRequested"
-    trigger SiteProjection::SiteToolchain::Roles, with: { run: :run }
+    ask     :roles, with: { run: :run }
   end
 
   policy "RecordTheProjection" do

data/lib/hecks/site/bluebook/site.ports.hecksagon

@@ -1,4 +1,4 @@
-# The port Site declares, for every hecksagon that attaches the chapter (`Chapters` loads this file
+# The port Site declares, for every hecksagon that attaches the bluebook (`Bluebooks` loads this file
 # with it). Each projection asks the SiteToolchain port, which the Hecks domain binds
 # (lib/hecks/hecks/adapters/site_toolchain.rb): the outside a projection reaches. The ask is
 # answered with the record's own arguments or refused with a reason. The port has to be declared

data/lib/hecks/sme/bluebook/sme.bluebook

@@ -2,7 +2,7 @@
 #
 # An interview is the record of one conversation with a subject matter expert about a domain: what
 # was asked, what was said, and what a developer then accepted as established. It is development
-# time work, so this chapter ships in the gem but is not attached to the Hecks domain: nothing
+# time work, so this bluebook ships in the gem but is not attached to the Hecks domain: nothing
 # boots it except the command that runs an interview.
 Hecks.bluebook "SME" do
   vision "Learn a business from the people who know it: an interview with a subject matter expert, kept as a record of what was asked, what was said, and what was accepted as established."
@@ -119,6 +119,7 @@ Hecks.bluebook "SME" do
       lifecycle :status, default: "proposed" do
         transition "AcceptThing" => "accepted", from: "proposed"
         transition "RejectThing" => "rejected", from: "proposed"
+        mark :terminal, "rejected"
       end
 
       command "AcceptThing", from: "proposed" do
@@ -156,6 +157,7 @@ Hecks.bluebook "SME" do
       lifecycle :status, default: "proposed" do
         transition "AcceptAction" => "accepted", from: "proposed"
         transition "RejectAction" => "rejected", from: "proposed"
+        mark :terminal, "rejected"
       end
 
       command "AcceptAction", from: "proposed" do
@@ -188,6 +190,7 @@ Hecks.bluebook "SME" do
       lifecycle :status, default: "proposed" do
         transition "AcceptRule" => "accepted", from: "proposed"
         transition "RejectRule" => "rejected", from: "proposed"
+        mark :terminal, "rejected"
       end
 
       command "AcceptRule", from: "proposed" do
@@ -223,6 +226,7 @@ Hecks.bluebook "SME" do
       lifecycle :status, default: "proposed" do
         transition "AcceptField" => "accepted", from: "proposed"
         transition "RejectField" => "rejected", from: "proposed"
+        mark :terminal, "rejected"
       end
 
       command "AcceptField", from: "proposed" do
@@ -259,6 +263,7 @@ Hecks.bluebook "SME" do
       lifecycle :status, default: "proposed" do
         transition "AcceptTransition" => "accepted", from: "proposed"
         transition "RejectTransition" => "rejected", from: "proposed"
+        mark :terminal, "rejected"
       end
 
       command "AcceptTransition", from: "proposed" do
@@ -282,6 +287,7 @@ Hecks.bluebook "SME" do
       transition "Begin"    => "underway",  from: "planned"
       transition "Conclude" => "concluded", from: "underway"
       transition "Cancel"   => "cancelled", from: ["planned", "underway"]
+      mark :terminal, "cancelled", "concluded"
     end
 
     command "Plan" do

data/lib/hecks/storehouse/audit.rb

@@ -4,7 +4,17 @@ module Hecks
     # 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
+      AUDIT_FIELDS = %i[verb summary source role actor_id surface].freeze
+
+      # A character a log file's name may not carry.
+      UNSAFE_NAME_CHARACTER = /[^A-Za-z0-9_-]/
+
+      # The boundary between a lowercase or digit character and an uppercase one, where a
+      # CamelCase word takes an underscore.
+      CAMEL_CASE_BOUNDARY = /([a-z\d])([A-Z])/
+
+      # The last segment of a qualified constant name, such as `TypeMismatch` in `Runtime::TypeMismatch`.
+      UNQUALIFIED_NAME = /[^:]+\z/
 
       # Kept under Hecks::CacheDir, not the domain directory (part of the domain's
       # own state) or the gem directory (read-only once installed).
@@ -13,7 +23,7 @@ module Hecks
 
       # :nodoc:
       def log_path(domain_name)
-        File.join(log_root, "#{domain_name.to_s.gsub(/[^A-Za-z0-9_-]/, "_")}.jsonl")
+        File.join(log_root, "#{domain_name.to_s.gsub(UNSAFE_NAME_CHARACTER, "_")}.jsonl")
       end
 
       # Never fails a real call because its own audit log couldn't be written —
@@ -24,14 +34,37 @@ module Hecks
       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)) }
+        File.open(log_path(domain_name), "a") { |f| f.puts(JSON.generate(audit_line(tool, outcome, entry))) }
       rescue StandardError
         nil
       end
 
+      # One audit line as a hash: when, the tool, the caller's fields, the outcome's fields, then
+      # the call's duration and refusal kind, with absent values left out.
+      # :nodoc:
+      def audit_line(tool, outcome, entry)
+        fields = AUDIT_FIELDS.to_h { |field| [field, entry[field]] }
+        { time: Time.now.utc.iso8601, tool: tool, **fields, **outcome.slice(:ok, :id, :error, :events),
+          **entry.slice(:duration_ms, :refusal) }.compact
+      end
+
+      # Whole milliseconds since `started`, a CLOCK_MONOTONIC reading.
+      # :nodoc:
+      def elapsed_ms(started)
+        ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+      end
+
+      # The refusal's class as a snake_case kind, such as `type_mismatch`.
+      # :nodoc:
+      def refusal_kind(error)
+        snake_case(error.class.name[UNQUALIFIED_NAME])
+      end
+
+      # The word with an underscore at each CamelCase boundary, in lowercase.
+      # :nodoc:
+      def snake_case(word) = word.gsub(CAMEL_CASE_BOUNDARY, '\\1_\\2').downcase
+
       # Tails this bus's own dispatch/query/state audit log — a pull-based
       # substitute for a push subscription, since a stdio server answers one
       # request at a time with no channel to push through.

data/lib/hecks/storehouse/bluebook_words.rb

@@ -0,0 +1,35 @@
+require_relative "../naming"
+
+module Hecks
+  module Storehouse
+    # Which bluebook a command or query name speaks to, read the way the CLI reads a line: the
+    # booted domain's own bluebook, or a bluebook its hecksagon attaches when the name starts with
+    # that bluebook's word and a space (`bulk bulk_run.request` reaches the attached Bulk bluebook).
+    # Extended onto `Storehouse`.
+    module BluebookWords
+      # The bluebook `name` speaks to, and the name within that bluebook.
+      #
+      # @param runtime [Runtime::Dispatcher] the booted domain
+      # @param name [String, Symbol] a command or query name, optionally led by a bluebook word
+      # @return [Array(Bluebook::Declaration, String)] the bluebook, and the name with its bluebook
+      #   word
+      #   dropped
+      # @raise [Runtime::NotFound] if the boot loaded no bluebook
+      def bluebook_and_name(runtime, name)
+        word, rest = name.to_s.split(" ", 2)
+        attached = rest && attached_bluebook(runtime, word)
+        attached ? [runtime.bluebook(attached), rest] : [bluebook_for(runtime), name.to_s]
+      end
+
+      # The name of the bluebook the booted domain attaches under `word`, or nil.
+      #
+      # @param runtime [Runtime::Dispatcher] the booted domain
+      # @param word [String] a bluebook's snake-cased name, such as `"bulk"`
+      # @return [String, nil] the attached bluebook's name
+      def attached_bluebook(runtime, word)
+        own = bluebook_for(runtime)
+        Array(runtime.hecksagon(own.name)&.member_bluebooks).find { |declaration| Naming.snake(declaration) == word }
+      end
+    end
+  end
+end

data/lib/hecks/storehouse/callers.rb

@@ -21,6 +21,7 @@ module Hecks
       def validate_caller_fields!(request)
         require_summary!(request.summary)
         valid_source!(request.source)
+        valid_surface!(request.surface)
         valid_caller!(request.role, request.actor_id)
       end
 
@@ -33,6 +34,13 @@ module Hecks
               "a one-line summary: is required on dispatch/query/state — it is what makes an audit row legible later"
       end
 
+      # :nodoc:
+      def valid_surface!(surface)
+        return if surface.nil? || SURFACES.include?(surface.to_s)
+
+        raise Runtime::TypeMismatch, "surface: #{surface.inspect} is not one of #{SURFACES.join(", ")}"
+      end
+
       # :nodoc:
       def valid_source!(source)
         return if source.nil? || SOURCE_TAGS.include?(source.to_s)

data/lib/hecks/storehouse/dispatching.rb

@@ -17,14 +17,14 @@ module Hecks
       # @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)
+        request.bluebook, request.name = bluebook_and_name(runtime, command)
         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)
+        spec = resolve!(cli_for(request.runtime, request.bluebook), request.name, asking: false)
         require_caller_for_role_gated!(spec, request.role)
         envelope = command_envelope(request.args, spec)
 
@@ -72,9 +72,12 @@ module Hecks
 
       # :nodoc:
       def settled_record(runtime, spec, result)
-        bluebook = bluebook_for(runtime)
+        bluebook = runtime.bluebook(spec[:command].to_s.split("::", 2).first) || bluebook_for(runtime)
         aggregate = top_level_aggregate(bluebook, spec[:command])
-        aggregate && runtime.registry.repository(bluebook.name, aggregate)&.find(result.id)&.to_h
+        return aggregate unless aggregate
+
+        repository = runtime.repository(bluebook.name, aggregate)
+        repository&.find(result.id)&.to_h
       end
 
       # :nodoc:
@@ -92,7 +95,7 @@ module Hecks
       # @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))
+        cli = cli_for(runtime, bluebook_for(runtime))
         names.filter_map do |name|
           guide_line(name, resolve!(cli, name.to_s, asking: false))
         rescue Runtime::NotFound
@@ -100,6 +103,17 @@ module Hecks
         end
       end
 
+      # The commands an agent may dispatch: those that explicitly declare `:agent` in their
+      # `audience`. A command that declares no audience is not an agent tool, so the default
+      # never grants agent access.
+      #
+      # @param runtime [Runtime::Dispatcher] the booted domain
+      # @return [Array<String>] the command names as the launcher lists them, in order
+      def agent_commands(runtime)
+        cli = cli_for(runtime, bluebook_for(runtime))
+        cli[:commands].filter_map { |name, spec| name.to_s if Array(spec[:audience]).include?("agent") }
+      end
+
       # :nodoc:
       def guide_line(name, spec)
         arguments = spec[:arguments].map { |arg| arg[:path].split(".").first + (arg[:required] ? "*" : "") }
@@ -128,7 +142,7 @@ module Hecks
       # @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])
+        check_options!(options, %i[source role actor_id surface])
         run_batch(runtime, steps, summary, options)
       end