hecks 3.5.0 → 3.7.0

data/lib/hecks/storehouse.rb

@@ -8,27 +8,41 @@ require_relative "doors/json_door"
 require_relative "naming"
 require_relative "projector"
 require_relative "runtime/errors"
+require_relative "storehouse/callers"
+require_relative "storehouse/audit"
+require_relative "storehouse/dispatching"
+require_relative "storehouse/querying"
+require_relative "storehouse/introspection"
 
 module Hecks
   # Dispatch/query/state and introspection over one booted domain, pure
   # beyond its own JSONL audit log — booting stays the caller's job.
+  #
+  # The tools are in `Dispatching`, `Querying`, `Introspection` and `Audit`, extended onto this
+  # module; what is here is what they share: the boot root, the alias table, and the checks on who
+  # is calling.
   module Storehouse
-    module_function
-
     # Optional on dispatch/query; omitted, source is recorded as nil rather
     # than guessed.
     SOURCE_TAGS = %w[process-manager operator hook sidequest-agent cascade daemon].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")
-
     # The root every domain path resolves under; HECKS_STOREHOUSE_ROOT widens it.
     # Hecks.boot Kernel.loads Ruby files here, so an unconfined path is
     # arbitrary code execution, not just a wrong-directory mistake.
     BOOT_ROOT = File.expand_path(ENV["HECKS_STOREHOUSE_ROOT"] || File.expand_path("../..", __dir__))
 
+    # One dispatch or query call: the booted domain, what it is asked, and who is asking.
+    Request = Struct.new(:runtime, :bluebook, :name, :summary, :args, :source, :dry_run, :role, :actor_id,
+                         keyword_init: true)
+
+    extend Callers
+    extend Audit
+    extend Dispatching
+    extend Querying
+    extend Introspection
+
+    module_function
+
     # Refuses a path outside BOOT_ROOT rather than silently clamping it — a
     # stray relative path and a deliberate escape both deserve a clear refusal.
     # :nodoc:
@@ -53,9 +67,13 @@ module Hecks
     def aggregate_ir!(bluebook, name)
       bluebook.aggregate(name) or
         raise Runtime::NotFound, "#{bluebook.name} declares no aggregate named #{name.inspect} — " \
-                                 "known: #{bluebook.aggregates.map(&:hecks_name).sort.join(', ')}"
+                                 "known: #{bluebook.aggregates.map(&:hecks_name).sort.join(", ")}"
     end
 
+    # The alias table CliRunner resolves against, for one bluebook.
+    # :nodoc:
+    def cli_for(bluebook) = Projector.call(:cli, bluebook: bluebook, options: { program: "mcp" })
+
     # The same alias table CliRunner resolves against, kept here so dispatch
     # and query never drift from what a human typing hecks run sees.
     # :nodoc:
@@ -66,7 +84,7 @@ module Hecks
       return spec if spec
 
       known = cli[:names][asking ? :question : :command].keys.sort.join(", ")
-      raise Runtime::NotFound, "no such #{asking ? 'query' : 'command'}: #{name.inspect} — known: #{known}"
+      raise Runtime::NotFound, "no such #{asking ? "query" : "command"}: #{name.inspect} — known: #{known}"
     end
 
     # A fingerprint of a domain directory: every file's relative path, size and modification time.
@@ -90,7 +108,7 @@ module Hecks
     # @param names [Array<String, nil>] short or qualified command names
     # @return [Array<String, nil>] one verb or nil per name, in order
     def verbs_for(runtime, names)
-      cli = Projector.call(:cli, bluebook: bluebook_for(runtime), options: { program: "mcp" })
+      cli = cli_for(bluebook_for(runtime))
       names.map do |name|
         resolve!(cli, name.to_s, asking: false)[:command]
       rescue Runtime::NotFound
@@ -98,50 +116,25 @@ module Hecks
       end
     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).
+    # Runs one audited tool call: the block's outcome, or the refusal it raised, is written to the
+    # audit log under `tool`, and the outcome answered without its `:verb`.
+    #
+    # @param request [Request] the call, its `bluebook` set
+    # @param tool [String] what the audit line calls the call
+    # @yieldreturn [Hash] the call's outcome
     # :nodoc:
