textus 0.43.2 → 0.45.1

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
@@ -91,7 +97,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/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

data/lib/textus/contract/resources/cursor.rb

@@ -0,0 +1,26 @@
+module Textus
+  module Contract
+    module Resources
+      # Reads the persisted file cursor as the `since` default when the caller
+      # did not supply one, runs pulse, then persists the returned cursor.
+      # Replaces CLI::Verb::Pulse's hand-coded CursorStore read/write (ADR 0068).
+      #
+      # A session-bearing surface (MCP) carries its own cursor via the contract's
+      # `session_default: :cursor`, so this defers entirely when a session is
+      # present — it is the sessionless CLI/Ruby surfaces that need the file.
+      class Cursor
+        def wrap(scope:, inputs:, session:)
+          return yield(inputs) if session
+
+          store = Textus::CursorStore.new(root: scope.container.root, role: scope.role)
+          effective = inputs.key?(:since) ? inputs : inputs.merge(since: store.read)
+          result = yield(effective)
+          store.write(result["cursor"]) if result.is_a?(Hash) && result["cursor"]
+          result
+        end
+      end
+    end
+  end
+end
+
+Textus::Contract::Around.register(:cursor, Textus::Contract::Resources::Cursor.new)

data/lib/textus/contract/sources.rb

@@ -0,0 +1,39 @@
+require "json"
+
+module Textus
+  module Contract
+    # CLI-only input acquisition. Transforms entries of the uniform `inputs`
+    # hash that declare a `source:`/`coerce:`, and builds `inputs` from a
+    # `cli_stdin` envelope — so put/propose/migrate/rule_lint/audit need no
+    # hand-authored CLI class (ADR 0068). MCP receives typed JSON, so these
+    # never run there.
+    module Sources
+      module_function
+
+      # Apply per-arg :file sources (value is a path -> file contents) and
+      # :coerce callables to a by-name inputs hash. Returns a new hash.
+      def acquire(spec, inputs)
+        spec.args.each_with_object(inputs.dup) do |a, h|
+          next unless h.key?(a.name)
+
+          h[a.name] = File.read(h[a.name]) if a.source == :file
+          h[a.name] = a.coerce.call(h[a.name]) if a.coerce
+        end
+      end
+
+      # Parse a cli_stdin :json envelope into a by-name inputs hash, mapping
+      # envelope keys (wire-names) to arg names.
+      def from_stdin(spec, stream)
+        return {} unless spec.cli_stdin == :json
+
+        raw = stream.read.to_s
+        return {} if raw.strip.empty? # no envelope piped -> required args surface as missing
+
+        envelope = JSON.parse(raw)
+        spec.args.each_with_object({}) do |a, h|
+          h[a.name] = envelope[a.wire.to_s] if envelope.key?(a.wire.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/textus/contract/view.rb

@@ -0,0 +1,15 @@
+module Textus
+  module Contract
+    # Renders a use-case result for a surface, using the verb's declared view
+    # (falling back to the default). The single replacement for the old
+    # response/cli_response split and the Proc#arity sniff: views are always
+    # called as (result, inputs); a one-parameter view ignores inputs.
+    module View
+      module_function
+
+      def render(spec, surface, result, inputs)
+        spec.view(surface).call(result, inputs)
+      end
+    end
+  end
+end

data/lib/textus/contract.rb

@@ -12,7 +12,14 @@ module Textus
     # envelope key) when it must differ from the use-case kwarg `name` — e.g. `put`
     # takes the `meta:` kwarg but exposes `_meta` on the wire to match what `get`
     # returns and what the CLI `--stdin` envelope already speaks (ADR 0057).
-    Arg = Data.define(:name, :type, :required, :positional, :session_default, :description, :wire_name) do
+    # `source: :file` (CLI only) reads the arg's value as a path -> file
+    # contents; `coerce:` is a callable applied to the raw value (CLI only);
+    # `cli_default:` supplies a CLI-specific default that diverges from the
+    # contract `default` the agent surfaces use (`:__unset` sentinel = none).
+    Arg = Data.define(
+      :name, :type, :required, :positional, :session_default,
+      :description, :wire_name, :default, :source, :coerce, :cli_default
+    ) do
       # The name used on the wire (defaults to the kwarg name).
       def wire = wire_name || name
     end
@@ -26,8 +33,21 @@ module Textus
       JSON_TYPES.fetch(type) { raise ArgumentError.new("no JSON type mapping for #{type.inspect}") }
     end
 
-    Spec = Data.define(:verb, :summary, :args, :surfaces, :response) do
+    Spec = Data.define(:verb, :summary, :args, :surfaces, :views, :cli, :around, :cli_stdin) do
       def mcp? = surfaces.include?(:mcp)
+      def cli? = surfaces.include?(:cli)
+
+      # The output shaper for a surface; falls back to the default view. Every
+      # view is invoked uniformly as `view.call(result, inputs)` — a view that
+      # declares one parameter ignores `inputs` (procs tolerate extra args).
+      def view(surface = :default) = views[surface] || views.fetch(:default)
+
+      # Operator-facing command path. Defaults to the verb token; grouped verbs
+      # declare e.g. `cli "schema show"`.
+      def cli_path = cli || verb.to_s
+      def cli_words = cli_path.split
+      def cli_group = cli_words.size > 1 ? cli_words.first : nil
+      def cli_leaf  = cli_words.last
 
       def required_args = args.select(&:required)
 
@@ -77,19 +97,56 @@ module Textus
         end
       end
 
-      def arg(name, type, required: false, positional: false, session_default: nil, description: nil, wire_name: nil) # rubocop:disable Metrics/ParameterLists
+      def cli(path = nil)
+        if path
+          raise "contract already built; declare cli before reading .contract" if defined?(@__contract) && @__contract
+
+          @__cli = path.to_s
+        else
+          @__cli
+        end
+      end
+
+      # Declare a stateful wrapper resource (Contract::Around) to run around
+      # dispatch — e.g. `around :cursor` (pulse) or `around :build_lock` (build).
+      def around(name = nil)
+        return @__around unless name
+
+        raise "contract already built; declare around before reading .contract" if defined?(@__contract) && @__contract
+
+        @__around = name
+      end
+
+      def arg(name, type, required: false, positional: false, session_default: nil, description: nil, wire_name: nil, default: nil, source: nil, coerce: nil, cli_default: :__unset) # rubocop:disable Metrics/ParameterLists,Layout/LineLength
         raise "contract already built; declare args before reading .contract" if defined?(@__contract) && @__contract
 
         (@__args ||= []) << Arg.new(
           name: name, type: type, required: required,
           positional: positional, session_default: session_default,
-          description: description, wire_name: wire_name
+          description: description, wire_name: wire_name, default: default,
+          source: source, coerce: coerce, cli_default: cli_default
         )
       end
 
-      def response(&blk)
-        @__response = blk if blk
-        @__response || ->(v) { v }
+      # Verb-level: the CLI reads its inputs from a stdin envelope of this mode.
+      # `:json` parses stdin as a JSON object and distributes its keys to args
+      # by wire-name. nil means no stdin acquisition.
+      def cli_stdin(mode = :__read)
+        return @__cli_stdin if mode == :__read
+
+        raise "contract already built; declare cli_stdin before reading .contract" if defined?(@__contract) && @__contract
+
+        @__cli_stdin = mode
+      end
+
+      # Declare an output shaper. `view { ... }` is the default (MCP + Ruby);
+      # `view(:cli) { ... }` overrides for the CLI. Both receive (result, inputs).
+      def view(surface = :default, &blk)
+        return (@__views ||= {})[surface] unless blk
+
+        raise "contract already built; declare view before reading .contract" if defined?(@__contract) && @__contract
+
+        (@__views ||= {})[surface] = blk
       end
 
       def contract?
@@ -105,7 +162,10 @@ module Textus
           summary: @__summary,
           args: (@__args || []).freeze,
           surfaces: (@__surfaces || []).freeze,
-          response: response,
+          views: ((@__views ||= {})[:default] ||= ->(v, _i) { v }) && @__views,
+          cli: @__cli,
+          around: @__around,
+          cli_stdin: @__cli_stdin,
         )
       end
       # rubocop:enable Naming/MemoizedInstanceVariableName

