hecks 3.0.4 → 3.1.0

data/lib/hecks/doors/mcp_door.rb

@@ -266,30 +266,28 @@ module Hecks
         end
       end
 
-      # `domain:` is confined to `Storehouse::BOOT_ROOT`, and further to a reader
-      # door's `HECKS_DOOR_DOMAINS`, before anything boots.
+      # `domain:` is confined to `Storehouse::BOOT_ROOT`, and further to a restricted
+      # door's `HECKS_DOOR_DOMAINS`, before anything boots. An unrestricted door boots the
+      # domain afresh on every call; a restricted door lives for one spawner's session and
+      # keeps each named domain booted until the files of its directory change.
       def boot(domain)
-        Hecks.boot(Storehouse.confine!(scope.admit_domain!(domain), "domain"), install_doors: false)
+        path = Storehouse.confine!(scope.admit_domain!(domain), "domain")
+        return Hecks.boot(path, install_doors: false) unless scope.restricted?
+
+        resident = (@resident ||= {})
+        fingerprint = Storehouse.fingerprint(path)
+        return resident[path][:runtime] if resident[path] && resident[path][:fingerprint] == fingerprint
+
+        resident[path] = { fingerprint: fingerprint, runtime: Hecks.boot(path, install_doors: false) }
+        resident[path][:runtime]
       end
 
       # One `when` per tool, so the shared `rescue` catches every branch's escape
       # once; a domain refusal is already `{ok: false, ...}` from `Storehouse`.
       def call_tool(name, args) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
         case name
-        when "dispatch"
-          runtime = boot(args["domain"])
-          if args["steps"]
-            Storehouse.dispatch_batch(runtime: runtime, steps: args["steps"], summary: args["summary"],
-                                      source: args["source"], role: args["role"], actor_id: args["actor_id"])
-          else
-            Storehouse.dispatch(runtime: runtime, command: args["command"], summary: args["summary"],
-                                args: args["args"] || {}, source: args["source"],
-                                dry_run: args["dry_run"] == true, role: args["role"], actor_id: args["actor_id"])
-          end
-        when "query"
-          Storehouse.query(runtime: boot(args["domain"]), question: args["question"],
-                           summary: args["summary"], args: args["args"] || {}, source: args["source"],
-                           role: args["role"], actor_id: args["actor_id"])
+        when "dispatch" then dispatch_tool(args)
+        when "query" then query_tool(args)
         when "events"
           Storehouse.events(runtime: boot(args["domain"]), aggregate: args["aggregate"], id: args["id"],
                             limit: args["limit"])
@@ -319,6 +317,29 @@ module Hecks
         { ok: false, error: "#{e.class}: #{e.message}" }
       end
 
+      # A question, once the scope has admitted its arguments.
+      def query_tool(args)
+        scope.admit_arguments!(args["args"])
+        Storehouse.query(runtime: boot(args["domain"]), question: args["question"],
+                         summary: args["summary"], args: args["args"] || {}, source: args["source"],
+                         role: args["role"], actor_id: args["actor_id"])
+      end
+
+      # A single command or a batch, once the scope has admitted every command in it.
+      def dispatch_tool(args)
+        runtime = boot(args["domain"])
+        if args["steps"]
+          scope.admit_steps!(runtime, args["steps"])
+          Storehouse.dispatch_batch(runtime: runtime, steps: args["steps"], summary: args["summary"],
+                                    source: args["source"], role: args["role"], actor_id: args["actor_id"])
+        else
+          scope.admit_command!(runtime, args["command"], args["args"])
+          Storehouse.dispatch(runtime: runtime, command: args["command"], summary: args["summary"],
+                              args: args["args"] || {}, source: args["source"],
+                              dry_run: args["dry_run"] == true, role: args["role"], actor_id: args["actor_id"])
+        end
+      end
+
       def answer_tool(name, args)
         return scope.refusal(name) unless scope.permits_tool?(name)
 
@@ -352,7 +373,8 @@ module Hecks
         when "notifications/initialized"
           nil # a notification — no id, no response
         when "tools/list"
