textus 0.43.2 → 0.46.0

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,15 @@ 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,
+      capabilities: Textus::Read::Capabilities,
 
       # Maintenance
       migrate: Textus::Maintenance::Migrate,

data/lib/textus/doctor/check/orphaned_publish_targets.rb

@@ -8,7 +8,7 @@ module Textus
       # that drift without making `build` scan globally.
       class OrphanedPublishTargets < Check
         def call
-          sdir = File.join(root, Textus::Ports::SentinelStore::DIR)
+          sdir = Textus::Layout.sentinels(root)
           return [] unless File.directory?(sdir)
 
           repo_root = File.dirname(root)

data/lib/textus/doctor/check/sentinels.rb

@@ -5,7 +5,7 @@ module Textus
         def call
           store      = Textus::Ports::SentinelStore.new
           file_stat  = Textus::Ports::Storage::FileStat.new
-          dir        = File.join(root, "sentinels")
+          dir        = Textus::Layout.sentinels(root)
           return [] unless file_stat.directory?(dir)
 
           repo_root = File.dirname(root)

data/lib/textus/domain/policy/predicates/fresh_within.rb

@@ -35,13 +35,14 @@ module Textus
           private
 
           # Domain-pure: reads the stored write timestamp from the envelope's
-          # freshness (checked_at) or meta (last_fetched_at/generated_at) and
-          # parses the stored ISO-8601 string. Parsing a stored string is not
-          # I/O (allowed in domain, ADR 0024).
+          # freshness (checked_at) or meta (last_fetched_at) and parses the
+          # stored ISO-8601 string. Parsing a stored string is not I/O (allowed
+          # in domain, ADR 0024). `generated_at` is intentionally NOT consulted:
+          # build-generation time is no longer carried in the artifact (ADR
+          # 0070), and fetch-freshness is a fetch concept, not a build one.
           def written_at(envelope)
             raw = envelope.freshness&.checked_at ||
-                  envelope.meta&.dig("last_fetched_at") ||
-                  envelope.meta&.dig("generated_at")
+                  envelope.meta&.dig("last_fetched_at")
             return raw if raw.is_a?(Time)
             return nil if raw.nil?
 

data/lib/textus/envelope/io/writer.rb

@@ -82,6 +82,7 @@ module Textus
           raise EtagMismatch.new(key, if_etag, etag_before) if if_etag && if_etag != etag_before
 
           @file_store.delete(path)
+          prune_empty_parents(path)
           @audit_log.append(
             role: @call.role, verb: "delete", key: key,
             etag_before: etag_before, etag_after: nil,
@@ -99,6 +100,7 @@ module Textus
 
           FileUtils.mkdir_p(File.dirname(to_path))
           FileUtils.mv(from_path, to_path)
+          prune_empty_parents(from_path)
           basename = to_key.split(".").last
           Entry.for_format(new_mentry.format).rewrite_name(to_path, basename)
           etag_after = Etag.for_file(to_path)
@@ -129,6 +131,38 @@ module Textus
 
         private
 
+        # After a file leaves a directory (delete or move-source), remove any
+        # now-empty parent dirs so bulk move/delete doesn't accrue orphan dirs
+        # (F3 of #161). Floored at the entry's *zone directory* — a zone is a
+        # declared, first-class container, so its own dir is preserved even when
+        # momentarily empty; only the sub-dirs the bulk op carved out are
+        # pruned. Stops at the first non-empty ancestor, so a dir holding a
+        # `.gitkeep` or sibling entries survives. Best-effort: a lost race or a
+        # non-empty dir is silently fine, never fatal to the write.
+        def prune_empty_parents(path)
+          floor = zone_floor(path)
+          return unless floor
+
+          dir = File.dirname(path)
+          while dir.start_with?("#{floor}/") && Dir.empty?(dir)
+            Dir.rmdir(dir)
+            dir = File.dirname(dir)
+          end
+        rescue SystemCallError
+          nil
+        end
+
+        # The zone directory under which `path` lives (`<root>/zones/<zone>`),
+        # or nil if `path` is not under the store's zones tree.
+        def zone_floor(path)
+          zones_root = File.join(@manifest.data.root, "zones")
+          prefix = "#{zones_root}/"
+          return nil unless path.start_with?(prefix)
+
+          zone_seg = path.delete_prefix(prefix).split("/").first
+          zone_seg && File.join(zones_root, zone_seg)
+        end
+
         def ensure_uid(format, meta, content, existing_uid)
           Textus::Entry.for_format(format).inject_uid(meta, content, existing_uid)
         end

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/layout.rb

@@ -29,6 +29,14 @@ module Textus
       File.join(run(root), "audit")
     end
 
+    # Sentinels are machine-generated (the published target's sha), not authored
+    # source, so they live on the runtime side under `.run/` — git-ignored,
+    # regenerated by the next build via content-identical adoption (ADR 0070,
+    # superseding ADR 0038's `:config` classification).
+    def self.sentinels(root)
+      File.join(run(root), "sentinels")
+    end
+
     def self.audit_log(root)
       File.join(audit_dir(root), "audit.log")
     end

data/lib/textus/maintenance/key_delete_prefix.rb

@@ -6,17 +6,20 @@ 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)
+      surfaces :cli, :mcp
+      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: false,
+                              description: "when true, returns the keys that would be deleted without deleting them; " \
+                                           "defaults to false, so omitting it deletes immediately"
+      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: false)
         raise UsageError.new("prefix required") if prefix.nil? || prefix.empty?
 
         leaves = Read::List.new(container: @container)