data/lib/textus/dispatcher.rb

@@ -11,14 +11,13 @@ module Textus
       mv: Textus::Write::Mv,
       accept: Textus::Write::Accept,
       reject: Textus::Write::Reject,
-      publish: Textus::Write::Publish,
+      build: Textus::Write::Build,
       fetch: Textus::Write::FetchWorker,
       fetch_all: Textus::Write::FetchAll,
-      retention_sweep: Textus::Write::RetentionSweep,
+      retain: Textus::Write::RetentionSweep,
 
       # Read
       get: Textus::Read::Get,
-      get_or_fetch: Textus::Read::GetOrFetch,
       list: Textus::Read::List,
       where: Textus::Read::Where,
       uid: Textus::Read::Uid,
@@ -29,14 +28,14 @@ module Textus
       deps: Textus::Read::Deps,
       rdeps: Textus::Read::Rdeps,
       pulse: Textus::Read::Pulse,
-      policy_explain: Textus::Read::PolicyExplain,
+      rule_explain: Textus::Read::RuleExplain,
+      rule_list: Textus::Read::RuleList,
       published: Textus::Read::Published,
-      schema: Textus::Read::SchemaEnvelope,
+      schema_show: Textus::Read::SchemaEnvelope,
       validate_all: Textus::Read::ValidateAll,
       doctor: Textus::Read::Doctor,
       boot: Textus::Read::Boot,
       retainable: Textus::Read::Retainable,