-          send_response(id, { tools: TOOLS.select { |tool| scope.permits_tool?(tool[:name]) } })
+          served = TOOLS.select { |tool| scope.permits_tool?(tool[:name]) }
+          send_response(id, { tools: served.map { |tool| scope.present(tool) } })
         when "tools/call"
           send_response(id, tool_result(answer_tool(params["name"], params["arguments"] || {})))
         when "ping"

data/lib/hecks/doors/mcp_door_scope.rb

@@ -2,27 +2,55 @@ require_relative "../runtime/errors"
 
 module Hecks
   module Doors
-    # What a spawned hecks mcp may do: every tool by default, or only
-    # reader tools against named domains in reader mode — reach, not identity (ADR 0072).
+    # What a spawned hecks mcp may do: every tool by default; only reader tools against named
+    # domains in reader mode; and in commands mode those plus `dispatch` of a closed list of
+    # commands — reach, not identity (ADR 0072, ADR 0089).
     class McpDoorScope
-      ENV_PREFIX       = "HECKS_DOOR_".freeze
-      TOOLS_VARIABLE   = "HECKS_DOOR_TOOLS".freeze
-      DOMAINS_VARIABLE = "HECKS_DOOR_DOMAINS".freeze
-      READERS          = "readers".freeze
-      EXIT_STATUS      = 2
+      ENV_PREFIX         = "HECKS_DOOR_".freeze
+      TOOLS_VARIABLE     = "HECKS_DOOR_TOOLS".freeze
+      DOMAINS_VARIABLE   = "HECKS_DOOR_DOMAINS".freeze
+      COMMANDS_VARIABLE  = "HECKS_DOOR_COMMANDS".freeze
+      READERS            = "readers".freeze
+      COMMANDS           = "commands".freeze
+      MODES              = [READERS, COMMANDS].freeze
+      EXIT_STATUS        = 2
 
       # The tools a reader door serves — each reads a domain or the door's own
       # audit log and writes no domain state. `validate` still boots its
       # domain, so it stays bound to the allowed set like every other tool.
       READER_TOOLS = %w[query events state catalog describe validate domains history follow].freeze
 
+      # The tools a commands door serves: the reader tools, and `dispatch` for the allowed commands.
+      COMMAND_TOOLS = (READER_TOOLS + %w[dispatch]).freeze
+
+      # Argument names a restricted door never passes on, whatever command carries them: each one
+      # names a host or a URL, a binary to run, a place to write, a port to open, a store to
+      # switch to, or flips a command from a preview to a change of state.
+      DENIED_ARGUMENTS = %w[
+        adapter artifact confirm expected from gem_only header health_path host no_wait npm_local
+        npm_only output path payload payload_file port rust_binary scheme state_path stdio url write
+      ].freeze
+
+      # Argument names whose values are paths (a comma-separated list for some). A restricted door
+      # passes them on only when each resolves, symlinks followed, inside `Storehouse::BOOT_ROOT`,
+      # and holds no colon: `host:repo` and `https://host/x` would otherwise pass as relative paths.
+      PATH_ARGUMENTS = %w[dir domain domains file fixture paths root script].freeze
+
+      # Argument names whose values are git refs: plain names only, so a value cannot read as an
+      # option to git.
+      REF_ARGUMENTS = %w[ref].freeze
+
+      # What a plain git ref looks like: no leading dash, no `..`, no spaces.
+      PLAIN_REF = %r{\A[A-Za-z0-9][A-Za-z0-9._/~^@-]*\z}
+
       # Unrestricted when no HECKS_DOOR_* variable is set.
       def self.from_env(env = ENV)
         problems = setting_problems(env)
         raise ArgumentError, problems.join("\n") unless problems.empty?
         return new(allowed_domains: nil) unless env[TOOLS_VARIABLE]
 
-        new(allowed_domains: env[DOMAINS_VARIABLE].split(File::PATH_SEPARATOR).reject(&:empty?))
+        commands = env[TOOLS_VARIABLE] == COMMANDS ? split_names(env[COMMANDS_VARIABLE]) : nil
+        new(allowed_domains: split_paths(env[DOMAINS_VARIABLE]), allowed_commands: commands)
       end
 
       # Refuses to stderr, not stdout, which carries the MCP protocol.
