textus 0.43.2 → 0.46.0

data/lib/textus/boot.rb

@@ -81,12 +81,11 @@ module Textus
       { "name" => "list" },
       { "name" => "get" },
       { "name" => "where", "summary" => "resolve a key to its zone and path without reading" },
-      { "name" => "schema" },
+      { "name" => "schema", "summary" => "schema operations: 'schema show KEY', 'schema diff', 'schema init', 'schema migrate'" },
       { "name" => "put" },
       { "name" => "propose" },
       { "name" => "accept",   "summary" => "apply a queued proposal to its target zone; requires the author capability" },
-      { "name" => "key",      "summary" => "key operations: 'key mv', 'key uid'" },
-      { "name" => "delete",   "summary" => "delete an entry; --as=<role>" },
+      { "name" => "key",      "summary" => "key operations: 'key delete', 'key mv', 'key uid'" },
       { "name" => "build",    "summary" => "materialize derived entries; publish_to and publish_tree fan out copies" },
       { "name" => "fetch" },
       { "name" => "freshness", "summary" => "per-entry freshness report (status, age, ttl, on_stale)" },
@@ -96,6 +95,7 @@ module Textus
       { "name" => "doctor",   "summary" => "health-check the store (missing schemas, illegal keys, sentinel drift, etc.)" },
       { "name" => "hook",     "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
       { "name" => "pulse" },
+      { "name" => "capabilities" },
     ].freeze
 
     # Build the CLI verb catalog by deriving each summary from the corresponding
@@ -131,7 +131,7 @@ module Textus
         # agent's real read and write surface, named as verbs the agent calls —
         # not CLI strings. read_verbs can neither advertise a verb the agent
         # cannot call (audit/freshness/doctor are CLI-only) nor omit one it can
-        # (schema/rules); write_verbs drops the old `put KEY --as=… --stdin` CLI
+        # (schema_show/rules); write_verbs drops the old `put KEY --as=… --stdin` CLI
         # framing (role is connection-resolved over MCP; there is no stdin).
         # writable_zones / propose_zone below carry the agent's write authority.
         "read_verbs" => Textus::MCP::Catalog.read_verbs,

data/lib/textus/builder/pipeline.rb

@@ -5,8 +5,12 @@ module Textus
   module Builder
     module InjectMeta
       # Returns a new hash with _meta as the first key, per SPEC §6 ordering.
+      # Carries only deterministic provenance (`from`/`reduce`/`template`) — the
+      # volatile `generated_at` is deliberately NOT stamped, so the built
+      # artifact is content-addressed and a rebuild is a byte-for-byte no-op
+      # (ADR 0070). Build time lives out of the tracked artifact.
       def self.call(content_hash, mentry)
-        meta = { "generated_at" => Time.now.utc.iso8601 }
+        meta = {}
         if mentry.is_a?(Textus::Manifest::Entry::Derived)
           src = mentry.source
           if src.is_a?(Textus::Manifest::Entry::Derived::Projection)
@@ -23,35 +27,6 @@ module Textus
       end
     end
 