-      rules: Textus::Read::Rules,
 
       # Maintenance
       migrate: Textus::Maintenance::Migrate,

data/lib/textus/hooks/context.rb

@@ -28,8 +28,17 @@ module Textus
         @scope
       end
 
-      # read
-      def get(key)                = @scope.get(key)
+      # read — a deliberately pure-observation surface: NOTHING here fetches
+      # (`list`/`deps`/`freshness` don't either). The invariant is that a hook
+      # observes current state and never triggers an I/O cascade. `get` bypasses
+      # the read-through behavior (ADR 0062) and reads with fetch:false directly,
+      # because read-through inside a hook would: (1) fire fetch events → hooks →
+      # unbounded reentrancy; (2) spawn the orchestrator's threads/fork from
+      # inside a hook callback; (3) probe the single-flight fetch lock its own
+      # enclosing fetch may hold (deadlock); (4) inject network latency into
+      # every hook read. With the merged Read::Get class, `fetch:false` (the
+      # method default) guarantees no orchestrator is built.
+      def get(key)                = pure_reader.call(key)
       def list(**)                = @scope.list(**)
       def deps(key)               = @scope.deps(key)
       def freshness(key)          = @scope.freshness(key)
@@ -50,6 +59,19 @@ module Textus
       def inspect
         "#<Textus::Hooks::Context role=#{@role} correlation_id=#{@correlation_id}>"
       end
+
+      private
+
+      def pure_reader
+        @pure_reader ||= Textus::Read::Get.new(
+          container: @scope.container,
+          call: Textus::Call.build(
+            role: @scope.role,
+            correlation_id: @scope.correlation_id,
+            dry_run: @scope.dry_run?,
+          ),
+        )
+      end
     end
   end
 end

data/lib/textus/maintenance/key_delete_prefix.rb

@@ -7,16 +7,18 @@ module Textus
       verb     :key_delete_prefix
       summary  "Bulk-delete every leaf key under prefix."
       surfaces :cli, :ruby, :mcp
-      arg :prefix,  String, required: true, description: "every leaf key under this dotted prefix is deleted"
-      arg :dry_run, :boolean, description: "true returns the Plan without writing; default false applies the delete immediately"
-      response(&:to_h)
+      cli      "key delete-prefix"
+      arg :prefix,  String, required: true, positional: true, description: "every leaf key under this dotted prefix is deleted"
+      arg :dry_run, :boolean, default: true, cli_default: false,
+                              description: "agents plan by default; the CLI applies by default (pass --dry-run to plan only)"
+      view { |v, _i| v.to_h }
 
       def initialize(container:, call:)
         @container    = container
         @call         = call
       end
 
-      def call(prefix:, dry_run: false)
+      def call(prefix, dry_run: true)
         raise UsageError.new("prefix required") if prefix.nil? || prefix.empty?
 
         leaves = Read::List.new(container: @container)

data/lib/textus/maintenance/key_mv_prefix.rb

