hecks 3.9.1 → 3.11.0

data/lib/hecks/adapters/driving/launcher_options.rb

@@ -0,0 +1,267 @@
+require "pathname"
+require "stringio"
+require_relative "../../ports/identity_generation"
+require_relative "../../runtime/errors"
+require_relative "cli"
+
+module Hecks
+  module Adapters
+    module Driving
+      # What a domain's world file adds to its generated launcher, all of it opt-in.
+      #
+      # A `.world` that declares a `launcher` setting switches these on for that chapter; a
+      # domain without one keeps the launcher's plain forms exactly:
+      #
+      # - **run_keys** mints the `run` key of a creating command that was given none.
+      # - **settled** lists the commands (`aggregate.command`) that always act as if given `--wait`.
+      # - **unknown_runs** lists the questions that refuse a run this process does not hold.
+      # - **report** lists the settled commands whose answer is the report they recorded, as text.
+      # - **names** maps a launcher name to the command it stands for (see `CliProjector`).
+      # - **streams** lists the questions `--stream` may tail, one JSON line per new entry.
+      # - **maintainer**, **chapters**, **maintainer_chapters** shape the help for its audience.
+      module LauncherOptions
+        SETTING = "launcher".freeze
+        WAIT    = "--wait".freeze
+        STREAM  = "--stream".freeze
+        RUN_KEY = "run.value".freeze
+        # The lifecycle mark naming the states `--wait` reports as a failure (exit 1); the lifecycle
+        # says so with `mark :failure, "flagged"` (ADR 0097), so no setting lists them.
+        FAILURE_MARK = "failure".freeze
+        # What makes a directory a hecks checkout: this file stands beside `lib/`, the same test
+        # the Codebase aggregate's `Accept` applies before it runs anything.
+        CHECKOUT_MARKER = "hecks.gemspec".freeze
+        # `HECKS_MAINTAINER=1` shows the maintainer help anywhere, `0` hides it even in a checkout.
+        MAINTAINER_VARIABLE = "HECKS_MAINTAINER".freeze
+
+        module_function
+
+        # Reads a chapter's `launcher` setting.
+        #
+        # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
+        # @param chapter [String] the chapter the command line speaks to
+        # @return [Hash{Symbol => Object}, nil] the setting, or nil when the chapter did not opt in
+        def settings(runtime, chapter)
+          return unless runtime.respond_to?(:registry)
+
+          found = runtime.registry.world(chapter)&.for_verb(SETTING)
+          found.nil? || found.empty? ? nil : found
+        end
+
+        # The options the launcher's projection is asked for: the program's name, the chapter's
+        # launcher names, and whether run keys are minted (so help shows them optional).
+        #
+        # @param settings [Hash, nil] the chapter's `launcher` setting
+        # @param program [String] how the caller was invoked
+        # @return [Hash{Symbol => Object}] the options `Projector::CliProjector` reads
+        def projection(settings, program)
+          { program: program, names: settings && settings[:names], mint_run_keys: settings && settings[:run_keys] }
+        end
+
+        # Whether the person is working on a hecks checkout: `dir` or a directory above it holds
+        # `hecks.gemspec` beside `lib/`. `HECKS_MAINTAINER` overrides the look.
+        #
+        # @param dir [String] where the command line was typed
+        # @param env [#[]] the environment
+        # @return [Boolean] true for the maintainer's view of the help
+        def maintainer?(dir = Dir.pwd, env = ENV)
+          forced = env[MAINTAINER_VARIABLE].to_s
+          return forced != "0" unless forced.empty?
+
+          Pathname.new(File.expand_path(dir)).ascend.any? do |root|
+            root.join(CHECKOUT_MARKER).exist? && root.join("lib").directory?
+          end
+        end
+
+        # The help options one audience gets: the aggregates left out of the lists (`maintainer`,
+        # shown only in a hecks checkout or to `--maintainer`) and the chapters pointed at
+        # (`chapters`, plus `maintainer_chapters` in a checkout). A chapter that did not opt in
+        # gets neither.
+        #
+        # @param settings [Hash, nil] the chapter's `launcher` setting
+        # @param maintainer [Boolean] whether the help is for someone working on a hecks checkout
+        # @return [Hash{Symbol => Object}] `:hide` and `:chapters`, to merge into the projection
+        def audience(settings, maintainer)
+          return {} unless settings
+
+          chapters = Array(settings[:chapters]) + (maintainer ? Array(settings[:maintainer_chapters]) : [])
+          { hide: maintainer ? [] : Array(settings[:maintainer]).map(&:to_s), chapters: chapters.map(&:to_s) }
+        end
+
+        # Runs the block with standard error held back, so the wiring notes hecks prints about its
+        # own
+        # chapters (a Memory journal loses sagas on restart) do not open a console session. They are
+        # for an operator running a stored journal. A raised error still surfaces, unchanged.
+        #
+        # @param hold [Boolean] whether to hold standard error back; false runs the block as it is
+        # @yield the boot
+        # @return [Object] the block's value
+        def quietly(hold: true)
+          return yield unless hold
+
+          shown = $stderr
+          $stderr = StringIO.new
+          yield
+        ensure
+          $stderr = shown if hold
+        end
+
+        # Takes `--wait` out of a command's words, unless it declares a `wait` argument of its own.
+        #
+        # `--wait=false` (or `no`, `0`, `off`) is a `--wait` that was switched off; a bare `--wait`
+        # may be followed by its Boolean word.
+        #
+        # @param spec [Hash] the command's projected spec
+        # @param words [Array<String>] the words after the command
+        # @return [Array(Array<String>, Boolean)] the remaining words, and whether `--wait` was
+        #   given
+        # @raise [Runtime::TypeMismatch] if `--wait=` carries something that is not a Boolean word
+        def take_wait(spec, words)
+          return [words, false] unless words.any? { |word| wait_word?(word) } && !declares_wait?(spec)
+
+          split_wait(words)
+        end
+
+        # Whether the command declares an argument of its own named `wait`.
+        # @api private
+        def declares_wait?(spec)
+          spec[:arguments].any? { |argument| argument[:path].split(".").first == "wait" }
+        end
+
+        # The words without `--wait`, and whether it was given.
+        # @api private
+        def split_wait(words)
+          wait  = false
+          rest  = []
+          queue = words.dup
+          until queue.empty?
+            word = queue.shift
+            wait_word?(word) ? wait ||= Cli.boolean(wait_value(word, queue)) : rest << word
+          end
+          [rest, wait]
+        end
+
+        # Whether a command always waits for its reactions, as if `--wait` had been given.
+        #
+        # @param launcher [Hash, nil] the chapter's `launcher` setting
+        # @param spec [Hash] the command's projected spec
+        # @return [Boolean] true for a command the setting lists under `settled`
+        def settled?(launcher, spec)
+          return false unless launcher && spec[:kind] == :command
+
+          Array(launcher[:settled]).map(&:to_s).include?(spec[:short].to_s)
+        end
+
+        # Whether a question about one run refuses a run this process does not hold, instead of
+        # answering an empty list.
+        #
+        # @param launcher [Hash, nil] the chapter's `launcher` setting
+        # @param spec [Hash] the question's projected spec
+        # @return [Boolean] true for a question the setting lists under `unknown_runs`
+        def unknown_run?(launcher, spec)
+          return false unless launcher && spec[:kind] == :query
+
+          Array(launcher[:unknown_runs]).map(&:to_s).include?(spec[:short].to_s)
+        end
+
+        # Whether a command prints the report it recorded instead of its whole record.
+        #
+        # @param launcher [Hash, nil] the chapter's `launcher` setting
+        # @param spec [Hash] the command's projected spec
+        # @return [Boolean] true for a command the setting lists under `report`
+        def report?(launcher, spec)
+          return false unless launcher && spec[:kind] == :command
+
+          Array(launcher[:report]).map(&:to_s).include?(spec[:short].to_s)
+        end
+
+        # Whether a question may be tailed with `--stream`: the chapter's `launcher` setting lists
+        # it
+        # under `streams`, by the question's own name.
+        #
+        # @param launcher [Hash, nil] the chapter's `launcher` setting
+        # @param spec [Hash] the question's projected spec
+        # @return [Boolean] true for a question the setting names
+        def streams?(launcher, spec)
+          return false unless launcher && spec[:kind] == :query
+
+          Array(launcher[:streams]).map(&:to_s).include?(spec[:command].to_s.split(/[.:]+/).last)
+        end
+
+        # Takes `--stream` out of a question's words.
+        #
+        # @param words [Array<String>] the words after the question
+        # @return [Array(Array<String>, Boolean)] the remaining words, and whether `--stream` was
+        #   given
+        def take_stream(words)
+          [words.reject { |word| word == STREAM }, words.include?(STREAM)]
+        end
+
+        # @api private
+        def wait_word?(word) = word == WAIT || word.start_with?("#{WAIT}=")
+
+        # The Boolean word a `--wait` carries: after `=`, or the next word when it is one.
+        # @api private
+        def wait_value(word, queue)
+          return word.split("=", 2).last if word.include?("=")
+
+          Cli::BOOLEAN_WORDS.key?(queue.first.to_s.downcase) ? queue.shift : "true"
+        end
+
+        # Whether a question's text answer reports a gap, which `--wait` turns into a failing exit.
+        #
+        # The coverage checks end their report with a `GAP (n)` heading; a non-zero count is a
+        # finding, and a CI stage that waits on the question fails on it.
+        #
+        # @param text [String, nil] the question's text answer
+        # @return [Boolean] whether a `GAP (n)` heading with n above zero is in the text
+        def gap_reported?(text)
+          text.is_a?(String) && text.match?(/^GAP \((?!0\))\d+\)/)
+        end
+
+        # Mints the `run` key a creating command was not given, when the domain opted in.
+        #
+        # An explicit key always wins. Nothing is minted for a command that acts on an existing
+        # record. When no identity adapter is bound the run is refused, saying to name a key,
+        # rather than sent on without one.
+        #
+        # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
+        # @param spec [Hash] the command's projected spec
+        # @param args [Hash] the parsed arguments
+        # @param settings [Hash, nil] the chapter's `launcher` setting
+        # @return [Array(Hash, String)] the arguments, and the key minted (nil when none was)
+        # @raise [Runtime::NotFound] if a key is owed but no identity adapter is bound
+        def run_key(runtime, spec, args, settings)
+          return [args, nil] unless key_owed?(runtime, spec, args, settings)
+
+          key = Ports::IdentityGeneration.uuid(runtime.registry)
+          [args.merge(run: { value: key }), key]
+        rescue Runtime::WiringError => e
+          raise Runtime::NotFound, "cannot mint a run key (#{e.message.lines.first.strip}); name one with run=<key>"
+        end
+
+        # Whether the command is a creating one of an opted-in chapter, takes a run key and was
+        # given none.
+        # @api private
+        def key_owed?(runtime, spec, args, settings)
+          return false unless settings && settings[:run_keys] && spec[:creates]
+          return false unless spec[:arguments].any? { |argument| argument[:path] == RUN_KEY }
+
+          !args.key?(:run) && runtime.respond_to?(:registry)
+        end
+
+        # Whether a settled record sits in a state its lifecycle marks as a failure.
+        #
+        # @param aggregate [Bluebook::Aggregate, nil] the record's aggregate
+        # @param state [Hash, nil] the record's state
+        # @param settings [Hash, nil] the chapter's `launcher` setting
+        # @return [Boolean] false when the aggregate has no lifecycle
+        def failed?(aggregate, state, settings)
+          field = aggregate&.lifecycle&.field
+          return false unless field && state && settings
+
+          Array(aggregate.lifecycle.marked(FAILURE_MARK)).include?(state[field.to_sym].to_s)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/mcp/properties.rb