-    # Replaces the freshly-stamped timestamp inside `new_bytes` with the
-    # timestamp pulled from `old_bytes` (same format). Returns the rewritten
-    # bytes, or nil if either side lacks a parseable timestamp.
-    module IdempotentWrite
-      def self.rewrite_with_prior_timestamp(new_bytes:, old_bytes:, format:)
-        prior = extract_timestamp(old_bytes, format)
-        fresh = extract_timestamp(new_bytes, format)
-        return nil unless prior && fresh
-        return new_bytes if prior == fresh
-
-        new_bytes.sub(fresh, prior)
-      end
-
-      def self.extract_timestamp(bytes, format)
-        case format
-        when "markdown"
-          parsed = Entry.for_format("markdown").parse(bytes)
-          parsed.dig("_meta", "generated", "at")
-        when "json", "yaml"
-          parsed = Entry.for_format(format).parse(bytes)
-          parsed.dig("_meta", "generated_at")
-        else # rubocop:disable Style/EmptyElse
-          nil
-        end
-      rescue Textus::BadFrontmatter
-        nil
-      end
-    end
-
     module Pipeline
       Deps = Data.define(
         :manifest, :reader, :lister, :rpc, :template_loader, :transform_context, :inject_boot
@@ -95,18 +70,12 @@ module Textus
         target_path
       end
 
-      def self.write_if_changed(target_path, bytes, format)
-        if File.exist?(target_path)
-          old_bytes = File.binread(target_path)
-          if format == "text"
-            return if old_bytes == bytes
-          else
-            rewritten = IdempotentWrite.rewrite_with_prior_timestamp(
-              new_bytes: bytes, old_bytes: old_bytes, format: format,
-            )
-            return if rewritten && rewritten == old_bytes
-          end
-        end
+      # Built artifacts are content-addressed (no volatile timestamp, ADR 0070),
+      # so identity is plain byte-equality: skip the write when nothing changed.
+      # `format` is retained for signature stability across renderers.
+      def self.write_if_changed(target_path, bytes, _format)
+        return if File.exist?(target_path) && File.binread(target_path) == bytes
+
         File.binwrite(target_path, bytes)
       end
     end

data/lib/textus/builder/renderer/markdown.rb

@@ -1,5 +1,3 @@
-require "time"
-
 module Textus
   module Builder
     class Renderer
@@ -14,12 +12,10 @@ module Textus
                  else
                    []
                  end
-          frontmatter = {
-            "generated" => {
-              "at" => Time.now.utc.iso8601,
-              "from" => from,
-            },
-          }
+          # Deterministic frontmatter only — `from` (the source keys), never a
+          # volatile `generated.at` (ADR 0070): the artifact is content-addressed
+          # so a rebuild is a byte-for-byte no-op and a revert never drifts.
+          frontmatter = { "generated" => { "from" => from } }
           Entry.for_format("markdown").serialize(meta: frontmatter, body: body)
         end
       end

data/lib/textus/cli/group/fetch.rb

@@ -5,9 +5,9 @@ module Textus
         command_name "fetch"
 
         def parse(argv)
-          if argv.first == "stale"
+          if argv.first == "all"
             argv.shift
-            @sub_klass = Verb::FetchStale
+            @sub_klass = Verb::FetchAll
           else
             @sub_klass = Verb::Fetch
           end

data/lib/textus/cli/group.rb

@@ -6,6 +6,7 @@ module Textus
         # `parent_group` is this group counts as a subcommand. Sorted
         # alphabetically by command_name for stable help output.
         def subcommands
+          Textus::CLI::Runner.install!
           Verb.descendants
               .select { |k| k.parent_group == self && k.command_name }
               .sort_by(&:command_name)

data/lib/textus/cli/runner.rb

@@ -0,0 +1,187 @@
+module Textus
+  class CLI
+    # Generates CLI::Verb (and CLI::Group) subclasses from per-verb contracts,
+    # so the CLI surface is a projection of the contract — the operator-facing
+    # mirror of MCP::Catalog (ADR 0063).
+    module Runner
+      # Subclassable base for contract-projected verbs. Carries the verb's
+      # contract (class attr `spec`) and the generic dispatch, exposing one
+      # overridable seam, #invoke, that defaults to the generic projection.
+      # Escape-hatch verbs subclass this and override #invoke to add behavior
+      # (suggestions, --stdin, BuildLock, multi-dispatch) WITHOUT restating the
+      # verb name — `spec.verb` remains the single source of dispatch.
+      class Base < Verb
+        class << self
+          attr_accessor :spec
+
+          # ADR 0064: derive the CLI command name from the contract's cli_leaf
+          # when not set explicitly, so an escape-hatch class never restates its
+          # own name. The reconciliation spec proves command_name == cli_leaf for
+          # every such class, so this is an equivalence, not a behavior change.
+          def command_name(name = nil)
+            return super if name
+
+            super() || spec&.cli_leaf
+          end
+        end
+
+        def spec = self.class.spec
+
+        def call(store)
+          invoke(store)
+        end
+
+        # Default: pure contract projection. Override in subclasses for behavior.
+        def invoke(store)
+          Runner.dispatch(self, store, spec)
+        end
+
+        def flag_values(s = spec)
+          s.args.reject(&:positional).each_with_object({}) do |a, h|
+            raw = respond_to?(a.name) ? public_send(a.name) : nil
+            next if raw.nil?
+
+            h[a.name] = Runner.coerce(a, raw)
+          end
+        end
+      end
+
+      module_function
+
+      # Normalize parsed CLI input into the uniform by-name inputs hash and
+      # dispatch through RoleScope's single bind+invoke site. A missing required
+      # arg becomes a UsageError phrased in the operator's command path (parity
+      # with the hand-written verbs).
+      def dispatch(verb_instance, store, spec)
+        inputs = Textus::Contract::Binder.inputs_from_ordered(
+          spec, verb_instance.positional, verb_instance.flag_values(spec)
+        )
+        inputs = inputs.merge(Textus::Contract::Sources.from_stdin(spec, verb_instance.stdin)) if spec.cli_stdin
+        inputs = Textus::Contract::Sources.acquire(spec, inputs)
+        inputs = apply_cli_defaults(spec, inputs)
+        scope = verb_instance.session_for(store)
+        begin
+          result = scope.dispatch_bound(spec.verb, inputs)
+        rescue Textus::Contract::MissingArgs => e
+          raise UsageError.new("#{spec.cli_path} requires #{e.missing.first.wire}")
+        end
+        verb_instance.emit(shape(spec, result, inputs))
+      end
+
+      # Fill CLI-specific defaults (cli_default:) for args the operator did not
+      # pass, where the CLI default diverges from the contract default the agent
+      # surfaces use — e.g. migrate/zone_mv apply by default on the CLI but plan
+      # by default for agents (ADR 0068). The divergence is legible in the
+      # contract, not hidden in a hand class.
+      def apply_cli_defaults(spec, inputs)
+        spec.args.each_with_object(inputs.dup) do |a, h|
+          next if a.cli_default == :__unset || h.key?(a.name)
+
+          h[a.name] = a.cli_default
+        end
+      end
+
+      # Shape the use-case result for the CLI wire via the verb's :cli view
+      # (falling back to the default view). The view is called uniformly as
+      # (result, inputs); an inputs-aware view echoes an input such as the key
+      # (ADR 0067).
+      def shape(spec, result, inputs)
+        Textus::Contract::View.render(spec, :cli, result, inputs)
+      end
+
+      # The default the CLI flag is generated against — `cli_default:` when the
+      # operator-facing default diverges from the contract default the agent
+      # surfaces use, else the contract `default`. This drives boolean flag
+      # polarity so a verb that applies-by-default on the CLI but plans-by-default
+      # for agents (migrate, zone_mv) gets a `--dry-run` flag, not `--no-dry-run`.
+      def effective_default(arg)
+        arg.cli_default == :__unset ? arg.default : arg.cli_default
+      end
+
+      def flagspec_for(arg)
+        wire = arg.wire.to_s.tr("_", "-")
+        if arg.type == :boolean
+          effective_default(arg) == true ? "--no-#{wire}" : "--#{wire}"
+        else
+          "--#{wire}=VALUE"
+        end
+      end
+
+      # NB: compare arg.type by equality, not `case`/`===` — `Integer === arg.type`
+      # is false when arg.type is the Integer *class* (it tests instance-of), so a
+      # `when Integer` branch would silently never coerce.
+      def coerce(arg, raw)
+        return effective_default(arg) != true if arg.type == :boolean
+        return Integer(raw) if arg.type == Integer
+
+        raw
+      end
+
+      def ensure_group(name)
+        const = name.split("_").map(&:capitalize).join
+        return Group.const_get(const, false) if Group.const_defined?(const, false)
+
+        g = Class.new(Group) { command_name name }
+        Group.const_set(const, g)
+        g
+      end
+
+      # Contract verbs whose CLI behavior is a genuine `< Runner::Base` override
+      # — behavior the generic projection cannot express (ADR 0068/0069):
+      #   get   — raises UnknownKey with resolver suggestions (a CLI-only
+      #           affordance; the agent surface deliberately returns nil)
+      #   put   — IntakeFetch read-through orchestration on --fetch
+      #   build — auto-resolves the build-capability actor role (not --as) and
+      #           serializes under BuildLock; the role resolution is policy, not
+      #           a projection (around: covers only the lock)
+      BEHAVIORAL_HATCHES = %i[get put build].freeze
+
+      # Contract verbs whose CLI is a plain `< Verb` command, not a projection at
+      # all — worker verbs and composite reports assembled outside the contract:
+      #   fetch, fetch_all — background intake workers (not request/response)
+      #   boot, doctor     — composite reports
+      NON_PROJECTED_CLI = %i[fetch fetch_all boot doctor].freeze
+
+      # The installer skips generation for either category.
+      HAND_AUTHORED_VERBS = (BEHAVIORAL_HATCHES + NON_PROJECTED_CLI).freeze
+
+      def hand_authored?(verb) = HAND_AUTHORED_VERBS.include?(verb)
+
+      def install!
+        @installed ||= {}
+        Textus::Dispatcher::VERBS.each_value do |klass|
+          next unless klass.respond_to?(:contract?) && klass.contract?
+
+          spec = klass.contract
+          next unless spec.cli?
+          next if hand_authored?(spec.verb)
+          next if @installed[spec.verb]
+
+          install_for(spec)
+          @installed[spec.verb] = true
+        end
+      end
+
+      def install_for(spec)
+        group = spec.cli_group ? ensure_group(spec.cli_group) : nil
+        leaf  = spec.cli_leaf
+        non_positional = spec.args.reject(&:positional)
+
+        klass = Class.new(Base)
+        klass.spec = spec
+        klass.command_name leaf
+        klass.parent_group group if group
+        klass.option :as_flag, "--as=ROLE"
+        klass.option :use_stdin, "--stdin" if spec.cli_stdin
+        non_positional.each { |a| klass.option a.name, Runner.flagspec_for(a) }
+
+        # Anchor the anonymous class to a constant so descendants discovery is
+        # stable. Name it after the verb under a Generated namespace.
+        const_name = spec.verb.to_s.split("_").map(&:capitalize).join
+        gen = "Gen#{const_name}"
+        Verb.const_set(gen, klass) unless Verb.const_defined?(gen, false)
+        klass
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/build.rb

@@ -1,12 +1,12 @@
 module Textus
   class CLI
     class Verb
-      class Build < Verb
-        command_name "build"
+      class Build < Runner::Base
+        self.spec = Textus::Write::Build.contract
 
         option :prefix, "--prefix=K"
 
-        def call(store)
+        def invoke(store)
           role = store.manifest.policy.actor_for("build") or
             raise UsageError.new(
               "no role holds the 'build' capability",
@@ -14,7 +14,7 @@ module Textus
             )
           Textus::Ports::BuildLock.with(root: store.root) do
             ops = store.as(role)
-            result = ops.publish(prefix: prefix)
+            result = ops.build(prefix: prefix)
             emit(result)
           end
         end

data/lib/textus/cli/verb/{fetch_stale.rb → fetch_all.rb}

@@ -1,8 +1,8 @@
 module Textus
   class CLI
     class Verb
-      class FetchStale < Verb
-        command_name "stale"
+      class FetchAll < Verb
+        command_name "all"
         parent_group Group::Fetch
 
         option :prefix, "--prefix=KEY"

data/lib/textus/cli/verb/get.rb

@@ -1,14 +1,15 @@
 module Textus
   class CLI
     class Verb
-      class Get < Verb
-        command_name "get"
-
+      class Get < Runner::Base
+        self.spec = Textus::Read::Get.contract
         option :as_flag, "--as=ROLE"
+        option :no_fetch, "--no-fetch"
 
-        def call(store)
+        def invoke(store)
           key = positional.shift or raise UsageError.new("get requires a key")
-          result = session_for(store).get_or_fetch(key)
+          kw = no_fetch.nil? ? {} : { fetch: false }
+          result = session_for(store).get(key, **kw)
           raise Textus::UnknownKey.new(key, suggestions: store.manifest.resolver.suggestions_for(key)) if result.nil?
 
           emit(result.to_h_for_wire)

data/lib/textus/cli/verb/put.rb

@@ -1,14 +1,14 @@
 module Textus
   class CLI
     class Verb
-      class Put < Verb
-        command_name "put"
+      class Put < Runner::Base
+        self.spec = Textus::Write::Put.contract
 
         option :as_flag, "--as=ROLE"
         option :use_stdin, "--stdin"
         option :fetch_name, "--fetch=NAME"
 
-        def call(store)
+        def invoke(store)
           key = positional.shift or raise UsageError.new("put requires a key")
           raise UsageError.new("put requires --stdin in v1") unless use_stdin
 

data/lib/textus/cli/verb.rb

@@ -108,6 +108,9 @@ module Textus
       def session_for(store)
         store.as(resolved_role(store))
       end
+
+      # The input stream — the source for a `cli_stdin` envelope (ADR 0068).
+      attr_reader :stdin
     end
   end
 end

data/lib/textus/cli.rb

@@ -7,9 +7,15 @@ module Textus
     # declares `command_name "X"` and has no `parent_group` is a top-level
     # verb. Sorted alphabetically for stable help output. Adding a new
     # verb requires only a new file declaring its `command_name`.
+    #
+    # `k.name` gates out anonymous (Class.new) subclasses: real verbs are always
+    # named constants (generated Gen* or hand-authored classes), so this is a
+    # no-op in production but keeps throwaway test fixtures from leaking into the
+    # registry (and tripping the reconciliation guards order-dependently).
     def self.verbs
+      Runner.install!
       Verb.descendants
-          .select { |k| k.command_name && k.parent_group.nil? }
+          .select { |k| k.name && k.command_name && k.parent_group.nil? }
           .sort_by(&:command_name)
           .to_h { |k| [k.command_name, k] }
     end
@@ -27,13 +33,21 @@ module Textus
     end
 
     def run(argv)
+      # `--root` is a global, position-agnostic option: pull it out of argv
+      # wherever it appears so it works uniformly before OR after any verb or
+      # group (e.g. both `textus --root=X hook list` and
+      # `textus hook list --root=X`). Without this, `order!` below only sees
+      # options before the first verb token, so a trailing `--root` reached the
+      # verb's own parser and raised InvalidOption (#161 F5). TEXTUS_ROOT already
+      # works everywhere via Store.discover, so this brings the flag to parity.
+      @root_arg = extract_root!(argv)
+
       # Define --version/--help ourselves so OptionParser doesn't intercept them
       # with its built-in handlers (which print "version unknown" and a bare usage
       # line, then exit before we ever reach the verb dispatch below).
       show_version = false
       show_help = false
       OptionParser.new do |o|
-        o.on("--root=PATH") { |v| @root_arg = v }
         o.on("--version", "-v") { show_version = true }
         o.on("--help", "-h") { show_help = true }
       end.order!(argv)
@@ -52,6 +66,26 @@ module Textus
 
     private
 
+    # Remove the first `--root=PATH` or `--root PATH` token from argv (anywhere)
+    # and return its value, or nil if absent. Mutates argv in place.
+    def extract_root!(argv)
+      i = argv.index { |a| a == "--root" || a.start_with?("--root=") }
+      return nil unless i
+
+      tok = argv[i]
+      if tok.start_with?("--root=")
+        argv.delete_at(i)
+        tok.delete_prefix("--root=")
+      else
+        val = argv[i + 1]
+        raise UsageError.new("--root requires a PATH") if val.nil? || val.start_with?("-")
+
+        argv.delete_at(i + 1)
+        argv.delete_at(i)
+        val
+      end
+    end
+
     def coerce_exit_code(value)
       case value
       when Integer then value
@@ -91,7 +125,7 @@ module Textus
           textus put KEY --stdin [--fetch=NAME] --as=ROLE
           textus freshness [--prefix=KEY] [--zone=Z]
           textus fetch KEY
-          textus fetch stale [--prefix=KEY] [--zone=Z]
+          textus fetch all [--prefix=KEY] [--zone=Z]
           textus audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]
           textus blame KEY [--limit=N]
           textus doctor