@@ -8,17 +8,19 @@ module Textus
       verb     :key_mv_prefix
       summary  "Bulk-rename every leaf key under from_prefix to to_prefix. Dry-run returns a Plan; apply with dry_run: false."
       surfaces :cli, :ruby, :mcp
-      arg :from_prefix, String, required: true, description: "dotted prefix whose leaf keys are renamed"
-      arg :to_prefix,   String, required: true, description: "dotted prefix the keys are renamed to"
-      arg :dry_run,     :boolean, description: "true returns the Plan without writing; default false applies the rename immediately"
-      response(&:to_h)
+      cli      "key mv-prefix"
+      arg :from_prefix, String, required: true, positional: true, description: "dotted prefix whose leaf keys are renamed"
+      arg :to_prefix,   String, required: true, positional: true, description: "dotted prefix the keys are renamed to"
+      arg :dry_run,     :boolean, default: true, cli_default: false,
+                                  description: "agents plan by default; the CLI applies by default (pass --dry-run to plan only)"
+      view { |v, _i| v.to_h }
 
       def initialize(container:, call:)
         @container    = container
         @call         = call
       end
 
-      def call(from_prefix:, to_prefix:, dry_run: false)
+      def call(from_prefix, to_prefix, dry_run: true)
         raise UsageError.new("from_prefix and to_prefix required") if from_prefix.nil? || to_prefix.nil?
 
         leaves = list_leaves_under(from_prefix)

data/lib/textus/maintenance/migrate.rb

@@ -10,17 +10,18 @@ module Textus
       verb     :migrate
       summary  "Run a YAML migration plan (multi-op)."
       surfaces :cli, :ruby, :mcp
-      arg :plan_yaml, String, required: true,
-                              description: "YAML listing the migration ops (zone_mv, key_mv_prefix, key_delete_prefix) run in order"
-      arg :dry_run,   :boolean, description: "true returns the combined plan without writing; default false applies every op immediately"
-      response(&:to_h)
+      arg :plan_yaml, String, required: true, positional: true, source: :file,
+                              description: "path to the YAML migration plan (zone_mv, key_mv_prefix, key_delete_prefix ops run in order)"
+      arg :dry_run, :boolean, default: true, cli_default: false,
+                              description: "agents plan by default; the CLI applies by default (pass --dry-run to plan only)"
+      view { |v, _i| v.to_h }
 
       def initialize(container:, call:)
         @container    = container
         @call         = call
       end
 
-      def call(plan_yaml:, dry_run: false)
+      def call(plan_yaml, dry_run: true)
         raw = YAML.safe_load(plan_yaml, permitted_classes: [Symbol], aliases: false)
         raise UsageError.new("migration plan must be a YAML mapping") unless raw.is_a?(Hash)
 
@@ -41,11 +42,13 @@ module Textus
       private
 
       def invoke_op(op_name, op_hash, dry_run:)
-        kwargs = op_hash.except("op").transform_keys(&:to_sym).merge(dry_run: dry_run)
         klass = op_class(op_name)
-        klass.new(
-          container: @container, call: @call,
-        ).call(**kwargs)
+        inputs = op_hash.except("op").transform_keys(&:to_sym).merge(dry_run: dry_run)
+        # Each op now carries positional args (from/to, from_prefix/to_prefix,
+        # prefix); split the YAML fields into (positional, keyword) via the op's
+        # own contract so we call its #call signature correctly (ADR 0066/0068).
+        args, kwargs = Textus::Contract::Binder.bind(klass.contract, inputs)
+        klass.new(container: @container, call: @call).call(*args, **kwargs)
       end
 
       def op_class(op_name)

data/lib/textus/maintenance/rule_lint.rb

@@ -11,9 +11,10 @@ module Textus
       verb     :rule_lint
       summary  "Diff candidate manifest YAML's rules against the live manifest. No writes."
       surfaces :cli, :ruby, :mcp
-      arg :candidate_yaml, String, required: true,
-                                   description: "manifest YAML; its `rules:` block is diffed against the live manifest (no writes)"
-      response(&:to_h)
+      cli      "rule lint"
+      arg :candidate_yaml, String, required: true, wire_name: :against, source: :file,
+                                   description: "path to candidate manifest YAML; its `rules:` block is diffed against the live manifest"
+      view { |v, _i| v.to_h }
 
       def initialize(container:, call:)
         @container = container