-    def with_caller(role, actor_id, &block)
-      return block.call if role.nil?
-
-      Hecks.as_caller(role: role, actor_id: actor_id, &block)
+    def audited(request, tool)
+      outcome = yield
+      record!(request.bluebook.name, tool: tool, verb: outcome[:verb], outcome: outcome, **audit_fields(request))
+      outcome.except(:verb)
+    rescue *refusal_classes => e
+      outcome = refused(e, summary: request.summary)
+      record!(request.bluebook&.name, tool: tool, outcome: outcome, **audit_fields(request))
+      outcome
     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
+    def audit_fields(request) = request.to_h.slice(:summary, :source, :role, :actor_id)
 
     # dry_run? (Runtime::Dispatcher) only understands the pre-envelope flat
     # args shape; this is the one door back into it from dispatch's own envelope.
@@ -160,407 +153,6 @@ module Hecks
       end
     end
 
-    # :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.
-    # :nodoc:
-    def record!(domain_name, tool:, summary:, source:, outcome:, verb: nil, role: nil, actor_id: nil)
-      return unless domain_name
-
-      entry = { time: Time.now.utc.iso8601, tool: tool, verb: verb, summary: summary, source: source,
-                role: role, actor_id: actor_id,
-                ok: outcome[:ok], id: outcome[:id], error: outcome[:error], events: outcome[:events] }.compact
-      FileUtils.mkdir_p(log_root)
-      File.open(log_path(domain_name), "a") { |f| f.puts(JSON.generate(entry)) }
-    rescue StandardError
-      nil
-    end
-
-    # 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 source [String, Symbol, nil] a SOURCE_TAGS tag naming who is calling
-    # @param dry_run [Boolean] true previews; a false would_succeed is not a failure
-    # @param role [String, Symbol, nil] the caller's bound role, or nil to run unbound
-    # @param actor_id [String, nil] the caller's identity; requires role:
-    # @return [Hash] :ok plus :id/:state/:events (real) or :would_succeed/:error
-    #   (dry run); or the refused shape
-    def dispatch(runtime:, command:, summary:, args: {}, source: nil, dry_run: false, role: nil, actor_id: nil)
-      bluebook = bluebook_for(runtime)
-      tool     = dry_run ? "dry_run" : "dispatch"
-      outcome  = perform_dispatch(runtime, bluebook, command, summary, args, source, dry_run, role, actor_id)
-
-      record!(bluebook.name, tool: tool, verb: outcome[:verb], summary: summary, source: source,
-              outcome: outcome, role: role, actor_id: actor_id)
-      outcome.except(:verb)
-    rescue *refusal_classes => e
-      outcome = refused(e, summary: summary)
-      record!(bluebook&.name, tool: tool, summary: summary, source: source, outcome: outcome,
-              role: role, actor_id: actor_id)
-      outcome
-    end
-
-    # :nodoc:
-    def perform_dispatch(runtime, bluebook, command, summary, args, source, dry_run, role, actor_id)
-      require_summary!(summary)
-      valid_source!(source)
-      valid_caller!(role, actor_id)
-      cli      = Projector.call(:cli, bluebook: bluebook, options: { program: "mcp" })
-      spec     = resolve!(cli, command, asking: false)
-      require_caller_for_role_gated!(spec, role)
-      envelope = Doors::CommandRequest.normalize(Doors::JsonDoor.deep_symbolize(args),
-                                                 receiver:        spec[:receiver],
-                                                 legacy_receiver: spec[:legacy_receiver])
-
-      result = with_caller(role, actor_id) do
-        dry_run ? dry_run_outcome(runtime, spec, envelope, summary: summary) : real_dispatch(runtime, spec, envelope, summary)
-      end
-      result.merge(verb: spec[:command])
-    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?
-
-      bluebook = bluebook_for(runtime)
-      head = spec[:command].split("::", 2).last
-      aggregate = bluebook.aggregates.find { |candidate| candidate.hecks_name == head.split(".").first } if
-        head.count(".") == 1
-      record = aggregate && runtime.registry.repository(bluebook.name, aggregate)&.find(result.id)&.to_h
-      Doors::JsonDoor.materialize(record || result.state)
-    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 = Projector.call(:cli, bluebook: bluebook_for(runtime), options: { program: "mcp" })
-      names.filter_map do |name|
-        spec = resolve!(cli, name.to_s, asking: false)
-        arguments = spec[:arguments].map { |arg| arg[:path].split(".").first + (arg[:required] ? "*" : "") }
-        "#{name} (role #{spec[:role] || 'none'}): #{spec[:summary]}. Arguments: #{arguments.uniq.join(', ')}"
-      rescue Runtime::NotFound
-        nil
-      end
-    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 an earlier one
-    # refuses, since a later step naming a since-refused record will refuse
-    # honestly on its own account.
-    #
-    # @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 source [String, Symbol, nil] a SOURCE_TAGS tag naming who is calling
-    # @param role [String, Symbol, nil] the caller's bound role, or nil to run unbound
-    # @param actor_id [String, nil] the caller's identity; requires role:
-    # @return [Hash] :ok (true only if every step's own :ok was true), :results
-    def dispatch_batch(runtime:, steps:, summary:, source: nil, role: nil, actor_id: nil)
-      require_summary!(summary)
-      results = Array(steps).map do |raw|
-        step = Doors::JsonDoor.deep_symbolize(raw)
-        dispatch(runtime: runtime, command: step[:command], args: step[:args] || {},
-                 summary: summary, source: source, role: role, actor_id: actor_id)
-      end
-      { ok: results.all? { |r| r[:ok] }, summary: summary, results: results }
-    rescue *refusal_classes => e
-      refused(e, summary: summary)
-    end
-
-    # Answers one declared query.
-    #
-    # @param runtime [Runtime::Registry] the booted domain to query
-    # @param question [String, Symbol] the query name, bare or qualified
-    # @param summary [String] a one-line audit summary; required
-    # @param args [Hash] the query's arguments, JSON-shaped
-    # @param source [String, Symbol, nil] a SOURCE_TAGS tag naming who is calling
-    # @param role [String, Symbol, nil] the caller's bound role, or nil to run unbound
-    # @param actor_id [String, nil] the caller's identity; requires role:
-    # @return [Hash] :ok and :rows (each JSON-safe); or the refused shape
-    def query(runtime:, question:, summary:, args: {}, source: nil, role: nil, actor_id: nil)
-      bluebook = bluebook_for(runtime)
-      outcome  = perform_query(bluebook, runtime, question, summary, args, source, role, actor_id)
-
-      record!(bluebook.name, tool: "query", verb: outcome[:verb], summary: summary, source: source,
-              outcome: outcome, role: role, actor_id: actor_id)
-      outcome.except(:verb)
-    rescue *refusal_classes => e
-      outcome = refused(e, summary: summary)
-      record!(bluebook&.name, tool: "query", summary: summary, source: source, outcome: outcome,
-              role: role, actor_id: actor_id)
-      outcome
-    end
-
-    # :nodoc:
-    def perform_query(bluebook, runtime, question, summary, args, source, role, actor_id)
-      require_summary!(summary)
-      valid_source!(source)
-      valid_caller!(role, actor_id)
-      cli  = Projector.call(:cli, bluebook: bluebook, options: { program: "mcp" })
-      spec = resolve!(cli, question, asking: true)
-      rows = with_caller(role, actor_id) { runtime.query(spec[:command], **Doors::JsonDoor.deep_symbolize(args)) }
-
-      ok(summary: summary, rows: rows.map { |row| Doors::JsonDoor.materialize(row) }).merge(verb: spec[:command])
-    end
-
-    # Reads one aggregate's stored records directly, bypassing any declared
-    # query — id: answers one record, omitted answers every record.
-    #
-    # @param runtime [Runtime::Registry] the booted domain to read
-    # @param aggregate [String, Symbol] the aggregate's declared name
-    # @param summary [String] a one-line audit summary; required
-    # @param id [String, Object, nil] one record's identity, or nil for every record
-    # @param source [String, Symbol, nil] a SOURCE_TAGS tag naming who is calling
-    # @return [Hash] :ok and, with id:, :record; without it, :count/:records; or refused
-    def state(runtime:, aggregate:, summary:, id: nil, source: nil)
-      bluebook = bluebook_for(runtime)
-      outcome  = perform_state(runtime, bluebook, aggregate, summary, id)
-
-      record!(bluebook.name, tool: "state", summary: summary, source: source, outcome: outcome)
-      outcome
-    rescue *refusal_classes => e
-      outcome = refused(e, summary: summary)
-      record!(bluebook&.name, tool: "state", summary: summary, source: source, outcome: outcome)
-      outcome
-    end
-
-    # :nodoc:
-    def perform_state(runtime, bluebook, aggregate, summary, id)
-      require_summary!(summary)
-      ir         = aggregate_ir!(bluebook, aggregate)
-      repository = runtime.registry.repository(bluebook.name, ir)
-
-      if id
-        instance = repository.find(id) or
-          raise Runtime::NotFound, "no #{ir.hecks_name} found for id #{id.inspect}"
-        ok(summary: summary, record: Doors::JsonDoor.materialize(instance.to_h))
-      else
-        records = repository.all.map { |instance| Doors::JsonDoor.materialize(instance.to_h) }
-        ok(summary: summary, count: records.length, records: records)
-      end
-    end
-
-    # Lists every domain directory found under a root (discovered, not typed).
-    #
-    # @param under [String] the directory to search, relative to BOOT_ROOT
-    # @return [Hash] :ok, :under, :domains (each path relative to BOOT_ROOT,
-    #   sorted); :domains is [] when under does not exist
-    # @raise [Runtime::TypeMismatch] if under resolves outside BOOT_ROOT
-    def domains(under: "examples")
-      root = confine!(under, "under")
-      return ok(under: under, domains: []) unless Dir.exist?(root)
-
-      folder = Adapters::Folder.new
-      found  = Dir.children(root).sort.select { |name| folder.domain?(File.join(root, name)) }
-
-      ok(under: under, domains: found.map { |name| File.join(under, name) })
-    end
-
-    # Lists a domain's aggregates and their command/query names, snake_cased
-    # exactly as dispatch/query want them.
-    #
-    # @param runtime [Runtime::Registry] the booted domain to describe
-    # @return [Hash] :ok, :domain, :aggregates (each {name:, commands:, queries:},
-    #   command names suffixed !); or the refused shape
-    def catalog(runtime:)
-      bluebook = bluebook_for(runtime)
-
-      ok(domain:     bluebook.name,
-         aggregates: bluebook.aggregates.map do |aggregate|
-           { name:     aggregate.hecks_name,
-             commands: aggregate.commands.map { |c| "#{Naming.snake(c.hecks_name)}!" }.sort,
-             queries:  aggregate.queries.map { |q| Naming.snake(q.hecks_name) }.sort }
-         end)
-    rescue *refusal_classes => e
-      refused(e)
-    end
-
-    # One aggregate's (or the whole chapter's) full usage documentation — the
-    # same document hecks docs renders for a human.
-    #
-    # @param runtime [Runtime::Registry] the booted domain to describe
-    # @param aggregate [String, Symbol, nil] one aggregate's name, or nil for the
-    #   whole chapter
-    # @return [Hash] :ok, :domain, :docs; or the refused shape
-    # @raise [Runtime::NotFound] if aggregate names no known aggregate
-    def describe(runtime:, aggregate: nil)
-      bluebook = bluebook_for(runtime)
-      options  = aggregate ? { aggregate: aggregate_ir!(bluebook, aggregate).hecks_name } : {}
-
-      ok(domain: bluebook.name, docs: Projector.call(:docs, bluebook: bluebook, options: options))
-    rescue *refusal_classes => e
-      refused(e)
-    end
-
-    # Boots a domain and reports whether its wiring is sound; deep: true also
-    # runs Bluebook::ModelCheck past wiring, into logic. Boots for itself,
-    # unlike every other tool here, since a domain that failed to boot has
-    # no runtime to hand in — any boot failure answers the question, not just
-    # WiringError.
-    #
-    # @param domain [String] the domain's directory path, relative to BOOT_ROOT
-    # @param deep [Boolean] also run Bluebook::ModelCheck past wiring, into logic
-    # @return [Hash] {ok: true, domain:, valid: true} plus :findings when deep;
-    #   {ok: false, domain:, valid: false, error:} if the boot itself failed
-    def validate(domain:, deep: false)
-      runtime = Hecks.boot(confine!(domain, "domain"), install_doors: false)
-      result  = { ok: true, domain: domain, valid: true }
-
-      if deep
-        require_relative "bluebook/model_check"
-        findings = runtime.registry.bluebooks.values.flat_map { |bluebook| Bluebook::ModelCheck.call(bluebook) }
-        result[:findings] = findings.map { |f| { kind: f.kind, severity: f.severity, subject: f.subject, message: f.message } }
-      end
-
-      result
-    rescue StandardError => e
-      { ok: false, domain: domain, valid: false, error: "#{e.class}: #{e.message}" }
-    end
-
-    # The full write history, not just the current head — every operation that
-    # ever touched each aggregate, off its repository's own append-only entries.
-    #
-    # @param runtime [Runtime::Registry] the booted domain to read
-    # @return [Hash] :ok, :domain, :history (each aggregate's storage name
-    #   mapped to its journal_entries); or the refused shape
-    def history(runtime:)
-      bluebook = bluebook_for(runtime)
-      entries  = bluebook.aggregates.each_with_object({}) do |aggregate, all|
-        repository = runtime.registry.repository(bluebook.name, aggregate)
-        all[aggregate.storage_name] = journal_entries(repository)
-      end
-
-      ok(domain: bluebook.name, history: entries)
-    rescue *refusal_classes => e
-      refused(e)
-    end
-
-    # :nodoc:
-    def journal_entries(repository)
-      repository.entries.map { |entry| { operation: entry.operation, id: entry.id, state: Doors::JsonDoor.materialize(entry.state) } }
-    end
-
-    # Runs a domain's hand-curated .behaviors examples and reports the results.
-    #
-    # @param target [String] a .behaviors file's path, or a directory to sweep
-    # @return [Hash] :ok, :target, :files (each file's behaviors_file shape),
-    #   :counts; or the refused shape
-    # @raise [Runtime::NotFound] if target is nil or names no real file or directory
-    def behaviors(target:)
-      require_relative "behaviors"
-      raise Runtime::NotFound, "no such file or directory: #{target.inspect}" unless target && File.exist?(target)
-
-      if File.directory?(target)
-        sweep = Hecks::Behaviors.run_all(target)
-        ok(target: target, files: sweep.files.map { |file| behaviors_file(file) }, counts: sweep.summary)
-      else
-        result = Hecks::Behaviors.run(target)
-        ok(target: target, files: [behaviors_file(result)], counts: Hecks::Behaviors.summarize([result]))
-      end
-    rescue *refusal_classes => e
-      refused(e)
-    end
-
-    # :nodoc:
-    def behaviors_file(result)
-      { path:        result.path,
-        parse_error: result.parse_error,
-        runs:        Array(result.runs).map { |run| { description: run.description, status: run.status, message: run.message } } }
-    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)
-      raise Runtime::TypeMismatch, "id: requires aggregate: too — an id alone is not unique across aggregates" if id && !aggregate
-
-      bluebook = bluebook_for(runtime)
-      fqn      = aggregate ? "#{bluebook.name}::#{aggregate_ir!(bluebook, aggregate).hecks_name}" : nil
-
-      found = log_lines(bluebook.name).filter_map { |entry| entry_events(entry, fqn, id) }.flatten(1)
-      found = found.last(limit.to_i) if limit
-
-      ok(domain: bluebook.name, events: found)
-    rescue *refusal_classes => e
-      refused(e)
-    end
-
-    # :nodoc:
-    def entry_events(entry, fqn, id)
-      return unless entry[:tool] == "dispatch" && entry[:ok] && entry[:events]
-      return if fqn && !entry[:verb].to_s.start_with?("#{fqn}.")
-      return if id && entry[:id] != id
-
-      entry[:events].map { |event| event.merge(time: entry[:time], verb: entry[:verb], id: entry[:id]) }
-    end
-
     # Runtime::WiringError is included alongside the true domain refusals: a
     # bus caller sees an honest refusal here too, not a crash, even though a
     # wiring defect isn't a rule the caller broke.