data/lib/textus/container.rb

@@ -1,22 +1,10 @@
 module Textus
   # Single capability record handed to every use case. Replaces the
-  # ReadCaps/WriteCaps/HookCaps trio from 0.26.x. Built once per Store.
+  # ReadCaps/WriteCaps/HookCaps trio from 0.26.x. Built once per Store
+  # (see Store#initialize); Store delegates its readers to this record,
+  # so this `Data.define` is the single source of truth for the field set.
   Container = Data.define(
     :manifest, :file_store, :schemas, :root,
     :audit_log, :events, :rpc
   )
-
-  class Container
-    def self.from_store(store)
-      new(
-        manifest: store.manifest,
-        file_store: store.file_store,
-        schemas: store.schemas,
-        root: store.root,
-        audit_log: store.audit_log,
-        events: store.events,
-        rpc: store.rpc,
-      )
-    end
-  end
 end

data/lib/textus/contract/around.rb

@@ -0,0 +1,29 @@
+module Textus
+  module Contract
+    # Registry of named, stateful wrappers a verb may declare via `around :name`.
+    # A resource implements
+    #   `wrap(scope:, inputs:, session:) { |effective_inputs| ... }`:
+    # it may adjust the inputs before the call and post-process the result after
+    # — exactly what build's lock and pulse's cursor need, without a hand-authored
+    # CLI class (ADR 0068). `session:` is the dispatching session (nil for the
+    # sessionless CLI/Ruby surfaces, present for MCP), so a session-aware resource
+    # like the cursor can defer to the session's own state instead of its file.
+    module Around
+      @registry = {}
+
+      module_function
+
+      def register(name, resource)
+        @registry[name] = resource
+      end
+
+      def fetch(name)
+        @registry.fetch(name) { raise "no around resource registered: #{name.inspect}" }
+      end
+
+      def with(name, scope:, inputs:, session: nil, &call)
+        fetch(name).wrap(scope: scope, inputs: inputs, session: session, &call)
+      end
+    end
+  end
+end