@@ -34,44 +62,80 @@ module Hecks
       end
 
       def self.setting_problems(env)
-        unknown = env.keys.select { |name| name.start_with?(ENV_PREFIX) } - [TOOLS_VARIABLE, DOMAINS_VARIABLE]
-        problems = unknown.map do |name|
-          "environment #{name} is not accepted; the door takes only #{TOOLS_VARIABLE} and #{DOMAINS_VARIABLE}"
+        known = [TOOLS_VARIABLE, DOMAINS_VARIABLE, COMMANDS_VARIABLE]
+        problems = (env.keys.select { |name| name.start_with?(ENV_PREFIX) } - known).map do |name|
+          "environment #{name} is not accepted; the door takes only #{known.join(', ')}"
         end
-        problems + mode_problems(env[TOOLS_VARIABLE], env[DOMAINS_VARIABLE])
+        problems + mode_problems(env[TOOLS_VARIABLE], env[DOMAINS_VARIABLE], env[COMMANDS_VARIABLE])
       end
 
-      def self.mode_problems(tools, domains)
-        if tools.nil?
-          domains.nil? ? [] : ["#{DOMAINS_VARIABLE} is set without #{TOOLS_VARIABLE}=#{READERS}; it only narrows a reader door"]
-        elsif tools != READERS
-          ["#{TOOLS_VARIABLE}=#{tools.inspect} is not accepted; the only value is #{READERS.inspect}"]
-        elsif domains.to_s.split(File::PATH_SEPARATOR).none? { |path| !path.empty? }
-          ["#{TOOLS_VARIABLE}=#{READERS} needs #{DOMAINS_VARIABLE}, the domains this door may read"]
+      def self.mode_problems(tools, domains, commands)
+        return stray_problems(domains, commands) if tools.nil?
+        unless MODES.include?(tools)
+          return ["#{TOOLS_VARIABLE}=#{tools.inspect} is not accepted; the values are #{MODES.map(&:inspect).join(' and ')}"]
+        end
+
+        problems = []
+        if split_paths(domains.to_s).empty?
+          problems << "#{TOOLS_VARIABLE}=#{tools} needs #{DOMAINS_VARIABLE}, the domains this door may read"
+        end
+        problems + command_problems(tools, commands)
+      end
+
+      def self.stray_problems(domains, commands)
+        stray = { DOMAINS_VARIABLE => domains, COMMANDS_VARIABLE => commands }.compact.keys
+        return [] if stray.empty?
+
+        ["#{stray.join(' and ')} set without #{TOOLS_VARIABLE}=#{READERS} or #{TOOLS_VARIABLE}=#{COMMANDS}; " \
+         "they only narrow a restricted door"]
+      end
+
+      def self.command_problems(tools, commands)
+        if tools == COMMANDS && split_names(commands).empty?
+          ["#{TOOLS_VARIABLE}=#{COMMANDS} needs #{COMMANDS_VARIABLE}, the commands this door may dispatch"]
+        elsif tools == READERS && !commands.nil?
+          ["#{COMMANDS_VARIABLE} is set in reader mode; it only narrows a commands door"]
         else
           []
         end
       end
 
+      def self.split_paths(value) = value.to_s.split(File::PATH_SEPARATOR).reject(&:empty?)
+
+      def self.split_names(value) = value.to_s.split(",").map(&:strip).reject(&:empty?).uniq
+
       # The named domains, resolved against Storehouse::BOOT_ROOT; nil when unrestricted.
       attr_reader :allowed_domains
 
-      def initialize(allowed_domains:)
+      # The command names a commands door dispatches, as the spawner wrote them; nil unless
+      # the door runs in commands mode.
+      attr_reader :allowed_commands
+
+      def initialize(allowed_domains:, allowed_commands: nil)
         @allowed_domains = allowed_domains&.map { |path| Storehouse.confine!(path, DOMAINS_VARIABLE) }.freeze