data/lib/textus/maintenance/key_mv_prefix.rb

@@ -7,21 +7,33 @@ 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)
+      surfaces :cli, :mcp
+      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: false,
+                                  description: "when true, returns the planned moves without applying them; " \
+                                               "defaults to false, so omitting it applies the rename immediately"
+      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: false)
         raise UsageError.new("from_prefix and to_prefix required") if from_prefix.nil? || to_prefix.nil?
 
         leaves = list_leaves_under(from_prefix)
+
+        # When from_prefix is itself a leaf, `delete_prefix("#{from_prefix}.")`
+        # finds no trailing dot to strip, so the tail keeps the whole key and the
+        # move silently targets "to_prefix.<full-from_prefix>". Refuse it — a
+        # single-key rename is `mv`'s job, not the bulk prefix verb's.
+        if leaves.include?(from_prefix)
+          raise UsageError.new("from_prefix '#{from_prefix}' is itself a leaf — use `mv` to rename a single key")
+        end
+
         warnings = []
         warnings << "no keys under #{from_prefix}" if leaves.empty?
 

data/lib/textus/maintenance/migrate.rb

@@ -9,18 +9,20 @@ 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)
+      surfaces :cli, :mcp
+      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: false,
+                              description: "when true, returns the planned ops without applying them; " \
+                                           "defaults to false, so omitting it runs the migration immediately"
+      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: false)
         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 +43,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

@@ -10,10 +10,11 @@ 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)
+      surfaces :cli, :mcp
+      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

@@ -10,11 +10,14 @@ 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)
+      surfaces :cli, :mcp
+      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: false,
+                              description: "when true, returns the planned zone move without applying it; " \
+                                           "defaults to false, so omitting it applies the move immediately"
+      view { |v, _i| v.to_h }
 
       def initialize(container:, call:)
         @container = container
@@ -23,7 +26,7 @@ module Textus
         @root      = container.root
       end
 
-      def call(from:, to:, dry_run: false)
+      def call(from, to, dry_run: false)
         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

data/lib/textus/ports/publisher.rb

@@ -7,8 +7,9 @@ module Textus
     # artifact; no parsing or stripping.
     #
     # Sentinel I/O is delegated to Textus::Ports::SentinelStore. Sentinels live
-    # under `<store_root>/sentinels/` and mirror the target's repo-relative layout
-    # so consumer directories aren't polluted with `.textus-managed.json` siblings.
+    # under `<store_root>/.run/sentinels/` (runtime, git-ignored — ADR 0070) and
+    # mirror the target's repo-relative layout so consumer directories aren't
+    # polluted with `.textus-managed.json` siblings.
     module Publisher
       def self.publish(source:, target:, store_root:)
         FileUtils.mkdir_p(File.dirname(target))