data/lib/textus/contract/binder.rb

@@ -0,0 +1,88 @@
+module Textus
+  module Contract
+    # Raised when a required arg is absent from the bound input. Surface
+    # adapters translate this to their native error (MCP ToolError, CLI
+    # UsageError); a direct Ruby call lets it surface as-is.
+    class MissingArgs < Textus::Error
+      attr_reader :spec, :missing
+
+      def initialize(spec, missing)
+        @spec = spec
+        @missing = missing
+        super("missing_args", "#{spec.verb}: missing #{missing.map(&:wire).join(", ")}")
+      end
+    end
+
+    # The single argument binder for every surface (spike: collapses the three
+    # historical implementations — MCP::Catalog.map_args, CLI::Runner.call_args,
+    # and RoleScope's default-injection loop — into one algorithm).
+    #
+    # Input is a uniform `inputs` hash keyed by arg NAME (the use-case kwarg
+    # name, never the wire name): each surface normalizes its own raw transport
+    # shape (MCP JSON keyed by wire-name, CLI argv+flags, Ruby args+kwargs) into
+    # this hash. Binder owns the shared algorithm and nothing transport-specific:
+    #
+    #   1. validate every required arg is present in `inputs`;
+    #   2. for absentees, fall back to session_default (when a session is given)
+    #      then to the literal default; otherwise omit the arg entirely;
+    #   3. split into the (positional, keyword) pair to splat into the use-case,
+    #      routing by `arg.positional`.
+    #
+    # Returns `[positional_array, keyword_hash]` — exactly what
+    # `RoleScope#<verb>(*pos, **kw)` expects.
+    module Binder
+      module_function
+
+      # Validation is unconditional: a `required:` arg absent from `inputs` is a
+      # contract violation on every surface (ADR 0069). `required:` is now an
+      # honest contract invariant, not a surface policy — args the use-case
+      # treats as optional (e.g. `meta`, whose real requiredness lives in schema
+      # validation downstream) are declared `required: false`, so this check
+      # never fires spuriously and never needs an opt-out.
+      def bind(spec, inputs, session: nil)
+        missing = spec.required_args.reject { |a| inputs.key?(a.name) }
+        raise MissingArgs.new(spec, missing) unless missing.empty?
+
+        pos = []
+        kw  = {}
+        spec.args.each do |a|
+          if inputs.key?(a.name)
+            value = inputs[a.name]
+          elsif a.session_default && session
+            value = session.public_send(a.session_default)
+          elsif !a.default.nil?
+            value = a.default
+          else
+            next
+          end
+
+          if a.positional
+            pos << value
+          else
+            kw[a.name] = value
+          end
+        end
+        [pos, kw]
+      end
+
+      # Normalize an ordered positional list + a by-name keyword hash (the shape
+      # CLI argv+flags and Ruby args+kwargs both arrive in) into the uniform
+      # by-name `inputs` hash bind expects. Positionals beyond what was supplied
+      # are dropped so bind's required-check sees them as absent.
+      def inputs_from_ordered(spec, ordered_positionals, by_name_keywords)
+        names = spec.args.select(&:positional).map(&:name)
+        names.zip(ordered_positionals).to_h.compact.merge(by_name_keywords)
+      end
+
+      # Normalize a raw transport hash keyed by WIRE name (the shape MCP JSON
+      # arrives in) into the uniform by-name `inputs` hash bind expects. Keys
+      # not declared on the contract are ignored.
+      def inputs_from_wire(spec, raw)
+        raw ||= {}
+        spec.args.each_with_object({}) do |a, h|
+          h[a.name] = raw[a.wire.to_s] if raw.key?(a.wire.to_s)
+        end
+      end
+    end
+  end
+end