data/lib/hecks/tickets/bluebook/tickets.bluebook

@@ -116,6 +116,24 @@ Hecks.bluebook "Tickets" do
       emits "RunFindingReported"
     end
 
+    # A lane that stood behind the lane it follows for longer than its Lane row allows reports
+    # itself. The alert key names the finding and carries the day, so a lane that stays late files
+    # one finding a day: the same key again is the same finding.
+    command "ReportLag" do
+      goal "Record a lane that has stood behind the lane it follows too long as a finding"
+
+      attribute :finding, FindingKey
+      attribute :body,    Body
+
+      sets :finding
+      sets :body
+      sets :fingerprint, to: "lane-lag"
+      sets :title,  to: "A lane is behind the lane it follows"
+      sets :source, to: "qa_loop"
+
+      emits "LagFindingReported"
+    end
+
     command "Triage" do
       role "Maintainer"
       goal "Give a finding its kind and severity"
@@ -283,6 +301,11 @@ Hecks.bluebook "Tickets" do
     trigger Finding::GitHubIssues::OpenIssue, with: { finding: :finding }
   end
 
+  policy "OpenIssueWhenLagReported" do
+    on      "Finding.LagFindingReported"
+    trigger Finding::GitHubIssues::OpenIssue, with: { finding: :finding }
+  end
+
   policy "LabelIssueWhenTriaged" do
     on      "Finding.FindingTriaged"
     trigger Finding::GitHubIssues::LabelIssue, with: { finding: :finding }