data/lib/textus/maintenance/zone_mv.rb

@@ -11,10 +11,12 @@ module Textus
       verb     :zone_mv
       summary  "Rename a zone — manifest + files. Refuses if destination exists."
       surfaces :cli, :ruby, :mcp
-      arg :from,    String, required: true, description: "current zone name"
-      arg :to,      String, required: true, description: "new zone name; refused if a zone by this name already exists"
-      arg :dry_run, :boolean, description: "true returns the plan without writing; default false applies the rename immediately"
-      response(&:to_h)
+      cli      "zone mv"
+      arg :from,    String, required: true, positional: true, description: "current zone name"
+      arg :to,      String, required: true, positional: true, description: "new zone name; refused if a zone by this name already exists"
+      arg :dry_run, :boolean, default: true, cli_default: false,
+                              description: "agents plan by default; the CLI applies by default (pass --dry-run to plan only)"
+      view { |v, _i| v.to_h }
 
       def initialize(container:, call:)
         @container = container
@@ -23,7 +25,7 @@ module Textus
         @root      = container.root
       end
 
-      def call(from:, to:, dry_run: false)
+      def call(from, to, dry_run: true)
         raise UsageError.new("from and to required") if from.nil? || to.nil? || from.empty? || to.empty?
         raise UsageError.new("zone '#{from}' not declared") unless @manifest.data.declared_zone_kinds.key?(from)
 

data/lib/textus/manifest/entry/base.rb

@@ -86,7 +86,7 @@ module Textus
         end
 
         # Returns: { kind: :built|:leaves, value: ... } to be accumulated by
-        # Write::Publish, or nil to skip.
+        # Write::Build, or nil to skip.
         def publish_via(pctx, prefix: nil)
           publish_mode.publish(pctx, prefix: prefix)
         end

data/lib/textus/mcp/catalog.rb

@@ -4,7 +4,7 @@ module Textus
     # (ADR 0039). `tool_schemas` feeds tools/list; `call` is the generic
     # tools/call dispatch: map JSON args -> (positional, keyword) per the
     # contract, invoke the verb through the role scope, then shape the
-    # return value with the contract's response block. No per-tool code.
+    # return value with the contract's default view. No per-tool code.
     module Catalog
       module_function
 
@@ -55,43 +55,16 @@ module Textus
         raise ToolError.new("unknown tool: #{name}") unless klass && mcp_surfaced?(klass)
 
         spec = klass.contract
-        pos, kw = map_args(spec, args || {}, session)
-        result = store.as(session.role).public_send(spec.verb, *pos, **kw)
-        spec.response.call(result)
+        inputs = Textus::Contract::Binder.inputs_from_wire(spec, args)
+        result = store.as(session.role).dispatch_bound(spec.verb, inputs, session: session)
+        Textus::Contract::View.render(spec, :default, result, inputs)
+      rescue Textus::Contract::MissingArgs => e
+        raise ToolError.new("#{spec.verb}: missing #{e.missing.map { |a| a.wire.to_s }.join(", ")}")
       rescue ContractDrift, CursorExpired
         raise
       rescue Textus::Error => e
         raise ToolError.new("#{name}: #{e.message}")
       end
-
-      # Splits the raw JSON arg hash into the positional list and keyword hash
-      # the use-case expects, validating required presence first.
-      # Session-default args (session_default: :method_name) are injected from
-      # the session when absent from the wire; they are never treated as missing.
-      # Positional args are emitted in contract declaration order; use-case signatures must match.
-      def map_args(spec, raw, session = nil)
-        missing = spec.required_args.map { |a| a.wire.to_s } - raw.keys
-        raise ToolError.new("#{spec.verb}: missing #{missing.join(", ")}") unless missing.empty?
-
-        positional = []
-        keyword = {}
-        spec.args.each do |a|
-          if raw.key?(a.wire.to_s)
-            value = raw[a.wire.to_s]
-          elsif a.session_default && session
-            value = session.public_send(a.session_default)
-          else
-            next
-          end
-
-          if a.positional
-            positional << value
-          else
-            keyword[a.name] = value
-          end
-        end
-        [positional, keyword]
-      end
     end
   end
 end