@@ -0,0 +1,49 @@
+require_relative "../../.."
+
+module Hecks
+  module Adapters
+    module Driving
+      module Mcp
+        # The input-schema properties the MCP server's tools share.
+        module Properties
+          SUMMARY_PROPERTY = {
+            type:        "string",
+            description: "One line: why this call is happening. Required — it is what makes the audit trail legible later."
+          }.freeze
+
+          DOMAIN_PROPERTY = {
+            type:        "string",
+            description: "The domain directory, containing a .hecksagon (e.g. \"examples/banking\"). The `domains` tool " \
+                         "lists what's available."
+          }.freeze
+
+          ARGS_PROPERTY = {
+            type:        "object",
+            description: "The command/query's declared arguments, nested value-object literals included " \
+                         "(e.g. {\"reference\":{\"value\":\"BUG#1\"}})."
+          }.freeze
+
+          SOURCE_PROPERTY = {
+            type:        "string",
+            enum:        Hecks::Storehouse::SOURCE_TAGS,
+            description: "Optional: who is calling, for the audit log `follow` reads back."
+          }.freeze
+
+          ROLE_PROPERTY = {
+            type:        "string",
+            description: "Bind a caller identity for the call's duration, so a role-gated command's authorization is " \
+                         "checked rather than merely documented. Required by `dispatch` for any command that declares a " \
+                         "role — omitting it refuses the call rather than running it unchecked. Also required if " \
+                         "`actor_id` is given."
+          }.freeze
+
+          ACTOR_ID_PROPERTY = {
+            type:        "string",
+            description: "Optional, alongside `role`: WHO holds that role — once the domain attaches Governance, checked " \
+                         "against a real Governance::RoleAssignment instead of a bare string match. Requires `role`."
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/mcp/tool_calls.rb

@@ -0,0 +1,116 @@
+require_relative "../../.."
+
+module Hecks
+  module Adapters
+    module Driving
+      module Mcp
+        # Answers one `tools/call`: the tool a name stands for, run against the booted domain the
+        # call names. A domain refusal is already `{ok: false, ...}` from `Storehouse`.
+        module ToolCalls
+          # The method that answers each tool.
+          HANDLERS = {
+            "dispatch"  => :dispatch_tool,
+            "query"     => :query_tool,
+            "events"    => :events_tool,
+            "state"     => :state_tool,
+            "catalog"   => :catalog_tool,
+            "describe"  => :describe_tool,
+            "validate"  => :validate_tool,
+            "domains"   => :domains_tool,
+            "history"   => :history_tool,
+            "behaviors" => :behaviors_tool,
+            "follow"    => :follow_tool
+          }.freeze
+
+          module_function
+
+          # Runs the tool `name` with `args`, so the shared `rescue` catches every tool's escape
+          # once.
+          #
+          # @param name [String] the tool's name
+          # @param args [Hash{String => Object}] the call's arguments
+          # @return [Hash{Symbol => Object}] the tool's answer, or `{ok: false, error: ...}`
+          def call(name, args)
+            handler = HANDLERS[name]
+            return unknown(name) unless handler
+
+            public_send(handler, args)
+          rescue StandardError => e
+            # A defect, not a refusal: reaching here means a bad domain path or an
+            # argument shape `Adapters::Driving::Json` could not symbolize.
+            { ok: false, error: "#{e.class}: #{e.message}" }
+          end
+
+          # The refusal for a tool the server does not have.
+          def unknown(name)
+            { ok: false, error: "no such tool: #{name.inspect} — known: #{HANDLERS.keys.join(", ")}" }
+          end
+
+          # A question, once the scope has admitted its arguments.
+          def query_tool(args)
+            Mcp.scope.admit_arguments!(args["args"])
+            Storehouse.query(runtime: Mcp.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 = Mcp.boot(args["domain"])
+            return dispatch_steps(runtime, args) if args["steps"]
+
+            Mcp.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
+
+          # Several commands in one call.
+          def dispatch_steps(runtime, args)
+            Mcp.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"])
+          end
+
+          def events_tool(args)
+            Storehouse.events(runtime: Mcp.boot(args["domain"]), aggregate: args["aggregate"], id: args["id"],
+                              limit: args["limit"])
+          end
+
+          def state_tool(args)
+            Storehouse.state(runtime: Mcp.boot(args["domain"]), aggregate: args["aggregate"],
+                             summary: args["summary"], id: args["id"])
+          end
+
+          def catalog_tool(args)
+            Storehouse.catalog(runtime: Mcp.boot(args["domain"]))
+          end
+
+          def describe_tool(args)
+            Storehouse.describe(runtime: Mcp.boot(args["domain"]), aggregate: args["aggregate"])
+          end
+
+          def validate_tool(args)
+            Storehouse.validate(domain: Mcp.scope.admit_domain!(args["domain"]), deep: args["deep"] == true)
+          end
+
+          def domains_tool(args)
+            Storehouse.domains(under: args["under"] || "examples")
+          end
+
+          def history_tool(args)
+            Storehouse.history(runtime: Mcp.boot(args["domain"]))
+          end
+
+          def behaviors_tool(args)
+            Storehouse.behaviors(target: args["target"])
+          end
+
+          def follow_tool(args)
+            Storehouse.follow(runtime: Mcp.boot(args["domain"]), limit: args["limit"] || 20)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/mcp/tool_definitions/auditing.rb

@@ -0,0 +1,53 @@
+require_relative "../../mcp/properties"
+
+module Hecks
+  module Adapters
+    module Driving
+      module Mcp
+        module ToolDefinitions
+          # The tools that read what has been recorded: write history, behaviors and the audit log.
+          module Auditing
+            include Properties
+
+            LIST = [
+              {
+                name:        "history",
+                description: "The full write history for every aggregate in a domain — every operation an append-only " \
+                             "adapter ever recorded, not just current state. An aggregate on a non-append-only adapter " \
+                             "answers an empty history honestly.",
+                inputSchema: {
+                  type:       "object",
+                  properties: { domain: DOMAIN_PROPERTY },
+                  required:   %w[domain]
+                }
+              },
+              {
+                name:        "behaviors",
+                description: "Run a domain's hand-curated `.behaviors` example tests and report pass/fail/error per test. " \
+                             "`target` is a single `.behaviors` file or a directory to sweep.",
+                inputSchema: {
+                  type:       "object",
+                  properties: { target: { type: "string", description: "A .behaviors file, or a directory to sweep." } },
+                  required:   %w[target]
+                }
+              },
+              {
+                name:        "follow",
+                description: "Tail this server's own audit log for a domain — the last `limit` dispatch/query/state/dry-run " \
+                             "calls made through it, each carrying its summary, source, and outcome.",
+                inputSchema: {
+                  type:       "object",
+                  properties: {
+                    domain: DOMAIN_PROPERTY,
+                    limit:  { type: "integer", description: "How many recent entries to return. Defaults to 20." }
+                  },
+                  required:   %w[domain]
+                }
+              }
+            ].freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/mcp/tool_definitions/calling.rb

@@ -0,0 +1,71 @@
+require_relative "../../mcp/properties"
+
+module Hecks
+  module Adapters
+    module Driving
+      module Mcp
+        module ToolDefinitions
+          # The tools that issue a command or ask a question.
+          module Calling
+            include Properties
+
+            LIST = [
+              {
+                name:        "dispatch",
+                description: "Issue a command against a booted domain — or, with `steps`, several in one call. `command` is " \
+                             "the short or qualified verb name (the catalog/describe tools show what's available). Set " \
+                             "`dry_run: true` to check whether it WOULD succeed without committing anything. Answers the " \
+                             "record's id, its resulting state, and the events it announced — or a structured refusal, " \
+                             "never a crash.",
+                inputSchema: {
+                  type:       "object",
+                  properties: {
+                    domain:   DOMAIN_PROPERTY,
+                    command:  { type: "string", description: "The command's short or qualified name, e.g. \"open_account\". " \
+                                                             "Ignored when `steps` is given." },
+                    args:     ARGS_PROPERTY,
+                    summary:  SUMMARY_PROPERTY,
+                    source:   SOURCE_PROPERTY,
+                    role:     ROLE_PROPERTY,
+                    actor_id: ACTOR_ID_PROPERTY,
+                    dry_run:  { type: "boolean", description: "Preview only — check the command would succeed, commit nothing. " \
+                                                              "Ignored when `steps` is given." },
+                    steps:    {
+                      type:        "array",
+                      description: "Run several commands in one call, in order. Each item: {command, args}. When given, " \
+                                   "`command`/`args`/`dry_run` above are ignored.",
+                      items:       {
+                        type:       "object",
+                        properties: { command: { type: "string" }, args: ARGS_PROPERTY },
+                        required:   %w[command]
+                      }
+                    }
+                  },
+                  required:   %w[domain summary]
+                }
+              },
+              {
+                name:        "query",
+                description: "Ask a declared question of a booted domain. `question` is the short or qualified query name. " \
+                             "Answers the row array the query itself declares.",
+                inputSchema: {
+                  type:       "object",
+                  properties: {
+                    domain:   DOMAIN_PROPERTY,
+                    question: { type: "string", description: "The query's short or qualified name." },
+                    args:     ARGS_PROPERTY,
+                    summary:  SUMMARY_PROPERTY,
+                    source:   SOURCE_PROPERTY,
+                    role:     ROLE_PROPERTY,
+                    actor_id: ACTOR_ID_PROPERTY
+                  },
+                  required:   %w[domain question summary]
+                }
+              }
+            ].freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/mcp/tool_definitions/reading.rb

@@ -0,0 +1,99 @@
+require_relative "../../mcp/properties"
+
+module Hecks
+  module Adapters
+    module Driving
+      module Mcp
+        module ToolDefinitions
+          # The tools that read a domain: its events, state, shape and wiring.
+          module Reading
+            include Properties
+
+            LIST = [
+              {
+                name:        "events",
+                description: "What actually HAPPENED, with payloads, to one aggregate/record — events THIS SERVER witnessed " \
+                             "(every real dispatch ever routed through it, sourced from its own audit log — not a full " \
+                             "domain-wide event-sourcing replay). Distinct from `state` (what's stored now) and `history` " \
+                             "(append-only operation snapshots, no payload). Narrow with `aggregate` and (requires " \
+                             "`aggregate`) `id`; `limit` keeps only the most recent.",
+                inputSchema: {
+                  type:       "object",
+                  properties: {
+                    domain:    DOMAIN_PROPERTY,
+                    aggregate: { type: "string", description: "Narrow to one aggregate, e.g. \"Account\"." },
+                    id:        { type: "string", description: "Narrow to one record's own events. Requires `aggregate`." },
+                    limit:     { type: "integer", description: "Keep only the most recent N events. Omit for all of them." }
+                  },
+                  required:   %w[domain]
+                }
+              },
+              {
+                name:        "state",
+                description: "Read what an aggregate actually has stored, no verb involved. Pass `id` for one record; " \
+                             "omit it to list every record the aggregate currently holds.",
+                inputSchema: {
+                  type:       "object",
+                  properties: {
+                    domain:    DOMAIN_PROPERTY,
+                    aggregate: { type: "string", description: "The aggregate's name, e.g. \"Account\"." },
+                    id:        { type: "string", description: "A specific record's id. Omit to list every record." },
+                    summary:   SUMMARY_PROPERTY
+                  },
+                  required:   %w[domain aggregate summary]
+                }
+              },
+              {
+                name:        "catalog",
+                description: "Zoom level one: every aggregate a domain declares, and every command/query name each " \
+                             "answers to. No summary needed — this changes nothing and commits nothing to any log.",
+                inputSchema: {
+                  type:       "object",
+                  properties: { domain: DOMAIN_PROPERTY },
+                  required:   %w[domain]
+                }
+              },
+              {
+                name:        "describe",
+                description: "Zoom level two: one aggregate's full contract — every command's arguments, the states it " \
+                             "may be issued from, and every way it can refuse. Omit `aggregate` for the whole domain.",
+                inputSchema: {
+                  type:       "object",
+                  properties: {
+                    domain:    DOMAIN_PROPERTY,
+                    aggregate: { type: "string", description: "Narrow to one aggregate. Omit for the whole domain." }
+                  },
+                  required:   %w[domain]
+                }
+              },
+              {
+                name:        "validate",
+                description: "Zoom level three: is this domain's wiring sound — every bind names a declared aggregate, " \
+                             "every adapter satisfies its port, the default adapter is usable. {valid:false, error:…} " \
+                             "on a real wiring defect, never a bare crash. Set `deep: true` to also model-check the IR " \
+                             "for dead lifecycle transitions, unreachable saga states, and dispatches to nowhere.",
+                inputSchema: {
+                  type:       "object",
+                  properties: {
+                    domain: DOMAIN_PROPERTY,
+                    deep:   { type: "boolean", description: "Also run the static model checker (lifecycle/saga/policy IR)." }
+                  },
+                  required:   %w[domain]
+                }
+              },
+              {
+                name:        "domains",
+                description: "Zoom level zero: every domain directory found under a root (default \"examples\"), so a " \
+                             "caller who doesn't already know a path can find one.",
+                inputSchema: {
+                  type:       "object",
+                  properties: { under: { type: "string", description: "Root directory to scan. Defaults to \"examples\"." } }
+                }
+              }
+            ].freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/mcp/tool_definitions.rb

@@ -0,0 +1,18 @@
+require_relative "../mcp/tool_definitions/calling"
+require_relative "../mcp/tool_definitions/reading"
+require_relative "../mcp/tool_definitions/auditing"
+
+module Hecks
+  module Adapters
+    module Driving
+      module Mcp
+        # The tools the MCP server answers: their names, descriptions and input schemas, in the
+        # order
+        # `tools/list` shows them.
+        module ToolDefinitions
+          TOOLS = (Calling::LIST + Reading::LIST + Auditing::LIST).freeze
+        end
+      end
+    end
+  end
+end