+        @allowed_commands = allowed_commands&.dup&.freeze
       end
 
       def restricted?
         !@allowed_domains.nil?
       end
 
+      def commands_mode?
+        !@allowed_commands.nil?
+      end
+
+      def served_tools
+        commands_mode? ? COMMAND_TOOLS : READER_TOOLS
+      end
+
       def permits_tool?(name)
-        !restricted? || READER_TOOLS.include?(name)
+        !restricted? || served_tools.include?(name)
       end
 
       def refusal(name)
         { ok:    false,
-          error: "#{name.inspect} is refused: this door runs in reader mode (#{TOOLS_VARIABLE}=#{READERS}), " \
-                 "which serves only #{READER_TOOLS.join(', ')}" }
+          error: "#{name.inspect} is refused: this door runs in #{mode_label}, " \
+                 "which serves only #{served_tools.join(', ')}" }
       end
 
       # Checked before anything boots, so a path outside the allowed set never reaches Kernel.load.
@@ -80,18 +144,174 @@ module Hecks
         return domain if @allowed_domains.include?(Storehouse.confine!(domain, "domain"))
 
         raise Runtime::TypeMismatch,
-              "domain: #{domain.inspect} is refused: this door runs in reader mode (#{TOOLS_VARIABLE}=#{READERS}) " \
+              "domain: #{domain.inspect} is refused: this door runs in #{mode_label} " \
               "and reads only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(', ')}"
       end
 
+      # A commands door dispatches only the commands it was given. A requested name and each
+      # allowed name resolve through the alias map `dispatch` uses, and the resolved verbs are
+      # compared, so `complete` cannot reach a command of another aggregate that shares its short
+      # name, and an allowed name that resolves to nothing admits nothing.
+      #
+      # @param runtime [Runtime::Dispatcher] the booted domain
+      # @param command [String, nil] the command name the caller asked for
+      # @param args [Hash, nil] the arguments the caller gave it; see `admit_arguments!`
+      # @raise [Runtime::TypeMismatch] when the command is not on the list or an argument is refused
+      def admit_command!(runtime, command, args = nil)
+        return unless commands_mode?
+
+        verbs = Storehouse.verbs_for(runtime, [command, *allowed_commands])
+        unless verbs.first && verbs.drop(1).include?(verbs.first)
+          raise Runtime::TypeMismatch,
+                "command: #{command.to_s.inspect} is refused: this door runs in #{mode_label} " \
+                "and dispatches only #{COMMANDS_VARIABLE}: #{allowed_commands.join(', ')}"
+        end
+
+        admit_arguments!(args)
+      end
+
+      # Every step of a batch is admitted before any step runs.
+      #
+      # @param runtime [Runtime::Dispatcher] the booted domain
+      # @param steps [Array<Hash>] the batch, each `{"command" => ..., "args" => ...}`
+      # @raise [Runtime::TypeMismatch] when a step names a command off the list or a bad argument
+      def admit_steps!(runtime, steps)
+        Array(steps).each do |step|
+          step = {} unless step.is_a?(Hash)
+          admit_command!(runtime, step["command"], step["args"])
+        end
+      end
+
+      # The arguments a restricted door is about to pass to a command or a question. A command
+      # list admits commands, not values, so each argument is checked by its name: a denied name
+      # is refused, a path must resolve inside the root with symlinks followed, and a git ref must
+      # be a plain name. Other names pass; a domain with an argument that reaches outside its own
+      # files should name it in `DENIED_ARGUMENTS` or `PATH_ARGUMENTS` (ADR 0089).
+      #
+      # @param args [Hash, Array, nil] the arguments as the caller gave them, nested or not
+      # @raise [Runtime::TypeMismatch] on the first argument refused
+      def admit_arguments!(args)
+        return unless restricted?
+
+        each_argument(args) do |name, value|
+          refuse_argument!(name, "never passes it on: it names a host, a binary, an output or a change of state") if
+            DENIED_ARGUMENTS.include?(name)
+          admit_path!(name, value) if PATH_ARGUMENTS.include?(name)
+          admit_ref!(name, value) if REF_ARGUMENTS.include?(name)
+        end
+      end
+
+      # The tool as `tools/list` shows it: on a commands door, `dispatch` names the commands it
+      # serves, so a caller sees them as an enum instead of finding out by being refused.
+      #
+      # @param tool [Hash] a tool definition from `McpDoor::TOOLS`
+      # @return [Hash] the definition, narrowed for this door
+      def present(tool)
+        return tool unless commands_mode? && tool[:name] == "dispatch"
+
+        properties = tool[:inputSchema][:properties]
+        narrowed = properties.merge(command: with_enum(properties[:command]),
+                                    steps:   properties[:steps].merge(items: step_items(properties[:steps][:items])))
+        tool.merge(description: "#{tool[:description]} This door dispatches only: #{allowed_commands.join(', ')}.",
+                   inputSchema: tool[:inputSchema].merge(properties: narrowed))
+      end
+
       def notes
         return [] unless restricted?
 