@@ -314,6 +337,12 @@ Hecks.bluebook "Tickets" do
     trigger Finding::ReportFailedRun, with: { finding: :run, body: :refusal }
   end
 
+  # A watch that finds a lane late faults it, and the fault files its finding.
+  policy "ReportWhenLaneLags" do
+    on      "PromotionRun.LaneLagged"
+    trigger Finding::ReportLag, with: { finding: :alert_key, body: :refusal }
+  end
+
   policy "ReportWhenGateFaulted" do
     on      "GateRun.GateFaulted"
     trigger Finding::ReportFailedRun, with: { finding: :run, body: :refusal }

data/lib/hecks/tools/argument_gate_matrix/dispatching.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module ArgumentGateMatrix
+      # Dispatches candidate rows against a booted domain and reads Ruby's dispatch trace to see
+      # which gate refused.
+      module Dispatching
+        def order_for(kind) = kind == "entity" ? ENTITY_ORDER : AGGREGATE_ORDER
+
+        # The first declared step missing from the dispatch trace is the one that refused.
+        def refused_step(kind)
+          interpreter = kind == "entity" ? Hecks::Runtime::EntityInterpreter : Hecks::Runtime::CommandInterpreter
+          ran = interpreter.trace || []
+          # `decode_arguments` never traces, so it must not be read as the refusing step.
+          order_for(kind).reject { |step| step == "decode_arguments" }.find { |step| !ran.include?(step.to_sym) }
+        end
+
+        # Dispatches one row; returns [refusal class, message, refused step], or nils if it
+        # succeeded.
+        def run_row(runtime, row, kind)
+          with_traces { attempt(runtime, row, kind) }
+        end
+
+        # Sorts a row by what Ruby did with it.
+        #
+        # @return [Array(Symbol, Hash)] `:kept` or `:dropped`, and the row with its verdict added
+        def judge(runtime, row, domain)
+          kind, error, refused = run_row(runtime, row, row[:kind])
+          if kind.nil?
+            [:dropped, row.merge(reason: "Ruby accepted it — neither gate refused")]
+          elsif refused.to_s != row[:pair].first
+            [:dropped, row.merge(reason: "Ruby refused at #{refused.inspect} (#{kind}), not the earlier declared step")]
+          else
+            [:kept, row.merge(domain: domain, expected: { "kind" => kind, "error" => error, "refused_at" => refused.to_s })]
+          end
+        end
+
+        private
+
+        # Records the dispatch trace of both interpreters while the block runs.
+        def with_traces
+          Hecks::Runtime::CommandInterpreter.trace = []
+          Hecks::Runtime::EntityInterpreter.trace = []
+          yield
+        ensure
+          Hecks::Runtime::CommandInterpreter.trace = nil
+          Hecks::Runtime::EntityInterpreter.trace = nil
+        end
+
+        def attempt(runtime, row, kind)
+          args = JSON.parse(JSON.generate(row[:args])).transform_keys(&:to_sym)
+          dispatch_row(runtime, row, args)
+          [nil, nil, nil]
+        rescue *Hecks::Runtime::DOMAIN_REFUSALS => e
+          [e.class.name.split("::").last, e.message, refused_step(kind)]
+        end
+
+        def dispatch_row(runtime, row, args)
+          return runtime.dispatch_flat(row[:verb], args) unless row[:role]
+
+          Hecks.as_caller(role: row[:role]) { runtime.dispatch_flat(row[:verb], args) }
+        end
+      end
+    end
+  end
+end