+        commands_mode? ? commands_notes : reader_notes
+      end
+
+      private
+
+      # Yields every argument name with its value, descending into nested objects and lists, so
+      # `{"file" => {"value" => "x"}}` is checked the way `{"file" => "x"}` is.
+      def each_argument(args, &visit)
+        case args
+        when Hash
+          args.each do |name, value|
+            visit.call(name.to_s, value)
+            each_argument(value, &visit)
+          end
+        when Array
+          args.each { |item| each_argument(item, &visit) }
+        end
+      end
+
+      # A value written as an object of one field (`{"value" => "x"}`) is that field's value.
+      def scalar(value)
+        return value unless value.is_a?(Hash)
+
+        value.fetch("value") { value.fetch(:value, value) }
+      end
+
+      def refuse_argument!(name, why)
+        raise Runtime::TypeMismatch, "argument: #{name.inspect} is refused: this door runs in #{mode_label} and #{why}"
+      end
+
+      def admit_path!(name, value)
+        Array(scalar(value)).flat_map { |item| item.to_s.split(",") }.reject(&:empty?).each do |path|
+          next if !path.include?(":") && inside_root?(path)
+
+          refuse_argument!(name, "passes a path only when it resolves inside #{Storehouse::BOOT_ROOT} " \
+                                 "and holds no colon: #{path.inspect}")
+        end
+      end
+
+      def admit_ref!(name, value)
+        ref = scalar(value).to_s
+        return if ref.match?(PLAIN_REF) && !ref.include?("..")
+
+        refuse_argument!(name, "passes only a plain git ref: #{ref.inspect}")
+      end
+
+      def inside_root?(path)
+        root = resolve_real(Storehouse::BOOT_ROOT)
+        resolved = resolve_real(File.expand_path(path, Storehouse::BOOT_ROOT))
+        resolved == root || resolved.start_with?("#{root}#{File::SEPARATOR}")
+      end
+
+      # The real path of `path`, symlinks followed: of the whole path when it exists, else of its
+      # deepest existing parent with the missing names put back, so a link above a file that does
+      # not exist yet still shows where the file would land.
+      def resolve_real(path)
+        missing = []
+        current = File.expand_path(path)
+        until File.exist?(current)
+          parent = File.dirname(current)
+          break if parent == current
+
+          missing.unshift(File.basename(current))
+          current = parent
+        end
+        File.join(File.realpath(current), *missing)
+      end
+
+      def with_enum(property)
+        property.merge(enum: allowed_commands)
+      end
+
+      def step_items(items)
+        items.merge(properties: items[:properties].merge(command: with_enum(items[:properties][:command])))
+      end
+
+      def mode_label
+        commands_mode? ? "commands mode (#{TOOLS_VARIABLE}=#{COMMANDS})" : "reader mode (#{TOOLS_VARIABLE}=#{READERS})"
+      end
+
+      def reader_notes
         ["Reader mode (#{TOOLS_VARIABLE}=#{READERS}): serves #{READER_TOOLS.join(', ')}; " \
          "refuses dispatch (with dry_run and steps), behaviors and every other tool.",
          "domain: boots only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(', ')}.",
          "Reader mode limits reach and identifies no one; it is not authentication."]
       end
+
+      def commands_notes
+        ["Commands mode (#{TOOLS_VARIABLE}=#{COMMANDS}): serves #{READER_TOOLS.join(', ')} and dispatch of only " \
+         "#{COMMANDS_VARIABLE}: #{@allowed_commands.join(', ')}; refuses behaviors and every other tool.",
+         "domain: boots only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(', ')}.",
+         "Commands mode limits reach and identifies no one; role: stays self-asserted and it is not authentication."]
+      end
     end
   end
 end

data/lib/hecks/doors.rb

@@ -2,7 +2,7 @@ module Hecks
   # The class-free public surface, installed per boot by `Runtime::Loader.bind_runtime`.
   module Doors
     # The removal release of the `Facade` and `install_facade:` spellings.
-    REMOVAL = "3.1.0".freeze
+    REMOVAL = "3.2.0".freeze
 
     module_function
 

data/lib/hecks/embryonaut_bluebook.rb

@@ -24,12 +24,12 @@ module Hecks
     def self.load!(name, registry: Hecks.current_registry)
       unless registry&.root
         raise Runtime::WiringError,
-              "uses_embryonaut_bluebook(#{name.inspect}) needs a registry with a root to vendor from"
+              "attaches(#{name.inspect}, from: :vendor) needs a registry with a root to vendor from"
       end
 
       unless name.to_s.match?(PACKAGE_NAME)
         raise Runtime::WiringError,
-              "uses_embryonaut_bluebook(#{name.inspect}) is not a package name — it must match " \
+              "attaches(#{name.inspect}, from: :vendor) is not a package name — it must match " \
               "[a-z][a-z0-9_]* (the name `hecks vendor` accepts)"
       end
 

data/lib/hecks/forms/banking_presentation.rb

@@ -37,7 +37,7 @@ module Hecks
         Hecks::Adapters::Folder.new.load_bluebooks(File.join(root, "examples/banking/bluebook"))
         Kernel.load(File.join(root, "lib/hecks/forms/examples/banking_console.bluebook"))
         Hecks.hecksagon("Banking") do
-          uses_framework "Governance"
+          attaches "Governance"
           AGGREGATES.each { |name| ::Banking.const_get(name).persisted_by("Memory") }
         end
         Hecks.hecksagon("Governance") do

data/lib/hecks/framework/bluebook/compliance.bluebook

@@ -2,7 +2,7 @@ Hecks.bluebook "Compliance" do
   vision "Something elsewhere already acted to contain a risk; this domain tracks the human review that decides what happens next."
   supporting
 
-  # Supports both modes from one source: `uses_framework "Compliance"` merges it in-process,
+  # Supports both modes from one source: `attaches "Compliance"` merges it in-process,
   # or a separately deployed service is reached with `across "Compliance"` on a policy.
   # examples/compliance/bluebook/compliance.bluebook symlinks here, since a symlink pointing
   # outside lib/ does not survive `gem build`.

data/lib/hecks/framework/bluebook/console_settings.bluebook

@@ -3,7 +3,7 @@ Hecks.bluebook "ConsoleSettings" do
   supporting
 
   # A framework member like Identity/Governance: attach with
-  # `uses_framework "ConsoleSettings"` in the consuming app's own `.hecksagon`,
+  # `attaches "ConsoleSettings"` in the consuming app's own `.hecksagon`,
   # plus a `Hecks.hecksagon "ConsoleSettings" do ... end` persistence binding.
 
   # Named ConsoleSettings, not "Forms" — Hecks::Forms (lib/hecks/forms/) names a

data/lib/hecks/framework/bluebook/framework.hecksagon

@@ -1,14 +1,14 @@
 # The framework members bound to Memory so they can boot standing alone with
-# `Hecks.boot("lib/hecks/framework")`. `uses_framework` does not read this file.
+# `Hecks.boot("lib/hecks/framework")`. `attaches` does not read this file.
 Hecks.hecksagon "Compliance" do
   # Every command declares `role "Compliance officer"`; the role check needs Governance.
-  uses_framework "Governance"
+  attaches "Governance"
   persisted_by "Memory"
 end
 
 Hecks.hecksagon "ConsoleSettings" do
   # Same reason as Compliance.
-  uses_framework "Governance"
+  attaches "Governance"
   persisted_by "Memory"
 end
 
@@ -18,6 +18,6 @@ end
 
 Hecks.hecksagon "Identity" do
   # `Identity.Register` declares `role "Identity registrar"`; same reason as Compliance.
-  uses_framework "Governance"
+  attaches "Governance"
   persisted_by "Memory"
 end

data/lib/hecks/framework.rb

@@ -55,7 +55,7 @@ module Hecks
     # Loads a member's bluebook unless this registry already holds it.
     #
     # `Kernel.load` re-executes the file, and a second `Declare` of the same aggregate is
-    # `AlreadyExists`, so repeated `uses_framework` calls in one boot must skip.
+    # `AlreadyExists`, so repeated `attaches` calls in one boot must skip.
     #
     # @param name [String, Symbol] the member's name, such as `"Governance"`
     # @return [Boolean, nil] true when this call loaded the member's bluebook, nil when

data/lib/hecks/fuzzing/combination_miner.rb

@@ -5,7 +5,7 @@ require_relative "form_census"
 module Hecks
   module Fuzzing
     # Asks an agent to write candidate bluebooks from the corpus's form-pair census.
-    # Opt-in: `hecks quality_control tick` never runs it; an agent call is costly and
+    # Opt-in: `hecks quality_control sweep.tick` never runs it; an agent call is costly and
     # nondeterministic.
     module CombinationMiner
       PROMPT_TEMPLATE = "qa/combination_miner/prompt.md".freeze

data/lib/hecks/fuzzing/concurrent_dispatch.rb

@@ -55,7 +55,7 @@ module Hecks
       end
 
       # Filters to verbs whose aggregate resolves to a `:cross_process_lock`-declaring
-      # adapter — a Memory-backed aggregate (e.g. one only `uses_framework`s) can never
+      # adapter — a Memory-backed aggregate (e.g. one only `attaches`s) can never
       # agree with the sequential oracle across two processes, a guaranteed false positive.
       def lockable_verbs(domain_path, steps, database:, schema:)
         verbs = steps.select { |step| COMMAND_STEP.call(step) }.map { |step| step["verb"] }.uniq

data/lib/hecks/fuzzing/differential.rb

@@ -4,12 +4,14 @@ require_relative "replay"
 require_relative "properties"
 require_relative "self_consistency"
 require_relative "rust_gap_manifest"
+require_relative "../rust_build/kernel_input"
 require_relative "nondeterministic"
 
 module Hecks
   module Fuzzing
     # The Ruby-vs-Rust comparison of one generated sequence, shared by the QualityControl sweep
-    # (`hecks quality_control ask run`) and `hecks quality_control check_generated_domains --rust`.
+    # (`hecks quality_control query sweep.run`) and `hecks quality_control
+    # target.check_generated_domains --rust`.
     #
     # `differ` is duck-typed (the `RustConformanceHelpers` comparison helpers plus a
     # `structural_skips` set) so lib never requires spec/.
@@ -91,7 +93,7 @@ module Hecks
           outcomes[:adapter_parity_sqlite] = adapter_parity_sqlite.call
         end
 
-        stdout, status = Open3.capture2(binary, stdin_data: JSON.generate({ "steps" => steps }))
+        stdout, status = Open3.capture2(binary, stdin_data: RustBuild::KernelInput.json(domain_path, steps))
         unless status.success?
           return outcomes.merge(differential: [{ field:  "process",
                                                  detail: "rust binary exited #{status.exitstatus}: #{stdout}" }])

data/lib/hecks/fuzzing/era_boundary.rb

@@ -9,7 +9,7 @@ module Hecks
 
       # `kind:` on a `checked: false` result distinguishes a target with no
       # lineage to audit (`:not_applicable`) from an audit that failed to
-      # run (`:error`) — `hecks quality_control ask run` holds the first and surfaces the
+      # run (`:error`) — `hecks quality_control query sweep.run` holds the first and surfaces the
       # second as a finding, instead of treating both as a clean audit.
       def diverged_ancestor_writes(domain_path)
         registry, directory = load_registry(domain_path)

data/lib/hecks/fuzzing/form_census.rb

@@ -5,8 +5,8 @@ module Hecks
   module Fuzzing
     # The declared forms an aggregate can exhibit, and the pairs it puts together.
     #
-    # Shared by the combination-coverage spec and `hecks quality_control judge_novelty` so they
-    # cannot drift. The unit is one aggregate: forms on one head meet at dispatch, forms in one
+    # Shared by the combination-coverage spec and `hecks quality_control target.judge_novelty` so
+    # they cannot drift. The unit is one aggregate: forms on one head meet at dispatch, forms in one
     # chapter do not.
     module FormCensus
       # A given path crossing two references has at least this many segments.

data/lib/hecks/fuzzing/generated_domain_check.rb

@@ -7,7 +7,7 @@ require_relative "differential"
 
 module Hecks
   module Fuzzing
-    # The child-process half of `hecks quality_control check_generated_domains`: checks one
+    # The child-process half of `hecks quality_control target.check_generated_domains`: checks one
     # generated domain.
     #
     # One domain per process, since every generated domain is named `QaGenerated`.

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -9,6 +9,12 @@ module Hecks
     # Rewrites a copied domain's persistence bindings before an ephemeral
     # fuzz/replay boot; a directory copy alone does not isolate Postgres state.
     module IsolatedBoot
+      # A vendored package named by `attaches "name", from: :vendor`.
+      VENDORED_ATTACHED = /attaches\s*\(?\s*"([\w-]+)"\s*\)?\s*,\s*from:\s*:vendor/
+
+      # A vendored package named by the deprecated `uses_embryonaut_bluebook "name"`.
+      VENDORED_DEPRECATED = /uses_embryonaut_bluebook\s*\(?\s*"([\w-]+)"/
+
       module_function
 
       # Copies `domain_path` to a tmpdir, rebinds its persistence to `adapter`, and
@@ -67,7 +73,8 @@ module Hecks
       # `Hecks.boot` only sees the domain directory itself, not `vendor/`.
       def carry_vendored_bluebooks!(source, destination)
         names = Dir.glob(File.join(destination, "**", "*.hecksagon")).flat_map do |path|
-          File.read(path).scan(/uses_embryonaut_bluebook\s*\(?\s*"([\w-]+)"/).flatten
+          text = File.read(path)
+          (text.scan(VENDORED_DEPRECATED) + text.scan(VENDORED_ATTACHED)).flatten
         end
         names.uniq.each do |name|
           package = File.join(File.dirname(source), "vendor", "embryonaut_bluebooks", name)
@@ -161,8 +168,8 @@ module Hecks
       # `:postgres_era` is the only mode that exercises era/lineage-bound SQL; plain
       # `:postgres` never touches that machinery. Unlike `:postgres`, there's no shared
       # scratch constant here — `database:`/`schema:` are required keyword args because
-      # the caller (`hecks quality_control ask run --persistence-parity`) owns that database's
-      # lifecycle.
+      # the caller (`hecks quality_control query sweep.run --persistence-parity`) owns that
+      # database's lifecycle.
       def rebind_to_postgres_era!(copy, database:, schema:)
         require "pg"
         if database.to_s.empty? || schema.to_s.empty?

data/lib/hecks/fuzzing/persistence_parity.rb

@@ -11,8 +11,8 @@ module Hecks
 
       # Replays `steps` on both adapters and lists where the results differ.
       #
-      # Compares the same six fields as `hecks quality_control ask run`'s Ruby-vs-Rust mode. Both
-      # results are JSON-round-tripped so plain data compares equal on both sides.
+      # Compares the same six fields as `hecks quality_control query sweep.run`'s Ruby-vs-Rust mode.
+      # Both results are JSON-round-tripped so plain data compares equal on both sides.
       #
       # @param left [Symbol] an `IsolatedBoot` adapter: `:memory`, `:sqlite`, `:postgres`,
       #   `:postgres_era`